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. Visit Pulumi’s Download & Install to install the CLI.

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 any of the Current, Active and Maintenance LTS versions. 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

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 $HOME/.dev-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

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, args: Inputs, opts: ComponentResourceOptions, remote: boolean)

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.
args Information passed to [initialize] method.
opts A bag of options that control this resource's behavior.
remote True if this is a remote component resource.

method getData

protected getData(): Promise<TData>

Retrieves the data produces by [initialize]. The data is immediately available in a derived class’s constructor after the super(...) call to ComponentResource.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method initialize

protected initialize(args: Inputs): Promise<TData>

Can be overridden by a subclass to asynchronously initialize data for this Component automatically when constructed. The data will be available immediately for subclass constructors to use. To access the data use .getData.

method isInstance

public static isInstance(obj: any): obj is ComponentResource

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

registerOutputs registers synthetic outputs that a component has initialized, usually by allocating other child sub-resources and propagating their resulting property values.

ComponentResources can call this at the end of their constructor to indicate that they are done creating child resources. This is not strictly necessary as this will automatically be called after the initialize method completes.

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, dependency: boolean)

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.
dependency True if this is a synthetic resource used internally for dependency tracking.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): obj is CustomResource

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 DependencyProviderResource

class DependencyProviderResource extends ProviderResource

A DependencyProviderResource is a resource that is used by the provider SDK as a stand-in for a provider that is only used for its reference. Its only valid properties are its URN and ID.

constructor

new DependencyProviderResource(ref: string)

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): obj is CustomResource

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 DependencyResource

class DependencyResource extends CustomResource

A DependencyResource is a resource that is used to indicate that an Output has a dependency on a particular resource. These resources are only created when dealing with remote component resources.

constructor

new DependencyResource(urn: URN)

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): obj is CustomResource

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, dependency: boolean)

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.
dependency True if this is a synthetic resource used internally for dependency tracking.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): obj is CustomResource

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, remote: boolean, dependency: boolean)

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.
remote True if this is a remote component resource.
dependency True if this is a synthetic resource used internally for dependency tracking.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): obj is Resource

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 getOutputDetails

public getOutputDetails(name: string): Promise<StackReferenceOutputDetails>

Fetches the value of the named stack output and builds a StackReferenceOutputDetails with it.

The returned object has its value or secretValue fields set depending on wehther the output is a secret. Neither field is set if the output was not found.

method getOutputValue

public getOutputValue(name: string): Promise<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 the named stack output is a secret.

method getProvider

public getProvider(moduleMember: string): ProviderResource | undefined

method isInstance

public static isInstance(obj: any): obj is CustomResource

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 requireOutputValue

public requireOutputValue(name: string): Promise<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 the named stack output is a secret.

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>, Input<T2>, Input<T3>, Input<T4>, Input<T5>, Input<T6>, Input<T7>, Input<T8>]): 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>, Input<T2>, Input<T3>, Input<T4>, Input<T5>, Input<T6>, Input<T7>]): 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>, Input<T2>, Input<T3>, Input<T4>, Input<T5>, Input<T6>]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>, Unwrap<T5>, Unwrap<T6>]>

all<T1,T2,T3,T4,T5>(values: [, Input<T1>, Input<T2>, Input<T3>, Input<T4>, Input<T5>]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>, Unwrap<T5>]>

all<T1,T2,T3,T4>(values: [, Input<T1>, Input<T2>, Input<T3>, Input<T4>]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>, Unwrap<T4>]>

all<T1,T2,T3>(values: [, Input<T1>, Input<T2>, Input<T3>]): Output<[, Unwrap<T1>, Unwrap<T2>, Unwrap<T3>]>

all<T1,T2>(values: [, Input<T1>, Input<T2>]): Output<[, Unwrap<T1>, Unwrap<T2>]>

all<T>(ds: Input<T>[]): Output<Unwrap<T>[]>

function allAliases

allAliases(childAliases: Input<URN | Alias>[], childName: string, childType: string, parent: Resource, parentName: string): Output<URN>[]

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 deletedWith

deletedWith?: Resource;

If set, the providers Delete method will not be called for this resource if specified is being deleted as well.

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 pluginDownloadURL

pluginDownloadURL?: undefined | string;

An option to specify the URL from which to download this resources associated plugin. This version overrides the URL information inferred from the current package and should rarely be used.

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.

Note: only a list should be used. Mapping keys are not respected.

property replaceOnChanges

replaceOnChanges?: string[];

Changes to any of these property paths will force a replacement. If this list includes "*", changes to any properties will force a replacement. Initialization errors from previous deployments will require replacement instead of update only if "*" is passed.

property retainOnDelete

retainOnDelete?: undefined | false | true;

If set to True, the providers Delete method will not be called for this resource.

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 urn

urn?: URN;

The URN of a previously-registered resource of this type to read from the engine.

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 secret. 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 containsUnknowns

containsUnknowns(value: any): boolean

containsUnknowns returns true if the given value is or contains unknown values.

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 deletedWith

deletedWith?: Resource;

If set, the providers Delete method will not be called for this resource if specified is being deleted as well.

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 pluginDownloadURL

pluginDownloadURL?: undefined | string;

An option to specify the URL from which to download this resources associated plugin. This version overrides the URL information inferred from the current package and should rarely be used.

property protect

protect?: undefined | false | true;

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

property provider

provider?: ProviderResource;

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

property replaceOnChanges

replaceOnChanges?: string[];

property retainOnDelete

retainOnDelete?: undefined | false | true;

