GVC (Global Virtual Cloud)

Overview

Refer to the GVC concepts page.

Create a GVC

Refer to the Create a GVC guide for additional details.

GVC Configuration Example

Here’s a comprehensive example of a GVC configuration that includes all available options:

kind: gvc
name: my-gvc
spec:
  staticPlacement:
    locationLinks:
      - //location/aws-us-west-2
      - //location/aws-eu-west-1
  pullSecretLinks:
    - //secret/docker-registry-secret
    - //secret/ecr-secret
  domain: myapp.example.com
  endpointNamingFormat: org
  tracing:
    provider:
      controlPlane: {}
    customTags:
      environment: production
    sampling: 10
  env:
    - name: ENVIRONMENT
      value: production
    - name: LOG_LEVEL
      value: info
  loadBalancer:
    dedicated: true
    trustedProxies: 1
    redirect:
      class:
        status5xx: https://error.example.com
        status401: https://auth.example.com/login?return_to=%REQ(:path)%
    ipSet: //ipset/my-ipset
  keda:
    enabled: true
    identityLink: //identity/keda-identity
    secrets:
      - //secret/keda-trigger-auth-1
      - //secret/keda-trigger-auth-2

Switching between GVCs

Using the console, if an Org has multiple GVCs, there will be an angle bracket > to the right of the current GVC name in the left menu. Click the bracket to show and select a GVC.

GVC Namespace

The GVC namespace is used when constructing the canonical endpoint and individual location endpoints to avoid naming collision between workloads with the same name in different GVCs. The namespace is also used when performing service-to-service calls.

GVC Locations

The cloud provider locations that workloads will be served from are mapped to a GVC. At least one location is required. The global and canonical endpoints will use DNS to route the request to the nearest healthy location.

Adding or removing a location will immediately provision or deprovision it from all workloads, respectively.

The available locations are scoped to an org and can be enabled/disabled globally. Any changes to the location at the org will be propagated to all GVCs using that location.

Load Balancer Configuration

The loadBalancer property allows you to configure load balancing settings for the GVC.

Dedicated Load Balancer

When a dedicated load balancer is enabled on a GVC, all inbound traffic is routed through a custom cloud load balancer for each enabled location. Enabling/disabling this option can cause a brief period when connectivity fails during DNS propagation. Additional charges apply when custom load balancing is enabled. Any domains configured to route traffic to this GVC will also leverage the custom load balancer. The following additional domain settings are available when using a custom load balancer:

Custom Ports : Allows domains to route TCP traffic and can be configured on a variety of ports.
Accept All Hosts : Allows the domain to accept traffic for any hostname.

Load Balancer Properties

dedicated: Creates a dedicated load balancer in each location and enables additional Domain features: custom ports, protocols and wildcard hostnames. Charges apply for each location.
multiZone.enabled: Enable/Disable multi-zone load balancing. Cross zone charges apply.
trustedProxies: Controls the address used for request logging and for setting the X-Envoy-External-Address header. Valid values are 0, 1, or 2.
- 0 (default): Use the source client IP address
- 1: Use the last address in an existing X-Forwarded-For header
- 2: Use the second to last address in an existing X-Forwarded-For header
ipSet: A link to an IPSet resource that will be used for this load balancer.

Load Balancer Access Logs

You can view access logs for the load balancer by navigating to the logs page in the console and filtering by {gvc="<GVC_NAME>",workload="_loadbalancer"}.

Redirect Configuration

When a dedicated load balancer is enabled on a GVC, you can specify URLs to redirect users for different HTTP status codes.

spec:
  loadBalancer:
    dedicated: true
    redirect:
      class:
        status5xx: https://redirect.example.com
        status401: https://your-oauth-server/oauth2/authorize?return_to=%REQ(:path)%&client_id=your-client-id

Redirect Properties

class.status5xx: Specify the redirect URL for any 500 level status code. Must be a valid URI.
class.status401: An optional URL redirect for 401 responses. Supports Envoy format strings to include request information (e.g., %REQ(:path)%).

Dedicated IP Address

You can set up an IpSet to be used with a dedicated load balancer. This will attach the ip address to the load balancer, so it remains known and static.

