1. Deploy your first workload

Create a GVC, deploy the official NGINX image as a workload across two cloud providers, and open it on a globally load-balanced TLS endpoint.

Overview

Everything on Control Plane starts with a Global Virtual Cloud (GVC), the set of locations your applications run in, and a workload, one application that Control Plane runs in every one of those locations. This part creates a GVC that spans an AWS region and a GCP region, and one workload that runs in both, with a replica in each location. The workload’s endpoint terminates TLS, sends each request to the nearest healthy location, and routes around a location that fails, so one workload definition gives you a multi-cloud deployment that survives the loss of a region or a provider.

What you’ll build:

• A GVC spanning AWS and GCP locations.
• A public workload serving the NGINX welcome page from both locations.
• A TLS-secured global endpoint that routes each request to the nearest healthy location.

Console

Prerequisites

• An org to deploy into. If you don’t have one yet, sign up for Control Plane: the Console walks you through creating a billing account and your first org.

Step 1: Log in to the Console

Navigate to console.cpln.io and sign in with your SSO provider. Your organization’s dashboard opens.

Step 2: Create a GVC

A GVC defines where your workloads run across cloud providers and regions.

1. Open the Create GVC form

   Click the Create dropdown in the upper right corner and select GVC.

2. Name the GVC

   Enter quickstart-gvc as the name.

3. Select locations

   Click Locations, then click Add Location. Select aws-us-west-2 and gcp-us-east1 to deploy across both AWS and GCP, then click OK.

4. Create the GVC

   Click Create. When the Console asks Set as Current Context?, click Yes, Set Context to browse this GVC’s workloads, identities, and volume sets from the sidebar.

Step 3: Create a workload

A workload is your application running on Control Plane.

1. Navigate to Workloads

   Click Workloads in the left menu, then click New.

2. Configure basic settings

   Enter web as the name and confirm the GVC dropdown under the description field shows quickstart-gvc.

3. Configure the container

   Click Containers. For the image source, select External, then enter:

   nginx:alpine
   

   Under Ports, set the number to 80 and keep the protocol http.

4. Make the workload public

   Click Firewall, then click Make Public to allow external access.

5. Create the workload

   Click Create. The workload summary page opens.

Step 4: Open the welcome page

1. Wait for deployment

   The workload health shows Ready once the first deployment completes.

2. Open the canonical endpoint

   In the summary, under Endpoints, click the link next to Canonical Endpoint (Global). The NGINX welcome page opens in a new window, served from the location nearest to you.

3. View individual deployments

   Click Deployments in the left pane. Each location lists its own endpoint; click the link icon next to it to open that specific deployment.

CLI

Prerequisites

• An org to deploy into. If you don’t have one yet, sign up for Control Plane: the Console walks you through creating a billing account and your first org.

Step 1: Install the CLI

npm

npm install -g @controlplane/cli

Requires Node.js version 18 or later (an active LTS release is recommended).

Homebrew

brew tap controlplane-com/cpln && brew install cpln

Binary

Download the binary

Pick your platform on the installation page.

Confirm the installation:

cpln --version

The CLI version number prints.

Step 2: Authenticate

Log in to Control Plane:

cpln login

The CLI prints a login URL and a six-digit confirmation code, then waits. Open the URL in a browser on any device, sign in, and enter the code. After the CLI confirms the login, set your default org (replace my-org with your org name):

cpln profile update default --org my-org

Step 3: Create a GVC

Create a GVC with locations in AWS and GCP:

cpln gvc create --name quickstart-gvc \
  --location aws-us-west-2 \
  --location gcp-us-east1

Set it as your default GVC:

cpln profile update default --gvc quickstart-gvc

Step 4: Create the workload

Create a public workload running the official NGINX image:

cpln workload create --name web \
  --image nginx:alpine \
  --port 80 \
  --public

Step 5: Open the welcome page

Wait for the workload to become ready:

cpln workload get web

When the READY column shows true, open the welcome page in your browser:

cpln workload open web

The output of cpln workload get also shows the workload’s global endpoint URL.

Check the deployment in each location:

