Dictionary

Dictionary secrets store multiple key-value pairs in a single secret, making them ideal for grouping related configuration values. Each key can be accessed individually when injecting into workloads.

Use Cases

Database Configuration: Store host, port, username, and database name together
API Configuration: Group related API settings (endpoint, version, timeout)
Feature Flags: Store multiple feature toggles in one secret
Environment Variables: Bundle related environment variables
Application Settings: Group configuration that belongs together logically

Use dictionary secrets when you have multiple related values that you want to manage as a single unit but access individually in your workload.

Configuration Options

Dictionary secrets store key-value pairs where:

Component	Description
Key	The identifier for each value (e.g., `DB_HOST`, `DB_PORT`)
Value	The secret value associated with the key

All values in a dictionary secret are stored as strings. If you need to store JSON or complex data, use an Opaque secret instead.

Create a Dictionary 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 Dictionary as the secret type.

Configure key-value pairs

Click Data in the left pane. Click Add to add key-value pairs, or drag and drop a file / click to import.

Create the secret

Click Create.

cpln secret create-dictionary \
  --name database-config \
  --entry DB_HOST=db.example.com \
  --entry DB_PORT=5432 \
  --entry DB_NAME=myapp_production \
  --entry DB_SSL_MODE=require \
  --org my-org

resource "cpln_secret" "database_config" {
  name        = "database-config"
  description = "Database connection configuration"

  dictionary = {
    DB_HOST     = "db.example.com"
    DB_PORT     = "5432"
    DB_NAME     = "myapp_production"
    DB_SSL_MODE = "require"
  }
}

Access individual keys using the dictionary_as_envs output:

# Reference in workload environment variables
resource "cpln_workload" "my_app" {
  # ... other config ...

  container {
    name  = "main"
    image = "my-app:latest"

    env = {
      DB_HOST = cpln_secret.database_config.dictionary_as_envs["DB_HOST"]
      DB_PORT = cpln_secret.database_config.dictionary_as_envs["DB_PORT"]
    }
  }
}

TypeScript
Python
Go
C#

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

const databaseConfig = new cpln.Secret("database-config", {
  name: "database-config",
  description: "Database connection configuration",
  dictionary: {
    DB_HOST: "db.example.com",
    DB_PORT: "5432",
    DB_NAME: "myapp_production",
    DB_SSL_MODE: "require",
  },
});

// Export for use in workloads
export const dbHostEnv = databaseConfig.dictionaryAsEnvs.apply(
  envs => envs["DB_HOST"]
);

import pulumiverse_cpln as cpln

database_config = cpln.Secret("database-config",
    name="database-config",
    description="Database connection configuration",
    dictionary={
        "DB_HOST": "db.example.com",
        "DB_PORT": "5432",
        "DB_NAME": "myapp_production",
        "DB_SSL_MODE": "require",
    })

# Export for use in workloads
pulumi.export("db_host_env", database_config.dictionary_as_envs["DB_HOST"])

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 {
        databaseConfig, err := cpln.NewSecret(ctx, "database-config", &cpln.SecretArgs{
            Name:        pulumi.String("database-config"),
            Description: pulumi.String("Database connection configuration"),
            Dictionary: pulumi.StringMap{
                "DB_HOST":     pulumi.String("db.example.com"),
                "DB_PORT":     pulumi.String("5432"),
                "DB_NAME":     pulumi.String("myapp_production"),
                "DB_SSL_MODE": pulumi.String("require"),
            },
        })
        if err != nil {
            return err
        }

        ctx.Export("secretLink", databaseConfig.SecretLink)
        return nil
    })
}

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

return await Deployment.RunAsync(() =>
{
    var databaseConfig = new Secret("database-config", new SecretArgs
    {
        Name = "database-config",
        Description = "Database connection configuration",
        Dictionary =
        {
            { "DB_HOST", "db.example.com" },
            { "DB_PORT", "5432" },
            { "DB_NAME", "myapp_production" },
            { "DB_SSL_MODE", "require" },
        },
    });

    return new Dictionary<string, object?>
    {
        ["secretLink"] = databaseConfig.SecretLink,
    };
});

Injecting into Workloads

Individual Keys as Environment Variables

Reference specific keys from the dictionary:

env:
  - name: DATABASE_HOST
    value: "cpln://secret/database-config.DB_HOST"
  - name: DATABASE_PORT
    value: "cpln://secret/database-config.DB_PORT"
  - name: DATABASE_NAME
    value: "cpln://secret/database-config.DB_NAME"

Mount as Directory

When mounted as a volume, each key becomes a file:

volumes:
  - uri: "cpln://secret/database-config"
    path: /etc/config

This creates:

/etc/config/DB_HOST containing db.example.com
/etc/config/DB_PORT containing 5432
/etc/config/DB_NAME containing myapp_production
/etc/config/DB_SSL_MODE containing require

Common Patterns

Database Configuration

kind: secret
name: postgres-config
type: dictionary
data:
  PGHOST: db.example.com
  PGPORT: "5432"
  PGDATABASE: myapp
  PGUSER: app_user
  PGSSLMODE: require

Redis Configuration

kind: secret
name: redis-config
type: dictionary
data:
  REDIS_HOST: redis.example.com
  REDIS_PORT: "6379"
  REDIS_DB: "0"
  REDIS_TLS: "true"

External API Settings

kind: secret
name: stripe-config
type: dictionary
data:
  STRIPE_API_VERSION: "2023-10-16"
  STRIPE_WEBHOOK_TOLERANCE: "300"
  STRIPE_MAX_RETRIES: "3"

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 Dictionary Secret

Injecting into Workloads

Individual Keys as Environment Variables

Mount as Directory

Common Patterns

Database Configuration

Redis Configuration

External API Settings

Next Steps

Using Secrets in Workloads

Opaque Secrets

​Use Cases

​Configuration Options

​Create a Dictionary Secret

​Injecting into Workloads

​Individual Keys as Environment Variables

​Mount as Directory

​Common Patterns

​Database Configuration

​Redis Configuration

​External API Settings

​Next Steps

Using Secrets in Workloads

Opaque Secrets

Use Cases

Configuration Options

Create a Dictionary Secret

Injecting into Workloads

Individual Keys as Environment Variables

Mount as Directory

Common Patterns

Database Configuration

Redis Configuration

External API Settings

Next Steps