Create a Secret - Control Plane

Secrets provide secure, centralized storage for sensitive data like credentials, API keys, certificates, and configuration values. Control Plane encrypts all secrets at rest and in transit, with fine-grained access control through policies ensuring only authorized workloads can access the data they need.

Encrypted Storage

All secrets are encrypted using industry-standard algorithms

Policy-Based Access

Fine-grained control over which workloads can access secrets

Multiple Injection Methods

Inject secrets as environment variables, mount as files, or use as pull secrets for private container registries

How Secrets Work

Secrets can be used in two primary ways: injected into workloads at runtime, or as pull secrets for accessing private container registries.

Injecting Secrets into Workloads

Create a Secret

Store your sensitive data in Control Plane using the Console, CLI, Terraform, or Pulumi. Choose the appropriate secret type for your use case.

Create an Identity

Create a workload identity that will be used to authenticate your workload and request access to secrets.

Grant Access with a Policy

Create a policy that grants the reveal permission on your secret to the workload identity.

Link Identity to Workload

Associate the identity with your workload so it inherits the policy permissions.

Reference the Secret

Use the cpln://secret/SECRET_NAME URI in your workload’s environment variables or volume mounts.

A workload identity must be granted the reveal permission on a secret to have its value injected at runtime.

Using Secrets as Pull Secrets

For pulling container images from private registries (Docker Hub, ECR, GCP Artifact Registry, etc.), you can attach registry credentials directly to your GVC as pull secrets. This approach doesn’t require identity or policy setup.

Create a Registry Secret

Create a Docker, ECR, or GCP secret with your registry credentials.

Add to GVC Pull Secrets

Add the secret to your GVC’s pullSecretLinks so all workloads in that GVC can pull from the private registry.

kind: gvc
name: my-gvc
spec:
  pullSecretLinks:
    - //secret/my-docker-registry
    - //secret/my-ecr-credentials

Pull secrets are configured at the GVC level and automatically available to all workloads within that GVC. No identity or policy configuration is needed for pull secrets.

Choosing the Right Secret Type

Cloud Provider Credentials

For authenticating with cloud services and pulling container images:

AWS

Access key credentials for AWS services

ECR

Pull images from Elastic Container Registry

GCP

Service account keys for Google Cloud

Azure SDK

Service principal for Azure services

Azure Connector

Connect to Azure Function Apps

Docker

Pull from any container registry

Application Secrets

For storing application configuration and credentials:

Opaque

API keys, tokens, and general secrets

Dictionary

Multiple related key-value pairs

Username & Password

Database and service credentials

Certificates & Keys

For cryptographic operations and secure communication:

TLS

SSL/TLS certificates for HTTPS

Keypair

SSH keys and signing keys

NATS Account

NATS messaging authentication

Best Practices

Use specific secret types

Choose the most specific secret type for your use case. For example, use AWS secrets for AWS credentials rather than storing them as Opaque. Specific types provide better validation and structured access.

Follow least-privilege access

Grant reveal permission only to identities that need it. Create separate policies for different secrets rather than granting broad access.

Use environment variables for simple values

For API keys and tokens, environment variables are the simplest approach. Use volume mounts for certificates or when your application expects files.

Rotate secrets regularly

Establish a rotation schedule for credentials. Update secrets in Control Plane and redeploy workloads to pick up new values.

Avoid hardcoding in IaC

Never commit secret values to version control. Use Terraform variables, Pulumi config secrets, or external secret management tools.

Use Dictionary for related values

Use caution when handling sensitive values in IaC scripts. Best practices recommend using variables, encrypted state files, or external secret management rather than hard-coding sensitive values.

Using Secrets in Workloads

Once created, secrets can be injected into workloads as environment variables or mounted as files.

Console UI
CLI
Terraform
Pulumi

This guide assumes you already have a GVC, workload, and secret. If you haven’t created these yet, see Create a GVC, Create a Workload, and the secret type guides above.

Step 1: Create an Identity

Navigate to Identities

Navigate to Identities and click New, or click Create in the top-right corner and select Identity.

Select GVC

Ensure the correct GVC is selected in the GVC dropdown.

Enter name

Enter a Name (e.g., my-workload-identity).

Create the identity

Click Create.

Step 2: Link Identity to Workload

