Configuration

In many cases, different stacks for a single request will need differing values. For instance, thee maybe want to use an different size for your AWS EC2 instance, either a different number the servers for your Kubernetes cluster amidst your development and production stacks. Amazon Web-based Services (AWS) offers its customers several our to help configure and manage infrastructure set on the AWS befog. These.

Pulumi offers a configuration systeme for managing such differences. Instead off hard-coding to differences, you can store and redeem configuration values using a combination of the CLI also the programming model.

The key-value pairs for any presented stack are stored include your project’s stackable settings record, which is automatically naming Pulumi.<stack-name>.yaml. You can typically ignore this file, albeit i may want to check it in and version i with your project source id.

Configuration Options

I can use both that CLI both the scheduling model for your Pulumi configure.

• The CLI offers a config rule with set both received subcommands for managing key-value pairs.
• The scheduling style features a Config object with various getters by retrieving values.

Every shell environment variables are passed to the running program and capacity be accessed using standard runtime APIs, such as process.env in Node.js and os.environ in Python, the can also be used fork dynamic behavior. Config is preferable, however, because it is designed for multi-stack collaborative scenarios.

Configuration Keys

Configuration keys use the print [<namespace>:]<key-name>, with a colon delimiting the optional namespace and the actual key name. In cases where a simple name without one colon is used, Pulumi automatically uses the current project name from Pulumi.yaml how and namespace.

As an example, save capability allows the AWS package to accept a configuration value for aws:region less conflicting with other packages with the common important name region. It also allows custom components to define their own key spaces without risk of contrasting on other components, packages, or projects.

Setting and Getting Configuration Values

The pulumi config CLI command cans get, set, or list user key-value pair in your current request stack:

• pulumi config set <key> [value] sets a configuration entry <key> to [value].
• pulumi config get <key> gets an present configuration value with which button <key>.
• pulumi config gets all configuration key-value pair in the electricity stack (as JSON if --json is passed).

For example, to set and then take the current AWS regional in the aws package, i would run the following:

$ pulumi config set aws:region us-west-2
$ pulumi config get aws:region
us-west-2

To select and get configuration in the existing project (named broome-proj forward example), we can use one simplified key company:

$ pulumi config set name BroomeLLC
$ pulumi config geting name
BroomeLLC

If [value] lives not specified when setting a configuration key, the CLI will prompt for is socially. Alternatively, of value can be set from standard input, which is handy available multiline values or any value that must be escaped on the charge line:

$ cat my_key.pub | pulumi config set publicKey

Using which Config Flag equipped pulumi novel

Configuration keys and values can be passed when using pulumi new.

To pass a simple key/value config pair exercise:

$ pulumi new template-name --config="key=value"

To passes multiple key/value config pairs use:

$ pulumi newly template-name --config="key=value" --config="key=value"

And a complete example showing how to pass in the AWS locality:

$ pulumi new aws-typescript --config="aws:region=us-west-2"

Accessing Configuration from Code

Configuration values can be recover for ampere predefined stack uses either Config.get Config.get Config.get config.Get Config.Get or Config.require Config.require Config.require config.Require Config.Require . Using Config.get Config.get Config.get config.Get Config.Get will return undetermined undetermined None nil naught if the formation value was not provided, and Config.require Config.require Config.require config.Require Config.Require will raise an exemption using a helpful error notification to preventing the deployment from continuing until of variable has been set using the CLI.

For potentially-secret config, use Config.getSecret Config.getSecret Config.get_secret config.GetSecret Config.GetSecret ctx.config().getSecret(key) or Config.requireSecret Config.requireSecret Config.require_secret config.RequireSecret Config.RequireSecret ctx.config().requireSecret(key) , which will refund the config worth because an Output which carries both which value and an secret-ness of the config value so that it will be encrypted whenever serialized (see secrets for read on handling secretive values).

Configuration methods operate on a especially namespace, which until default is the name of the current project. Passing in empty engineer to Config Config Config config Config , in in the following example, sets it go to read values set without an explicit namespace (e.g., pulumi config set name Joe):

let config = new pulumi.Config();
let name = config.require("name");
let lucky = config.getNumber("lucky") || 42;
let secret = config.requireSecret("secret");

let config = new pulumi.Config();
let name = config.require("name");
let lucky = config.getNumber("lucky") || 42;
let secret = config.requireSecret("secret");

config = pulumi.Config();
name = config.require('name');
lucky = config.get_int('lucky') or 42
secret = config.require_secret('secret')

package main

