3. Service-to-service communication

Overview

The launch page gets its backend. The quickstart API is built from source like the frontend and runs as a workload with no public endpoint. The frontend reaches it the way workloads reach each other on Control Plane, over an internal endpoint the service mesh encrypts with mTLS using certificates it manages for you, and only once the API’s firewall names the frontend as a caller. That is the zero-trust shape a production backend wants, and you will watch the default deny block the first call before you allow it. What you’ll build:

A container image of the quickstart API in your org’s private registry.
An api workload in quickstart-gvc, reachable only over the internal network.
The frontend workload calling api, allowed by api’s internal firewall, with the waitlist open.

Inside the GVC quickstart-gvc, the workload frontend calls the workload api at api.quickstart-gvc.cpln.local:8080 over the internal network, encrypted by the mesh. frontend keeps its public endpoint and api has none, and api admits frontend by name on its internal firewall. Two workloads talk inside the GVC; the API answers only the callers its firewall names.

How internal communication works

Workloads reach each other through internal endpoints of the form:

http://WORKLOAD_NAME.GVC_NAME.cpln.local:PORT

The receiving workload’s internal firewall decides who may connect. A new workload starts with none, so no other workload reaches it, not even one in the same GVC. The API keeps that default until you name frontend on its workload list.

Prerequisites

Completed 2. Deploy your own application with the frontend workload running.
The CLI installed and logged in, as in part 2, to build the API’s image.

Step 1: Download the API

macOS / Linux

Downloads api.tgz, a gzipped tar archive.

Windows

Downloads api.zip, the same source as a zip archive.

Extract the archive and navigate to the directory:

macOS / Linux
Windows PowerShell

tar -xvf api.tgz && cd api

Expand-Archive api.zip && cd api

The API is a Node.js service with three routes, all in src/server.ts:

Route	Answer
`GET /`	The service name, version, location, and which storage is in use
`GET /signups`	The signup count and the ten latest signups, each stamped with the location that stored it
`POST /signups`	Stores an email address

It keeps the signups in memory. Part 4 gives it a database.

Step 2: Build and push the image

With Docker
Without Docker

cpln image build --name api:1.0 --push

cpln image build --name api:1.0 --remote

The command ends by printing the image it pushed, your-org.registry.cpln.io/api:1.0 where your-org is the name of your org, together with its link. Workloads reference it as //image/api:1.0.

Console
CLI
Terraform
Pulumi
AI Agent

Step 3: Create the API workload

Navigate to Workloads

With quickstart-gvc as the current context, click Workloads in the left menu, then click New.

Configure basic settings

Enter api as the name and make sure quickstart-gvc is the selected GVC.

Configure the container

Click Containers in the left pane and keep Control Plane as the image source. In the image dropdown, type api and select api:1.0. Under Ports, keep protocol http and number 8080.

Create it with the firewall closed

Click Create. A new workload has no public endpoint, and under Firewall, Internal, its Inbound Allow Type is None: nothing reaches it yet.

Step 4: Point the frontend at the API

Add the environment variable

Open the frontend workload, click Containers in the left pane, and open the Env Vars tab. Click Add Environment Variable, enter API_URL as the Name, keep Literal Value as the value type, and enter http://api.quickstart-gvc.cpln.local:8080 as the value.

Update

Click Update. The workload rolls out a new version.

Step 5: See the default deny

Wait until frontend reports Ready again, then open its canonical endpoint. The page waits for its call to the API to time out, then reports below the waitlist form: Could not reach the API at http://api.quickstart-gvc.cpln.local:8080: no answer within 3 seconds. The name resolves and the connection is never answered, because api admits no caller yet.

Step 6: Allow the frontend

Open the API's internal firewall

Open the api workload, click Firewall in the left pane, then Internal.

Switch to a workload list

Set Inbound Allow Type to Workload List. Under Inbound Allow List, click Add Workload, select frontend, and confirm.

Update

Click Update.

Step 3: Create the API workload

cpln workload create --name api \
  --image //image/api:1.0 \
  --gvc quickstart-gvc \
  --port 8080

Without --public the workload has no public endpoint, and its internal firewall starts as none: nothing reaches it yet.

Step 4: Point the frontend at the API

cpln workload update frontend --gvc quickstart-gvc \
  --set spec.containers.frontend.env.API_URL.value=http://api.quickstart-gvc.cpln.local:8080

Step 5: See the default deny