Navigate to your workload

Navigate to your workload.

Open Identity settings

Click Identity in the left pane.

Select identity

Select the identity you created (e.g., my-workload-identity).

Save changes

Click Save.

Step 3: Create a Policy for Secret Access

Navigate to Policies

Navigate to Policies and click New, or click Create in the top-right corner and select Policy.

Enter name

Enter a Name (e.g., workload-secret-access).

Configure target

Click Target in the left pane. Under Kind, select Secret.

Add secret items

Click Items in the left pane. Click Add and select the secret you want to grant access to.

Add binding

Click Bindings in the left pane. Click Add.

Configure permissions

In the Permissions tab, select reveal. In the Identities tab, select the identity linked to your workload. Click OK.

Create the policy

Click Create.

Step 4: Inject Secret into Workload

Option 1: Environment Variables

Navigate to your workload

Navigate to your workload.

Open Env Vars

Click Containers in the left pane, then select the Env Vars tab.

Add environment variable

Click Add. Enter the variable Name (e.g., MY_SECRET).

Select secret

In the Value dropdown, change Literal Value to CPLN Secret. In the dropdown next to it, find and select your secret by name.

Update workload

Click Update.

Option 2: Volume Mount

Navigate to your workload

Navigate to your workload.

Open Volumes

Click Containers in the left pane, then select the Volumes tab.

Add volume

Click Add. Ensure CPLN Secret is selected for the URI type.

Configure mount

Select the secret from the dropdown by name. Enter the Path where the secret will be mounted (e.g., /secrets/my-secret.txt).

Update workload

Click Update.

This guide assumes you already have a GVC, workload, and secret. If you haven’t created these yet, see Create a GVC, Create a Workload, and the secret type guides above.

Step 1: Create an Identity

cpln identity create \
  --name my-workload-identity \
  --gvc my-gvc \
  --org my-org

Step 2: Link Identity to Workload

cpln workload update my-workload \
  --set spec.identityLink=my-workload-identity \
  --gvc my-gvc \
  --org my-org

Step 3: Create a Policy for Secret Access

Create the policy targeting your secret:

cpln policy create \
  --name workload-secret-access \
  --target-kind secret \
  --resource my-secret \
  --org my-org

Add a binding to grant the identity the reveal permission:

cpln policy add-binding workload-secret-access \
  --permission reveal \
  --identity my-workload-identity \
  --gvc my-gvc \
  --org my-org

Step 4: Inject Secret into Workload

Update your workload to reference the secret as an environment variable:

cpln workload update my-workload \
  --set spec.containers.<container-name>.env.MY_SECRET.value=cpln://secret/my-secret \
  --gvc my-gvc \
  --org my-org

Or mount as a volume by exporting your workload, editing it, and applying:

cpln workload get my-workload \
  -o yaml-slim \
  --gvc my-gvc \
  --org my-org > my-workload.yaml

Edit my-workload.yaml to add a volume to your container:

spec:
  containers:
    - name: main
      # ... existing config ...
      volumes:
        - uri: "cpln://secret/my-secret"
          path: /secrets/my-secret.txt

Apply the updated workload:

cpln apply --file my-workload.yaml --gvc my-gvc --org my-org

The following example shows a complete Terraform configuration that creates all the resources needed to inject a secret into a workload. Comments highlight each resource and the key configurations for secret access.

# Create a GVC
resource "cpln_gvc" "my_gvc" {
  name        = "my-gvc"
  description = "My GVC"
  locations   = ["aws-us-west-2", "gcp-us-east1"]
}

# Create a Secret
resource "cpln_secret" "my_secret" {
  name        = "my-secret"
  description = "Third-party API key"

  opaque {
    payload  = "my-secret-value"
    encoding = "plain"
  }
}

# Create an Identity for the workload
resource "cpln_identity" "workload_identity" {
  gvc         = cpln_gvc.my_gvc.name
  name        = "my-workload-identity"
  description = "Identity for workload secret access"
}

