Package @pulumi/pulumi

Pulumi Node.js SDK

The Pulumi Node.js SDK lets you write cloud programs in JavaScript.

Installation

Using npm:

$ npm install --save @pulumi/pulumi

Using yarn:

$ yarn add @pulumi/pulumi

This SDK is meant for use with the Pulumi CLI. Please visit pulumi.com for installation instructions.

Building and Testing

For anybody who wants to build from source, here is how you do it.

Prerequisites

This SDK uses Node.js and we support the Active LTS and Current releases, as defined by this table. We support both NPM and Yarn for package management.

At the moment, we only support building on macOS and Linux, where standard GNU tools like make are available.

Make Targets

The first time you build, run make ensure to install and prepare native plugins for V8:

$ make ensure

This is only necessary if you intend to produce a build that is capable of running older versions of the SDK contained in this directory. If you do intend to do this, you must have node 6.10.2 installed.

To build the SDK, simply run make from the root directory (where this README lives, at sdk/nodejs/ from the repo’s root). This will build the code, run tests, and install the package and its supporting artifacts.

At the moment, for local development, we install everything into /opt/pulumi. You will want this on your $PATH.

The tests will verify that everything works, but feel free to try running pulumi preview and/or pulumi up from the examples/minimal/ directory. Remember to run tsc first, since pulumi expects JavaScript, not TypeScript.

var pulumi = require("@pulumi/pulumi");
import * as pulumi from "@pulumi/pulumi";

Modules

Resources

Others

Resources

Resource ComponentResource

class ComponentResource extends Resource

ComponentResource is a resource that aggregates one or more other child resources into a higher level abstraction. The component resource itself is a resource, but does not require custom CRUD operations for provisioning.

constructor

new ComponentResource(type: string, name: string, unused?: Inputs, opts: ComponentResourceOptions)

Creates and registers a new component resource. [type] is the fully qualified type token and [name] is the “name” part to use in creating a stable and globally unique URN for the object. [opts.parent] is the optional parent for this component, and [opts.dependsOn] is an optional list of other resources that this resource depends on, controlling the order in which we perform resource operations.

  • name The unique name of the resource.
  • unused . Component resources do not communicate or store their properties with the Pulumi engine.
  • opts A bag of options that control this resource's behavior.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): boolean

Returns true if the given object is an instance of CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

method registerOutputs

protected registerOutputs(outputs?: Inputs | Promise<Inputs> | Output<Inputs>): void

property urn

public urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

Resource CustomResource

class CustomResource extends Resource

CustomResource is a resource whose create, read, update, and delete (CRUD) operations are managed by performing external operations on some physical entity. The engine understands how to diff and perform partial updates of them, and these CRUD operations are implemented in a dynamically loaded plugin for the defining package.

constructor

new CustomResource(t: string, name: string, props?: Inputs, opts: CustomResourceOptions)

Creates and registers a new managed resource. t is the fully qualified type token and name is the “name” part to use in creating a stable and globally unique URN for the object. dependsOn is an optional list of other resources that this resource depends on, controlling the order in which we perform resource operations. Creating an instance does not necessarily perform a create on the physical entity which it represents, and instead, this is dependent upon the diffing of the new goal state compared to the current known resource state.

  • t The type of the resource.
  • name The unique name of the resource.
  • props The arguments to use to populate the new resource.
  • opts A bag of options that control this resource's behavior.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): boolean

Returns true if the given object is an instance of CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

property id

public id: Output<ID>;

id is the provider-assigned unique ID for this managed resource. It is set during deployments and may be missing (undefined) during planning phases.

property urn

public urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

Resource ProviderResource

class ProviderResource extends CustomResource

ProviderResource is a resource that implements CRUD operations for other custom resources. These resources are managed similarly to other resources, including the usual diffing and update semantics.

constructor

new ProviderResource(pkg: string, name: string, props?: Inputs, opts: ResourceOptions)

Creates and registers a new provider resource for a particular package.

  • pkg The package associated with this provider.
  • name The unique name of the provider.
  • props The configuration to use for this provider.
  • opts A bag of options that control this provider's behavior.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): boolean

Returns true if the given object is an instance of CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

method register

public static register(provider: ProviderResource | undefined): Promise<string | undefined>

property id

public id: Output<ID>;

id is the provider-assigned unique ID for this managed resource. It is set during deployments and may be missing (undefined) during planning phases.

property urn

public urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

Resource Resource

class Resource

Resource represents a class whose CRUD operations are implemented by a provider plugin.

constructor

new Resource(t: string, name: string, custom: boolean, props: Inputs, opts: ResourceOptions)

Creates and registers a new resource object. [t] is the fully qualified type token and [name] is the “name” part to use in creating a stable and globally unique URN for the object. dependsOn is an optional list of other resources that this resource depends on, controlling the order in which we perform resource operations.

  • t The type of the resource.
  • name The unique name of the resource.
  • custom True to indicate that this is a custom resource, managed by a plugin.
  • props The arguments to use to populate the new resource.
  • opts A bag of options that control this resource's behavior.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): boolean

property urn

public urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

Resource StackReference