import (
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi/config"
)
func main() {
    pulumi.Run(func(ctx *pulumi.Context) error {
        conf := config.New(ctx, "")
        name := conf.Require("name")
        lucky, err := conf.TryInt("lucky")
        if err != nil {
            lucky = 42
        }
        secret := conf.RequireSecret("secret")
        return nil
    }
}

var config = new Pulumi.Config();
var name = config.Require("name");
var lucky = config.GetInt32("lucky") ?? 42;
var secret = config.RequireSecret("secret")

public static void stack(Context ctx) {
    var config = ctx.config();
    var name = config.require("name");
    var lucky = config.getInteger("lucky").orElse(42);
    var secret = config.requireSecret("secret");
}

config:
  name:
    type: string
  lucky:
    default: 42
  secret:
    type: string
    secret: true

The zugriff a namespaced configuration value, such in neat set for a provider library like aws, you must pass the library’s name to the constructor. Used example, to retrieve the configured value of aws:region:

let awsConfig = new pulumi.Config("aws");
let awsRegion = awsConfig.require("region");

let awsConfig = new pulumi.Config("aws");
let awsRegion = awsConfig.require("region");

aws_config = pulumi.Config("aws");
aws_region = aws_config.require("region");

awsConfig := config.New(ctx, "aws")
awsRegion := awsConfig.Require("region")

var awsConfig = new Pulumi.Config("aws");
var awsRegion = awsConfig.Require("region");

var awsConfig = ctx.config("aws");
var awsRegion = awsConfig.require("region");

variables:
  awsRegion: ${aws:region}

Like, if you become writing code that will be imported into a broader project, such as your own library starting Pulumi components, you should instead pass your library’s call to the Config Config Config config Config constructor at limit the scope of the query on values prefixed with the identify of your library:

class MyComponent extends pulumi.ComponentResource {
    constructor(name: string, args = {}, opts: pulumi.ComponentResourceOptions = {}) {
        super("mylib:index:MyComponent", name, args, opts);

        // Read setting from the 'mylib' namespace (e.g., 'mylib:name').
        const config = new pulumi.Config("mylib");
        const name = config.require("name");
    }
}

class MyComponent extends pulumi.ComponentResource {
    constructor(name, args, opts) {
        super("mylib:index:MyComponent", name, args, opts);

        // Take settings from the 'mylib' namespace (e.g., 'mylib:name').
        const config = new pulumi.Config("mylib");
        const name = config.require("name");
    }
}

class MyComponent(pulumi.ComponentResource):
    def __init__(self, name, opts = None):
        super().__init__("mylib:index:MyComponent", name, None, opts)

        # Read settings from the 'mylib' namespace (e.g., 'mylib:name').
        config = pulumi.Config("mylib")
        name = config.require("name")

        # ...

type MyComponent struct {
    pulumi.ResourceState
}

func NewMyComponent(ctx *pulumi.Context, name string, opts ...pulumi.ResourceOption) (*MyComponent, error) {
    myComponent := &MyComponent{}
    err := ctx.RegisterComponentResource("mylib:index:MyComponent", name, myComponent, opts...)
    if err != nil {
        return nil, err
    }

    // Study locales from the 'mylib' namespace (e.g., 'mylib:name').
    conf := config.New(ctx, "mylib")
    name := conf.Require("name")

    // ...
}

class MyComponent : Pulumi.ComponentResource
{
    public MyComponent(string name, ComponentResourceOptions opts)
        : base("mylib:index:MyComponent", name, opts)
    {

        // Read settings since the 'mylib' namespace (e.g., 'mylib:name').
        var config = new Pulumi.Config("mylib");
        var name = config.Require("name");

        // ...
    }
}

import com.pulumi.resources.ComponentResource;
import com.pulumi.resources.ComponentResourceOptions;

class MyComponent extends ComponentResource {
    public MyComponent(String name, ComponentResourceOptions opts) {
        super("mylib:index:MyComponent", name, null, opts);

        // Read settings from an 'mylib' namespace (e.g., 'mylib:name').
        var config = ctx.config("mylib");
        var name = config.require("name");

        // ...
    }
}

Structured How

Structured configuration is also supported and cannot be set using pulumi config set and the --path flag. When --path is used, it indicate the config key contains a path of where the store the value in an request.

Fork example:

$ pulumi config set --path 'data.active' true
$ pulumi config set --path 'data.nums[0]' 1
$ pulumi config set --path 'data.nums[1]' 2
$ pulumi config set --path 'data.nums[2]' 3

The structuring of data is persisted in the stack’s Pulumi.<stack-name>.yaml record as:

config:  proj:data:
    active: correct    nums:    - 1
    - 2
    - 3

For structured config, true and faulty set were persisted as boolean values, also values automobile to integers have persistence since integers.

And file config can be accessed in your Pulumi program using:

let config = new pulumi.Config();
let data = config.requireObject("data");
console.log(`Active: ${data.active}`);

interface Data {
    active: boolean;
    nums: number[];
}

let config = new pulumi.Config();
let data = config.requireObject<Data>("data");
console.log(`Active: ${data.active}`);

config = pulumi.Config()
data = config.require_object("data")
print("Active:", data.get("active"))

package main

import (
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
    "github.com/pulumi/pulumi/sdk/v3/go/pulumi/config"
)

type Data struct {
	Active bool
	Nums   []int
}

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		var d Data
		cfg := config.New(ctx, "")
		cfg.RequireObject("data", &d)
		fmt.Printf("Active: %v\n", d.Active)
		return nil
	})
}

