mirror of https://github.com/pulumi/pulumi.git
9d0b0fed91
These changes add support for remapping environment variables when
launching providers. This allows users to work around problems with
dynamic provider configuration that is stored in statefiles causing
problems during refresh and destroy operations.
For a bit of background: `pulumi up` is distinctly different from
`pulumi destroy` and `pulumi refresh` in that it involves running the
Pulumi program associated with the stack's project. As it runs, the
Pulumi program defines the desired state for resources--including
provider resources--using values computed by the program in coordination
with the Pulumi engine. When the program creates a provider resource,
the inputs for the provider are either sourced from the program itself
(i.e. from values provided by the program) or are read out-of-band by
the provider plugin. The exact set of configuration that may be sourced
from the environment is particular to each provider--for example, the
Kubernetes provider uses the ambient `kubeconfig` by default, the AWS
provider reads various AWS-specific environment variables, etc. Any
_explicitly-provided inputs_ are written into the stack's statefile.
For example, consider the following program:
```typescript
import * as aws from "@pulumi/aws";
const usEast1 = new aws.Provider("us-east-1", { region: "us-east-1" });
const defaultRegion = new aws.Provider("default-region");
```
The `usEast1` provider's `region` is explicitly specified by the
program, but the `defaultRegion` provider's `region` will be read from
the environment (e.g. from the `AWS_REGION` environment variable). In
the resulting statefile, the `usEast1` provider's state will include the
`region` input, but the `defaultRegion` provider's state will not.
Because `pulumi refresh` and `pulumi destroy` do not run the Pulumi
program associated with the stack's project, they are unable to
recompute configuration values that were explicitly provided by the
program, and must use the values stored in the statefile. Unfortunately,
this may include credential information, which is what causes the errors
described here. The current workaround--which is certainly not
sufficient for explicitly-instantiated providers--is to use environment
variables to provide credentials out-of-band.
The clearest/most complete solution here is to run the Pulumi program
associated with a stack's project as part of `pulumi refresh` and
`pulumi destroy`. Unfortunately, this is a _major_ behavioral change,
and the exact semantics of the run are not clear.
These changes allow explicitly-instantiated providers to make use of the
same workaround that is available to default providers: pass dynamic,
environmentally-sourced provider configuration in environment variables
rather than as provider inputs. The environment variable remapping allows
users to replace the value for a provider environment variable with the
value of a different environment variable before the provider is loaded.
This allows users to place configuration in environment variables that
the provider would not normally read and remap them to
provider-supported envvars, which allows multiple distinct sets of
environment variables for providers.
For the example above, this might look like so:
```typescript
import * as aws from "@pulumi/aws";
const usEast1 = new aws.Provider("us-east-1", {
pluginEnvVars: { "AWS_REGION": { from: "US_EAST_1_REGION" } },
});
const defaultRegion = new aws.Provider("default-region");
```
Or, if the providers needed different credentials (much more common):
```typescript
import * as aws from "@pulumi/aws";
const usEast1 = new aws.Provider("us-east-1", {
pluginEnvVars: {
"AWS_ACCESS_KEY_ID": { from: "US_EAST_1_AWS_ACCESS_KEY_ID" },
"AWS_SECRET_ACCESS_KEY": { from: "US_EAST_1_AWS_SECRET_ACCESS_KEY" },
"AWS_SESSION_TOKEN": { from: "US_EAST_1_AWS_SESSION_TOKEN" },
},
});
const defaultRegion = new aws.Provider("default-region");
```
|
||
|---|---|---|
| .. | ||
| cgstrings | ||
| convert | ||
| docs | ||
| dotnet | ||
| gen_program_test | ||
| go | ||
| hcl2 | ||
| nodejs | ||
| pcl | ||
| python | ||
| report | ||
| schema | ||
| testing | ||
| README.md | ||
| docs.go | ||
| docs_test.go | ||
| utilities.go | ||
| utilities_test.go | ||
| utilities_types.go | ||
README.md
Pulumi CrossCode
The github.com/pulumi/pulumi/pkg/v3/codegen package defines the core components of Pulumi's CrossCode technology. CrossCode provides a set of foundational capabilities for working across a variety of programming languages supported by the Pulumi platform.
The core components of CrossCode in this package are:
- Schema: The definition of Pulumi Schema, a language-neutral specification of cloud resource models. Pulumi Schema is the interface definition language for all Pulumi Packages, and is used as input to SDK code generation for each supported Pulumi language.
- SDK Code Generation for Node.js, Python, Go and .NET: These libraries define how to create Pulumi SDKs from a Pulumi Schema definition of a package. The resulting SDKs expose the resource, components and functions from that package into the the Pulumi programming model defined for the given language.
- Docs Generation: In addition to generating per-language SDKs, CrossCode supports generating language-neutral documentation for a package from it's Pulumi Schema. This documentation is currently hosted in the Pulumi Registry, but can in principle be hosted in other contexts as well.
- Pulumi Configuration Language: An internal representation of Pulumi programs which supports all core concepts of the Pulumi programming model in a minimal form. Although not exposed directly to users today, this intermediate representation is used to support a variety of program conversion tasks, from and to various supported Pulumi languages.
- Program Generation for Node.js, Python, Go and .NET: Support for lowering Pulumi Configuration Language into each of the supported Pulumi languages, such that examples and programs can be generated for the language.
These foundations enable a vast array of features supported in the Pulumi Platform, including:
- Pulumi support for Node.js, Python, Go, .NET, Java and YAML: Each Pulumi language is supported by defining a representation of the Pulumi resource model in that language, and then implementing SDK Code Generation and Program Generation for the language.
- Pulumi Packages: Pulumi packages define a set of resources using Pulumi Schema, and use the CrossCode SDK Code Generators for every Pulumi language automatically.
pulumi import: Cloud infrastructure resources deployed outside of Pulumi can be imported into Pulumi, including generated Pulumi code in your language of choice which defines the infrastructure. This builds on the program generation support from CrossCode.- tf2pulumi, arm2pulumi, crd2pulumi, kube2pulumi and cf2pulumi: These tools convert the source IaC format into an intermediate Pulumi Configuration Language model, and then use the CrossCode program generation support to convert that ultimately into the language a Pulumi user wants to use for their infrastructure.
pulumi convert: Thepulumi convertcommand allows Pulumi YAML programs to be converted into programs in any other Pulumi language. Because Pulumi YAML is a proper subset of what can be expressed in Pulumi Configuration Language, this conversion from Pulumi YAML to Pulumi Configuration Language and then into each Pulumi language can be done faithfully.- Pulumi Registry: The Pulumi Registry provides discovery and documentation hosting for all Pulumi Packages. It is powered by the Pulumi Schema and CrossCode documentation generation features.
Learn more about Pulumi CrossCode at https://www.pulumi.com/crosscode/.