# Create the Workload with identity linked
resource "cpln_workload" "my_workload" {
  gvc  = cpln_gvc.my_gvc.name
  name = "my-workload"
  type = "standard"

  # Link the identity to the workload
  identity_link = cpln_identity.workload_identity.self_link

  container {
    name   = "main"
    image  = "kennethreitz/httpbin"
    cpu    = "50m"
    memory = "128Mi"

    ports {
      number   = 80
      protocol = "http"
    }

    # Inject secret as environment variable
    env = {
      MY_SECRET = cpln_secret.my_secret.secret_link
    }

    # Mount secret as a file
    volume {
      uri  = cpln_secret.my_secret.secret_link
      path = "/secrets/my-secret.txt"
    }
  }

  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"]
    }
  }
}

# Create a Policy granting the identity reveal permission on the secret
resource "cpln_policy" "secret_access" {
  name        = "workload-secret-access"
  description = "Allow workload to reveal secret"
  target_kind = "secret"
  target_links = [cpln_secret.my_secret.self_link]

  binding {
    permissions     = ["reveal"]
    principal_links = [cpln_identity.workload_identity.self_link]
  }
}

This example uses a hardcoded secret value for testing. In production, use Terraform variables with sensitive = true or integrate with a secrets manager.

The following examples show complete Pulumi programs that create all the resources needed to inject a secret into a workload. Comments highlight each resource and the key configurations for secret access.

TypeScript
Python
Go
C#

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

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

// Create a Secret
const secret = new cpln.Secret("my-secret", {
  name: "my-secret",
  description: "Third-party API key",
  opaque: {
    payload: "my-secret-value",
    encoding: "plain",
  },
});

// Create an Identity for the workload
const workloadIdentity = new cpln.Identity("my-workload-identity", {
  gvc: gvc.name,
  name: "my-workload-identity",
  description: "Identity for workload secret access",
});

// Create the Workload with identity linked
const workload = new cpln.Workload("my-workload", {
  gvc: gvc.name,
  name: "my-workload",
  type: "standard",
  // Link the identity to the workload
  identityLink: workloadIdentity.selfLink,
  containers: [
    {
      name: "main",
      image: "kennethreitz/httpbin",
      cpu: "50m",
      memory: "128Mi",
      ports: [
        {
          number: 80,
          protocol: "http",
        },
      ],
      // Inject secret as environment variable
      env: {
        MY_SECRET: secret.secretLink,
      },
      // Mount secret as a file
      volumes: [
        {
          uri: secret.secretLink,
          path: "/secrets/my-secret.txt",
        },
      ],
    },
  ],
  options: {
    capacityAi: true,
    timeoutSeconds: 5,
    autoscaling: {
      metric: "disabled",
      target: 95,
      minScale: 1,
      maxScale: 1,
    },
  },
  firewallSpec: {
    external: {
      inboundAllowCidrs: ["0.0.0.0/0"],
    },
  },
});

// Create a Policy granting the identity reveal permission on the secret
const secretAccessPolicy = new cpln.Policy("workload-secret-access", {
  name: "workload-secret-access",
  description: "Allow workload to reveal secret",
  targetKind: "secret",
  targetLinks: [secret.selfLink],
  bindings: [
    {
      permissions: ["reveal"],
      principalLinks: [workloadIdentity.selfLink],
    },
  ],
});

import pulumiverse_cpln as cpln

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

# Create a Secret
secret = cpln.Secret("my-secret",
    name="my-secret",
    description="Third-party API key",
    opaque={
        "payload": "my-secret-value",
        "encoding": "plain",
    })

# Create an Identity for the workload
workload_identity = cpln.Identity("my-workload-identity",
    gvc=gvc.name,
    name="my-workload-identity",
    description="Identity for workload secret access")

# Create the Workload with identity linked
workload = cpln.Workload("my-workload",
    gvc=gvc.name,
    name="my-workload",
    type="standard",
    # Link the identity to the workload
    identity_link=workload_identity.self_link,
    containers=[{
        "name": "main",
        "image": "kennethreitz/httpbin",
        "cpu": "50m",
        "memory": "128Mi",
        "ports": [{
            "number": 80,
            "protocol": "http",
        }],
        # Inject secret as environment variable
        "env": {
            "MY_SECRET": secret.secret_link,
        },
        # Mount secret as a file
        "volumes": [{
            "uri": secret.secret_link,
            "path": "/secrets/my-secret.txt",
        }],
    }],
    options={
        "capacity_ai": True,
        "timeout_seconds": 5,
        "autoscaling": {
            "metric": "disabled",
            "target": 95,
            "min_scale": 1,
            "max_scale": 1,
        },
    },
    firewall_spec={
        "external": {
            "inbound_allow_cidrs": ["0.0.0.0/0"],
        },
    })

