Docker

Docker secrets store container registry credentials, enabling your workloads to pull images from private registries like Docker Hub, GitHub Container Registry, Azure Container Registry, or any Docker-compatible registry.

Use Cases

Private Docker Hub: Pull images from private Docker Hub repositories
GitHub Container Registry: Access private packages hosted on GHCR
Azure Container Registry: Pull images from ACR
Google Artifact Registry: Access private Google container images
Self-Hosted Registries: Connect to private/enterprise registries
Cross-Org Images: Pull images from another Control Plane org

Images stored in your current Control Plane org don’t require a pull secret. Reference them directly using the //image/IMAGE:TAG format.

Configuration Options

The Docker secret uses the standard Docker config.json format:

{
  "auths": {
    "<registry-url>": {
      "username": "<username>",
      "password": "<password-or-token>"
    }
  }
}

You can include credentials for multiple registries in a single secret.

Create a Docker Secret

Console UI
CLI
Terraform
Pulumi

Navigate to Secrets

In the Console, navigate to Secrets and click New, or use the Create dropdown in the top-right corner and select Secret.

Enter basic information

Enter a Name and optional Description.

Select secret type

Select Docker as the secret type.

Configure credentials

Click Data in the left pane. Enter the Docker Secret Data (JSON format), or drag and drop a file / click to import.

Create the secret

Click Create.

Option 1: Use your existing Docker config file:

cpln secret create-docker \
  --name dockerhub-credentials \
  --file ~/.docker/config.json \
  --org my-org

Option 2: Create a dedicated config file:

docker-config.json

{
  "auths": {
    "https://index.docker.io/v1/": {
      "username": "my-username",
      "password": "my-access-token"
    }
  }
}

cpln secret create-docker \
  --name dockerhub-credentials \
  --file docker-config.json \
  --org my-org

For Docker Hub, use a Personal Access Token instead of your password for better security and easier revocation.

Docker Hub example:

resource "cpln_secret" "dockerhub" {
  name        = "dockerhub-credentials"
  description = "Docker Hub private registry access"

  docker = jsonencode({
    auths = {
      "https://index.docker.io/v1/" = {
        username = "my-username"
        password = "my-access-token"
      }
    }
  })
}

GitHub Container Registry example:

resource "cpln_secret" "ghcr" {
  name        = "ghcr-credentials"
  description = "GitHub Container Registry access"

  docker = jsonencode({
    auths = {
      "ghcr.io" = {
        username = "my-github-username"
        password = "ghp_xxxxxxxxxxxx"  # PAT with read:packages scope
      }
    }
  })
}

Multiple registries in one secret:

resource "cpln_secret" "multi_registry" {
  name        = "multi-registry-credentials"
  description = "Access to multiple container registries"

  docker = jsonencode({
    auths = {
      "https://index.docker.io/v1/" = {
        username = "my-username"
        password = "my-access-token"
      }
      "ghcr.io" = {
        username = "my-github-username"
        password = "ghp_xxxxxxxxxxxx"
      }
    }
  })
}

TypeScript
Python
Go
C#

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

const dockerSecret = new cpln.Secret("dockerhub-credentials", {
  name: "dockerhub-credentials",
  description: "Docker Hub private registry access",
  docker: JSON.stringify({
    auths: {
      "https://index.docker.io/v1/": {
        username: "my-username",
        password: "my-access-token",
      },
    },
  }),
});

import json
import pulumiverse_cpln as cpln

docker_secret = cpln.Secret("dockerhub-credentials",
    name="dockerhub-credentials",
    description="Docker Hub private registry access",
    docker=json.dumps({
        "auths": {
            "https://index.docker.io/v1/": {
                "username": "my-username",
                "password": "my-access-token",
            }
        }
    }))

package main

import (
    "encoding/json"
    "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 {
        dockerConfig, _ := json.Marshal(map[string]interface{}{
            "auths": map[string]interface{}{
                "https://index.docker.io/v1/": map[string]string{
                    "username": "my-username",
                    "password": "my-access-token",
                },
            },
        })

        _, err := cpln.NewSecret(ctx, "dockerhub-credentials", &cpln.SecretArgs{
            Name:        pulumi.String("dockerhub-credentials"),
            Description: pulumi.String("Docker Hub private registry access"),
            Docker:      pulumi.String(string(dockerConfig)),
        })
        return err
    })
}

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

return await Deployment.RunAsync(() =>
{
    var dockerConfig = JsonSerializer.Serialize(new
    {
        auths = new Dictionary<string, object>
        {
            ["https://index.docker.io/v1/"] = new
            {
                username = "my-username",
                password = "my-access-token",
            }
        }
    });

    var dockerSecret = new Secret("dockerhub-credentials", new SecretArgs
    {
        Name = "dockerhub-credentials",
        Description = "Docker Hub private registry access",
        Docker = dockerConfig,
    });
});

Common Registry URLs

Registry	URL	Notes
Docker Hub	`https://index.docker.io/v1/`	Use access token, not password
GitHub Container Registry	`ghcr.io`	PAT with `read:packages` scope
Azure Container Registry	`<registry>.azurecr.io`	Service principal or admin user
Google Artifact Registry	`<region>-docker.pkg.dev`	Service account JSON key
AWS ECR	Use ECR secret	Dedicated secret type available
Control Plane (other org)	`<org>.registry.cpln.io`	Service account token

Using the Secret

After creating the Docker secret, add it as a pull secret to your GVC:

Console UI
CLI
Terraform
Pulumi

Navigate to your GVC

Open your GVC in the Console.

Open Pull Secrets

Click Pull Secrets in the left pane.

Add the secret

Click Add and select your Docker secret.

Save changes

Click Save.

cpln gvc update my-gvc \
  --set spec.pullSecretLinks+="dockerhub-credentials" \
  --org my-org

resource "cpln_gvc" "my_gvc" {
  name = "my-gvc"

  pull_secrets = [
    cpln_secret.dockerhub.name
  ]
}

TypeScript
Python
Go
C#

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

const gvc = new cpln.Gvc("my-gvc", {
  name: "my-gvc",
  pullSecrets: [dockerSecret.name],
});

import pulumiverse_cpln as cpln

gvc = cpln.Gvc("my-gvc",
    name="my-gvc",
    pull_secrets=[docker_secret.name])

gvc, err := cpln.NewGvc(ctx, "my-gvc", &cpln.GvcArgs{
    Name:        pulumi.String("my-gvc"),
    PullSecrets: pulumi.StringArray{dockerSecret.Name},
})

var gvc = new Gvc("my-gvc", new GvcArgs
{
    Name = "my-gvc",
    PullSecrets = new[] { dockerSecret.Name },
});

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Sandbox

Workload Access

Use Cases

Configuration Options

Create a Docker Secret

Common Registry URLs

Using the Secret

Next Steps

GVC Pull Secrets

ECR Secrets

​Use Cases

​Configuration Options

​Create a Docker Secret

​Common Registry URLs

​Using the Secret

​Next Steps

GVC Pull Secrets

ECR Secrets

Use Cases

Configuration Options

Create a Docker Secret

Common Registry URLs

Using the Secret

Next Steps