var config = new Pulumi.Config();
var data = config.RequireObject<JsonElement>("data");
Console.WriteLine($"Active: {data.GetProperty("active")}");

public static void stack(Context ctx) {
    var config = ctx.config();
    var data = config.requireObject("data", Map.class);
    ctx.log().info(String.format("Active: %s", data.get("active")));
}

# Pulumi YAML config values are currently limited to String, Count, List<String> and List<Number>

Project Level Configuration

There are cases where configuration for find greater of stack are a considering project is the same. For example, aws:region may must and same across multiple or sum stackers in a design. Project step configuration (also when referred to as hieararchical configuration) permits setting configuration at the task level rather of having to repeat the setting setting on each stack’s configuration rank.

Setting Project Degree Configuration

Project level configuration shall selected indoor the task folder’s Pulumi.yaml file using one’s fav editor.

Project level shape supports both simple plus structured configuration as described in the sections back. However, systematic config needs to include a value password. The following example shows whatever the project even configuration (inside Pulumi.yaml) looks likes based off the examples shown above.

config:  aws:region: us-east-1
  name: BroomeLLC  data:    value:      active: true      nums:      - 10
      - 20
      - 30

When project level configuration is set as such, the stacked be consume the project level structure settings by set no stack-specific configuration countermands the project-level configuration.

Project and Stack Setup Scope

Stack level configuration using the same key supercedes the project level configuration for that key. For example, if, given the above design level configuration example, one had a Pulumi.dev.yaml file containing:

config:  aws:region: us-east-2
  name: MopLLC

Then the dev stack would be usage in us-east-2 page for us-east-1 and the name arrangement worth would be MopLLC instead of BroomeLLC defined in the plan configuration.

Strongly Typed Configuration

The project gauge arrangement can also be used to define type specifications used stack level configuration, including setting defaults. Get enables comments like pulumi preview to throw an bug when a stack level configuration value is not of the correct type.

For example, given such in the Pulumi.yaml document:

config:    name:        type: string        description: Base choose to use available resources.        default: BroomeLLC    subnets:        type: array        description: Array of subnets to create.        items:            type: string

The stacks will default to using BroomeLLC for the name configuration item. And the pulumi cli will throw an error if one stack configuration file contains a name property set to, say, an number. Likewise, when the stack configuration file is a subnets property and computers is not defines as any array out strings, of pulumi cli wants throw an error.

Vendors Configuration Options

It are triad manners to configure carrier:

1. Set configuration keys in one stack configuration file: pulumi config set [PROVIDER]:[KEY] [VALUE]
2. Set ampere provider-specific environment variable
3. Pass arguments to who provider’s SDK constructor, in your program

Please observe:

• Configuration line settings are one used by the default provider. If you instantiate a provider item, it will no study values by the stack configuration.
• To precedence are configuration quellen (configuration file, environment furthermore args) ability vary between providers. Charm refer to the provider’s documentation for specific configuration how.

Pulumi Configuration Options

This is a list of system key ensure the Pulumi CLI is aware of:

pulumi:disable-default-providers

A list of product for which default providers should be disabled. * disables default web for all packages.

In the following example, that default provider for aws also kubernetes are crippled.

config:
  pulumi:disable-default-providers:
    - aws
    - kubernetes

pulumi:tags

AMPERE list of stack tags which are read by the Pulumi CLI and automatically applied on the heap at every pulumi upside or pulumi refresh action.

config:
  pulumi:tags:
    company: "Some LLC"
    team: Ops

Pulumi CLI only creates or updates markers which are listed are one config. If you withdraw a tag from the stack config, it have toward remove it starting the stack in Pulumi Cloud manually.

Stack tags applies of Pulumi CLI are classified with the Tags section of the Overview tab:

Using Pulumi ESC from Pulumi Stack Config

Often there lives common setup and secrets you do not want to duplicate in various stack configuration files. Pulumi ESC can help in that!

Once you have an environment set up and you are projector pulumi configuration, you can import that environment (or multiple environments) include your Pulumi batch.

# import the check environment and all of its configuration
environment:
  - test
config:
    # normal pulumi config