Once frontend reports Ready again, open it:

cpln workload open frontend --gvc quickstart-gvc

The page waits for its call to the API to time out, then reports below the waitlist form: Could not reach the API at http://api.quickstart-gvc.cpln.local:8080: no answer within 3 seconds. The name resolves and the connection is never answered, because api admits no caller yet.

Step 6: Allow the frontend

cpln workload update api --gvc quickstart-gvc \
  --set spec.firewallConfig.internal.inboundAllowType=workload-list \
  --set spec.firewallConfig.internal.inboundAllowWorkload=frontend

The CLI expands frontend to the workload’s full link inside the same GVC.

Step 3: Define the API workload

Add to your main.tf. Without an external firewall rule the workload has no public endpoint, and its internal firewall starts as none:

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

  container {
    name   = "api"
    image  = "/org/my-org/image/api:1.0"
    cpu    = "50m"
    memory = "128Mi"

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

  options {
    capacity_ai     = true
    timeout_seconds = 5

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

  firewall_spec {
    internal {
      inbound_allow_type = "none"
    }
  }
}

Replace my-org with your org name; Terraform needs the full image path.

Step 4: Point the frontend at the API

Add the environment variable to the frontend container in cpln_workload.frontend:

    env = {
      API_URL = "http://api.quickstart-gvc.cpln.local:8080"
    }

Apply both changes:

terraform apply

Step 5: See the default deny

Wait until frontend reports Ready again, then open its endpoint from the frontend_endpoint output. The page waits for its call to the API to time out, then reports below the waitlist form: Could not reach the API at http://api.quickstart-gvc.cpln.local:8080: no answer within 3 seconds. The name resolves and the connection is never answered, because api admits no caller yet.

Step 6: Allow the frontend

Name frontend on the API’s workload list in cpln_workload.api:

  firewall_spec {
    internal {
      inbound_allow_type     = "workload-list"
      inbound_allow_workload = [cpln_workload.frontend.self_link]
    }
  }

Apply the change:

terraform apply

Step 3: Define the API workload

Without an external firewall rule the workload has no public endpoint, and its internal firewall starts as none.

TypeScript
Python
Go
C#

Add to your index.ts:

// The quickstart API: internal only
const api = new cpln.Workload("api", {
  gvc: gvc.name,
  name: "api",
  type: "standard",
  containers: [
    {
      name: "api",
      image: "/org/my-org/image/api:1.0",
      cpu: "50m",
      memory: "128Mi",
      ports: [{ protocol: "http", number: 8080 }],
    },
  ],
  options: {
    capacityAi: true,
    timeoutSeconds: 5,
    autoscaling: {
      metric: "disabled",
      target: 95,
      minScale: 1,
      maxScale: 1,
    },
  },
  firewallSpec: {
    internal: {
      inboundAllowType: "none",
    },
  },
});

Add to your __main__.py:

# The quickstart API: internal only
api = cpln.Workload("api",
    gvc=gvc.name,
    name="api",
    type="standard",
    containers=[cpln.WorkloadContainerArgs(
        name="api",
        image="/org/my-org/image/api:1.0",
        cpu="50m",
        memory="128Mi",
        ports=[cpln.WorkloadContainerPortArgs(
            protocol="http",
            number=8080,
        )],
    )],
    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(
        internal=cpln.WorkloadFirewallSpecInternalArgs(
            inbound_allow_type="none",
        ),
    ))

Add inside pulumi.Run in your main.go:

// The quickstart API: internal only
api, err := cpln.NewWorkload(ctx, "api", &cpln.WorkloadArgs{
	Gvc:  gvc.Name,
	Name: pulumi.String("api"),
	Type: pulumi.String("standard"),
	Containers: cpln.WorkloadContainerArray{
		&cpln.WorkloadContainerArgs{
			Name:   pulumi.String("api"),
			Image:  pulumi.String("/org/my-org/image/api:1.0"),
			Cpu:    pulumi.String("50m"),
			Memory: pulumi.String("128Mi"),
			Ports: cpln.WorkloadContainerPortArray{
				&cpln.WorkloadContainerPortArgs{
					Protocol: pulumi.String("http"),
					Number:   pulumi.Int(8080),
				},
			},
		},
	},
	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{
		Internal: &cpln.WorkloadFirewallSpecInternalArgs{
			InboundAllowType: pulumi.String("none"),
		},
	},
})
if err != nil {
	return err
}
_ = api

Add to your Program.cs:

// The quickstart API: internal only
var api = new Workload("api", new WorkloadArgs
{
    Gvc = gvc.Name,
    Name = "api",
    Type = "standard",
    Containers = new[]
    {
        new WorkloadContainerArgs
        {
            Name = "api",
            Image = "/org/my-org/image/api:1.0",
            Cpu = "50m",
            Memory = "128Mi",
            Ports = new[]
            {
                new WorkloadContainerPortArgs
                {
                    Protocol = "http",
                    Number = 8080
                }
            }
        }
    },
    Options = new WorkloadOptionsArgs
    {
        CapacityAi = true,
        TimeoutSeconds = 5,
        Autoscaling = new WorkloadOptionsAutoscalingArgs
        {
            Metric = "disabled",
            Target = 95,
            MinScale = 1,
            MaxScale = 1
        }
    },
    FirewallSpec = new WorkloadFirewallSpecArgs
    {
        Internal = new WorkloadFirewallSpecInternalArgs
        {
            InboundAllowType = "none"
        }
    }
});

Replace my-org with your org name; Pulumi needs the full image path.

Step 4: Point the frontend at the API

Add the environment variable to the frontend container:

TypeScript
Python
Go
C#

      env: {
        API_URL: "http://api.quickstart-gvc.cpln.local:8080",
      },

        env={
            "API_URL": "http://api.quickstart-gvc.cpln.local:8080",
        },

			Env: pulumi.StringMap{
				"API_URL": pulumi.String("http://api.quickstart-gvc.cpln.local:8080"),
			},

            Env =
            {
                { "API_URL", "http://api.quickstart-gvc.cpln.local:8080" }
            }

Deploy both changes:

pulumi up

Step 5: See the default deny

Step 6: Allow the frontend

Name frontend on the API’s workload list:

TypeScript
Python
Go
C#

  firewallSpec: {
    internal: {
      inboundAllowType: "workload-list",
      inboundAllowWorkloads: [frontend.selfLink],
    },
  },

    firewall_spec=cpln.WorkloadFirewallSpecArgs(
        internal=cpln.WorkloadFirewallSpecInternalArgs(
            inbound_allow_type="workload-list",
            inbound_allow_workloads=[frontend.self_link],
        ),
    ))

	FirewallSpec: &cpln.WorkloadFirewallSpecArgs{
		Internal: &cpln.WorkloadFirewallSpecInternalArgs{
			InboundAllowType:      pulumi.String("workload-list"),
			InboundAllowWorkloads: pulumi.StringArray{frontend.SelfLink},
		},
	},

    FirewallSpec = new WorkloadFirewallSpecArgs
    {
        Internal = new WorkloadFirewallSpecInternalArgs
        {
            InboundAllowType = "workload-list",
            InboundAllowWorkloads = { frontend.SelfLink }
        }
    }

