Configuration Management Commands

Relevant source files

The following files were used as context for generating this wiki page:

• pkg/cmd/pulumi/config/config.go
• sdk/go/common/workspace/config.go
• sdk/go/common/workspace/project.json
• pkg/codegen/dotnet/gen.go
• pkg/cmd/pulumi/markdown/gen.go
• pkg/cmd/pulumi/about/about.go
• tests/testdata/codegen/kubernetes20/dotnet/Config/Config.cs

Configuration management in Pulumi allows for the parameterization of infrastructure code, making it reusable and adaptable across different environments (stacks). The primary interface for this is the pulumi config command, which provides a suite of tools to set, get, and manage configuration values for a given stack. These values are stored securely in the backend and can be accessed programmatically within a Pulumi program.

This system enables developers to define configuration schemas in their project files, including types, descriptions, and default values. Pulumi's code generation process can then create strongly-typed accessors for these configuration values, improving developer experience and catching errors early.

Sources: pkg/cmd/pulumi/markdown/gen.go:30-34, sdk/go/common/workspace/project.json:71-106

pulumi config Command Suite

The pulumi config command is the entry point for all configuration-related operations. It acts as a parent command for several subcommands that handle specific aspects of configuration management.

Sources: pkg/cmd/pulumi/config/config.go:42-50

Command Hierarchy

The following diagram illustrates the structure of the pulumi config command and its subcommands.

Subcommand Descriptions

Command	Description
ls	Lists all configuration values for the current stack.
get <key>	Gets the value for a specific configuration key.
set <key> [value]	Sets a configuration value. If a value is not provided, the CLI will prompt for it.
set-all	Sets multiple configuration values at once from a file or standard input.
rm <key>	Removes a specific configuration key.
rm-all	Removes multiple or all configuration keys.
refresh	Reloads configuration from the backend.
cp	Copies configuration from one stack to another.

Sources: pkg/cmd/pulumi/config/config.go:52-106

Configuration Data Model

At its core, stack configuration is a map of string keys to structured values. The primary data structures are ConfigMap and ConfigValue.

Sources: sdk/go/common/workspace/config.go

Core Data Structures

A ConfigMap is a type alias for map[string]ConfigValue, representing all configuration for a stack. Each entry in the map is a ConfigValue.

The ConfigValue struct is central to how Pulumi handles configuration. It contains the configuration value and metadata, most importantly whether the value is a secret.

// sdk/go/common/workspace/config.go:21-25
type ConfigValue struct {
	Value  string `json:"value"`
	Secret bool   `json:"secret,omitempty"`
}

The diagram below shows the relationship between these structures.

Secret Handling

When a configuration value is marked as a secret (either via the --secret flag in pulumi config set or by being defined as secret in the project schema), the Secret field of ConfigValue is set to true. The Pulumi engine ensures that this value is encrypted before being sent to the backend and is only decrypted in memory when accessed by the Pulumi program. The about command can display token information, which relates to the permissions for accessing these secrets.

Sources: pkg/cmd/pulumi/config/config.go:193-195, sdk/go/common/workspace/config.go:23, pkg/cmd/pulumi/about/about.go:221-237

Project-Level Configuration Schema

The Pulumi.yaml project file can contain a config section to define a schema for expected configuration keys. This allows for type checking, descriptions, and default values.

The schema for this is defined in project.json.

// sdk/go/common/workspace/project.json:71-106
"config":{
    "description":"A map of configuration keys to their types. Using config directory location relative to the location of Pulumi.yaml is a deprecated use of this key. Use stackConfigDir instead.",
    "type":[
        "object",
        "string",
        "null"
    ],
    "properties":{
        "secret":{
            "description":"If true this configuration value should be encrypted.",
            "type":"boolean",
            "default":false
        }
    },
    "additionalProperties":{
        "oneOf":[
            {
                "type":"string"
            },
            {
                "type":"integer"
            },
            {
                "type":"boolean"
            },
            {
                "type": "array"
            },
            {
                "$ref":"#/$defs/configTypeDeclaration"
            }
        ]
    }
}

Field	Type	Description
description	string	A description of the configuration variable.
type	string	The expected type (e.g., string, integer, boolean).
default	any	A default value to use if none is provided in the stack config.
secret	boolean	If true, the value will be treated as a secret and encrypted.

Sources: sdk/go/common/workspace/project.json:71-106, sdk/go/common/workspace/project.json:406-425

Language-Specific Configuration Generation

Pulumi leverages the configuration schema in Pulumi.yaml to generate strongly-typed helper classes in target languages. This provides a convenient and type-safe way to access configuration values.

.NET Example

For .NET projects, the pulumi-gen-dotnet tool generates a static Config class.

The genConfig function in the .NET code generator is responsible for this process. It creates a Config class with static properties for each configuration variable defined in Pulumi.yaml. For lazy-loading and handling of default values, it uses a private nested class __Value<T>.

This flow is shown in the diagram below.

Here is an example of a generated Config.cs file:

// tests/testdata/codegen/kubernetes20/dotnet/Config/Config.cs:7-45
namespace Pulumi.Kubernetes
{
    public static class Config
    {
        [global::System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "IDE1006", Justification = 
        "Double underscore prefix used to avoid conflicts with variable names.")]
        private sealed class __Value<T>
        {
            private readonly Func<T> _getter;
            private T _value = default!;
            private bool _set;

            public __Value(Func<T> getter)
            {
                _getter = getter;
            }

            public T Get() => _set ? _value : _getter();

            public void Set(T value)
            {
                _value = value;
                _set = true;
            }
        }

        private static readonly global::Pulumi.Config __config = new global::Pulumi.Config("kubernetes");

        private static readonly __Value<string?> _kubeconfig = new __Value<string?>(() => __config.Get("kubeconfig"));
        /// <summary>
        /// The contents of a kubeconfig file or the path to a kubeconfig file. If this is set, this config will be used instead of $KUBECONFIG.
        /// </summary>
        public static string? KubeConfig
        {
            get => _kubeconfig.Get();
            set => _kubeconfig.Set(value);
        }
        // ... other config properties
    }
}

This generated code provides static properties (e.g., KubeConfig) that internally use the Pulumi Config object to retrieve values, providing a clean and discoverable API for developers.

Sources: pkg/codegen/dotnet/gen.go:2104-2212, tests/testdata/codegen/kubernetes20/dotnet/Config/Config.cs

pulumi config set Flow

The pulumi config set command is a common operation. The following sequence diagram details the internal flow when a user sets a configuration value.

Conclusion

The configuration management system is a cornerstone of Pulumi's approach to Infrastructure as Code. It provides a robust mechanism for parameterizing deployments, managing secrets, and creating environment-agnostic code. By integrating configuration schemas directly into the project definition and leveraging code generation, Pulumi offers a developer-friendly, type-safe, and secure way to manage the variables that define an infrastructure's behavior across different stacks. The pulumi config command-line tool serves as the user's primary interface for these powerful capabilities.

Sources: pkg/cmd/pulumi/markdown/gen.go:33-34, sdk/go/common/workspace/project.json:71-73