class StackReference extends CustomResource

Manages a reference to a Pulumi stack. The referenced stack’s outputs are available via the outputs property or the output method.

constructor

new StackReference(name: string, args?: StackReferenceArgs, opts?: CustomResourceOptions)

Create a StackReference resource with the given unique name, arguments, and options.

If args is not specified, the name of the referenced stack will be the name of the StackReference resource.

  • name The unique name of the stack reference.
  • args The arguments to use to populate this resource's properties.
  • opts A bag of options that control this resource's behavior.

method getOutput

public getOutput(name: Input<string>): Output<any>

Fetches the value of the named stack output, or undefined if the stack output was not found.

method getOutputSync

public getOutputSync(name: string): any

Fetches the value promptly of the named stack output. May return undefined if the value is not known for some reason.

This operation is not supported (and will throw) if any exported values of the StackReference are secrets.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): boolean

Returns true if the given object is an instance of CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

method requireOutput

public requireOutput(name: Input<string>): Output<any>

Fetches the value of the named stack output, or throws an error if the output was not found.

method requireOutputSync

public requireOutputSync(name: string): any

Fetches the value promptly of the named stack output. Throws an error if the stack output is not found.

This operation is not supported (and will throw) if any exported values of the StackReference are secrets.

property id

public id: Output<ID>;

id is the provider-assigned unique ID for this managed resource. It is set during deployments and may be missing (undefined) during planning phases.

property name

public name: Output<string>;

The name of the referenced stack.

property outputs

public outputs: Output<{[name: string]: any}>;

The outputs of the referenced stack.

property secretOutputNames

public secretOutputNames: Output<string[]>;

The names of any stack outputs which contain secrets.

property urn

public urn: Output<URN>;

urn is the stable logical URN used to distinctly address a resource, both before and after deployments.

Others

interface Alias

interface Alias

Alias is a partial description of prior named used for a resource. It can be processed in the context of a resource creation to determine what the full aliased URN would be.

Note there is a semantic difference between properties being absent from this type and properties having the undefined value. Specifically, there is a difference between:

{ name: "foo", parent: undefined } // and
{ name: "foo" }

The presence of a property indicates if its value should be used. If absent, then the value is not used. So, in the above while alias.parent is undefined for both, the first alias means “the original urn had no parent” while the second alias means “use the current parent”.

Note: to indicate that a resource was previously parented by the root stack, it is recommended that you use:

aliases: [{ parent: pulumi.rootStackResource }]

This form is self-descriptive and makes the intent clearer than using:

aliases: [{ parent: undefined }]

property name

name?: Input<string>;

The previous name of the resource. If not provided, the current name of the resource is used.

property parent

parent?: Resource | Input<URN>;

The previous parent of the resource. If not provided (i.e. { name: "foo" }), the current parent of the resource is used (opts.parent if provided, else the implicit stack resource parent).

To specify no original parent, use { parent: pulumi.rootStackResource }.

property project

project?: Input<string>;

The previous project of the resource. If not provided, defaults to pulumi.getProject().

property stack

stack?: Input<string>;

The previous stack of the resource. If not provided, defaults to pulumi.getStack().

property type

type?: Input<string>;

The previous type of the resource. If not provided, the current type of the resource is used.

function all

all<T>(val: Record<string, Input<T>>): Output<Record<string, Unwrap<T>>>

Allows for multiple Output objects to be combined into a single Output object. The single Output will depend on the union of Resources that the individual dependencies depend on.

This can be used in the following manner:

var d1: Output<string>;
var d2: Output<number>;

var d3: Output<ResultType> = Output.all([d1, d2]).apply(([s, n]) => ...);

In this example, taking a dependency on d3 means a resource will depend on all the resources of d1 and d2.

all<T1,T2,T3,T4,T5,T6,T7,T8>(values: [, Input<T1> | undefined, Input<T2> | undefined, Input<T3> | undefined, Input<T4> | undefined, Input<T5> | undefined, Input<T6> | undefined, Input<T7> | undefined, Input<T8> | undefined]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>, Unwrap<T5>, Unwrap<T6>, Unwrap<T7>, Unwrap<T8>]>
all<T1,T2,T3,T4,T5,T6,T7>(values: [, Input<T1> | undefined, Input<T2> | undefined, Input<T3> | undefined, Input<T4> | undefined, Input<T5> | undefined, Input<T6> | undefined, Input<T7> | undefined]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>, Unwrap<T5>, Unwrap<T6>, Unwrap<T7>]>
all<T1,T2,T3,T4,T5,T6>(values: [, Input<T1> | undefined, Input<T2> | undefined, Input<T3> | undefined, Input<T4> | undefined, Input<T5> | undefined, Input<T6> | undefined]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>, Unwrap<T5>, Unwrap<T6>]>
all<T1,T2,T3,T4,T5>(values: [, Input<T1> | undefined, Input<T2> | undefined, Input<T3> | undefined, Input<T4> | undefined, Input<T5> | undefined]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>, Unwrap<T5>]>
all<T1,T2,T3,T4>(values: [, Input<T1> | undefined, Input<T2> | undefined, Input<T3> | undefined, Input<T4> | undefined]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>]>
all<T1,T2,T3>(values: [, Input<T1> | undefined, Input<T2> | undefined, Input<T3> | undefined]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>]>
all<T1,T2>(values: [, Input<T1> | undefined, Input<T2> | undefined]): Output<[, Unwrap<T1>, Unwrap<T2>]>
all<T>(ds: undefined | T | Promise<T> | OutputInstance<T>[]): Output<Unwrap<T>[]>

