1. Deploy Your First Workload

Overview

This quickstart guides you through deploying your first application on Control Plane. You’ll create a Global Virtual Cloud (GVC), deploy a Workload, and access it via a globally load-balanced endpoint. What you’ll accomplish:

Create a GVC spanning multiple cloud providers and locations.
Deploy a sample web application as a workload.
Access your application via a TLS-secured, geo-routed global endpoint.

Console
CLI
Terraform
Pulumi

Prerequisites

Sign up for Control Plane and create a billing account.
An existing org, or permission to create an org.

Step 1: Log in to the Console

Navigate to console.cpln.io.
Select your SSO provider and authenticate.
You’ll be directed to your organization’s dashboard.

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.

Configure the GVC name

Enter a name for your GVC (e.g., quickstart-gvc).

Select locations

Click Locations, then click Add Location. Choose the locations where your workload will be deployed. For this quickstart, select:

aws-us-west-2
gcp-us-east1

This deploys your application across both AWS and GCP. Click OK.

Create the GVC

Click Create. The GVC summary page will be displayed.

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 a name (e.g., hello-world). Ensure the GVC dropdown under the description field has quickstart-gvc selected.

Configure the container

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

gcr.io/knative-samples/helloworld-go

Under Ports, ensure there is a port configured with:

Protocol: http
Number: 8080

Make the workload public

Click Firewall, then click the Make Public button at the top to allow external access.

Create the workload

Click Create. The workload summary page opens.

Step 4: Access Your Application

Wait for deployment

After 1-2 minutes, the workload health will show Ready.

Open the canonical endpoint

In the summary, under Endpoints, click the link next to Canonical Endpoint. Your application opens in a new window, served from the location nearest to you.

View individual deployments

Click Deployments in the left pane to see each location’s endpoint. Click Open next to any location to access that specific deployment.

Prerequisites

Sign up for Control Plane and create a billing account.
An existing org, or permission to create an org.

Step 1: Install the CLI

Choose your preferred installation method:

npm
Homebrew
Binary

npm install -g @controlplane/cli

Requires Node.js version 16+.

For other installation options, see Installation.

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

For other installation options, see Installation.

Step 2: Verify the Installation

Confirm the CLI is installed and accessible:

cpln --version

You should see the CLI version number.

Step 3: Authenticate

cpln login

This opens your browser for authentication. After successful login, you can close the browser.Set your default organization:

cpln profile update default --org YOUR_ORG_NAME

Step 4: 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 5: Create and deploy a workload

Create a public workload with the sample application:

cpln workload create --name hello-world \
  --image gcr.io/knative-samples/helloworld-go \
  --port 8080 \
  --public

Step 6: Access Your Application

Wait for the workload to become ready:

cpln workload get hello-world

Once the READY column shows true, open the application:

cpln workload open hello-world

You can also view the workload’s global endpoint URL in the output of cpln workload get.

View Deployment Status

Check deployments across all locations:

cpln workload get-deployments hello-world

Prerequisites

Sign up for Control Plane and create a billing account.
An existing org, or permission to create an org.
Terraform installed.

Step 1: Authenticate

The Terraform provider needs credentials to interact with Control Plane. Choose one of the following methods:

CLI Profile
Service Account Token

If you have the Control Plane CLI installed, log in first:

cpln login

This creates a profile named default with your credentials. You’ll reference this profile in the provider configuration.

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

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.
Click Keys, add a description, and click Add.
Copy the generated key. It won’t be shown again.

Set the token as an environment variable:

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     = "YOUR_ORG_NAME"
  profile = "default"
}

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

provider "cpln" {
  org = "YOUR_ORG_NAME"
  # Token is read from CPLN_TOKEN environment variable
}

Initialize Terraform:

terraform init