spec:
  loadBalancer:
    dedicated: true
    ipSet: //ipset/example

The IpSet must be configured to be used with the gvc load balancer

Endpoint Naming Format

Workload canonical endpoints in this GVC can be prefixed with the org endpoint prefix. This adds the prefix as a subdomain to cpln.app. To configure which endpoint prefix to use, set the endpointNamingFormat field:

spec:
  endpointNamingFormat: org # can be "org" or "default"

Canonical Endpoint Formatting

default: {workloadName}-{gvcAlias}.cpln.app
org: {workloadName}-{gvcAlias}.{orgEndpointPrefix}.cpln.app

Tracing

OpenTelemetry traces are supported and can be configured with the native Control Plane tracing provider or sent to an OpenTelemetry collector endpoint by using the OpenTelemetry tracing provider.

Control Plane Tracing Provider

The Control Plane tracing provider is the default method for collecting OpenTelemetry traces. They will be accessible for exploration using Grafana by accessing the Traces link from any workload in the Console. To enable traces using the Console, navigate to your GVC, click on Tracing, and choose Control Plane as the metric provider. Then, configure the sampling percentage and, optionally, the Custom Tags. When using the Control Plane tracing provider, workloads can forward additional Open Telemetry traces to the following endpoints: GRPC: tracing.controlplane:80 HTTP: tracing.controlplane:4318 For each of these endpoints, mutual tls is added automatically for requests and any clients/libraries should be configured to send requests using plain text. Here is an example of a GVC with tracing enabled for 10 percent of requests to be forwarded to the Control Plane tracing provider. Additionally, the tag team=profile will also be added to each trace.

YAML

kind: gvc
name: online-boutique
spec:
...
  tracing:
    provider:
      controlPlane: {}
    customTags: {
      team: profile
    }
    sampling: 10

OpenTelemetry Tracing Provider

Similarly, traces can be sent to an OTEL collector endpoint using the OpenTelemetry tracing provider. For details, see the Online Boutique example.

Pull Secrets

Pull secrets are secrets that are assigned to a GVC and used by workloads when authentication is required when pulling an image from a private registry. Only Docker, Amazon ECR, and GCP secrets types are supported for pull secrets.

If the image was pushed to the Control Plane registry for the same Org, no pull secret is required when a workload pulls from the image from the same Org.

Multiple pull secrets can be assigned to a GVC. A workload’s container will use the appropriate secret when pulling the image from a private registry. If there are multiple secrets, the container will cycle through each one. If authentication fails, the deployment will not be updated and the image pull will have an exponential backoff retry starting at 10 seconds and ending at 5 minutes (e.g., 10 seconds, 20 seconds, 40 seconds, etc.).

Environment Variables

You may set environment variables at the GVC level, which can then be inherited by any of the GVC’s workloads. To inherit GVC environment variables, a container must have its inheritEnv property set to true. For more information about how environment variables work in Control Plane, please see the environment variables section of the workload reference page.

Sticky Sessions

Add the following tags and desired values to a GVC to enable sticky sessions for ALL Workloads within the GVC:

cpln/sessionCookie
- The name of the session cookie.
cpln/sessionDuration
- The Golang duration for the maximum session length (e.g., 300s, 30m, etc.).
- Review this link for the proper Golang duration string format.

Once these tags are set, soft session affinity based on a cookie will consistently route requests to the same replica. The affinity to a particular replica will be lost if the replica restarts.

How to add Tags using the UI

Browse to the Console UI and select the desired GVC.
Click the Tags link in the middle context menu.
Click Edit Tags.
Enter the string cpln/sessionCookie in the Tag Key text box and enter the desired cookie name in the Tag Value text box. Click Add Tag.
Enter the string cpln/sessionDuration in the Tag Key text box and enter the desired duration in the Tag Value text box. Click Add Tag.
Click Save.

How to add Tags using the CLI

Execute the following CLI command (substitute the GVC_NAME, ORG_NAME, COOKIE_NAME, DURATION tokens) to add the requires Tags to a GVC:

cpln gvc tag GVC_NAME --tag cpln/sessionCookie=COOKIE_NAME --tag cpln/sessionDuration=DURATION --org ORG_NAME