interface ComponentResourceOptions

interface ComponentResourceOptions extends ResourceOptions

ComponentResourceOptions is a bag of optional settings that control a component resource’s behavior.

property aliases

aliases?: Input<URN | Alias>[];

An optional list of aliases to treat this resource as matching.

property customTimeouts

customTimeouts?: CustomTimeouts;

An optional customTimeouts configuration block.

property dependsOn

dependsOn?: Input<Input<Resource>[]> | Input<Resource>;

An optional additional explicit dependencies on other resources.

property id

id?: Input<ID>;

An optional existing ID to load, rather than create.

property ignoreChanges

ignoreChanges?: string[];

Ignore changes to any of the specified properties.

property parent

parent?: Resource;

An optional parent resource to which this resource belongs.

property protect

protect?: undefined | false | true;

When set to true, protect ensures this resource cannot be deleted.

property provider

provider?: ProviderResource;

An optional provider to use for this resource’s CRUD operations. If no provider is supplied, the default provider for the resource’s package will be used. The default provider is pulled from the parent’s provider bag (see also ComponentResourceOptions.providers).

If this is a [ComponentResourceOptions] do not provide both [provider] and [providers]

property providers

providers?: Record<string, ProviderResource> | ProviderResource[];

An optional set of providers to use for child resources. Either keyed by package name (e.g. “aws”), or just provided as an array. In the latter case, the package name will be retrieved from the provider itself.

In the case of a single provider, the options can be simplified to just pass along provider: theProvider

Note: do not provide both [provider] and [providers];

property transformations

transformations?: ResourceTransformation[];

Optional list of transformations to apply to this resource during construction. The transformations are applied in order, and are applied prior to transformation applied to parents walking from the resource up to the stack.

property version

version?: undefined | string;

An optional version, corresponding to the version of the provider plugin that should be used when operating on this resource. This version overrides the version information inferred from the current package and should rarely be used.

function concat

concat(params: Input<any>[]): Output<string>

[concat] takes a sequence of [Inputs], stringifies each, and concatenates all values into one final string. Individual inputs can be any sort of [Input] value. i.e. they can be [Promise]s, [Output]s, or just plain JavaScript values. This can be used like so:

     // 'server' and 'loadBalancer' are both resources that expose [Output] properties.
     let val: Output<string> = pulumi.concat("http://", server.hostname, ":", loadBalancer.port);

class Config

class Config

Config is a bag of related configuration state. Each bag contains any number of configuration variables, indexed by simple keys, and each has a name that uniquely identifies it; two bags with different names do not share values for variables that otherwise share the same key. For example, a bag whose name is pulumi:foo, with keys a, b, and c, is entirely separate from a bag whose name is pulumi:bar with the same simple key names. Each key has a fully qualified names, such as pulumi:foo:a, …, and pulumi:bar:a, respectively.

constructor

new Config(name?: undefined | string)

method get

public get<K>(key: string, opts?: StringConfigOptions<K>): K | undefined

get loads an optional configuration value by its key, or undefined if it doesn’t exist.

method getBoolean

public getBoolean(key: string): boolean | undefined

getBoolean loads an optional configuration value, as a boolean, by its key, or undefined if it doesn’t exist. If the configuration value isn’t a legal boolean, this function will throw an error.

method getNumber

public getNumber(key: string, opts?: NumberConfigOptions): number | undefined

getNumber loads an optional configuration value, as a number, by its key, or undefined if it doesn’t exist. If the configuration value isn’t a legal number, this function will throw an error.

method getObject

public getObject<T>(key: string): T | undefined

getObject loads an optional configuration value, as an object, by its key, or undefined if it doesn’t exist. This routine simply JSON parses and doesn’t validate the shape of the contents.

method getSecret

public getSecret<K>(key: string, opts?: StringConfigOptions<K>): Output<K> | undefined

getSecret loads an optional configuration value by its key, marking it as a secret, or undefined if it doesn’t exist.

method getSecretBoolean

public getSecretBoolean(key: string): Output<boolean> | undefined

getSecretBoolean loads an optional configuration value, as a boolean, by its key, making it as a secret or undefined if it doesn’t exist. If the configuration value isn’t a legal boolean, this function will throw an error.

method getSecretNumber

public getSecretNumber(key: string, opts?: NumberConfigOptions): Output<number> | undefined

getSecretNumber loads an optional configuration value, as a number, by its key, marking it as a secret or undefined if it doesn’t exist. If the configuration value isn’t a legal number, this function will throw an error.

method getSecretObject

public getSecretObject<T>(key: string): Output<T> | undefined

