Update Config Concept Page

[toriancrane]

Proposed changes

This PR makes some quality of life updates to the Configuration concept page.

Related issues (optional)

Fixes #11235

[toriancrane]

@cnunciato Regarding this section I have the following questions:

• What does disabling default providers do? What are use cases in which this functionality is useful?
• ”Pulumi CLI only creates or updates tags which are listed in the config. If you remove a tag from the stack config, you have to remove it from the stack in Pulumi Cloud manually.” Do you happen to know why?

[cnunciato]

What does disabling default providers do?

It's worth trying this out yourself to see how it works. When you add this block to Pulumi.dev.yaml on an AWS project, for example:

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

...you'll get this error -- even when you've set all of your your AWS_* creds on your shell:

Diagnostics:
  aws:s3:Bucket (my-bucket):
    error: Default provider for 'aws' disabled. 'urn:pulumi:dev::aws-typescript-448b3d4::aws:s3/bucket:Bucket::my-bucket' must use an explicit provider.

So it seems that means the default (sometimes called the "ambient") provider won't be used, and you'll have to define an explicit one yourself -- e.g., using something like this:

import * as aws from "@pulumi/aws";

const provider = new aws.Provider("my-provider", {
    region: process.env.AWS_REGION as aws.Region,
    accessKey: process.env.AWS_ACCESS_KEY_ID,
    secretKey: process.env.AWS_SECRET_ACCESS_KEY,
    token: process.env.AWS_SESSION_TOKEN,
});

const bucket = new aws.s3.Bucket("my-bucket", {}, { provider });

What are use cases in which this functionality is useful?

I'd ask this in #questions, as I haven't ever done this myself.

"If you remove a tag from the stack config, you have to remove it from the stack in Pulumi Cloud manually.” Do you happen to know why?

IIRC it's because you can add tags in Pulumi Cloud as well. If the config file were the single source of truth, and the Cloud console were read-only, you wouldn't have to do this; you could remove the tag from the config, run Pulumi, and be done. But because you can set these tags in the UI as well, there's no way for the CLI to know whether to delete tags that exist remotely but not locally or just leave them alone. So it leaves them alone to avoid getting that wrong.

There might be more to it than that, but I think that's the gist.

[pulumi-bot]

Your site preview for commit edf442c is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-11886-edf442c0.s3-website.us-west-2.amazonaws.com.

[cnunciato]

Curious what's "better" about this change. Configuration being a core Pulumi feature that speaks directly to the need identified in the preceding paragraph, it seems important and valuable to make this clear right up front, as we do now. It's not just a recommendation over using environment variables -- it's fundamentally "the Pulumi way". (Particularly when it comes to the kinds of settings just described, where using environment variables would make much less sense.)

I'm sure there are improvements we could make to the content of this paragraph, but keeping this here as the main topic -- that Pulumi has a built-in system for managing differences like these -- seems super important and valuable to me. I don't see a benefit to removing this or pushing it farther down the page, as it's what this page is fundamentally about.

especially for multi-stack collaboration scenarios

Couple of notes on this phrasing and where it's located. First, when I read this, I'm left wondering two things:

• What exactly is a "multi-stack collaboration scenario"?
• How does "configuration" (which hasn't yet been defined) especially help me in this kind of scenario as as opposed to others?

It sounds like this is relevant, but it's not clear how. (I'm also not even sure it is relevant, since configuration is valuable in lots of scenarios that involve neither multiple stacks nor collaboration.)

Secondly, by positioning this phrase at the end of the paragraph like this, we're sort of inherently implying that the reader either knows what it means already (which I suspect many won't, as I wasn't sure myself) or will be told what it means at the beginning of the next paragraph, which doesn't happen here. So as a reader, I'm sort of left wondering what I'm supposed to take away from what I just read.

So we should probably explain both what this phrase means and why it's "especially" helpful when multiple people are collaborating on multiple projects. IMO we don't have to do this here (at the beginning of the page), as we're still very much in intro mode at this point, but it'd probably be good to flesh this out a bit farther down once we've established how it's useful in even the simplest (e.g, single-stack, single-human) scenarios.

[cnunciato]

IMO this doesn't quite work as a note, especially not at the top of the page like this. Users are likely to want to know whether and how to configure their stacks with environment variables, though, so we should probably give this topic its own heading (and farther down the page, as another way of configuring a program) and include examples in multiple languages (rather than just JS and Py) that show what that looks like.

which can also be used for dynamic behavior

What would an example of "dynamic behavior" be. It's not clear to me what this means.