Deploy the change:

pulumi up

Step 3: Create the API workload

The first prompt names your org and the GVC, so it works in a new conversation too. Replace my-org with your org name:

Using org "my-org" and GVC "quickstart-gvc", create a workload
called "api" from the image //image/api:1.0 on port 8080, with
one replica per location and the container named "api". Keep
it off the internet and leave its internal firewall closed for
now. Keep everything else at its default.

The agent creates the workload with no public endpoint and its internal firewall at none, then follows its deployments until both locations report ready. Nothing reaches it yet.

Step 4: Point the frontend at the API

Set the environment variable API_URL on the frontend workload
to http://api.quickstart-gvc.cpln.local:8080.

The agent reads the workload, adds the variable to its container, and follows the rollout until both locations report ready.

Step 5: See the default deny

Once frontend reports Ready again, open its canonical endpoint, or ask the agent for it. The page waits for its call to the API to time out, then reports below the waitlist form: Could not reach the API at http://api.quickstart-gvc.cpln.local:8080: no answer within 3 seconds. The name resolves and the connection is never answered, because api admits no caller yet.

Step 6: Allow the frontend

Let only the frontend workload reach the API through its
internal firewall.

The agent reads the API’s firewall, switches its internal inbound type to a workload list that names frontend, and follows the rollout until both locations report ready.

Verify