# Create a Policy granting the identity reveal permission on the secret
secret_access_policy = cpln.Policy("workload-secret-access",
    name="workload-secret-access",
    description="Allow workload to reveal secret",
    target_kind="secret",
    target_links=[secret.self_link],
    bindings=[{
        "permissions": ["reveal"],
        "principal_links": [workload_identity.self_link],
    }])

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, "my-gvc", &cpln.GvcArgs{
            Name:        pulumi.String("my-gvc"),
            Description: pulumi.String("My GVC"),
            Locations:   pulumi.StringArray{pulumi.String("aws-us-west-2"), pulumi.String("gcp-us-east1")},
        })
        if err != nil {
            return err
        }

        // Create a Secret
        secret, err := cpln.NewSecret(ctx, "my-secret", &cpln.SecretArgs{
            Name:        pulumi.String("my-secret"),
            Description: pulumi.String("Third-party API key"),
            Opaque: &cpln.SecretOpaqueArgs{
                Payload:  pulumi.String("my-secret-value"),
                Encoding: pulumi.String("plain"),
            },
        })
        if err != nil {
            return err
        }

        // Create an Identity for the workload
        workloadIdentity, err := cpln.NewIdentity(ctx, "my-workload-identity", &cpln.IdentityArgs{
            Gvc:         gvc.Name,
            Name:        pulumi.String("my-workload-identity"),
            Description: pulumi.String("Identity for workload secret access"),
        })
        if err != nil {
            return err
        }

        // Create the Workload with identity linked
        _, err = cpln.NewWorkload(ctx, "my-workload", &cpln.WorkloadArgs{
            Gvc:  gvc.Name,
            Name: pulumi.String("my-workload"),
            Type: pulumi.String("standard"),
            // Link the identity to the workload
            IdentityLink: workloadIdentity.SelfLink,
            Containers: cpln.WorkloadContainerArray{
                &cpln.WorkloadContainerArgs{
                    Name:   pulumi.String("main"),
                    Image:  pulumi.String("kennethreitz/httpbin"),
                    Cpu:    pulumi.String("50m"),
                    Memory: pulumi.String("128Mi"),
                    Ports: cpln.WorkloadContainerPortArray{
                        &cpln.WorkloadContainerPortArgs{
                            Number:   pulumi.Int(80),
                            Protocol: pulumi.String("http"),
                        },
                    },
                    // Inject secret as environment variable
                    Env: pulumi.StringMap{
                        "MY_SECRET": secret.SecretLink,
                    },
                    // Mount secret as a file
                    Volumes: cpln.WorkloadContainerVolumeArray{
                        &cpln.WorkloadContainerVolumeArgs{
                            Uri:  secret.SecretLink,
                            Path: pulumi.String("/secrets/my-secret.txt"),
                        },
                    },
                },
            },
            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
        }

        // Create a Policy granting the identity reveal permission on the secret
        _, err = cpln.NewPolicy(ctx, "workload-secret-access", &cpln.PolicyArgs{
            Name:        pulumi.String("workload-secret-access"),
            Description: pulumi.String("Allow workload to reveal secret"),
            TargetKind:  pulumi.String("secret"),
            TargetLinks: pulumi.StringArray{secret.SelfLink},
            Bindings: cpln.PolicyBindingArray{
                &cpln.PolicyBindingArgs{
                    Permissions:    pulumi.StringArray{pulumi.String("reveal")},
                    PrincipalLinks: pulumi.StringArray{workloadIdentity.SelfLink},
                },
            },
        })
        if err != nil {
            return err
        }

        return nil
    })
}