Configuration is preferable, however, because it is designed for multi-stack collaborative scenarios.

It feels like this is just repeating the last part of the preceding paragraph.

[cnunciato]

You can typically ignore this file

I've never quite understood why we say "you can ignore these files", as you can't really ignore them -- they're important files, and understanding their significance is sort of fundamental to understanding and using the product. I'd argue we should just remove this line, or if not, replace it with something more practically accurate, like "You won't often edit this file by hand..." or the like. I don't think there's any benefit to telling people just to ignore these files, though. It just undermines their significance and implies they're "extra stuff", when they're anything but.

[cnunciato]

This phrasing -- "in addition to A, you can also B" -- suggests you can do B as well as A, which of course in this case you can't. (That is, you can't "create the pre-designated namespaces for default providers.") Since we've already covered using default and package namespaces, I'd just start the next paragraph by saying you can create your own:

To access a namespaced config value, you must pass the namespace to the constructor. [...] 

You can also define your own custom namespaces. For example, [...].

I also think it's important to point out that the recommendation here is for component authors to use namespaced configuration, not users. (Users actually have no choice.) The language (both here and in the previous version) muddies this a bit in that "working with configuration and components" could apply to either one. (Although to me, "working with" sounds more like it applies more to users than to authors.) It'd be clearer to say that component authors should use namespaced configuration, specifically to avoid naming collisions (e.g., accidentally reading configuration from the containing project), and that users must set those values using the namespaces defined and supplied by component authors.

A best practice [...] is to explicitly pass your namespace’s name to the Config constructor.

This is true (when "you" refers to the component author, and the task is reading from a namespace the author expects the component user to have used), but it's only part of the story. Three things must happen for all this to work:

• The author must write the component to read only from the component's custom namespace.
• The author must somehow tell the user (e.g., through documentation) what namespace to use.
• The user must use that namespace (e.g., with pulumi config set mylib:name).

We should complete the picture by making this clear. (I thought we talked about this on our call, but I might be misremembering.)

I'd also recommend that we point out somehow that the mylib string passed to super() here has nothing to do with the mechanics of configuration; it could be mycomponent and the config-related stuff would work just the same. Duplication like this can lead users to wonder whether the duplicated values must be the same or just happen to be, and in this case, they just happen to be. I'd therefore suggest we actually change that value from mylib to something else to eliminate this ambiguity.

[cnunciato]

What does disabling default providers do?

It's worth trying this out yourself to see how it works. When you add this block to Pulumi.dev.yaml on an AWS project, for example:

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

...you'll get this error -- even when you've set all of your your AWS_* creds on your shell:

Diagnostics:
  aws:s3:Bucket (my-bucket):
    error: Default provider for 'aws' disabled. 'urn:pulumi:dev::aws-typescript-448b3d4::aws:s3/bucket:Bucket::my-bucket' must use an explicit provider.

So it seems that means the default (sometimes called the "ambient") provider won't be used, and you'll have to define an explicit one yourself -- e.g., using something like this:

import * as aws from "@pulumi/aws";

const provider = new aws.Provider("my-provider", {
    region: process.env.AWS_REGION as aws.Region,
    accessKey: process.env.AWS_ACCESS_KEY_ID,
    secretKey: process.env.AWS_SECRET_ACCESS_KEY,
    token: process.env.AWS_SESSION_TOKEN,
});

const bucket = new aws.s3.Bucket("my-bucket", {}, { provider });

What are use cases in which this functionality is useful?

I'd ask this in #questions, as I haven't ever done this myself.

"If you remove a tag from the stack config, you have to remove it from the stack in Pulumi Cloud manually.” Do you happen to know why?

IIRC it's because you can add tags in Pulumi Cloud as well. If the config file were the single source of truth, and the Cloud console were read-only, you wouldn't have to do this; you could remove the tag from the config, run Pulumi, and be done. But because you can set these tags in the UI as well, there's no way for the CLI to know whether to delete tags that exist remotely but not locally or just leave them alone. So it leaves them alone to avoid getting that wrong.

There might be more to it than that, but I think that's the gist.

[cnunciato]

@toriancrane I spent some time with this page myself this morning and made a few notes for things to consider as we move through this. (Some overlap with the feedback I've left here, but not much.) Hope it helps!

https://docs.google.com/document/d/1wPc-JC9oA_BIGX3n18T2aJsD_EEO9azvurVTZbGCgR8/edit

[pulumi-bot]

Your site preview for commit ad73224 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-11886-ad73224f.s3-website.us-west-2.amazonaws.com.