If set to True, the providers Delete method will not be called for this resource.

property transformations

transformations?: ResourceTransformation[];

property urn

urn?: URN;

The URN of a previously-registered resource of this type to read from the engine.

property version

version?: undefined | string;

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 getOrganization

getOrganization(): string

getOrganization returns the current organization name.

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.

interface InvokeOptions

interface InvokeOptions

property async

async?: undefined | false | true;

Invoke this data source function asynchronously. Defaults to true if unspecified.

When true, only the Promise<> side of the invoke result is present. Explicitly pass in false to get the non-Promise side of the result. Invoking data source functions synchronously is deprecated. The ability to do this will be removed at a later point in time.

property parent

parent?: Resource;

An optional parent to use for default options for this invoke (e.g. the default provider to use).

property pluginDownloadURL

pluginDownloadURL?: undefined | string;

An option to specify the URL from which to download this resources associated plugin. This version overrides the URL information inferred from the current package and should rarely be used.

property provider

provider?: ProviderResource;

An optional provider to use for this invocation. If no provider is supplied, the default provider for the invoked function’s package will be used.

property version

version?: undefined | string;

An optional version, corresponding to the version of the provider plugin that should be used when performing this invoke.

function isGrpcError

isGrpcError(err: Error): boolean

function isSecret

isSecret<T>(val: Output<T>): Promise<boolean>

function isUnknown

isUnknown(val: any): boolean

isUnknown returns true if the given value is unknown.

function jsonParse

jsonParse(text: Input<string>, reviver?: undefined | (this: any, key: string, value: any) => any): Output<any>

[jsonParse] Uses JSON.parse to deserialize the given Input JSON string into a value.

function jsonStringify

jsonStringify(obj: Input<any>, replacer?: undefined | (this: any, key: string, value: any) => any | string | number[], space?: string | number): Output<string>

[jsonStringify] Uses JSON.stringify to serialize the given Input value into a JSON string.

type Lifted

type Lifted = T extends string ? LiftedObject<String, NonFunctionPropertyNames<String>> : T extends Array<infer U> ? LiftedArray<U> : T extends object ? LiftedObject<T, NonFunctionPropertyNames<T>> : { ... };

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 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:

if the property is a collection, the final value will be a collection containing the values from each options object.
Simple scaler values from opts2 (i.e. strings, numbers, bools) will replace the values of opts1.
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.
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

interface NumberConfigOptions

interface NumberConfigOptions

NumberConfigOptions may be used to constrain the set of legal values a number config value may contain.

property max

max?: undefined | number;

The maximum number value, inclusive. If the number is greater than this, a ConfigRangeError is thrown.

property min

min?: undefined | number;

The minimum number value, inclusive. If the number is less than this, a ConfigRangeError is thrown.

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>>

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]);

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): obj is Output<T>

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 also 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): obj is ResourceError

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 deletedWith

deletedWith?: Resource;

If set, the providers Delete method will not be called for this resource if specified is being deleted as well.

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 pluginDownloadURL

pluginDownloadURL?: undefined | string;

An option to specify the URL from which to download this resources associated plugin. This version overrides the URL information inferred from the current package and should rarely be used.

property protect

protect?: undefined | false | true;

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

property provider

provider?: ProviderResource;

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

property replaceOnChanges

replaceOnChanges?: string[];

property retainOnDelete

retainOnDelete?: undefined | false | true;

If set to True, the providers Delete method will not be called for this resource.

property transformations

transformations?: ResourceTransformation[];

property urn

urn?: URN;

The URN of a previously-registered resource of this type to read from the engine.

property version

version?: undefined | string;

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.

method isInstance

public static isInstance(obj: any): obj is RunError

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 returned output is marked as containing 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.

interface StackReferenceOutputDetails

interface StackReferenceOutputDetails

Records the output of a StackReference. At most one of th evalue and secretValue fields will be set.

property secretValue

secretValue?: any;

Secret value returned by the StackReference. This is null if the value is not a secret or it does not exist.

property value

value?: any;

Output value returned by the StackReference. This is null if the value is a secret or it does not exist.

interface StringConfigOptions

interface StringConfigOptions

StringConfigOptions may be used to constrain the set of legal values a string config value may contain.

property allowedValues

allowedValues?: K[];

The legal enum values. If it does not match, a ConfigEnumError is thrown.

property maxLength

maxLength?: undefined | number;

The maximum string length. If the string is longer than this, a ConfigRangeError is thrown.

property minLength

minLength?: undefined | number;

The minimum string length. If the string is not this long, a ConfigRangeError is thrown.

property pattern

pattern?: string | RegExp;

A regular expression the string must match. If it does not match, a ConfigPatternError is thrown.

function unsecret

unsecret<T>(val: Output<T>): Output<T>

[unsecret] behaves the same as [output] except the returned output takes the existing output and unwraps the secret

type Unwrap

type Unwrap = T extends Promise<infer U1> ? UnwrapSimple<U1> : T extends OutputInstance<infer U2> ? UnwrapSimple<U2> : UnwrapSimple<T>;

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<...> }.

type UnwrappedArray

type UnwrappedArray = Array<Unwrap<T>>;

type UnwrappedObject

type UnwrappedObject = { ... };

type UnwrapSimple

type UnwrapSimple = T extends primitive ? T : T extends Resource ? T : T extends Array<infer U> ? UnwrappedArray<U> : T extends object ? UnwrappedObject<T> : never;

Handles encountering basic types when unwrapping.

type URN

type URN = string;

const version

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