cpln workload get-deployments web

Terraform

Prerequisites

• An org to deploy into. If you don’t have one yet, sign up for Control Plane: the Console walks you through creating a billing account and your first org.

• Terraform installed.

Step 1: Authenticate

The provider needs credentials for Control Plane. Choose one of the following methods:

CLI Profile

With the Control Plane CLI installed, log in:

cpln login

This creates a profile named default with your credentials, which the provider configuration references.

Service Account Token

For CI/CD pipelines or environments without the CLI, create a service account token:

1. Create the service account

   In the Console, click Service Accounts in the left menu, then New. Enter a name, select superusers from the Assign to Group dropdown, and click Create.

2. Create a key

   Click Keys, add a description, and click Add. Copy the generated key; it is not shown again.

3. Export the token

   export CPLN_TOKEN=your-service-account-key
   

Step 2: Configure the provider

Create a new directory and add main.tf with the provider configuration:

CLI Profile

terraform {
  required_providers {
    cpln = {
      source = "controlplane-com/cpln"
    }
  }
}

provider "cpln" {
  org     = "my-org"
  profile = "default"
}

Service Account Token

terraform {
  required_providers {
    cpln = {
      source = "controlplane-com/cpln"
    }
  }
}

provider "cpln" {
  org = "my-org"
  # Token is read from the CPLN_TOKEN environment variable
}

Replace my-org with your org name, then initialize Terraform:

terraform init

More authentication options: Terraform provider.

Step 3: Define the GVC

Add the GVC resource to main.tf:

resource "cpln_gvc" "quickstart" {
  name        = "quickstart-gvc"
  description = "Quickstart GVC"

  locations = [
    "aws-us-west-2",
    "gcp-us-east1"
  ]
}

Step 4: Define the workload

Add the workload resource to main.tf:

resource "cpln_workload" "web" {
  gvc  = cpln_gvc.quickstart.name
  name = "web"
  type = "standard"

  container {
    name   = "web"
    image  = "nginx:alpine"
    cpu    = "50m"
    memory = "128Mi"

    ports {
      number   = 80
      protocol = "http"
    }
  }

  options {
    capacity_ai     = true
    timeout_seconds = 5

    autoscaling {
      metric      = "disabled"
      target      = 95
      min_scale   = 1
      max_scale   = 1
    }
  }

  firewall_spec {
    external {
      inbound_allow_cidr = ["0.0.0.0/0"]
    }
  }
}

output "canonical_endpoint" {
  value = cpln_workload.web.status[0].canonical_endpoint
}

Step 5: Deploy

Review the plan:

terraform plan

Apply the configuration:

terraform apply

Type yes when prompted. After deployment completes, the canonical endpoint URL prints.

Step 6: Open the welcome page

Open the canonical endpoint URL in your browser. To print it again:

terraform output

The Terraform Registry documentation lists every workload option.

Pulumi

Prerequisites

• An org to deploy into. If you don’t have one yet, sign up for Control Plane: the Console walks you through creating a billing account and your first org.

• Pulumi CLI installed.

Step 1: Authenticate

The provider needs credentials for Control Plane. Choose one of the following methods:

CLI Profile

With the Control Plane CLI installed, log in:

cpln login

This creates a profile named default with your credentials, which the provider configuration references.

Service Account Token

For CI/CD pipelines or environments without the CLI, create a service account token:

1. Create the service account

   In the Console, click Service Accounts in the left menu, then New. Enter a name, select superusers from the Assign to Group dropdown, and click Create.

2. Create a key

   Click Keys, add a description, and click Add. Copy the generated key; it is not shown again.

3. Export the token

   export CPLN_TOKEN=your-service-account-key
   

Step 2: Create a new project

Create a new directory and initialize a Pulumi project:

TypeScript

mkdir cpln-quickstart && cd cpln-quickstart
pulumi new typescript

Follow the prompts in the terminal to complete project setup. Then install the Control Plane provider:

npm

npm install @pulumiverse/cpln

pnpm

pnpm add @pulumiverse/cpln

yarn

yarn add @pulumiverse/cpln

