1. Deploy your first workload

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.

The workload web is created in the GVC quickstart-gvc, and the GVC spans two locations, aws-us-west-2 on AWS and gcp-us-east1 on Google Cloud. One workload, created once, running in two clouds behind one endpoint.

Console
CLI
Terraform
Pulumi
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.

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.

Open the Create GVC form

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

Name the GVC

Enter quickstart-gvc as the name.

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.

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.

Navigate to Workloads

Click Workloads in the left menu, then click New.

Configure basic settings

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

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.

Make the workload public

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

Create the workload

Click Create. The workload summary page opens.

Step 4: Open the welcome page

Wait for deployment

The workload health shows Ready once the first deployment completes.

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.

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.

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
Homebrew
Binary

npm install -g @controlplane/cli

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

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

Confirm the installation:

cpln --version

The CLI version number prints.

Step 2: Authenticate

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

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
Service Account Token

With the Control Plane CLI installed, log in:

cpln login

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

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

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.

Create a key

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

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
Service Account Token

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

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

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.

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
Service Account Token

With the Control Plane CLI installed, log in:

cpln login

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

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

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.

Create a key

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

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
Python
Go
C#

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
pnpm
yarn
bun

npm install @pulumiverse/cpln

pnpm add @pulumiverse/cpln

yarn add @pulumiverse/cpln

bun add @pulumiverse/cpln

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
poetry
uv

source venv/bin/activate
pip install pulumiverse-cpln

poetry add pulumiverse-cpln

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

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

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
Service Account Token

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

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
Python
Go
C#

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
);

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
))

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
	})
}

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.

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
CLI
Terraform
Pulumi
AI Agent

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

cpln gvc delete quickstart-gvc

terraform destroy

pulumi destroy

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.

​Overview

​Prerequisites

​Step 1: Log in to the Console

​Step 2: Create a GVC

​Step 3: Create a workload

​Step 4: Open the welcome page

​Prerequisites

​Step 1: Install the CLI

Download the binary

​Step 2: Authenticate

​Step 3: Create a GVC

​Step 4: Create the workload

​Step 5: Open the welcome page

​Prerequisites

​Step 1: Authenticate

​Step 2: Configure the provider

​Step 3: Define the GVC

​Step 4: Define the workload

​Step 5: Deploy

​Step 6: Open the welcome page

​Prerequisites

​Step 1: Authenticate

​Step 2: Create a new project

​Step 3: Configure the provider

​Step 4: Define the infrastructure

​Step 5: Deploy

​Step 6: Open the welcome page

​Prerequisites

​Step 1: Connect your AI agent

MCP Server

AI Plugin

​Step 2: Set the org

​Step 3: Create a GVC

​Step 4: Create the workload

​Step 5: Open the welcome page

​Verify

​What you’ve learned

​Next steps

2. Deploy your own application

​Clean up

Overview

Prerequisites

Step 1: Log in to the Console

Step 2: Create a GVC

Step 3: Create a workload

Step 4: Open the welcome page

Prerequisites

Step 1: Install the CLI

Step 2: Authenticate

Step 3: Create a GVC

Step 4: Create the workload

Step 5: Open the welcome page

Prerequisites

Step 1: Authenticate

Step 2: Configure the provider

Step 3: Define the GVC

Step 4: Define the workload

Step 5: Deploy

Step 6: Open the welcome page

Prerequisites

Step 1: Authenticate

Step 2: Create a new project

Step 3: Configure the provider

Step 4: Define the infrastructure

Step 5: Deploy

Step 6: Open the welcome page

Prerequisites

Step 1: Connect your AI agent

Step 2: Set the org

Step 3: Create a GVC

Step 4: Create the workload

Step 5: Open the welcome page

Verify

What you’ve learned

Next steps

Clean up