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>"
}
}
}
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
{
"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"
}
}
})
}
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
}
}
})
}
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"
}
}
})
}
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.
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
]
}
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 },
});
Next Steps