getSecretObject loads an optional configuration value, as an object, by its key, marking it as a secret or undefined if it doesn’t exist. This routine simply JSON parses and doesn’t validate the shape of the contents.

method require

public require<K>(key: string, opts?: StringConfigOptions<K>): K

require loads a configuration value by its given key. If it doesn’t exist, an error is thrown.

method requireBoolean

public requireBoolean(key: string): boolean

requireBoolean loads a configuration value, as a boolean, by its given key. If it doesn’t exist, or the configuration value is not a legal boolean, an error is thrown.

method requireNumber

public requireNumber(key: string, opts?: NumberConfigOptions): number

requireNumber loads a configuration value, as a number, by its given key. If it doesn’t exist, or the configuration value is not a legal number, an error is thrown.

method requireObject

public requireObject<T>(key: string): T

requireObject loads a configuration value as a JSON string and deserializes the JSON into a JavaScript object. If it doesn’t exist, or the configuration value is not a legal JSON string, an error is thrown.

method requireSecret

public requireSecret<K>(key: string, opts?: StringConfigOptions<K>): Output<K>

require loads a configuration value by its given key, marking it as a secet. If it doesn’t exist, an error is thrown.

method requireSecretBoolean

public requireSecretBoolean(key: string): Output<boolean>

requireSecretBoolean loads a configuration value, as a boolean, by its given key, marking it as a secret. If it doesn’t exist, or the configuration value is not a legal boolean, an error is thrown.

method requireSecretNumber

public requireSecretNumber(key: string, opts?: NumberConfigOptions): Output<number>

requireSecretNumber loads a configuration value, as a number, by its given key, marking it as a secret. If it doesn’t exist, or the configuration value is not a legal number, an error is thrown.

method requireSecretObject

public requireSecretObject<T>(key: string): Output<T>

requireSecretObject loads a configuration value as a JSON string and deserializes the JSON into a JavaScript object, marking it as a secret. If it doesn’t exist, or the configuration value is not a legal JSON string, an error is thrown.

property name

public name: string;

name is the configuration bag’s logical name and uniquely identifies it. The default is the name of the current project.

function createUrn

createUrn(name: Input<string>, type: Input<string>, parent?: Resource | Input<URN>, project?: undefined | string, stack?: undefined | string): Output<string>

createUrn computes a URN from the combination of a resource name, resource type, optional parent, optional project and optional stack.

interface CustomResourceOptions

interface CustomResourceOptions extends ResourceOptions

CustomResourceOptions is a bag of optional settings that control a custom resource’s behavior.

property additionalSecretOutputs

additionalSecretOutputs?: string[];

The names of outputs for this resource that should be treated as secrets. This augments the list that the resource provider and pulumi engine already determine based on inputs to your resource. It can be used to mark certain ouputs as a secrets on a per resource basis.

property aliases

aliases?: Input<URN | Alias>[];

An optional list of aliases to treat this resource as matching.

property customTimeouts

customTimeouts?: CustomTimeouts;

An optional customTimeouts configuration block.

property deleteBeforeReplace

deleteBeforeReplace?: undefined | false | true;

When set to true, deleteBeforeReplace indicates that this resource should be deleted before its replacement is created when replacement is necessary.

property dependsOn

dependsOn?: Input<Input<Resource>[]> | Input<Resource>;

An optional additional explicit dependencies on other resources.

property id

id?: Input<ID>;

An optional existing ID to load, rather than create.

property ignoreChanges

ignoreChanges?: string[];

Ignore changes to any of the specified properties.

property import

import?: ID;

When provided with a resource ID, import indicates that this resource’s provider should import its state from the cloud resource with the given ID. The inputs to the resource’s constructor must align with the resource’s current state. Once a resource has been imported, the import property must be removed from the resource’s options.

property parent

parent?: Resource;

An optional parent resource to which this resource belongs.

property protect

protect?: undefined | false | true;

When set to true, protect ensures this resource cannot be deleted.

property provider

provider?: ProviderResource;

An optional provider to use for this resource’s CRUD operations. If no provider is supplied, the default provider for the resource’s package will be used. The default provider is pulled from the parent’s provider bag (see also ComponentResourceOptions.providers).

If this is a [ComponentResourceOptions] do not provide both [provider] and [providers]

property transformations

transformations?: ResourceTransformation[];

Optional list of transformations to apply to this resource during construction. The transformations are applied in order, and are applied prior to transformation applied to parents walking from the resource up to the stack.

property version

version?: undefined | string;

An optional version, corresponding to the version of the provider plugin that should be used when operating on this resource. This version overrides the version information inferred from the current package and should rarely be used.

interface CustomTimeouts

interface CustomTimeouts

property create

create?: undefined | string;

The optional create timeout represented as a string e.g. 5m, 40s, 1d.

property delete

delete?: undefined | string;

The optional delete timeout represented as a string e.g. 5m, 40s, 1d.

property update

update?: undefined | string;

The optional update timeout represented as a string e.g. 5m, 40s, 1d.

function getProject

getProject(): string

getProject returns the current project name. It throws an exception if none is registered.

function getStack

getStack(): string

getStack returns the current stack name. It throws an exception if none is registered.