Once api reports Ready again, reload the frontend (a 503 from the API means the mesh is still switching to the new version, so reload once more). The form is enabled and the note reads Be the first on the list. Join with an email address. The form answers You're on the list as you@example.com., the note becomes 1 person is already waiting., and Recent signups lists the address, with the badge next to its heading reading, for the location nearest to you, Stored in memory by api in aws-us-west-2. Open the other location’s endpoint from the Deployments page (or cpln workload get-deployments frontend --gvc quickstart-gvc, or by asking your AI agent for it). It still reads Be the first on the list. with No signups yet., because the frontend’s call stays in its own location and each API replica keeps its own memory. Part 4 gives them one database.

Two workloads communicate over the internal network, encrypted with mTLS, with access granted by the receiving workload’s firewall, and the API has no public endpoint at all.

Internal firewall options

Value	Behavior
`none`	No internal access to this workload
`same-gvc`	Any workload in the same GVC may access it
`same-org`	Any workload in the org may access it
`workload-list`	Only the workloads listed in `inboundAllowWorkload` may access it, from any GVC

The workload-list option requires view permission on the allowed workloads.

What you’ve learned

Closed by default: a new workload admits no internal caller until its firewall names one, and without a public endpoint it is invisible from the internet.
Internal endpoints use the .cpln.local domain, resolve from every workload in the org, and work across GVCs.
Calls stay local: a call to an internal endpoint is served by the replica in the caller’s own location whenever one is ready there.
One build path for every service: the API went from source to a running workload with the same cpln image build and the same workload creation as the frontend.

Next steps

4. Add a database and wire its secret

Give the API a PostgreSQL database from the Template Catalog, with its credentials delivered through an identity, a policy, and a secret reference.

Clean up

To remove everything the series has created so far:

Console
CLI
Terraform
Pulumi
AI Agent

Delete the GVC

Open quickstart-gvc, click Actions, then Delete, type the GVC name to confirm, and click Delete. web, frontend, and api go with it.

Delete the images

Open Images, select frontend, and click Actions, then Delete to remove all its tags. Repeat for api.

cpln gvc delete quickstart-gvc
cpln image delete frontend:1.0
cpln image delete frontend:1.1
cpln image delete api:1.0

terraform destroy

The images were built by the CLI, so delete them with it: cpln image delete frontend:1.0, cpln image delete frontend:1.1, and cpln image delete api:1.0.

pulumi destroy

The images were built by the CLI, so delete them with it: cpln image delete frontend:1.0, cpln image delete frontend:1.1, and cpln image delete api:1.0.

Delete the GVC "quickstart-gvc" and the images frontend:1.0,
frontend:1.1, and api:1.0.

The agent lists what goes: the GVC with web, frontend, and api, and the images. Confirm, and it deletes them.

A --remote build also pushes the build cache images frontend-cache:latest and api-cache:latest; delete those too if you built without Docker.

Getting Started

Quickstart

Concepts

Core

Reference

3. Service-to-service communication

Overview

Prerequisites

Step 1: Download the API

macOS / Linux

Windows

Step 2: Build and push the image

Step 3: Create the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Step 3: Create the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Step 3: Define the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Step 3: Define the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Step 3: Create the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Verify

Internal firewall options

What you’ve learned

Next steps

4. Add a database and wire its secret

Clean up

​Overview

​Prerequisites

​Step 1: Download the API

macOS / Linux

Windows

​Step 2: Build and push the image

​Step 3: Create the API workload

​Step 4: Point the frontend at the API

​Step 5: See the default deny

​Step 6: Allow the frontend

​Step 3: Create the API workload

​Step 4: Point the frontend at the API

​Step 5: See the default deny

​Step 6: Allow the frontend

​Step 3: Define the API workload

​Step 4: Point the frontend at the API

​Step 5: See the default deny

​Step 6: Allow the frontend

​Step 3: Define the API workload

​Step 4: Point the frontend at the API

​Step 5: See the default deny

​Step 6: Allow the frontend

​Step 3: Create the API workload

​Step 4: Point the frontend at the API

​Step 5: See the default deny

​Step 6: Allow the frontend

​Verify

​Internal firewall options

​What you’ve learned

​Next steps

4. Add a database and wire its secret

​Clean up

Overview

Prerequisites

Step 1: Download the API

Step 2: Build and push the image

Step 3: Create the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Step 3: Create the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Step 3: Define the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Step 3: Define the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Step 3: Create the API workload

Step 4: Point the frontend at the API

Step 5: See the default deny

Step 6: Allow the frontend

Verify

Internal firewall options

What you’ve learned

Next steps

Clean up