For more authentication options, see 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" "hello-world" {
  gvc  = cpln_gvc.quickstart.name
  name = "hello-world"
  type = "standard"

  container {
    name   = "helloworld-go"
    image  = "gcr.io/knative-samples/helloworld-go"
    cpu    = "50m"
    memory = "128Mi"

    ports {
      number   = 8080
      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.hello-world.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 is displayed.

Step 6: Access Your Application

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

terraform output

View the full list of workload configuration options in the Terraform Registry documentation.

Prerequisites

Sign up for Control Plane and create a billing account.
An existing org, or permission to create an org.
Pulumi CLI installed.

Step 1: Authenticate

The Pulumi provider needs credentials to interact with Control Plane. Choose one of the following methods:

CLI Profile
Service Account Token

If you have the Control Plane CLI installed, log in first:

cpln login

This creates a profile named default with your credentials.

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

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.
Click Keys, add a description, and click Add.
Copy the generated key. It won’t be shown again.

Set the token as an environment variable:

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 1.0.0

Step 3: Configure the Provider

Set your organization and authentication method:

CLI Profile
Service Account Token

pulumi config set cpln:org YOUR_ORG_NAME
pulumi config set cpln:profile default

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

Or paste the token directly:

pulumi config set cpln:org YOUR_ORG_NAME
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 a Workload
const workload = new cpln.Workload("hello-world", {
  gvc: gvc.name,
  name: "hello-world",
  type: "standard",
  containers: [
    {
      name: "helloworld-go",
      image: "gcr.io/knative-samples/helloworld-go",
      cpu: "50m",
      memory: "128Mi",
      ports: [
        {
          number: 8080,
          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 = workload.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 a Workload
workload = cpln.Workload("hello-world",
    gvc=gvc.name,
    name="hello-world",
    type="standard",
    containers=[cpln.WorkloadContainerArgs(
        name="helloworld-go",
        image="gcr.io/knative-samples/helloworld-go",
        cpu="50m",
        memory="128Mi",
        ports=[cpln.WorkloadContainerPortArgs(
            number=8080,
            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", workload.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 a Workload
		workload, err := cpln.NewWorkload(ctx, "hello-world", &cpln.WorkloadArgs{
			Gvc:  gvc.Name,
			Name: pulumi.String("hello-world"),
			Type: pulumi.String("standard"),
			Containers: cpln.WorkloadContainerArray{
				&cpln.WorkloadContainerArgs{
					Name:   pulumi.String("helloworld-go"),
					Image:  pulumi.String("gcr.io/knative-samples/helloworld-go"),
					Cpu:    pulumi.String("50m"),
					Memory: pulumi.String("128Mi"),
					Ports: cpln.WorkloadContainerPortArray{
						&cpln.WorkloadContainerPortArgs{
							Number:   pulumi.Int(8080),
							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", workload.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 a Workload
    var workload = new Workload("hello-world", new WorkloadArgs
    {
        Gvc = gvc.Name,
        Name = "hello-world",
        Type = "standard",
        Containers = new[]
        {
            new WorkloadContainerArgs
            {
                Name = "helloworld-go",
                Image = "gcr.io/knative-samples/helloworld-go",
                Cpu = "50m",
                Memory = "128Mi",
                Ports = new[]
                {
                    new WorkloadContainerPortArgs
                    {
                        Number = 8080,
                        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"] = workload.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 is displayed.

Step 6: Access Your Application

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

pulumi stack output

If the canonical endpoint doesn’t appear, run pulumi up again to refresh the state.

View the full list of resources in the Pulumi Registry documentation.

What You Deployed

Your application is now:

Globally distributed across AWS and GCP.
Automatically load balanced with geo-routing to the nearest healthy location.
TLS secured with automatic certificate management.
Running in each selected location with one replica per location.

Hello World!

Provider: aws
Location: /org/YOUR_ORG/location/aws-us-west-2

Continue

2. Deploy Your Own Application

Build and deploy your own containerized application to Control Plane.

Want your AI assistant to do the next deploy for you?

Install the Control Plane AI Plugin for Claude Code, Codex, or Gemini CLI. It knows the workload types, secret access chain, firewall defaults, and deploy waits — so you can describe what you want instead of writing manifests.

Clean Up

If you want to stop here instead, delete the resources created in this quickstart:

Console UI
CLI
Terraform
Pulumi

Navigate to your GVC and click Delete from the Actions pulldown menu. This removes the GVC and all associated workloads.

cpln gvc delete quickstart-gvc

terraform destroy

pulumi destroy

Documentation Index

​Overview

​Prerequisites

​Step 1: Log in to the Console

​Step 2: Create a GVC

​Step 3: Create a Workload

​Step 4: Access Your Application

​Prerequisites

​Step 1: Install the CLI

​Step 2: Verify the Installation

​Step 3: Authenticate

​Step 4: Create a GVC

​Step 5: Create and deploy a workload

​Step 6: Access Your Application

​View Deployment Status

​Prerequisites

​Step 1: Authenticate

​Step 2: Configure the Provider

​Step 3: Define the GVC

​Step 4: Define the workload

​Step 5: Deploy

​Step 6: Access Your Application

​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: Access Your Application

​What You Deployed

​Continue

2. Deploy Your Own Application

Want your AI assistant to do the next deploy for you?

​Clean Up

Overview

Prerequisites

Step 1: Log in to the Console

Step 2: Create a GVC

Step 3: Create a Workload

Step 4: Access Your Application

Prerequisites

Step 1: Install the CLI

Step 2: Verify the Installation

Step 3: Authenticate

Step 4: Create a GVC

Step 5: Create and deploy a workload

Step 6: Access Your Application

View Deployment Status

Prerequisites

Step 1: Authenticate

Step 2: Configure the Provider

Step 3: Define the GVC

Step 4: Define the workload

Step 5: Deploy

Step 6: Access Your Application

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: Access Your Application

What You Deployed

Continue

Clean Up