type ID

type ID = string;

type Input

type Input = T | Promise<T> | OutputInstance<T>;

[Input] is a property input for a resource. It may be a promptly available T, a promise for one, or the output from a existing Resource.

type Inputs

type Inputs = Record<string, Input<any>>;

[Inputs] is a map of property name to property input, one for each resource property value.

function interpolate

interpolate(literals: TemplateStringsArray, placeholders: Input<any>[]): Output<string>

[interpolate] is similar to [concat] but is designed to be used as a tagged template expression. i.e.:

     // 'server' and 'loadBalancer' are both resources that expose [Output] properties.
     let val: Output<string> = pulumi.interpolate `http://${server.hostname}:${loadBalancer.port}`

As with [concat] the ‘placeholders’ between ${} can be any Inputs. i.e. they can be [Promise]s, [Output]s, or just plain JavaScript values.

type Lifted

type Lifted = Lifted;

The [Lifted] type allows us to express the operation of taking a type, with potentially deeply nested objects and arrays and to then get a type with the same properties, except whose property types are now [Output]s of the original property type.

For example:

 `type X = { A: string, B: { c: boolean } }`

Then Lifted<X> would be equivalent to:

 `...    = { A: Output<string>, B: Output<{ C: Output<boolean> }> }`

[Lifted] is somewhat the opposite of [Unwrap]. It’s primary purpose is to allow an instance of [Output] to provide simple access to the properties of [SomeType] directly on the instance itself (instead of haveing to use [.apply]).

This lifting only happens through simple pojo objects and arrays. Functions, for example, are not lifted. So you cannot do:

     const o: Output<string> = ...;
     const c: Output<number> = o.charCodeAt(0);

Instead, you still need to write;

     const o: Output<string> = ...;
     const c: Output<number> = o.apply(v => v.charCodeAt(0));

type LiftedArray

type LiftedArray = {
    length: Output<number>;
};

type LiftedObject

type LiftedObject = { ... };

function liftProperties

liftProperties<T>(promise: Promise<T>, opts: InvokeOptions): Promise<T> & T

No longer supported. This function is now a no-op and will directly return the promise passed into it.

This is an advanced compat function for libraries and should not generally be used by normal Pulumi application.

function mergeOptions

mergeOptions(opts1: CustomResourceOptions | undefined, opts2: CustomResourceOptions | undefined): CustomResourceOptions

[mergeOptions] takes two ResourceOptions values and produces a new ResourceOptions with the respective properties of opts2 merged over the same properties in opts1. The original options objects will be unchanged.

Conceptually property merging follows these basic rules: 1. if the property is a collection, the final value will be a collection containing the values from each options object. 2. Simple scaler values from opts2 (i.e. strings, numbers, bools) will replace the values of opts1. 3. opts2 can have properties explicitly provided with null or undefined as the value. If explicitly provided, then that will be the final value in the result. 4. For the purposes of merging dependsOn, provider and providers are always treated as collections, even if only a single value was provided.

mergeOptions(opts1: ComponentResourceOptions | undefined, opts2: ComponentResourceOptions | undefined): ComponentResourceOptions
mergeOptions(opts1: ResourceOptions | undefined, opts2: ResourceOptions | undefined): ResourceOptions

type Output

type Output = OutputInstance<T> & Lifted<T>;

[Output] helps encode the relationship between Resources in a Pulumi application. Specifically an [Output] holds onto a piece of Data and the Resource it was generated from. An [Output] value can then be provided when constructing new Resources, allowing that new Resource to know both the value as well as the Resource the value came from. This allows for a precise ‘Resource dependency graph’ to be created, which properly tracks the relationship between resources.

An [Output] is used in a Pulumi program differently depending on if the application is executing at ‘deployment time’ (i.e. when actually running the ‘pulumi’ executable), or at ‘run time’ (i.e. a piece of code running in some Cloud).

At ‘deployment time’, the correct way to work with the underlying value is to call [Output.apply(func)]. This allows the value to be accessed and manipulated, while still resulting in an [Output] that is keeping track of [Resource]s appropriately. At deployment time the underlying value may or may not exist (for example, if a preview is being performed). In this case, the ‘func’ callback will not be executed, and calling [.apply] will immediately return an [Output] that points to the [undefined] value. During a normal [update] though, the ‘func’ callbacks should always be executed.

At ‘run time’, the correct way to work with the underlying value is to simply call [Output.get] which will be promptly return the entire value. This will be a simple JavaScript object that can be manipulated as necessary.

To ease with using [Output]s at ‘deployment time’, pulumi will ‘lift’ simple data properties of an underlying value to the [Output] itself. For example:

     const o: Output<{ name: string, age: number, orders: Order[] }> = ...;
     const name : Output<string> = o.name;
     const age  : Output<number> = o.age;
     const first: Output<Order>  = o.orders[0];

Instead of having to write:

     const o: Output<{ name: string, age: number, orders: Order[] }> = ...;
     const name : Output<string> = o.apply(v => v.name);
     const age  : Output<number> = o.apply(v => v.age);
     const first: Output<Order> = o.apply(v => v.orders[0]);