bun

bun add @pulumiverse/cpln

Python

mkdir cpln-quickstart && cd cpln-quickstart
pulumi new python

Follow the prompts in the terminal to complete project setup. Activate the virtual environment and install the Control Plane provider:

pip

source venv/bin/activate
pip install pulumiverse-cpln

poetry

poetry add pulumiverse-cpln

uv

source .venv/bin/activate
uv add pulumiverse-cpln

Go

mkdir cpln-quickstart && cd cpln-quickstart
pulumi new go

Follow the prompts in the terminal to complete project setup. Then install the Control Plane provider:

go get github.com/pulumiverse/pulumi-cpln/sdk/go/cpln

C#

mkdir cpln-quickstart && cd cpln-quickstart
pulumi new csharp

Follow the prompts in the terminal to complete project setup. Then install the Control Plane provider:

dotnet add package Pulumiverse.Cpln --version 0.0.89

Step 3: Configure the provider

Set your org (replace my-org with your org name) and authentication method:

CLI Profile

pulumi config set cpln:org my-org
pulumi config set cpln:profile default

Service Account Token

pulumi config set cpln:org my-org
pulumi config set --secret cpln:token $CPLN_TOKEN

Or paste the token directly:

pulumi config set cpln:org my-org
pulumi config set --secret cpln:token your-service-account-key

Step 4: Define the infrastructure

TypeScript

Replace index.ts with:

import * as cpln from "@pulumiverse/cpln";

// Create a GVC
const gvc = new cpln.Gvc("quickstart-gvc", {
  name: "quickstart-gvc",
  description: "Quickstart GVC",
  locations: ["aws-us-west-2", "gcp-us-east1"],
});

// Create the workload
const web = new cpln.Workload("web", {
  gvc: gvc.name,
  name: "web",
  type: "standard",
  containers: [
    {
      name: "web",
      image: "nginx:alpine",
      cpu: "50m",
      memory: "128Mi",
      ports: [
        {
          number: 80,
          protocol: "http",
        },
      ],
    },
  ],
  options: {
    capacityAi: true,
    timeoutSeconds: 5,
    autoscaling: {
      metric: "disabled",
      target: 95,
      minScale: 1,
      maxScale: 1,
    },
  },
  firewallSpec: {
    external: {
      inboundAllowCidrs: ["0.0.0.0/0"],
    },
  },
});

// Export the canonical endpoint
export const canonical_endpoint = web.statuses.apply(
  (s) => s?.[0]?.canonicalEndpoint
);

Python

Replace __main__.py with:

import pulumiverse_cpln as cpln
import pulumi

# Create a GVC
gvc = cpln.Gvc("quickstart-gvc",
    name="quickstart-gvc",
    description="Quickstart GVC",
    locations=["aws-us-west-2", "gcp-us-east1"])

# Create the workload
web = cpln.Workload("web",
    gvc=gvc.name,
    name="web",
    type="standard",
    containers=[cpln.WorkloadContainerArgs(
        name="web",
        image="nginx:alpine",
        cpu="50m",
        memory="128Mi",
        ports=[cpln.WorkloadContainerPortArgs(
            number=80,
            protocol="http",
        )],
    )],
    options=cpln.WorkloadOptionsArgs(
        capacity_ai=True,
        timeout_seconds=5,
        autoscaling=cpln.WorkloadOptionsAutoscalingArgs(
            metric="disabled",
            target=95,
            min_scale=1,
            max_scale=1,
        ),
    ),
    firewall_spec=cpln.WorkloadFirewallSpecArgs(
        external=cpln.WorkloadFirewallSpecExternalArgs(
            inbound_allow_cidrs=["0.0.0.0/0"],
        ),
    ))

# Export the canonical endpoint
pulumi.export("canonical_endpoint", web.statuses.apply(
    lambda s: s[0].canonical_endpoint if s else None
))

Go

Replace main.go with:

package main