using Pulumi;
using Pulumiverse.Cpln;
using Pulumiverse.Cpln.Inputs;

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

    // Create a Secret
    var secret = new Secret("my-secret", new SecretArgs
    {
        Name = "my-secret",
        Description = "Third-party API key",
        Opaque = new SecretOpaqueArgs
        {
            Payload = "my-secret-value",
            Encoding = "plain",
        },
    });

    // Create an Identity for the workload
    var workloadIdentity = new Identity("my-workload-identity", new IdentityArgs
    {
        Gvc = gvc.Name,
        Name = "my-workload-identity",
        Description = "Identity for workload secret access",
    });

    // Create the Workload with identity linked
    var workload = new Workload("my-workload", new WorkloadArgs
    {
        Gvc = gvc.Name,
        Name = "my-workload",
        Type = "standard",
        // Link the identity to the workload
        IdentityLink = workloadIdentity.SelfLink,
        Containers = new[]
        {
            new WorkloadContainerArgs
            {
                Name = "main",
                Image = "kennethreitz/httpbin",
                Cpu = "50m",
                Memory = "128Mi",
                Ports = new[]
                {
                    new WorkloadContainerPortArgs
                    {
                        Number = 80,
                        Protocol = "http",
                    },
                },
                // Inject secret as environment variable
                Env = {
                    { "MY_SECRET", secret.SecretLink },
                },
                // Mount secret as a file
                Volumes = new[]
                {
                    new WorkloadContainerVolumeArgs
                    {
                        Uri = secret.SecretLink,
                        Path = "/secrets/my-secret.txt",
                    },
                },
            },
        },
        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 = { "0.0.0.0/0" },
            },
        },
    });

    // Create a Policy granting the identity reveal permission on the secret
    var secretAccessPolicy = new Policy("workload-secret-access", new PolicyArgs
    {
        Name = "workload-secret-access",
        Description = "Allow workload to reveal secret",
        TargetKind = "secret",
        TargetLinks = { secret.SelfLink },
        Bindings = new[]
        {
            new PolicyBindingArgs
            {
                Permissions = { "reveal" },
                PrincipalLinks = { workloadIdentity.SelfLink },
            },
        },
    });
});

This example uses a hardcoded secret value for testing. In production, use Pulumi config secrets (pulumi config set --secret) to manage sensitive values securely.

Secret Reference Formats

When referencing secrets, use the cpln://secret/ URI format:

Format	Description	Example
`cpln://secret/SECRET_NAME`	Reference entire secret payload	`cpln://secret/my-secret`
`cpln://secret/SECRET_NAME.KEY`	Reference specific key in dictionary/structured secrets	`cpln://secret/my-config.DB_PASSWORD`

The mount behavior varies by secret type:

Opaque: The payload is mounted as a file at the specified path
Dictionary and other structured secrets: A directory is created containing files for each key/property
Docker, Azure SDK, and GCP: The secret is mounted as a file named ___cpln___.secret in the specified directory

For more details, see the Workload Volumes Reference.

Next Steps

Secret Reference

Complete API reference for secrets

Identity Reference

Learn more about workload identities

Policy Reference

Understand policy-based access control

Workload Volumes

Volume mount options and behaviors

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Workload Access

Encrypted Storage

Policy-Based Access

Multiple Injection Methods

​How Secrets Work

​Injecting Secrets into Workloads

​Using Secrets as Pull Secrets

​Choosing the Right Secret Type

​Cloud Provider Credentials

AWS

ECR

GCP

Azure SDK

Azure Connector

Docker

​Application Secrets

Opaque

Dictionary

Username & Password

​Certificates & Keys

TLS

Keypair

NATS Account

​Best Practices

​Using Secrets in Workloads

​Step 1: Create an Identity

​Step 2: Link Identity to Workload

​Step 3: Create a Policy for Secret Access

​Step 4: Inject Secret into Workload

​Step 1: Create an Identity

​Step 2: Link Identity to Workload

​Step 3: Create a Policy for Secret Access

​Step 4: Inject Secret into Workload

​Secret Reference Formats

​Next Steps

Secret Reference

Identity Reference

Policy Reference

Workload Volumes

How Secrets Work

Injecting Secrets into Workloads

Using Secrets as Pull Secrets

Choosing the Right Secret Type

Cloud Provider Credentials

Application Secrets

Certificates & Keys

Best Practices

Using Secrets in Workloads

Step 1: Create an Identity

Step 2: Link Identity to Workload

Step 3: Create a Policy for Secret Access

Step 4: Inject Secret into Workload

Step 1: Create an Identity

Step 2: Link Identity to Workload

Step 3: Create a Policy for Secret Access

Step 4: Inject Secret into Workload

Secret Reference Formats

Next Steps