function output

output<T>(val: Input<T>): Output<Unwrap<T>>

[output] takes any Input value and converts it into an Output, deeply unwrapping nested Input values as necessary.

The expected way to use this function is like so:

     var transformed = pulumi.output(someVal).apply(unwrapped => {
         // Do whatever you want now.  'unwrapped' will contain no outputs/promises inside
         // here, so you can easily do whatever sort of transformation is most convenient.
     });

     // the result can be passed to another Resource.  The dependency information will be
     // properly maintained.
     var someResource = new SomeResource(name, { data: transformed ... });
output<T>(val: Input<T> | undefined): Output<Unwrap<T | undefined>>

interface OutputConstructor

interface OutputConstructor

Static side of the [Output] type. Can be used to [create] Outputs as well as test arbitrary values to see if they are [Output]s.

method create

create<T>(val: Input<T>): Output<Unwrap<T>>
create<T>(val: Input<T> | undefined): Output<Unwrap<T | undefined>>

method isInstance

isInstance<T>(obj: any): boolean

interface OutputInstance

interface OutputInstance

Instance side of the [Output] type. Exposes the deployment-time and run-time mechanisms for working with the underlying value of an [Output].

method apply

apply<U>(func: (t: T) => Promise<U>): Output<U>

Transforms the data of the output with the provided func. The result remains a Output so that dependent resources can be properly tracked.

‘func’ is not allowed to make resources.

‘func’ can return other Outputs. This can be handy if you have a Output and you want to get a transitive dependency of it. i.e.

var d1: Output<SomeVal>;
var d2 = d1.apply(v => v.x.y.OtherOutput); // getting an output off of 'v'.

In this example, taking a dependency on d2 means a resource will depend on all the resources of d1. It will not depend on the resources of v.x.y.OtherDep.

Importantly, the Resources that d2 feels like it will depend on are the same resources as d1. If you need have multiple Outputs and a single Output is needed that combines both set of resources, then ‘pulumi.all’ should be used instead.

This function will only be called execution of a ‘pulumi up’ request. It will not run during ‘pulumi preview’ (as the values of resources are of course not known then). It is not available for functions that end up executing in the cloud during runtime. To get the value of the Output during cloud runtime execution, use get().

apply<U>(func: (t: T) => OutputInstance<U>): Output<U>
apply<U>(func: (t: T) => U): Output<U>

method get

get(): T

Retrieves the underlying value of this dependency.

This function is only callable in code that runs in the cloud post-deployment. At this point all Output values will be known and can be safely retrieved. During pulumi deployment or preview execution this must not be called (and will throw). This is because doing so would allow Output values to flow into Resources while losing the data that would allow the dependency graph to be changed.

class ResourceError

class ResourceError extends Error

ResourceError can be used for terminating a program abruptly, specifically associating the problem with a Resource. Depending on the nature of the problem, clients can choose whether or not a call stack should be returned as well. This should be very rare, and would only indicate no usefulness of presenting that stack to the user.

constructor

new ResourceError(message: string, resource: Resource | undefined, hideStack?: undefined | false | true)

method isInstance

public static isInstance(obj: any): boolean

Returns true if the given object is an instance of a ResourceError. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

property Error

static Error: ErrorConstructor;

property hideStack

public hideStack?: undefined | false | true;

property message

message: string;

property name

name: string;

property resource

public resource: Resource | undefined;

property stack

stack?: undefined | string;

interface ResourceOptions

interface ResourceOptions

ResourceOptions is a bag of optional settings that control a resource’s behavior.

property aliases

aliases?: Input<URN | Alias>[];

An optional list of aliases to treat this resource as matching.

property customTimeouts

customTimeouts?: CustomTimeouts;

An optional customTimeouts configuration block.

property dependsOn

dependsOn?: Input<Input<Resource>[]> | Input<Resource>;

An optional additional explicit dependencies on other resources.

property id

id?: Input<ID>;

An optional existing ID to load, rather than create.

property ignoreChanges

ignoreChanges?: string[];

Ignore changes to any of the specified properties.

property parent

parent?: Resource;

An optional parent resource to which this resource belongs.

property protect

protect?: undefined | false | true;

When set to true, protect ensures this resource cannot be deleted.

property provider

provider?: ProviderResource;

An optional provider to use for this resource’s CRUD operations. If no provider is supplied, the default provider for the resource’s package will be used. The default provider is pulled from the parent’s provider bag (see also ComponentResourceOptions.providers).

If this is a [ComponentResourceOptions] do not provide both [provider] and [providers]

property transformations

transformations?: ResourceTransformation[];

Optional list of transformations to apply to this resource during construction. The transformations are applied in order, and are applied prior to transformation applied to parents walking from the resource up to the stack.

property version

version?: undefined | string;

An optional version, corresponding to the version of the provider plugin that should be used when operating on this resource. This version overrides the version information inferred from the current package and should rarely be used.

type ResourceTransformation

type ResourceTransformation = (args: ResourceTransformationArgs) => ResourceTransformationResult | undefined;