import (
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
	"github.com/pulumiverse/pulumi-cpln/sdk/go/cpln"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		// Create a GVC
		gvc, err := cpln.NewGvc(ctx, "quickstart-gvc", &cpln.GvcArgs{
			Name:        pulumi.String("quickstart-gvc"),
			Description: pulumi.String("Quickstart GVC"),
			Locations: pulumi.StringArray{
				pulumi.String("aws-us-west-2"),
				pulumi.String("gcp-us-east1"),
			},
		})
		if err != nil {
			return err
		}

		// Create the workload
		web, err := cpln.NewWorkload(ctx, "web", &cpln.WorkloadArgs{
			Gvc:  gvc.Name,
			Name: pulumi.String("web"),
			Type: pulumi.String("standard"),
			Containers: cpln.WorkloadContainerArray{
				&cpln.WorkloadContainerArgs{
					Name:   pulumi.String("web"),
					Image:  pulumi.String("nginx:alpine"),
					Cpu:    pulumi.String("50m"),
					Memory: pulumi.String("128Mi"),
					Ports: cpln.WorkloadContainerPortArray{
						&cpln.WorkloadContainerPortArgs{
							Number:   pulumi.Int(80),
							Protocol: pulumi.String("http"),
						},
					},
				},
			},
			Options: &cpln.WorkloadOptionsArgs{
				CapacityAi:     pulumi.Bool(true),
				TimeoutSeconds: pulumi.Int(5),
				Autoscaling: &cpln.WorkloadOptionsAutoscalingArgs{
					Metric:   pulumi.String("disabled"),
					Target:   pulumi.Int(95),
					MinScale: pulumi.Int(1),
					MaxScale: pulumi.Int(1),
				},
			},
			FirewallSpec: &cpln.WorkloadFirewallSpecArgs{
				External: &cpln.WorkloadFirewallSpecExternalArgs{
					InboundAllowCidrs: pulumi.StringArray{pulumi.String("0.0.0.0/0")},
				},
			},
		})
		if err != nil {
			return err
		}

		// Export the canonical endpoint
		ctx.Export("canonical_endpoint", web.Statuses.Index(pulumi.Int(0)).CanonicalEndpoint())
		return nil
	})
}

C#

Replace Program.cs with:

using Pulumi;
using Pulumiverse.Cpln;
using Pulumiverse.Cpln.Inputs;
using System.Collections.Generic;

return await Deployment.RunAsync(() =>
{
    // Create a GVC
    var gvc = new Gvc("quickstart-gvc", new GvcArgs
    {
        Name = "quickstart-gvc",
        Description = "Quickstart GVC",
        Locations = new[] { "aws-us-west-2", "gcp-us-east1" }
    });

    // Create the workload
    var web = new Workload("web", new WorkloadArgs
    {
        Gvc = gvc.Name,
        Name = "web",
        Type = "standard",
        Containers = new[]
        {
            new WorkloadContainerArgs
            {
                Name = "web",
                Image = "nginx:alpine",
                Cpu = "50m",
                Memory = "128Mi",
                Ports = new[]
                {
                    new WorkloadContainerPortArgs
                    {
                        Number = 80,
                        Protocol = "http"
                    }
                }
            }
        },
        Options = new WorkloadOptionsArgs
        {
            CapacityAi = true,
            TimeoutSeconds = 5,
            Autoscaling = new WorkloadOptionsAutoscalingArgs
            {
                Metric = "disabled",
                Target = 95,
                MinScale = 1,
                MaxScale = 1
            }
        },
        FirewallSpec = new WorkloadFirewallSpecArgs
        {
            External = new WorkloadFirewallSpecExternalArgs
            {
                InboundAllowCidrs = new[] { "0.0.0.0/0" }
            }
        }
    });

    // Export the canonical endpoint
    return new Dictionary<string, object?>
    {
        ["canonical_endpoint"] = web.Statuses.Apply(s => s[0].CanonicalEndpoint)
    };
});

Step 5: Deploy

Preview the changes:

pulumi preview

Deploy the infrastructure:

pulumi up

Select yes when prompted. After deployment, the canonical endpoint URL prints, unless Control Plane had not published it yet; step 6 covers that case.

Step 6: Open the welcome page

Open the canonical endpoint URL in your browser. To print it again:

pulumi stack output

If the canonical endpoint doesn’t appear, the workload was created before Control Plane published it. Run pulumi refresh to read the current status, then pulumi up to re-evaluate the output. A second pulumi up on its own finds nothing to change and leaves the output empty.

The Pulumi Registry documentation lists every resource the provider supports.

AI Agent

Prerequisites

• An org to deploy into. If you don’t have one yet, sign up for Control Plane: the Console walks you through creating a billing account and your first org.

• An AI agent that supports MCP servers, whether a chat app such as Claude Desktop, an IDE such as Cursor, or a terminal agent such as Claude Code. Every compatible tool has a setup page.

Step 1: Connect your AI agent

Your AI agent operates Control Plane through the MCP server, whether it runs in a chat app, an IDE, or a terminal. Pick the path for your tool:

MCP Server

Works with every MCP client, such as Claude Desktop, Claude Web, Cursor, VS Code, Antigravity IDE, Amp, or OpenCode. Point it at the endpoint and sign in.

AI Plugin

If your tool is Claude Code, Codex, or Antigravity CLI, install the plugin instead. It bundles the MCP server and adds Control Plane skills, agents, slash commands, and guardrails.

Your tool opens Control Plane in the browser: sign in, pick the orgs the agent may access, including the org you deploy into, and click Authorize. Then continue with Step 2.

Step 2: Set the org

Every prompt below runs in the same conversation, so name your org once (replace my-org with your org name):

Use org "my-org" for this conversation and list its GVCs.

The agent lists the org’s GVCs, or reports that there are none yet. If it answers that it has no Control Plane tools or is not signed in, finish the setup page for your tool first.

Step 3: Create a GVC

Create a GVC called "quickstart-gvc" with the locations
aws-us-west-2 and gcp-us-east1.

The agent creates the GVC and confirms its two locations.

Step 4: Create the workload

Create a public workload called "web" in that GVC from the
image nginx:alpine on port 80, with one replica per location
and the container named "web". Keep everything else at its
default.

The agent creates the workload, follows its deployments until both locations report ready, and reports the canonical endpoint.

Step 5: Open the welcome page

Ask for the endpoint of each location. The prompt also returns the canonical endpoint, in case the agent stopped before reporting it:

Once it is ready in both locations, give me the endpoint of
each location and its canonical endpoint.

Open the canonical endpoint in your browser. The NGINX welcome page opens, served from the location nearest to you. Then open each location’s endpoint to confirm the workload responds from AWS and from GCP.

Verify

Whichever interface you used: once the workload reports Ready, its canonical endpoint serves the NGINX welcome page:

Welcome to nginx!
If you see this page, the nginx web server is successfully installed and working.

Each location also serves its own endpoint: open both from the Deployments page in the Console (or the cpln workload get-deployments web output) to confirm the workload responds from AWS and GCP.

Your workload runs on AWS and GCP behind one TLS-secured endpoint, geo-routed to the nearest healthy location.

What you’ve learned

• One definition, every location: a workload runs in each location of its GVC, and a location added to the GVC later runs it too.
• Availability by placement: two locations on two providers, with the endpoint routing around an unhealthy one, is what keeps the application reachable when a region or a provider fails.
• The endpoint comes with the workload: TLS termination, the certificate, and geo-routing are part of every public workload.
• Five interfaces, one result: the Console, the CLI, Terraform, Pulumi, and an AI agent create the same GVC and workload.

Next steps

2. Deploy your own application

Build and deploy your own containerized application to Control Plane.

Clean up

To remove everything this part created:

Console

Open quickstart-gvc, click Actions, then Delete. Type the GVC name to confirm and click Delete. Deleting the GVC removes its workloads with it.

CLI

cpln gvc delete quickstart-gvc

Terraform

terraform destroy

Pulumi

pulumi destroy

AI Agent

Delete the GVC "quickstart-gvc".

The agent reads the GVC, tells you that deleting it removes the workload web with it, and asks you to confirm. Your AI tool may also ask you to approve the call. Answer yes, and the GVC and its workload are gone.