Keda

In order to use Keda to scale workloads, you must first enable it on the GVC. If the keda deployment requires network or cloud resources, you must attach a valid identity on the keda configuration here.

spec:
  keda:
    enabled: true
    identityLink: //identity/keda-identity # optional
    secrets: # optional
      - //secret/keda-secret-1
      - //secret/keda-secret-2

Keda Configuration

enabled: Enable KEDA for this GVC. KEDA is a Kubernetes-based event-driven autoscaler that allows you to scale workloads based on external events. When enabled, a keda operator will be deployed in the GVC and workloads in the GVC can use KEDA to scale based on external metrics.
identityLink: A link to an Identity resource that will be used for KEDA. This will allow the keda operator to access cloud and network resources.
secrets: A list of secrets to be used as TriggerAuthentication objects. The TriggerAuthentication object will be named after the secret and can be used by triggers on workloads in this GVC.

Export GVC

Using the console UI, when a GVC is selected, an Export GVC link is available which will save (as a local multi-document YAML manifest file) the GVC and all associated resources (Identities, Volume Sets and Workloads). Links to other resources are relative within the exported file. This allows the file to be easily used to backup and restore an entire GVC. It can also be used when promoting to other Orgs. The export doesn’t contain any referenced Org resources, such as, Secrets, Cloud Accounts, and Agents. These resources would need to be exported separately.

Permissions

The permissions below are used to define policies together with one or more of the four principal types:

Permission	Description	Implies
create	Create new gvcs
delete	Delete existing gvcs
edit	Modify existing gvcs	view
manage	Full access	create, delete, edit, manage, view
view	Read-only access

Access Report

Displays the permissions granted to principals for the GVC.

CLI

To view the CLI documentation for GVCs, click here.

Quickstart

Concepts

Guides

External Logging

Kubernetes (Managed)

CPLN Platform (BYOK)

Terraform Provider

Pulumi Provider

Kubernetes Operator

Reference

GVC (Global Virtual Cloud)

Overview

Create a GVC

GVC Configuration Example

Switching between GVCs

GVC Namespace

GVC Locations

Load Balancer Configuration

Dedicated Load Balancer

Load Balancer Properties

Load Balancer Access Logs

Redirect Configuration

Redirect Properties

Dedicated IP Address

Endpoint Naming Format

Canonical Endpoint Formatting

Tracing

Control Plane Tracing Provider

OpenTelemetry Tracing Provider

Pull Secrets

Environment Variables

Sticky Sessions

How to add Tags using the UI

How to add Tags using the CLI

Keda

Keda Configuration

Export GVC

Permissions

Access Report

CLI

Quickstart

Concepts

Guides

External Logging

Kubernetes (Managed)

CPLN Platform (BYOK)

Terraform Provider

Pulumi Provider

Kubernetes Operator

Reference

​Overview

​Create a GVC

​GVC Configuration Example

​Switching between GVCs

​GVC Namespace

​GVC Locations

​Load Balancer Configuration

​Dedicated Load Balancer

​Load Balancer Properties

​Load Balancer Access Logs

​Redirect Configuration

​Redirect Properties

​Dedicated IP Address

​Endpoint Naming Format

​Canonical Endpoint Formatting

​Tracing

​Control Plane Tracing Provider

​OpenTelemetry Tracing Provider

​Pull Secrets

​Environment Variables

​Sticky Sessions

​How to add Tags using the UI

​How to add Tags using the CLI

​Keda

​Keda Configuration

​Export GVC

​Permissions

​Access Report

​CLI

Overview

Create a GVC

GVC Configuration Example

Switching between GVCs

GVC Namespace

GVC Locations

Load Balancer Configuration

Dedicated Load Balancer

Load Balancer Properties

Load Balancer Access Logs

Redirect Configuration

Redirect Properties

Dedicated IP Address

Endpoint Naming Format

Canonical Endpoint Formatting

Tracing

Control Plane Tracing Provider

OpenTelemetry Tracing Provider

Pull Secrets

Environment Variables

Sticky Sessions

How to add Tags using the UI

How to add Tags using the CLI

Keda

Keda Configuration

Export GVC

Permissions

Access Report

CLI