ResourceTransformation is the callback signature for the transformations resource option. A transformation is passed the same set of inputs provided to the Resource constructor, and can optionally return back alternate values for the props and/or opts prior to the resource actually being created. The effect will be as though those props and opts were passed in place of the original call to the Resource constructor. If the transformation returns undefined, this indicates that the resource will not be transformed.

interface ResourceTransformationArgs

interface ResourceTransformationArgs

ResourceTransformationArgs is the argument bag passed to a resource transformation.

property name

name: string;

The name of the Resource.

property opts

opts: ResourceOptions;

The original resource options passed to the Resource constructor.

property props

props: Inputs;

The original properties passed to the Resource constructor.

property resource

resource: Resource;

The Resource instance that is being transformed.

property type

type: string;

The type of the Resource.

interface ResourceTransformationResult

interface ResourceTransformationResult

ResourceTransformationResult is the result that must be returned by a resource transformation callback. It includes new values to use for the props and opts of the Resource in place of the originally provided values.

property opts

opts: ResourceOptions;

The new resource options to use in place of the original opts

property props

props: Inputs;

The new properties to use in place of the original props

const rootStackResource

const rootStackResource: Resource =  undefined!;

Constant to represent the ‘root stack’ resource for a Pulumi application. The purpose of this is solely to make it easy to write an [Alias] like so:

aliases: [{ parent: rootStackResource }].

This indicates that the prior name for a resource was created based on it being parented directly by the stack itself and no other resources. Note: this is equivalent to:

aliases: [{ parent: undefined }]

However, the former form is preferable as it is more self-descriptive, while the latter may look a bit confusing and may incorrectly look like something that could be removed without changing semantics.

class RunError

class RunError extends Error

RunError can be used for terminating a program abruptly, but resulting in a clean exit rather than the usual verbose unhandled error logic which emits the source program text and complete stack trace. This type should be rarely used. Ideally ResourceError should always be used so that as many errors as possible can be associated with a Resource.

constructor

new RunError(message: string)

method isInstance

public static isInstance(obj: any): boolean

Returns true if the given object is an instance of a RunError. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

property Error

static Error: ErrorConstructor;

property message

message: string;

property name

name: string;

property stack

stack?: undefined | string;

function secret

secret<T>(val: Input<T>): Output<Unwrap<T>>

[secret] behaves the same as [output] except the resturned output is marked as contating sensitive data.

secret<T>(val: Input<T> | undefined): Output<Unwrap<T | undefined>>

interface StackReferenceArgs

interface StackReferenceArgs

The set of arguments for constructing a StackReference resource.

property name

name?: Input<string>;

The name of the stack to reference.

type Unwrap

type Unwrap = Unwrap;

The ‘Unwrap’ type allows us to express the operation of taking a type, with potentially deeply nested Promises and Outputs and to then get that same type with all the Promises and Outputs replaced with their wrapped type. Note that this Unwrapping is ‘deep’. So if you had:

 `type X = { A: Promise<{ B: Output<{ c: Input<boolean> }> }> }`

Then Unwrap<X> would be equivalent to:

 `...    = { A: { B: { C: boolean } } }`

Unwrapping sees through Promises, Outputs, Arrays and Objects.

Note: due to TypeScript limitations there are some things that cannot be expressed. Specifically, if you had a Promise<Output<T>> then the Unwrap type would not be able to undo both of those wraps. In practice that should be ok. Values in an object graph should not wrap Outputs in Promises. Instead, any code that needs to work Outputs and also be async should either create the Output with the Promise (which will collapse into just an Output). Or, it should start with an Output and call [apply] on it, passing in an async function. This will also collapse and just produce an Output.

In other words, this should not be used as the shape of an object: { a: Promise<Output<...>> }. It should always either be { a: Promise<NonOutput> } or just { a: Output<...> }.

interface UnwrappedArray

interface UnwrappedArray extends Array<Unwrap<T>>

method __@iterator

__@iterator(): IterableIterator<Unwrap<T>>

Iterator

method __@unscopables

__@unscopables(): {
    copyWithin: boolean;
    entries: boolean;
    fill: boolean;
    find: boolean;
    findIndex: boolean;
    keys: boolean;
    values: boolean;
}

Returns an object whose properties have the value ‘true’ when they will be absent when used in a ‘with’ statement.

method concat

concat(items: ConcatArray<Unwrap<T>>[]): Unwrap<T>[]

Combines two or more arrays.

concat(items: T | ConcatArray<T>[]): Unwrap<T>[]

Combines two or more arrays.

method copyWithin

copyWithin(target: number, start: number, end?: undefined | number): this

Returns the this object after copying a section of the array identified by start and end to the same array starting at position target

method entries

entries(): IterableIterator<[, number, Unwrap<T>]>

Returns an iterable of key, value pairs for every entry in the array

method every

every(callbackfn: (value: Unwrap<T>, index: number, array: Unwrap<T>[]) => boolean, thisArg?: any): boolean

Determines whether all the members of an array satisfy the specified test.

method fill

fill(value: Unwrap<T>, start?: undefined | number, end?: undefined | number): this

Returns the this object after filling the section identified by start and end with value

method filter

filter<S>(callbackfn: (value: Unwrap<T>, index: number, array: Unwrap<T>[]) => boolean, thisArg?: any): S[]

Returns the elements of an array that meet the condition specified in a callback function.

filter(callbackfn: (value: Unwrap<T>, index: number, array: Unwrap<T>[]) => any, thisArg?: any): Unwrap<T>[]

Returns the elements of an array that meet the condition specified in a callback function.

method find

find<S>(predicate: (this: void, value: Unwrap<T>, index: number, obj: Unwrap<T>[]) => boolean, thisArg?: any): S | undefined

Returns the value of the first element in the array where predicate is true, and undefined otherwise.

find(predicate: (value: Unwrap<T>, index: number, obj: Unwrap<T>[]) => boolean, thisArg?: any): Unwrap<T> | undefined

method findIndex

findIndex(predicate: (value: Unwrap<T>, index: number, obj: Unwrap<T>[]) => boolean, thisArg?: any): number

Returns the index of the first element in the array where predicate is true, and -1 otherwise.

method forEach

forEach(callbackfn: (value: Unwrap<T>, index: number, array: Unwrap<T>[]) => void, thisArg?: any): void

Performs the specified action for each element in an array.

method includes

includes(searchElement: Unwrap<T>, fromIndex?: undefined | number): boolean

Determines whether an array includes a certain element, returning true or false as appropriate.

method indexOf

indexOf(searchElement: Unwrap<T>, fromIndex?: undefined | number): number

Returns the index of the first occurrence of a value in an array.

method join

join(separator?: undefined | string): string

Adds all the elements of an array separated by the specified separator string.

method keys

keys(): IterableIterator<number>

Returns an iterable of keys in the array

method lastIndexOf

lastIndexOf(searchElement: Unwrap<T>, fromIndex?: undefined | number): number

Returns the index of the last occurrence of a specified value in an array.

method map

map<U>(callbackfn: (value: Unwrap<T>, index: number, array: Unwrap<T>[]) => U, thisArg?: any): U[]

Calls a defined callback function on each element of an array, and returns an array that contains the results.

method pop

pop(): Unwrap<T> | undefined

Removes the last element from an array and returns it.

method push

push(items: Unwrap<T>[]): number

Appends new elements to an array, and returns the new length of the array.

method reduce

reduce(callbackfn: (previousValue: Unwrap<T>, currentValue: Unwrap<T>, currentIndex: number, array: Unwrap<T>[]) => Unwrap<T>): Unwrap<T>

Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

reduce(callbackfn: (previousValue: Unwrap<T>, currentValue: Unwrap<T>, currentIndex: number, array: Unwrap<T>[]) => Unwrap<T>, initialValue: Unwrap<T>): Unwrap<T>
reduce<U>(callbackfn: (previousValue: U, currentValue: Unwrap<T>, currentIndex: number, array: Unwrap<T>[]) => U, initialValue: U): U

Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

method reduceRight

reduceRight(callbackfn: (previousValue: Unwrap<T>, currentValue: Unwrap<T>, currentIndex: number, array: Unwrap<T>[]) => Unwrap<T>): Unwrap<T>

Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

reduceRight(callbackfn: (previousValue: Unwrap<T>, currentValue: Unwrap<T>, currentIndex: number, array: Unwrap<T>[]) => Unwrap<T>, initialValue: Unwrap<T>): Unwrap<T>
reduceRight<U>(callbackfn: (previousValue: U, currentValue: Unwrap<T>, currentIndex: number, array: Unwrap<T>[]) => U, initialValue: U): U

Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

method reverse

reverse(): Unwrap<T>[]

Reverses the elements in an Array.

method shift

shift(): Unwrap<T> | undefined

Removes the first element from an array and returns it.

method slice

slice(start?: undefined | number, end?: undefined | number): Unwrap<T>[]

Returns a section of an array.

method some

some(callbackfn: (value: Unwrap<T>, index: number, array: Unwrap<T>[]) => boolean, thisArg?: any): boolean

Determines whether the specified callback function returns true for any element of an array.

method sort

sort(compareFn?: undefined | (a: Unwrap<T>, b: Unwrap<T>) => number): this

Sorts an array.

method splice

splice(start: number, deleteCount?: undefined | number): Unwrap<T>[]

Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.

splice(start: number, deleteCount: number, items: Unwrap<T>[]): Unwrap<T>[]

Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.

method toLocaleString

toLocaleString(): string

Returns a string representation of an array. The elements are converted to string using their toLocalString methods.

method toString

toString(): string

Returns a string representation of an array.

method unshift

unshift(items: Unwrap<T>[]): number

Inserts new elements at the start of an array.

method values

values(): IterableIterator<Unwrap<T>>

Returns an iterable of values in the array

property Array

Array: ArrayConstructor;

property length

length: number;

Gets or sets the length of the array. This is a number one higher than the highest element defined in an array.

type UnwrappedObject

type UnwrappedObject = { ... };

type UnwrapSimple

type UnwrapSimple = UnwrapSimple;

Handles encountering basic types when unwrapping.

type URN

type URN = string;

const version

const version: "${VERSION}" = "${VERSION}";