pulumi

The Pulumi Core SDK for Python. This package defines the core primitives that providers and libraries in the Pulumi ecosystem use to create and manage resources.

class pulumi.Alias(name: str | None = Ellipsis, type_: str | None = Ellipsis, parent: Resource | Input[str] | None = Ellipsis, stack: Input[str] | None = Ellipsis, project: Input[str] | None = Ellipsis)

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 attributes being given the None value and attributes not being given at all. Specifically, there is a difference between:

`ts Alias(name="foo", parent=None) # and Alias(name="foo") `

So 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=[Alias(parent=pulumi.ROOT_STACK_RESOURCE)]

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

aliases=[Alias(parent=None)]

name: str | None

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

parent: Resource | Input[str] | None

The previous parent of the resource. If not provided (i.e. Alias(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 Alias(parent=pulumi.ROOT_STACK_RESOURCE).

project: Input[str] | None

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

stack: Input[str] | None

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

type_: str | None

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

class pulumi.Archive

Archive represents a collection of named assets.

class pulumi.Asset

Asset represents a single blob of text or data that is managed as a first class entity.

class pulumi.AssetArchive(assets: Dict[str, Asset | Archive])

An AssetArchive is an archive created from an in-memory collection of named assets or other archives.

class pulumi.ComponentResource(t: str, name: str, props: Inputs | None = None, opts: ResourceOptions | None = None, remote: bool = False)

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

Parameters:
  • t (str) – The type of this resource.

  • name (str) – The name of this resource.

  • props (Optional[dict]) – An optional list of input properties to use as inputs for the resource.

  • opts (Optional[ResourceOptions]) – Optional set of pulumi.ResourceOptions to use for this resource.

  • remote (bool) – True if this is a remote component resource.

register_outputs(outputs: Inputs)

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

Parameters:

output (dict) – A dictionary of outputs to associate with this resource.

class pulumi.Config(name: str | None = None)

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.

Parameters:

name (str) – The configuration bag’s logical name that uniquely identifies it. If not provided, the name of the current project is used.

full_key(key: str) str

Turns a simple configuration key into a fully resolved one, by prepending the bag’s name.

Parameters:

key (str) – The name of the configuration key.

Returns:

The name of the configuration key, prefixed with the bag’s name.

Return type:

str

get(key: str, default: str | None = None) str | None

Returns an optional configuration value by its key, a default value if that key is unset and a default is provided, or None if it doesn’t exist.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[str]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[str]

get_bool(key: str, default: bool | None = None) bool | None

Returns an optional configuration value, as a bool, by its key, a default value if that key is unset and a default is provided, or None if it doesn’t exist. If the configuration value isn’t a legal boolean, this function will throw an error.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[bool]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[bool]

Raises:

ConfigTypeError – The configuration value existed but couldn’t be coerced to bool.

get_float(key: str, default: float | None = None) float | None

Returns an optional configuration value, as a float, by its key, marked as a secret, a default value if that key is unset and a default is provided, or None if it doesn’t exist. If the configuration value isn’t a legal float, this function will throw an error.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[float]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[float]

Raises:

ConfigTypeError – The configuration value existed but couldn’t be coerced to float.

get_int(key: str, default: int | None = None) int | None

Returns an optional configuration value, as an int, by its key, a default value if that key is unset and a default is provided, or None if it doesn’t exist. If the configuration value isn’t a legal int, this function will throw an error.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[int]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[int]

Raises:

ConfigTypeError – The configuration value existed but couldn’t be coerced to int.

get_object(key: str, default: Any | None = None) Any | None

Returns an optional configuration value, as an object, by its key, a default value if that key is unset and a default is provided, or undefined if it doesn’t exist. This routine simply JSON parses and doesn’t validate the shape of the contents.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[Any]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[Any]

Raises:

ConfigTypeError – The configuration value existed but couldn’t be coerced to float.

get_secret(key: str, default: str | None = None) Output[str] | None

Returns an optional configuration value by its key, marked as a secret, a default value if that key is unset and a default is provided, or None if it doesn’t exist.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[str]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[str]

get_secret_bool(key: str, default: bool | None = None) Output[bool] | None

Returns an optional configuration value, as a bool, by its key, marked as a secret, a default value if that key is unset and a default is provided, or None if it doesn’t exist. If the configuration value isn’t a legal boolean, this function will throw an error.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[bool]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[bool]

Raises:

ConfigTypeError – The configuration value existed but couldn’t be coerced to bool.

get_secret_float(key: str, default: float | None = None) Output[float] | None

Returns an optional configuration value, as a float, by its key, marked as a secret, a default value if that key is unset and a default is provided, or None if it doesn’t exist. If the configuration value isn’t a legal float, this function will throw an error.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[float]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[float]

Raises:

ConfigTypeError – The configuration value existed but couldn’t be coerced to float.

get_secret_int(key: str, default: int | None = None) Output[int] | None

Returns an optional configuration value, as an int, by its key, marked as a secret, a default value if that key is unset and a default is provided, or None if it doesn’t exist. If the configuration value isn’t a legal int, this function will throw an error.

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[int]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[int]

Raises:

ConfigTypeError – The configuration value existed but couldn’t be coerced to int.

get_secret_object(key: str, default: Any | None = None) Output[Any] | None

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

Parameters:
  • key (str) – The requested configuration key.

  • default (Optional[Any]) – An optional fallback value to use if the given configuration key is not set.

Returns:

The configuration key’s value, or None if one does not exist.

Return type:

Optional[Any]

Raises:

ConfigTypeError – The configuration value existed but couldn’t be coerced to float.

name: str

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

require(key: str) str

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

Parameters:

key (str) – The requested configuration key.

Returns:

The configuration key’s value.

Return type:

str

Raises:

ConfigMissingError – The configuration value did not exist.

require_bool(key: str) bool

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

Parameters:

key (str) – The requested configuration key.

Returns:

The configuration key’s value.

Return type:

bool

Raises:
require_float(key: str) float

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

Parameters:

key (str) – The requested configuration key.

Returns:

The configuration key’s value.

Return type:

float

Raises:
require_int(key: str) int

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

Parameters:

key (str) – The requested configuration key.

Returns:

The configuration key’s value.

Return type:

int

Raises:
require_object(key: str) Any

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

require_secret(key: str) Output[str]

Returns a configuration value, marked as a secret by its given key. If it doesn’t exist, an error is thrown.

Parameters:

key (str) – The requested configuration key.

Returns:

The configuration key’s value.

Return type:

str

Raises:

ConfigMissingError – The configuration value did not exist.

require_secret_bool(key: str) Output[bool]

Returns a configuration value, as a bool, marked as a secret by its given key. If it doesn’t exist, or the configuration value is not a legal bool, an error is thrown.

Parameters:

key (str) – The requested configuration key.

Returns:

The configuration key’s value.

Return type:

bool

Raises:
require_secret_float(key: str) Output[float]

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

Parameters:

key (str) – The requested configuration key.

Returns:

The configuration key’s value.

Return type:

float

Raises:
require_secret_int(key: str) Output[int]

Returns a configuration value, as an int, marked as a secret by its given key. If it doesn’t exist, or the configuration value is not a legal int, an error is thrown.

Parameters:

key (str) – The requested configuration key.

Returns:

The configuration key’s value.

Return type:

int

Raises:
require_secret_object(key: str) Output[Any]

Returns a configuration value as a JSON string and deserializes the JSON into a Python 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.

exception pulumi.ConfigMissingError(key: str, secret: bool)

Indicates a configuration value is missing.

key: str

The name of the missing configuration key.

secret: bool

If this is a secret configuration key.

exception pulumi.ConfigTypeError(key: str, value: str, expect_type: str)

Indicates a configuration value is of the wrong type.

expect_type: str

The expected type of this value.

key: str

The name of the key whose value was ill-typed.

value: str

The ill-typed value.

class pulumi.CustomResource(t: str, name: str, props: Inputs | None = None, opts: ResourceOptions | None = None, dependency: bool = False)

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.

Parameters:
  • t (str) – The type of this resource.

  • name (str) – The name of this resource.

  • props (Optional[dict]) – An optional list of input properties to use as inputs for the resource.

  • opts (Optional[ResourceOptions]) – Optional set of pulumi.ResourceOptions to use for this resource.

  • dependency (bool) – True if this is a synthetic resource used internally for dependency tracking.

property id: Output[str]

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

class pulumi.FileArchive(path: str)

A FileArchive is a file-based archive, or collection of file-based assets. This can be a raw directory or a single archive file in one of the supported formats (.tar, .tar.gz, or .zip).

class pulumi.FileAsset(path: str | PathLike)

A FileAsset is a kind of asset produced from a given path to a file on the local filesystem.

class pulumi.InvokeOptions(parent: Resource | None = None, provider: ProviderResource | None = None, version: str | None = '', plugin_download_url: str | None = None)

InvokeOptions is a bag of options that control the behavior of a call to runtime.invoke.

Parameters:
  • parent (Optional[Resource]) – An optional parent to use for default options for this invoke (e.g. the default provider to use).

  • provider (Optional[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.

  • version (Optional[str]) – An optional version. If provided, the provider plugin with exactly this version will be used to service the invocation.

  • plugin_download_url (Optional[str]) – An optional URL. If provided, the provider plugin with this download URL will be used to service the invocation. This will override the URL sourced from the host package, and should be rarely used.

static merge(opts1: InvokeOptions | None, opts2: InvokeOptions | None) InvokeOptions

merge produces a new InvokeOptions object with the respective attributes of the opts1 instance in it with the attributes of opts2 merged over them.

Both the opts1 instance and the opts2 instance will be unchanged. Both of opts1 and opts2 can be None, in which case its attributes are ignored.

Conceptually attributes merging follows these basic rules:

  1. If the attributes is a collection, the final value will be a collection containing the values from each options object. Both original collections in each options object will be unchanged.

  2. Simple scalar values from opts2 (i.e. strings, numbers, bools) will replace the values from opts1.

  3. For the purposes of merging depends_on is always treated as collections, even if only a single value was provided.

  4. Attributes with value ‘None’ will not be copied over.

This method can be called either as static-method like InvokeOptions.merge(opts1, opts2) or as an instance-method like opts1.merge(opts2). The former is useful for cases where opts1 may be None so the caller does not need to check for this case.

parent: Resource | None

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

plugin_download_url: str | None

An optional URL. If provided, the provider plugin with exactly this download URL will be used to service the invocation. This will override the URL sourced from the host package, and should be rarely used.

provider: ProviderResource | None

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.

version: str | None

An optional version. If provided, the provider plugin with exactly this version will be used to service the invocation.

class pulumi.Output(resources: Awaitable[Set[Resource]] | Set[Resource], future: Awaitable[T_co], is_known: Awaitable[bool], is_secret: Awaitable[bool] | None = None)

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.

static all(*args: T | Awaitable[T] | Output[T]) Output[List[T]]
static all(**kwargs: T | Awaitable[T] | Output[T]) Output[Dict[str, T]]

Produces an Output of a list (if args i.e a list of inputs are supplied) or dict (if kwargs i.e. keyworded arguments are supplied).

This function can be used to combine multiple, separate Inputs into a single Output which can then be used as the target of apply. Resource dependencies are preserved in the returned Output.

Examples:

Output.all(foo, bar) -> Output[[foo, bar]]
Output.all(foo=foo, bar=bar) -> Output[{"foo": foo, "bar": bar}]
Parameters:
  • args (Input[T]) – A list of Inputs to convert.

  • kwargs (Input[T]) – A list of named Inputs to convert.

Returns:

An output of list or dict, converted from unnamed or named Inputs respectively.

apply(func: Callable[[T_co], U | Awaitable[U] | Output[T]], run_with_unknowns: bool | None = None) Output[U]

Transforms the data of the output with the provided func. The result remains an 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<SomeVal> and you want to get a transitive dependency of it.

This function will be called during execution of a pulumi up request. It may not run during pulumi preview (as the values of resources are of course may not be known then).

Parameters:

func (Callable[[T_co],Input[U]]) – A function that will, given this Output’s value, transform the value to an Input of some kind, where an Input is either a prompt value, a Future, or another Output of the given type.

Returns:

A transformed Output obtained from running the transformation function on this Output’s value.

Return type:

Output[U]

static concat(*args: str | Awaitable[str] | Output[T]) Output[str]

Concatenates a collection of Input[str] into a single Output[str].

This function takes a sequence of Input[str], stringifies each, and concatenates all values into one final string. This can be used like so:

url = Output.concat(”http://”, server.hostname, “:”, loadBalancer.port)

Parameters:

args (Input[str]) – A list of string Inputs to concatenate.

Returns:

A concatenated output string.

Return type:

Output[str]

static format(format_string: str | Awaitable[str] | Output[T], *args: object | Awaitable[object] | Output[T], **kwargs: object | Awaitable[object] | Output[T]) Output[str]

Perform a string formatting operation.

This has the same semantics as str.format except it handles Input types.

Parameters:
  • format_string (Input[str]) – A formatting string

  • args (Input[object]) – Positional arguments for the format string

  • kwargs (Input[object]) – Keyword arguments for the format string

Returns:

A formatted output string.

Return type:

Output[str]

static from_input(val: T_co | Awaitable[T_co] | Output[T]) Output[T_co]

Takes an Input value and produces an Output value from it, deeply unwrapping nested Input values through nested lists, dicts, and input classes. Nested objects of other types (including Resources) are not deeply unwrapped.

Parameters:

val (Input[T_co]) – An Input to be converted to an Output.

Returns:

A deeply-unwrapped Output that is guaranteed to not contain any Input values.

Return type:

Output[T_co]

static json_dumps(obj: Any | Awaitable[Any] | Output[T], *, skipkeys: bool = False, ensure_ascii: bool = True, check_circular: bool = True, allow_nan: bool = True, cls: Type[JSONEncoder] | None = None, indent: int | str | None = None, separators: Tuple[str, str] | None = None, default: Callable[[Any], Any] | None = None, sort_keys: bool = False, **kw: Any) Output[str]

Uses json.dumps to serialize the given Input[object] value into a JSON string.

The arguments have the same meaning as in json.dumps except obj is an Input.

static json_loads(s: str | bytes | bytearray | Awaitable[str | bytes | bytearray] | Output[T], *, cls: Type[JSONDecoder] | None = None, object_hook: Callable[[Dict[Any, Any]], Any] | None = None, parse_float: Callable[[str], Any] | None = None, parse_int: Callable[[str], Any] | None = None, parse_constant: Callable[[str], Any] | None = None, object_pairs_hook: Callable[[List[Tuple[Any, Any]]], Any] | None = None, **kwds: Any) Output[Any]

Uses json.loads to deserialize the given JSON Input[str] value into a value.

The arguments have the same meaning as in json.loads except s is an Input.

static secret(val: T | Awaitable[T] | Output[T]) Output[T]

Takes an Input value and produces an Output value from it, deeply unwrapping nested Input values as necessary given the type. It also marks the returned Output as a secret, so its contents will be persisted in an encrypted form in state files.

Parameters:

val (Input[T]) – An Input to be converted to an Secret Output.

Returns:

A deeply-unwrapped Output that is guaranteed to not contain any Input values and is marked as a Secret.

Return type:

Output[T]

static unsecret(val: Output[T]) Output[T]

Takes an existing Output, deeply unwraps the nested values and returns a new Output without any secrets included

Parameters:

val (Output[T]) – An Output to be converted to a non-Secret Output.

Returns:

A deeply-unwrapped Output that is guaranteed to not contain any secret values.

Return type:

Output[T]

class pulumi.ProviderResource(pkg: str, name: str, props: Inputs | None = None, opts: ResourceOptions | None = None, dependency: bool = False)

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.

Parameters:
  • pkg (str) – The package type of this provider resource.

  • name (str) – The name of this resource.

  • props (Optional[dict]) – An optional list of input properties to use as inputs for the resource.

  • opts (Optional[ResourceOptions]) – Optional set of pulumi.ResourceOptions to use for this resource.

  • dependency (bool) – True if this is a synthetic resource used internally for dependency tracking.

package: str

package is the name of the package this is provider for. Common examples are “aws” and “azure”.

class pulumi.RemoteArchive(uri: str)

A RemoteArchive is a file-based archive fetched from a remote location. The URI’s scheme dictates the protocol for fetching contents: “file://” specifies a local file, “http://” and “https://” specify HTTP and HTTPS, respectively, and specific providers may recognize custom schemes.

class pulumi.RemoteAsset(uri: str)

A RemoteAsset is a kind of asset produced from a given URI string. The URI’s scheme dictates the protocol for fetching contents: “file://” specifies a local file, “http://” and “https://” specify HTTP and HTTPS, respectively. Note that specific providers may recognize alternative schemes; this is merely the base-most set that all providers support.

class pulumi.Resource(t: str, name: str, custom: bool, props: Inputs | None = None, opts: ResourceOptions | None = None, remote: bool = False, dependency: bool = False)

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

Parameters:
  • t (str) – The type of this resource.

  • name (str) – The name of this resource.

  • custom (bool) – True if this resource is a custom resource.

  • props (Optional[Inputs]) – An optional list of input properties to use as inputs for the resource. If props is an input type (decorated with @input_type), dict keys will be translated using the type’s and resource’s type/name metadata rather than using the translate_input_property and translate_output_property methods.

  • opts (Optional[ResourceOptions]) – Optional set of pulumi.ResourceOptions to use for this resource.

  • remote (bool) – True if this is a remote component resource.

  • dependency (bool) – True if this is a synthetic resource used internally for dependency tracking.

get_provider(module_member: str) ProviderResource | None

Fetches the provider for the given module member, if this resource has been provided a specific provider for the given module member.

Returns None if no provider was provided.

Parameters:

module_member (str) – The requested module member.

Returns:

The ProviderResource associated with the given module member, or None if one does not exist.

Return type:

Optional[ProviderResource]

translate_input_property(prop: str) str

Provides subclasses of Resource an opportunity to translate names of input properties into a format of their choosing before sending those properties to the Pulumi engine.

If the props passed to __init__ is an input type (decorated with @input_type), the type/name metadata of props will be used to translate names instead of calling this method.

Parameters:

prop (str) – A property name.

Returns:

A potentially transformed property name.

Return type:

str

translate_output_property(prop: str) str

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

If the props passed to __init__ is an input type (decorated with @input_type), the type/name metadata of the resource will be used to translate names instead of calling this method.

Parameters:

prop (str) – A property name.

Returns:

A potentially transformed property name.

Return type:

str

property urn: Output[str]

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

class pulumi.ResourceOptions(parent: Resource | None = None, depends_on: Input[Sequence[Input[Resource]] | Resource] | None = None, protect: bool | None = None, provider: ProviderResource | None = None, providers: Mapping[str, ProviderResource] | List[ProviderResource] | None = None, delete_before_replace: bool | None = None, ignore_changes: List[str] | None = None, version: str | None = None, aliases: Sequence[Input[str | Alias]] | None = None, additional_secret_outputs: List[str] | None = None, id: Input[str] | None = None, import_: str | None = None, custom_timeouts: CustomTimeouts | None = None, transformations: List[Callable[[ResourceTransformationArgs], ResourceTransformationResult | None]] | None = None, urn: str | None = None, replace_on_changes: List[str] | None = None, plugin_download_url: str | None = None, retain_on_delete: bool | None = None, deleted_with: Resource | None = None)

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

Parameters:
  • parent (Optional[Resource]) – If provided, the currently-constructing resource should be the child of the provided parent resource.

  • depends_on (Optional[Input[Union[List[Input[Resource]],Resource]]]) – If provided, declares that the currently-constructing resource depends on the given resources.

  • protect (Optional[bool]) – If provided and True, this resource is not allowed to be deleted.

  • provider (Optional[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 providers field, then the parent’s provider bag.

  • providers (Optional[Union[Mapping[str, ProviderResource], List[ProviderResource]]]) – An optional set of providers to use for this resource and child resources. Keyed by package name (e.g. “aws”), or just provided as a list. 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.

  • delete_before_replace (Optional[bool]) – If provided and True, this resource must be deleted before it is replaced.

  • ignore_changes (Optional[List[str]]) – If provided, a list of property names to ignore for purposes of updates or replacements.

  • version (Optional[str]) – An optional version. If provided, the engine loads a provider with exactly the requested version to operate on this resource. This version overrides the version information inferred from the current package and should rarely be used.

  • aliases (Optional[List[Input[Union[str, Alias]]]]) – An optional list of aliases to treat this resource as matching.

  • additional_secret_outputs (Optional[List[str]]) – If provided, a list of output property names that should also be treated as secret.

  • id (Optional[Input[str]]) – If provided, an existing resource ID to read, rather than create.

  • import (Optional[str]) – 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.

  • custom_timeouts (Optional[CustomTimeouts]) – If provided, a config block for custom timeout information.

  • transformations (Optional[List[ResourceTransformation]]) – If provided, a list of transformations to apply to this resource during construction.

  • urn (Optional[str]) – The URN of a previously-registered resource of this type to read from the engine.

  • replace_on_changes (Optional[List[str]]) – 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.

  • plugin_download_url (Optional[str]) – An optional url. If provided, the engine loads a provider with downloaded from the provided url. This url overrides the plugin download url inferred from the current package and should rarely be used.

  • retain_on_delete (Optional[bool]) – If set to True, the providers Delete method will not be called for this resource.

  • deleted_with (Optional[Resource]) – If set, the providers Delete method will not be called for this resource if specified resource is being deleted as well.

additional_secret_outputs: List[str] | None

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 outputs as a secrets on a per resource basis.

aliases: Sequence[Input[str | Alias]] | None

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

custom_timeouts: CustomTimeouts | None

An optional customTimeouts config block.

delete_before_replace: bool | None

If provided and True, this resource must be deleted before it is replaced.

deleted_with: Resource | None

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

depends_on: Input[Sequence[Input[Resource]] | Resource] | None

If provided, declares that the currently-constructing resource depends on the given resources.

id: Input[str] | None

An optional existing ID to load, rather than create.

ignore_changes: List[str] | None

If provided, ignore changes to any of the specified properties.

import_: str | None

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.

static merge(opts1: ResourceOptions | None, opts2: ResourceOptions | None) ResourceOptions

merge produces a new ResourceOptions object with the respective attributes of the opts1 instance in it with the attributes of opts2 merged over them.

Both the opts1 instance and the opts2 instance will be unchanged. Both of opts1 and opts2 can be None, in which case its attributes are ignored.

Conceptually attributes merging follows these basic rules:

  1. If the attributes is a collection, the final value will be a collection containing the values from each options object. Both original collections in each options object will be unchanged.

  2. Simple scalar values from opts2 (i.e. strings, numbers, bools) will replace the values from opts1.

  3. For the purposes of merging depends_on is always treated as collections, even if only a single value was provided.

  4. Attributes with value ‘None’ will not be copied over.

This method can be called either as static-method like ResourceOptions.merge(opts1, opts2) or as an instance-method like opts1.merge(opts2). The former is useful for cases where opts1 may be None so the caller does not need to check for this case.

parent: Resource | None

If provided, the currently-constructing resource should be the child of the provided parent resource.

plugin_download_url: str | None

An optional url. If provided, the engine loads a provider with downloaded from the provided url. This url overrides the plugin download url inferred from the current package and should rarely be used.

protect: bool | None

If provided and True, this resource is not allowed to be deleted.

provider: ProviderResource | None

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 ResourceOptions.providers).

providers: Mapping[str, ProviderResource] | Sequence[ProviderResource] | None

An optional set of providers to use for this resource and child resources. Keyed by package name (e.g. “aws”), or just provided as a list. 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.

replace_on_changes: List[str] | None

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.

retain_on_delete: bool | None

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

transformations: List[Callable[[ResourceTransformationArgs], ResourceTransformationResult | None]] | None

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.

urn: str | None

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

version: str | None

An optional version. If provided, the engine loads a provider with exactly the requested version to operate on this resource. This version overrides the version information inferred from the current package and should rarely be used.

class pulumi.ResourceTransformationArgs(resource: Resource, type_: str, name: str, props: Inputs, opts: ResourceOptions)

ResourceTransformationArgs is the argument bag passed to a resource transformation.

name: str

The name of the Resource.

opts: ResourceOptions

The original resource options passed to the Resource constructor.

props: Inputs

The original properties passed to the Resource constructor.

resource: Resource

The Resource instance that is being transformed.

type_: str

The type of the Resource.

class pulumi.ResourceTransformationResult(props: Inputs, opts: ResourceOptions)

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.

opts: ResourceOptions

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

props: Inputs

The new properties to use in place of the original props.

exception pulumi.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.

class pulumi.StackReference(name: str, stack_name: str | None = None, opts: ResourceOptions | None = None)

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

Parameters:
  • name (str) – The unique name of the stack reference.

  • stack_name (Optional[str]) – The name of the stack to reference. If not provided, defaults to the name of this resource.

  • opts (Optional[ResourceOptions]) – An optional set of resource options for this resource.

get_output(name: str | Awaitable[str] | Output[T]) Output[Any]

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

Parameters:

name (Input[str]) – The name of the stack output to fetch.

async get_output_details(name: str) StackReferenceOutputDetails

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

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

name: Output[str]

The name of the referenced stack.

outputs: Output[dict]

The outputs of the referenced stack.

require_output(name: str | Awaitable[str] | Output[T]) Output[Any]

Fetches the value of the named stack output, or raises a KeyError if the output was not found.

Parameters:

name (Input[str]) – The name of the stack output to fetch.

secret_output_names: Output[List[str]]

The names of any stack outputs which contain secrets.

translate_output_property(prop: str) str

Provides subclasses of Resource an opportunity to translate names of output properties into a format of their choosing before writing those properties to the resource object.

Parameters:

prop (str) – A property name.

Returns:

A potentially transformed property name.

Return type:

str

class pulumi.StackReferenceOutputDetails(value: Any | None = None, secret_value: Any | None = None)

Records the output of a StackReference. At most one of the value and secret_value fields will be set.

Parameters:
  • value (Optional[Any]) – Non-secret output value, if any.

  • secret_value (Optional[Any]) – Secret output value, if any.

secret_value

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

alias of Optional[Any]

value

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

alias of Optional[Any]

class pulumi.StringAsset(text: str)

A StringAsset is a kind of asset produced from an in-memory UTF-8 encoded string.

pulumi.create_urn(name: Input[str], type_: Input[str], parent: Resource | Input[str] | None = None, project: str | None = None, stack: str | None = None) Output[str]

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

pulumi.debug(msg: str, resource: Resource | None = None, stream_id: int | None = None, ephemeral: bool | None = None) None

Logs a message to the Pulumi CLI’s debug channel, associating it with a resource and stream_id if provided.

Parameters:
  • msg (str) – The message to send to the Pulumi CLI.

  • resource (Optional[Resource]) – If provided, associate this message with the given resource in the Pulumi CLI.

  • stream_id (Optional[int]) – If provided, associate this message with a stream of other messages.

pulumi.error(msg: str, resource: Resource | None = None, stream_id: int | None = None, ephemeral: bool | None = None)

Logs a message to the Pulumi CLI’s error channel, associating it with a resource and stream_id if provided.

Consider raising an exception after calling error to stop the Pulumi program.

Parameters:
  • msg (str) – The message to send to the Pulumi CLI.

  • resource (Optional[Resource]) – If provided, associate this message with the given resource in the Pulumi CLI.

  • stream_id (Optional[int]) – If provided, associate this message with a stream of other messages.

pulumi.export(name: str, value: Any)

Exports a named stack output.

Parameters:
  • name (str) – The name to assign to this output.

  • value (Any) – The value of this output.

pulumi.get(self, name: str) Any

Used to get values in types decorated with @input_type or @output_type.

pulumi.get_organization() str

Returns the current organization name.

pulumi.get_project() str

Returns the current project name.

pulumi.get_stack() str

Returns the current stack name.

pulumi.getter(_fn=None, *, name: str | None = None)

Decorator to indicate a function is a Pulumi property getter.

name is the Pulumi property name. If not set, the name of the function is used.

pulumi.info(msg: str, resource: Resource | None = None, stream_id: int | None = None, ephemeral: bool | None = None) None

Logs a message to the Pulumi CLI’s info channel, associating it with a resource and stream_id if provided.

Parameters:
  • msg (str) – The message to send to the Pulumi CLI.

  • resource (Optional[Resource]) – If provided, associate this message with the given resource in the Pulumi CLI.

  • stream_id (Optional[int]) – If provided, associate this message with a stream of other messages.

pulumi.input_type(cls: Type[T]) Type[T]

Returns the same class as was passed in, but marked as an input type.

pulumi.output_type(cls: Type[T]) Type[T]

Returns the same class as was passed in, but marked as an output type.

Python property getters are created for each Pulumi output property defined in the class.

If the class is not a subclass of dict and doesn’t have an __init__ method, an __init__ method is added to the class that accepts a dict representing the outputs.

pulumi.property(name: str, *, default: ~typing.Any = <pulumi._types._MISSING_TYPE object>) Any

Return an object to identify Pulumi properties.

name is the Pulumi property name.

pulumi.set(self, name: str, value: Any) None

Used to set values in types decorated with @input_type or @output_type.

pulumi.warn(msg: str, resource: Resource | None = None, stream_id: int | None = None, ephemeral: bool | None = None) None

Logs a message to the Pulumi CLI’s warning channel, associating it with a resource and stream_id if provided.

Parameters:
  • msg (str) – The message to send to the Pulumi CLI.

  • resource (Optional[Resource]) – If provided, associate this message with the given resource in the Pulumi CLI.

  • stream_id (Optional[int]) – If provided, associate this message with a stream of other messages.

pulumi.automation

The automation module contains the Pulumi Automation API, the programmatic interface for driving Pulumi programs without the CLI. Generally this can be thought of as encapsulating the functionality of the CLI (pulumi up, pulumi preview, pulumi destroy, pulumi stack init, etc.) but with more flexibility. This still requires a CLI binary to be installed and available on your $PATH.

In addition to fine-grained building blocks, Automation API provides two out of the box ways to work with Stacks:

  1. Programs locally available on-disk and addressed via a filepath (local source):

    ```python
    stack = create_stack("myOrg/myProj/myStack", work_dir=os.path.join("..", "path", "to", "project"))
    ```
    
  2. Programs defined as a function alongside your Automation API code (inline source):

    ```python
    def pulumi_program():
        bucket = s3.Bucket("bucket")
        pulumi.export("bucket_name", bucket.Bucket)
    
    stack = create_stack("myOrg/myProj/myStack", program=pulumi_program)
    ```
    

Each of these creates a stack with access to the full range of Pulumi lifecycle methods (up/preview/refresh/destroy), as well as methods for managing config, stack, and project settings:

stack.set_config("key", ConfigValue(value="value", secret=True))
preview_response = stack.preview()

The Automation API provides a natural way to orchestrate multiple stacks, feeding the output of one stack as an input to the next as shown in the package-level example below. The package can be used for a number of use cases:

  • Driving pulumi deployments within CI/CD workflows

  • Integration testing

  • Multi-stage deployments such as blue-green deployment patterns

  • Deployments involving application code like database migrations

  • Building higher level tools, custom CLIs over pulumi, etc.

  • Using pulumi behind a REST or GRPC API

  • Debugging Pulumi programs (by using a single main entrypoint with “inline” programs)

To enable a broad range of runtime customization the API defines a Workspace interface. A Workspace is the execution context containing a single Pulumi project, a program, and multiple stacks. Workspaces are used to manage the execution environment, providing various utilities such as plugin installation, environment configuration ($PULUMI_HOME), and creation, deletion, and listing of Stacks. Every Stack including those in the above examples are backed by a Workspace which can be accessed via:

ws = stack.workspace()
ws.install_plugin("aws", "v3.20.0")

Workspaces can be explicitly created and customized beyond the three Stack creation helpers noted above:

ws = LocalWorkspace(work_dir=os.path.join(".", "project", "path"), pulumi_home="~/.pulumi")
stack = create_stack("org/proj/stack", ws)

A default implementation of workspace is provided as LocalWorkspace. This implementation relies on Pulumi.yaml and Pulumi.[stack].yaml as the intermediate format for Project and Stack settings. Modifying ProjectSettings will alter the Workspace Pulumi.yaml file, and setting config on a Stack will modify the Pulumi.[stack].yaml file. This is identical to the behavior of Pulumi CLI driven workspaces. Custom Workspace implementations can be used to store Project and Stack settings as well as Config in a different format, such as an in-memory data structure, a shared persistent SQL database, or cloud object storage. Regardless of the backing Workspace implementation, the Pulumi SaaS Console will still be able to display configuration applied to updates as it does with the local version of the Workspace today.

The Automation API also provides error handling utilities to detect common cases such as concurrent update conflicts:

try:
    up_response = stack.up()
except ConcurrentUpdateError:
    { /* retry logic here */ }
class pulumi.automation.CancelEvent

CancelEvent is emitted when the user initiates a cancellation of the update in progress, or the update successfully completes.

exception pulumi.automation.CommandError(command_result: CommandResult)
exception pulumi.automation.CompilationError(command_result: CommandResult)
exception pulumi.automation.ConcurrentUpdateError(command_result: CommandResult)
class pulumi.automation.ConfigValue(value: str, secret: bool = False)

ConfigValue is the input/output of a pulumi config command. It has a plaintext value, and an option boolean indicating secretness.

class pulumi.automation.DestroyResult(stdout: str, stderr: str, summary: UpdateSummary)
class pulumi.automation.DiagnosticEvent(message: str, color: str, severity: str, stream_id: int | None = None, ephemeral: bool | None = None, urn: str | None = None, prefix: str | None = None)

DiagnosticEvent is emitted whenever a diagnostic message is provided, for example errors from a cloud resource provider while trying to create or update a resource.

Attributes

message: str

The message

color: str

The color to render the message

severity: str

The severity of the message. One of “info”, “info#err”, “warning”, “error”

stream_id: Optional[str]

The stream id

ephemeral: Optional[bool]

Signifies whether the message should be rendered ephemerally in the progress display

urn: Optional[str]

The urn of the resource

prefix: Optional[str]

An optional prefix

class pulumi.automation.DiffKind(value)

DiffKind enumerates the possible kinds of diffs.

Values

  • ADD: indicates that the property was added.

  • ADD_REPLACE: indicates that the property was added and requires that the resource be replaced.

  • DELETE: delete indicates that the property was deleted.

  • DELETE_REPLACE: indicates that the property was deleted and requires that the resource be replaced.

  • UPDATE: update indicates that the property was updated.

  • UPDATE_REPLACE: indicates that the property was updated and requires that the resource be replaced.

class pulumi.automation.EngineEvent(sequence: int, timestamp: int, cancel_event: CancelEvent | None = None, stdout_event: StdoutEngineEvent | None = None, diagnostic_event: DiagnosticEvent | None = None, prelude_event: PreludeEvent | None = None, summary_event: SummaryEvent | None = None, resource_pre_event: ResourcePreEvent | None = None, res_outputs_event: ResOutputsEvent | None = None, res_op_failed_event: ResOpFailedEvent | None = None, policy_event: PolicyEvent | None = None)

EngineEvent describes a Pulumi engine event, such as a change to a resource or diagnostic message. EngineEvent is a discriminated union of all possible event types, and exactly one field will be non-nil.

Attributes

sequence: str

Sequence is a unique, and monotonically increasing number for each engine event sent to the Pulumi Service. Since events may be sent concurrently, and/or delayed via network routing, the sequence number is to ensure events can be placed into a total ordering. - No two events can have the same sequence number. - Events with a lower sequence number must have been emitted before those with a higher

sequence number.

timestamp: int

Timestamp is a Unix timestamp (seconds) of when the event was emitted.

exception pulumi.automation.InlineSourceRuntimeError(command_result: CommandResult)
exception pulumi.automation.InvalidVersionError
class pulumi.automation.LocalWorkspace(work_dir: str | None = None, pulumi_home: str | None = None, program: Callable[[], Awaitable[None] | None] | None = None, env_vars: Mapping[str, str] | None = None, secrets_provider: str | None = None, project_settings: ProjectSettings | None = None, stack_settings: Mapping[str, StackSettings] | None = None, pulumi_command: PulumiCommand | None = None)

LocalWorkspace is a default implementation of the Workspace interface. A Workspace is the execution context containing a single Pulumi project, a program, and multiple stacks. Workspaces are used to manage the execution environment, providing various utilities such as plugin installation, environment configuration ($PULUMI_HOME), and creation, deletion, and listing of Stacks. LocalWorkspace relies on Pulumi.yaml and Pulumi.[stack].yaml as the intermediate format for Project and Stack settings. Modifying ProjectSettings will alter the Workspace Pulumi.yaml file, and setting config on a Stack will modify the Pulumi.[stack].yaml file. This is identical to the behavior of Pulumi CLI driven workspaces.

add_environments(stack_name: str, *environment_names: str) None

Adds environments to the end of a stack’s import list. Imported environments are merged in order per the ESC merge rules. The list of environments behaves as if it were the import list in an anonymous environment.

Parameters:
  • stack_name – The name of the stack.

  • environment_names – The names of the environment to add.

create_stack(stack_name: str) None

Creates and sets a new stack with the stack name, failing if one already exists.

Parameters:

stack_name (str) – The name of the stack to create

Returns:

None

:raises CommandError Raised if a stack with the same name exists.

export_stack(stack_name: str) Deployment

ExportStack exports the deployment state of the stack matching the given name. This can be combined with ImportStack to edit a stack’s state (such as recovery from failed deployments).

Parameters:

stack_name – The name of the stack to export.

Returns:

Deployment

get_all_config(stack_name: str) MutableMapping[str, ConfigValue]

Returns the config map for the specified stack name, scoped to the current Workspace.

Parameters:

stack_name – The name of the stack.

Returns:

ConfigMap

get_config(stack_name: str, key: str, *, path: bool = False) ConfigValue

Returns the value associated with the specified stack name and key, scoped to the Workspace.

Parameters:
  • stack_name – The name of the stack.

  • key – The key for the config item to get.

  • path – The key contains a path to a property in a map or list to get.

Returns:

ConfigValue

get_tag(stack_name: str, key: str) str

Returns the value associated with the specified stack name and key, scoped to the Workspace.

Parameters:
  • stack_name – The name of the stack.

  • key – The key to use for the tag lookup.

Returns:

str

import_stack(stack_name: str, state: Deployment) None

ImportStack imports the specified deployment state into a pre-existing stack. This can be combined with ExportStack to edit a stack’s state (such as recovery from failed deployments).

Parameters:
  • stack_name – The name of the stack to import.

  • state – The deployment state to import.

install_plugin(name: str, version: str, kind: str = 'resource') None

Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.

Parameters:
  • name – The name of the plugin to install.

  • version – The version to install.

  • kind – The kind of plugin.

install_plugin_from_server(name: str, version: str, server: str) None

Installs a plugin in the Workspace from a remote server, for example a third party plugin.

Parameters:
  • name – The name of the plugin to install.

  • version – The version to install.

  • server – The server to install from.

list_environments(stack_name: str) List[str]

Returns the list of environments specified in a stack’s configuration.

Parameters:

stack_name – The name of the stack.

Returns:

List[str]

list_plugins() List[PluginInfo]

Returns a list of all plugins installed in the Workspace.

Returns:

List[PluginInfo]

list_stacks() List[StackSummary]

Returns all Stacks created under the current Project. This queries underlying backend and may return stacks not present in the Workspace (as Pulumi.<stack>.yaml files).

Returns:

List[StackSummary]

list_tags(stack_name: str) MutableMapping[str, str]

Returns the tag map for the specified tag name, scoped to the Workspace.

Parameters:

stack_name – The name of the stack.

Returns:

TagMap

post_command_callback(stack_name: str) None

A hook executed after every command. Called with the stack name. An extensibility point to perform workspace cleanup (CLI operations may create/modify a Pulumi.stack.yaml) LocalWorkspace does not utilize this extensibility point.

Parameters:

stack_name – The name of the stack.

project_settings() ProjectSettings

Returns the settings object for the current project if any.

Returns:

ProjectSettings

property pulumi_version: str
refresh_config(stack_name: str) None

Gets and sets the config map used with the last update for Stack matching stack name.

Parameters:

stack_name – The name of the stack.

remove_all_config(stack_name: str, keys: List[str], *, path: bool = False) None

Removes all values in the provided key list for the specified stack name.

Parameters:
  • stack_name – The name of the stack.

  • keys – The keys to remove from config.

  • path – The keys contain a path to a property in a map or list to remove.

remove_config(stack_name: str, key: str, *, path: bool = False) None

Removes the specified key-value pair on the provided stack name.

Parameters:
  • stack_name – The name of the stack.

  • key – The key to remove from config.

  • path – The key contains a path to a property in a map or list to remove.

remove_environment(stack_name: str, environment_name: str) None

Removes the specified environment from the stack configuration.

Parameters:
  • stack_name – The name of the stack.

  • environment_name – The name of the environment to remove.

remove_plugin(name: str | None = None, version_range: str | None = None, kind: str = 'resource') None

Removes a plugin from the Workspace matching the specified name and version.

Parameters:
  • name – The name of the plugin to remove.

  • version_range – The version range to remove.

  • kind – The kind of plugin.

remove_stack(stack_name: str) None

Deletes the stack and all associated configuration and history.

Parameters:

stack_name – The name of the stack to remove

remove_tag(stack_name: str, key: str) None

Removes the specified key-value pair on the provided stack name.

Parameters:
  • stack_name – The name of the stack.

  • key – The tag key to remove.

save_project_settings(settings: ProjectSettings) None

Overwrites the settings object in the current project. There can only be a single project per workspace. Fails is new project name does not match old.

Parameters:

settings – The project settings to save.

save_stack_settings(stack_name: str, settings: StackSettings) None

Overwrites the settings object for the stack matching the specified stack name.

Parameters:
  • stack_name – The name of the stack.

  • settings – The stack settings to save.

select_stack(stack_name: str) None

Selects and sets an existing stack matching the stack stack_name, failing if none exists.

Parameters:

stack_name – The name of the stack to select

Returns:

None

:raises CommandError Raised if no matching stack exists.

serialize_args_for_op(stack_name: str) List[str]

A hook to provide additional args to CLI commands before they are executed. Provided with stack name, returns a list of args to append to an invoked command [”–config=…”, ] LocalWorkspace does not utilize this extensibility point.

Parameters:

stack_name – The name of the stack.

set_all_config(stack_name: str, config: MutableMapping[str, ConfigValue], *, path: bool = False) None

Sets all values in the provided config map for the specified stack name.

Parameters:
  • stack_name – The name of the stack.

  • config – A mapping of key to ConfigValue to set to config.

  • path – The keys contain a path to a property in a map or list to set.

set_config(stack_name: str, key: str, value: ConfigValue, *, path: bool = False) None

Sets the specified key-value pair on the provided stack name.

Parameters:
  • stack_name – The name of the stack.

  • key – The config key to add.

  • value – The config value to add.

  • path – The key contains a path to a property in a map or list to set.

set_tag(stack_name: str, key: str, value: str) None

Sets the specified key-value pair on the provided stack name.

Parameters:
  • stack_name – The name of the stack.

  • key – The tag key to set.

  • value – The tag value to set.

stack() StackSummary | None

Returns a summary of the currently selected stack, if any.

Returns:

Optional[StackSummary]

stack_outputs(stack_name: str) MutableMapping[str, OutputValue]

Gets the current set of Stack outputs from the last Stack.up().

Parameters:

stack_name – The name of the stack.

Returns:

OutputMap

stack_settings(stack_name: str) StackSettings

Returns the settings object for the stack matching the specified stack name if any.

Parameters:

stack_name – The name of the stack.

Returns:

StackSettings

who_am_i() WhoAmIResult

Returns the currently authenticated user.

Returns:

WhoAmIResult

class pulumi.automation.OpType(value)

The granular CRUD operation performed on a particular resource during an update.

class pulumi.automation.PolicyEvent(message: str, color: str, policy_name: str, policy_pack_name: str, policy_pack_version: str, policy_pack_version_tag: str, enforcement_level: str, resource_urn: str | None = None)

PolicyEvent is emitted whenever there is a Policy violation.

Attributes

message: str

The message

color: str

The color to render the message

policy_name: str

The name of the policy

policy_pack_name: str

The name of the policy pack

policy_pack_version: str

The version of the policy pack

policy_pack_version_tag: str

The policy pack version tag

enforcement_level: str

The enforcement level of the policy. One of “warning or “mandatory”

resource_urn: Optional[str]

The urn of the resource associated with this event

class pulumi.automation.PreludeEvent(config: Mapping[str, str])

PreludeEvent is emitted at the start of an update.

Attributes

config: Mapping[str, str]

config contains the keys and values for the update. Encrypted configuration values may be blinded.

class pulumi.automation.PreviewResult(stdout: str, stderr: str, change_summary: MutableMapping[OpType, int])
class pulumi.automation.ProjectBackend(url: str | None = None)

Configuration for the project’s Pulumi state storage backend.

class pulumi.automation.ProjectRuntimeInfo(name: str, options: Mapping[str, Any] | None = None)

A description of the Project’s program runtime and associated metadata.

class pulumi.automation.ProjectSettings(name: str, runtime: str | ProjectRuntimeInfo, main: str | None = None, description: str | None = None, author: str | None = None, website: str | None = None, license: str | None = None, config: str | None = None, template: ProjectTemplate | None = None, backend: ProjectBackend | None = None)

A Pulumi project manifest. It describes metadata applying to all sub-stacks created from the project.

class pulumi.automation.PropertyDiff(diff_kind: DiffKind, input_diff: bool)

PropertyDiff describes the difference between a single property’s old and new values.

Attributes

diff_kind: DiffKind

diff_kind is the kind of difference.

input_diff: bool

input_diff is true if this is a difference between old and new inputs rather than old state and new inputs.

class pulumi.automation.PulumiCommand(root: str | None = None, version: VersionInfo | None = None, skip_version_check: bool = False)

PulumiCommand manages the Pulumi CLI. It can be used to to install the CLI and run commands.

Creates a new PulumiCommand.

Parameters:
  • root – The directory where to look for the Pulumi installation. Defaults to running pulumi from $PATH.

  • version – The minimum version of the Pulumi CLI to use and validates that it is compatbile with this version.

  • skip_version_check – If true the version validation will be skipped. The env variable PULUMI_AUTOMATION_API_SKIP_VERSION_CHECK also disable this check, and takes precendence. If it is set it is not possible to re-enable the validation even if skip_version_check is True.

classmethod install(root: str | None = None, version: VersionInfo | None = None, skip_version_check: bool = False) PulumiCommand

Downloads and installs the Pulumi CLI. By default the CLI version matching the current SDK release is installed in $HOME/.pulumi/versions/$VERSION. Set root to specify a different directory, and version to install a custom version.

Parameters:
  • root – The root directory to install the CLI to. Defaults to ~/.pulumi/versions/<version>

  • version – The version of the CLI to install. Defaults to the version matching the SDK version.

Skip_version_check:

If true, the version validation will be skipped. See parameter skip_version_check in __init__.

run(args: List[str], cwd: str, additional_env: Mapping[str, str], on_output: Callable[[str], Any] | None = None) CommandResult

Runs a Pulumi command, returning a CommandResult. If the command fails, a CommandError is raised.

Parameters:
  • args – The arguments to pass to the Pulumi CLI, for example [“stack”, “ls”].

  • cwd – The working directory to run the command in.

  • additional_env – Additional environment variables to set when running the command.

  • on_output – A callback to invoke when the command outputs data.

class pulumi.automation.RefreshResult(stdout: str, stderr: str, summary: UpdateSummary)
class pulumi.automation.RemoteGitAuth(*, ssh_private_key_path: str | None = None, ssh_private_key: str | None = None, password: str | None = None, personal_access_token: str | None = None, username: str | None = None)

Authentication options for the repository that can be specified for a private Git repo. There are three different authentication paths:

  • Personal accesstoken

  • SSH private key (and its optional password)

  • Basic auth username and password

Only one authentication path is valid.

password: str | None

The password that pairs with a username or as part of an SSH Private Key.

personal_access_token: str | None

A Git personal access token in replacement of your password.

ssh_private_key: str | None

The (contents) private key for access to the git repo.

ssh_private_key_path: str | None

The absolute path to a private key for access to the git repo.

username: str | None

The username to use when authenticating to a git repository.

class pulumi.automation.RemoteStack(stack: Stack)

RemoteStack is an isolated, independencly configurable instance of a Pulumi program that is operated on remotely (up/preview/refresh/destroy).

cancel() None

Cancel stops a stack’s currently running update. It returns an error if no update is currently running. Note that this operation is _very dangerous_, and may leave the stack in an inconsistent state if a resource operation was pending when the update was canceled. This command is not supported for diy backends.

destroy(on_output: Callable[[str], Any] | None = None, on_event: Callable[[EngineEvent], Any] | None = None) DestroyResult

Destroy deletes all resources in a stack, leaving all history and configuration intact.

Parameters:
  • on_output – A function to process the stdout stream.

  • on_event – A function to process structured events from the Pulumi event stream.

Returns:

DestroyResult

export_stack() Deployment

export_stack exports the deployment state of the stack. This can be combined with Stack.import_state to edit a stack’s state (such as recovery from failed deployments).

Returns:

Deployment

history(page_size: int | None = None, page: int | None = None) List[UpdateSummary]

Returns a list summarizing all previous and current results from Stack lifecycle operations (up/preview/refresh/destroy).

Parameters:
  • page_size – Paginate history entries (used in combination with page), defaults to all.

  • page – Paginate history entries (used in combination with page_size), defaults to all.

  • show_secrets – Show config secrets when they appear in history.

Returns:

List[UpdateSummary]

import_stack(state: Deployment) None

import_stack imports the specified deployment state into a pre-existing stack. This can be combined with Stack.export_state to edit a stack’s state (such as recovery from failed deployments).

Parameters:

state – The deployment state to import.

outputs() MutableMapping[str, OutputValue]

Gets the current set of Stack outputs from the last Stack.up().

Returns:

OutputMap

preview(on_output: Callable[[str], Any] | None = None, on_event: Callable[[EngineEvent], Any] | None = None) PreviewResult

Performs a dry-run update to a stack, returning pending changes. https://www.pulumi.com/docs/cli/commands/pulumi_preview/

Parameters:
  • on_output – A function to process the stdout stream.

  • on_event – A function to process structured events from the Pulumi event stream.

Returns:

PreviewResult

refresh(on_output: Callable[[str], Any] | None = None, on_event: Callable[[EngineEvent], Any] | None = None) RefreshResult

Compares the current stack’s resource state with the state known to exist in the actual cloud provider. Any such changes are adopted into the current stack.

Parameters:
  • on_output – A function to process the stdout stream.

  • on_event – A function to process structured events from the Pulumi event stream.

Returns:

RefreshResult

up(on_output: Callable[[str], Any] | None = None, on_event: Callable[[EngineEvent], Any] | None = None) UpResult

Creates or updates the resources in a stack by executing the program in the Workspace. https://www.pulumi.com/docs/cli/commands/pulumi_up/

Parameters:
  • on_output – A function to process the stdout stream.

  • on_event – A function to process structured events from the Pulumi event stream.

Returns:

UpResult

class pulumi.automation.RemoteWorkspaceOptions(*, env_vars: Mapping[str, str | Secret] | None = None, pre_run_commands: List[str] | None = None, skip_install_dependencies: bool | None = None)

Extensibility options to configure a RemoteWorkspace.

class pulumi.automation.ResOpFailedEvent(metadata: StepEventMetadata, status: int, steps: int)

ResOpFailedEvent is emitted when a resource operation fails. Typically a DiagnosticEvent is emitted before this event, indicating the root cause of the error.

class pulumi.automation.ResOutputsEvent(metadata: StepEventMetadata, planning: bool | None = None)

ResOutputsEvent is emitted when a resource is finished being provisioned.

class pulumi.automation.ResourcePreEvent(metadata: StepEventMetadata, planning: bool | None = None)

ResourcePreEvent is emitted before a resource is modified.

exception pulumi.automation.RuntimeError(command_result: CommandResult)
class pulumi.automation.Secret

Represents a secret value.

exception pulumi.automation.StackAlreadyExistsError(command_result: CommandResult)
exception pulumi.automation.StackNotFoundError(command_result: CommandResult)
class pulumi.automation.StackSettings(secrets_provider: str | None = None, encrypted_key: str | None = None, encryption_salt: str | None = None, config: Dict[str, Any] | None = None)

A description of the Stack’s configuration and encryption metadata.

class pulumi.automation.StackSummary(name: str, current: bool, update_in_progress: bool | None = None, last_update: datetime | None = None, resource_count: int | None = None, url: str | None = None)

A summary of the status of a given stack.

class pulumi.automation.StdoutEngineEvent(message: str, color: str)

StdoutEngineEvent is emitted whenever a generic message is written, for example warnings from the pulumi CLI itself. Less common than DiagnosticEvent.

Attributes

message: str

The message

color: str

The color to render the message

class pulumi.automation.StepEventMetadata(op: OpType, urn: str, type: str, provider: str, old: StepEventStateMetadata | None = None, new: StepEventStateMetadata | None = None, keys: List[str] | None = None, diffs: List[str] | None = None, detailed_diff: Mapping[str, PropertyDiff] | None = None, logical: bool | None = None)

StepEventMetadata describes a “step” within the Pulumi engine, which is any concrete action to migrate a set of cloud resources from one state to another.

Attributes

op: OpType

The operation being performed.

urn: str

The urn of the resource.

type: str

The type of resource.

provider: str

The provider actually performing the step.

old: Optional[StepEventStateMetadata]

old is the state of the resource before performing the step.

new: Optional[StepEventStateMetadata]

new is the state of the resource after performing the step.

keys: Optional[List[str]]

keys causing a replacement (only applicable for “create” and “replace” Ops)

diffs: Optional[List[str]]

Keys that changed with this step.

detailed_diff: Optional[Mapping[str, PropertyDiff]]

The diff for this step as a list of property paths and difference types.

logical: Optional[bool]

Logical is set if the step is a logical operation in the program.

class pulumi.automation.StepEventStateMetadata(type: str, urn: str, id: str, parent: str, provider: str, custom: bool | None = None, delete: bool | None = None, protect: bool | None = None, retain_on_delete: bool | None = None, inputs: Mapping[str, Any] | None = None, outputs: Mapping[str, Any] | None = None, init_errors: List[str] | None = None)

StepEventStateMetadata is the more detailed state information for a resource as it relates to a step(s) being performed.

Attributes

type: str

The type of the resource

urn: str

The URN of the resource

id: str

The resource’s id

parent: str

The URN of the parent resource

provider: str

The URN of the resource provider

custom: bool

Indicates if the resource is managed by a plugin

delete: bool

True when the resource is pending deletion due to replacement.

protect: bool

Protect is true to “protect” this resource (protected resources cannot be deleted).

retain_on_delete: boolean;

RetainOnDelete is true if the resource is not physically deleted when it is logically deleted.

inputs: Mapping[str, Any]

Inputs contains the resource’s input properties (as specified by the program). Secrets have filtered out, and large assets have been replaced by hashes as applicable.

outputs: Mapping[str, Any]

Outputs contains the resource’s complete output state (as returned by the resource provider).

init_errors: Optional[List[str]]

init_errors is the set of errors encountered in the process of initializing resource.

class pulumi.automation.SummaryEvent(maybe_corrupt: bool, duration_seconds: int, resource_changes: MutableMapping[OpType, int], policy_packs: Mapping[str, str])

SummaryEvent is emitted at the end of an update, with a summary of the changes made.

Attributes

maybe_corrupt: bool

maybeCorrupt is set if one or more of the resources is in an invalid state.

duration_seconds: int

duration is the number of seconds the update was executing.

resource_changes: OpMap

resourceChanges contains the count for resource change by type. The keys are deploy.StepOp, which is not exported in this package.

policy_packs: Mapping[str, str]

policyPacks run during update. Maps PolicyPackName -> version. Note: When this field was initially added, we forgot to add the JSON tag and are now locked into using PascalCase for this field to maintain backwards compatibility. For older clients this will map to the version, while for newer ones it will be the version tag prepended with “v”.

class pulumi.automation.UpResult(stdout: str, stderr: str, summary: UpdateSummary, outputs: MutableMapping[str, OutputValue])
class pulumi.automation.WhoAmIResult(user: str, url: str | None = None, organizations: List[str] | None = None)

The currently logged-in Pulumi identity.

class pulumi.automation.Workspace

Workspace is the execution context containing a single Pulumi project, a program, and multiple stacks. Workspaces are used to manage the execution environment, providing various utilities such as plugin installation, environment configuration ($PULUMI_HOME), and creation, deletion, and listing of Stacks.

abstract add_environments(stack_name: str, *environment_names: str) None

Adds environments to the end of a stack’s import list. Imported environments are merged in order per the ESC merge rules. The list of environments behaves as if it were the import list in an anonymous environment.

Parameters:
  • stack_name – The name of the stack.

  • environment_names – The names of the environment to add.

abstract create_stack(stack_name: str) None

Creates and sets a new stack with the stack name, failing if one already exists.

Parameters:

stack_name (str) – The name of the stack to create

Returns:

None

:raises CommandError Raised if a stack with the same name exists.

env_vars: Mapping[str, str] = {}

Environment values scoped to the current workspace. These will be supplied to every Pulumi command.

abstract export_stack(stack_name: str) Deployment

ExportStack exports the deployment state of the stack matching the given name. This can be combined with ImportStack to edit a stack’s state (such as recovery from failed deployments).

Parameters:

stack_name – The name of the stack to export.

Returns:

Deployment

abstract get_all_config(stack_name: str) MutableMapping[str, ConfigValue]

Returns the config map for the specified stack name, scoped to the current Workspace.

Parameters:

stack_name – The name of the stack.

Returns:

ConfigMap

abstract get_config(stack_name: str, key: str, *, path: bool = False) ConfigValue

Returns the value associated with the specified stack name and key, scoped to the Workspace.

Parameters:
  • stack_name – The name of the stack.

  • key – The key for the config item to get.

  • path – The key contains a path to a property in a map or list to get.

Returns:

ConfigValue

abstract get_tag(stack_name: str, key: str) str

Returns the value associated with the specified stack name and key, scoped to the Workspace.

Parameters:
  • stack_name – The name of the stack.

  • key – The key to use for the tag lookup.

Returns:

str

abstract import_stack(stack_name: str, state: Deployment) None

ImportStack imports the specified deployment state into a pre-existing stack. This can be combined with ExportStack to edit a stack’s state (such as recovery from failed deployments).

Parameters:
  • stack_name – The name of the stack to import.

  • state – The deployment state to import.

abstract install_plugin(name: str, version: str, kind: str = 'resource') None

Installs a plugin in the Workspace, for example to use cloud providers like AWS or GCP.

Parameters:
  • name – The name of the plugin to install.

  • version – The version to install.

  • kind – The kind of plugin.

abstract install_plugin_from_server(name: str, version: str, server: str) None

Installs a plugin in the Workspace from a remote server, for example a third party plugin.

Parameters:
  • name – The name of the plugin to install.

  • version – The version to install.

  • server – The server to install from.

abstract list_environments(stack_name: str) List[str]

Returns the list of environments specified in a stack’s configuration.

Parameters:

stack_name – The name of the stack.

Returns:

List[str]

abstract list_plugins() List[PluginInfo]

Returns a list of all plugins installed in the Workspace.

Returns:

List[PluginInfo]

abstract list_stacks() List[StackSummary]

Returns all Stacks created under the current Project. This queries underlying backend and may return stacks not present in the Workspace (as Pulumi.<stack>.yaml files).

Returns:

List[StackSummary]

abstract list_tags(stack_name: str) MutableMapping[str, str]

Returns the tag map for the specified tag name, scoped to the Workspace.

Parameters:

stack_name – The name of the stack.

Returns:

TagMap

abstract post_command_callback(stack_name: str) None

A hook executed after every command. Called with the stack name. An extensibility point to perform workspace cleanup (CLI operations may create/modify a Pulumi.stack.yaml) LocalWorkspace does not utilize this extensibility point.

Parameters:

stack_name – The name of the stack.

program: Callable[[], Awaitable[None] | None] | None

The inline program PulumiFn to be used for Preview/Update operations if any. If none is specified, the stack will refer to ProjectSettings for this information.

abstract project_settings() ProjectSettings

Returns the settings object for the current project if any.

Returns:

ProjectSettings

pulumi_command: PulumiCommand

The underlying PulumiCommand instance that is used to execute CLI commands.

pulumi_home: str | None

The directory override for CLI metadata if set. This customizes the location of $PULUMI_HOME where metadata is stored and plugins are installed.

pulumi_version: str

The version of the underlying Pulumi CLI/Engine.

abstract refresh_config(stack_name: str) None

Gets and sets the config map used with the last update for Stack matching stack name.

Parameters:

stack_name – The name of the stack.

abstract remove_all_config(stack_name: str, keys: List[str], *, path: bool = False) None

Removes all values in the provided key list for the specified stack name.

Parameters:
  • stack_name – The name of the stack.

  • keys – The keys to remove from config.

  • path – The keys contain a path to a property in a map or list to remove.

abstract remove_config(stack_name: str, key: str, *, path: bool = False) None

Removes the specified key-value pair on the provided stack name.

Parameters:
  • stack_name – The name of the stack.

  • key – The key to remove from config.

  • path – The key contains a path to a property in a map or list to remove.

abstract remove_environment(stack_name: str, environment_name: str) None

Removes the specified environment from the stack configuration.

Parameters:
  • stack_name – The name of the stack.

  • environment_name – The name of the environment to remove.

abstract remove_plugin(name: str | None = None, version_range: str | None = None, kind: str = 'resource') None

Removes a plugin from the Workspace matching the specified name and version.

Parameters:
  • name – The name of the plugin to remove.

  • version_range – The version range to remove.

  • kind – The kind of plugin.

abstract remove_stack(stack_name: str) None

Deletes the stack and all associated configuration and history.

Parameters:

stack_name – The name of the stack to remove

abstract remove_tag(stack_name: str, key: str) None

Removes the specified key-value pair on the provided stack name.

Parameters:
  • stack_name – The name of the stack.

  • key – The tag key to remove.

abstract save_project_settings(settings: ProjectSettings) None

Overwrites the settings object in the current project. There can only be a single project per workspace. Fails is new project name does not match old.

Parameters:

settings – The project settings to save.

abstract save_stack_settings(stack_name: str, settings: StackSettings) None

Overwrites the settings object for the stack matching the specified stack name.

Parameters:
  • stack_name – The name of the stack.

  • settings – The stack settings to save.

secrets_provider: str | None

The secrets provider to use for encryption and decryption of stack secrets. See: https://www.pulumi.com/docs/intro/concepts/secrets/#available-encryption-providers

abstract select_stack(stack_name: str) None

Selects and sets an existing stack matching the stack stack_name, failing if none exists.

Parameters:

stack_name – The name of the stack to select

Returns:

None

:raises CommandError Raised if no matching stack exists.

abstract serialize_args_for_op(stack_name: str) List[str]

A hook to provide additional args to CLI commands before they are executed. Provided with stack name, returns a list of args to append to an invoked command [”–config=…”, ] LocalWorkspace does not utilize this extensibility point.

Parameters:

stack_name – The name of the stack.

abstract set_all_config(stack_name: str, config: MutableMapping[str, ConfigValue], *, path: bool = False) None

Sets all values in the provided config map for the specified stack name.

Parameters:
  • stack_name – The name of the stack.

  • config – A mapping of key to ConfigValue to set to config.

  • path – The keys contain a path to a property in a map or list to set.

abstract set_config(stack_name: str, key: str, value: ConfigValue, *, path: bool = False) None

Sets the specified key-value pair on the provided stack name.

Parameters:
  • stack_name – The name of the stack.

  • key – The config key to add.

  • value – The config value to add.

  • path – The key contains a path to a property in a map or list to set.

abstract set_tag(stack_name: str, key: str, value: str) None

Sets the specified key-value pair on the provided stack name.

Parameters:
  • stack_name – The name of the stack.

  • key – The tag key to set.

  • value – The tag value to set.

abstract stack() StackSummary | None

Returns a summary of the currently selected stack, if any.

Returns:

Optional[StackSummary]

abstract stack_outputs(stack_name: str) MutableMapping[str, OutputValue]

Gets the current set of Stack outputs from the last Stack.up().

Parameters:

stack_name – The name of the stack.

Returns:

OutputMap

abstract stack_settings(stack_name: str) StackSettings

Returns the settings object for the stack matching the specified stack name if any.

Parameters:

stack_name – The name of the stack.

Returns:

StackSettings

abstract who_am_i() WhoAmIResult

Returns the currently authenticated user.

Returns:

WhoAmIResult

work_dir: str

The working directory to run Pulumi CLI commands

pulumi.automation.create_or_select_remote_stack_git_source(stack_name: str, url: str, *, branch: str | None = None, commit_hash: str | None = None, project_path: str | None = None, auth: RemoteGitAuth | None = None, opts: RemoteWorkspaceOptions | None = None) RemoteStack

PREVIEW: Creates or selects an existing Stack backed by a RemoteWorkspace with source code from the specified Git repository. Pulumi operations on the stack (Preview, Update, Refresh, and Destroy) are performed remotely.

pulumi.automation.create_or_select_stack(stack_name: str, project_name: str | None = None, program: Callable[[], Awaitable[None] | None] | None = None, work_dir: str | None = None, opts: LocalWorkspaceOptions | None = None) Stack

Creates or selects an existing Stack with a LocalWorkspace utilizing the specified inline (in process) Pulumi program or the local Pulumi CLI program from the specified working dir.

Inline Programs

For inline programs, the program and project_name keyword arguments must be provided. This program is fully debuggable and runs in process. The work_dir keyword argument is ignored (but see the note on the work_dir field of opts, below).

If no project_settings option is specified, default project settings will be created on behalf of the user. Similarly, unless a work_dir option is specified, the working directory will default to a new temporary directory provided by the OS.

Example of selecting a stack with an inline program:

create_or_select_stack(‘dev’, project_name=’my-app’, program=myAppFn)

Local Programs

For local programs, the work_dir keyword argument must be provided, and will override the work_dir field in opts. Keyword arguments other than work_dir and opts are ignored.

This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files (Pulumi.yaml, Pulumi.[stack].yaml).

Example of creating or selecting a stack with a local program:

create_or_select_stack(‘dev’, work_dir=’myapp/’)

Parameters:
  • stack_name – The name of the stack.

  • project_name – The name of the project - required for inline programs.

  • program – The inline program - required for inline programs.

  • work_dir – The directory for a CLI-driven stack - required for local programs.

  • opts – Extensibility options to configure a LocalWorkspace; e.g: settings to seed and environment variables to pass through to every command.

Returns:

Stack

pulumi.automation.create_remote_stack_git_source(stack_name: str, url: str, *, branch: str | None = None, commit_hash: str | None = None, project_path: str | None = None, auth: RemoteGitAuth | None = None, opts: RemoteWorkspaceOptions | None = None) RemoteStack

PREVIEW: Creates a Stack backed by a RemoteWorkspace with source code from the specified Git repository. Pulumi operations on the stack (Preview, Update, Refresh, and Destroy) are performed remotely.

pulumi.automation.create_stack(stack_name: str, project_name: str | None = None, program: Callable[[], Awaitable[None] | None] | None = None, work_dir: str | None = None, opts: LocalWorkspaceOptions | None = None) Stack

Creates a Stack with a LocalWorkspace utilizing the specified inline (in process) Pulumi program or the local Pulumi CLI program from the specified working dir.

Inline Programs

For inline programs, the program and project_name keyword arguments must be provided. This program is fully debuggable and runs in process. The work_dir keyword argument is ignored (but see the note on the work_dir field of opts, below).

If no project_settings option is specified, default project settings will be created on behalf of the user. Similarly, unless a work_dir option is specified, the working directory will default to a new temporary directory provided by the OS.

Example of creating a stack with an inline program:

create_stack(‘dev’, project_name=’my-app’, program=myAppFn)

Local Programs

For local programs, the work_dir keyword argument must be provided, and will override the work_dir field in opts. Keyword arguments other than work_dir and opts are ignored.

This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files (Pulumi.yaml, Pulumi.[stack].yaml).

Example of creating a stack with a local program:

create_stack(‘dev’, work_dir=’myapp/’)

Parameters:
  • stack_name – The name of the stack.

  • project_name – The name of the project - required for inline programs.

  • program – The inline program - required for inline programs.

  • work_dir – The directory for a CLI-driven stack - required for local programs.

  • opts – Extensibility options to configure a LocalWorkspace; e.g: settings to seed and environment variables to pass through to every command.

Returns:

Stack

pulumi.automation.fully_qualified_stack_name(org: str, project: str, stack: str) str

Returns a stack name formatted with the greatest possible specificity: org/project/stack or user/project/stack

Using this format avoids ambiguity in stack identity guards creating or selecting the wrong stack.

Note that legacy diy backends (local file, S3, Azure Blob) do not support stack names in this format, and instead only use the stack name without an org/user or project to qualify it. See: https://github.com/pulumi/pulumi/issues/2522 Non-legacy diy backends do support the org/project/stack format but org must be set to “organization”.

Parameters:
  • org – The name of the org or user.

  • project – The name of the project.

  • stack – The name of the stack.

Returns:

The fully qualified stack name.

pulumi.automation.select_remote_stack_git_source(stack_name: str, url: str, *, branch: str | None = None, commit_hash: str | None = None, project_path: str | None = None, auth: RemoteGitAuth | None = None, opts: RemoteWorkspaceOptions | None = None) RemoteStack

PREVIEW: Creates or selects an existing Stack backed by a RemoteWorkspace with source code from the specified Git repository. Pulumi operations on the stack (Preview, Update, Refresh, and Destroy) are performed remotely.

pulumi.automation.select_stack(stack_name: str, project_name: str | None = None, program: Callable[[], Awaitable[None] | None] | None = None, work_dir: str | None = None, opts: LocalWorkspaceOptions | None = None) Stack

Selects a Stack with a LocalWorkspace utilizing the specified inline (in process) Pulumi program or the local Pulumi CLI program from the specified working dir.

Inline Programs

For inline programs, the program and project_name keyword arguments must be provided. This program is fully debuggable and runs in process. The work_dir keyword argument is ignored (but see the note on the work_dir field of opts, below).

If no project_settings option is specified, default project settings will be created on behalf of the user. Similarly, unless a work_dir option is specified, the working directory will default to a new temporary directory provided by the OS.

Example of selecting a stack with an inline program:

select_stack(‘dev’, project_name=’my-app’, program=myAppFn)

Local Programs

For local programs, the work_dir keyword argument must be provided, and will override the work_dir field in opts. Keyword arguments other than work_dir and opts are ignored.

This is a way to create drivers on top of pre-existing Pulumi programs. This Workspace will pick up any available Settings files (Pulumi.yaml, Pulumi.[stack].yaml).

Example of selecting a stack with a local program:

select_stack(‘dev’, work_dir=’myapp/’)

Parameters:
  • stack_name – The name of the stack.

  • project_name – The name of the project - required for inline programs.

  • program – The inline program - required for inline programs.

  • work_dir – The directory for a CLI-driven stack - required for local programs.

  • opts – Extensibility options to configure a LocalWorkspace; e.g: settings to seed and environment variables to pass through to every command.

Returns:

Stack

pulumi.dynamic

Dynamic Providers for Python.

class pulumi.dynamic.CheckFailure(property_: str, reason: str)

CheckFailure represents a single failure in the results of a call to ResourceProvider.check

property: str

The property that failed validation.

reason: str

The reason that the property failed validation.

class pulumi.dynamic.CheckResult(inputs: Any, failures: List[CheckFailure])

CheckResult represents the results of a call to ResourceProvider.check.

failures: List[CheckFailure]

Any validation failures that occurred.

inputs: Any

The inputs to use, if any.

class pulumi.dynamic.CreateResult(id_: str, outs: Any | None = None)

CreateResult represents the results of a call to ResourceProvider.create.

id: str

The ID of the created resource.

outs: Any | None

Any properties that were computed during creation.

class pulumi.dynamic.DiffResult(changes: bool | None = None, replaces: List[str] | None = None, stables: List[str] | None = None, delete_before_replace: bool | None = None)

DiffResult represents the results of a call to ResourceProvider.diff.

changes: bool | None

If true, this diff detected changes and suggests an update.

delete_before_replace: bool | None

If true, and a replacement occurs, the resource will first be deleted before being recreated. This is to void potential side-by-side issues with the default create before delete behavior.

replaces: List[str] | None

If this update requires a replacement, the set of properties triggering it.

stables: List[str] | None

An optional list of properties that will not ever change.

class pulumi.dynamic.ReadResult(id_: str | None = None, outs: Any | None = None)

The ID of the resource ready back (or blank if missing).

id: str | None

The ID of the resource ready back (or blank if missing).

outs: Any | None

The current property state read from the live environment.

class pulumi.dynamic.Resource(provider: ResourceProvider, name: str, props: Inputs, opts: ResourceOptions | None = None)

Resource represents a Pulumi Resource that incorporates an inline implementation of the Resource’s CRUD operations.

Parameters:
  • provider (str) – The implementation of the resource’s CRUD operations.

  • name (str) – The name of this resource.

  • props (Optional[dict]) – The arguments to use to populate the new resource. Must not define the reserved property “__provider”.

  • opts (Optional[ResourceOptions]) – A bag of options that control this resource’s behavior.

class pulumi.dynamic.ResourceProvider

ResourceProvider is a Dynamic Resource Provider which allows defining new kinds of resources whose CRUD operations are implemented inside your Python program.

check(_olds: Any, news: Any) CheckResult

Check validates that the given property bag is valid for a resource of the given type.

create(props: Any) CreateResult

Create allocates a new instance of the provided resource and returns its unique ID afterwards. If this call fails, the resource must not have been created (i.e., it is “transactional”).

delete(_id: str, _props: Any) None

Delete tears down an existing resource with the given ID. If it fails, the resource is assumed to still exist.

diff(_id: str, _olds: Any, _news: Any) DiffResult

Diff checks what impacts a hypothetical update will have on the resource’s properties.

read(id_: str, props: Any) ReadResult

Reads the current live state associated with a resource. Enough state must be included in the inputs to uniquely identify the resource; this is typically just the resource ID, but it may also include some properties.

update(_id: str, _olds: Any, _news: Any) UpdateResult

Update updates an existing resource with new values.

class pulumi.dynamic.UpdateResult(outs: Any | None = None)

UpdateResult represents the results of a call to ResourceProvider.update.

outs: Any | None

Any properties that were computed during updating.

pulumi.provider

class pulumi.provider.CallResult(outputs: Mapping[str, Any | Awaitable[Any] | Output[T]], failures: Sequence[CheckFailure] | None = None)

CallResult represents the results of a call to Provider.call.

failures: Sequence[CheckFailure] | None

Any validation failures that occurred.

outputs: Mapping[str, Any | Awaitable[Any] | Output[T]]

The outputs returned by the invoked function, if any.

class pulumi.provider.CheckFailure(property: str, reason: str)

CheckFailure represents a single failure in the results of a call to Provider.call.

property: str

The property that failed validation.

reason: str

The reason that the property failed validation.

class pulumi.provider.ConstructResult(urn: str | Awaitable[str] | Output[T], state: Mapping[str, Any | Awaitable[Any] | Output[T]])

ConstructResult represents the results of a call to Provider.construct.

state: Mapping[str, Any | Awaitable[Any] | Output[T]]

Any state that was computed during construction.

urn: str | Awaitable[str] | Output[T]

The URN of the constructed resource.

class pulumi.provider.Provider(version: str, schema: str | None = None)

Provider represents an object that implements the resources and functions for a particular Pulumi package.

Parameters:
  • version (str) – The version of the provider. Must be valid semver.

  • schema (Optional[str]) – The JSON-encoded schema for this provider’s package.

call(token: str, args: Mapping[str, Any | Awaitable[Any] | Output[T]]) CallResult

Call calls the indicated function.

Parameters:
  • token (str) – The token of the function to call.

  • args (Inputs) – The inputs to the function.

construct(name: str, resource_type: str, inputs: Mapping[str, Any | Awaitable[Any] | Output[T]], options: ResourceOptions | None = None) ConstructResult

Construct creates a new component resource.

Parameters:
  • name (str) – The name of the resource to create.

  • resource_type (str) – The type of the resource to create.

  • inputs (Inputs) – The inputs to the resource.

  • options (Optional[ResourceOptions]) – The options for the resource.

invoke(token: str, args: Mapping[str, Any]) InvokeResult

Invoke calls the indicated function.

Parameters:
  • token (str) – The token of the function to call.

  • args (Inputs) – The inputs to the function.

pulumi.provider.main(provider: Provider, args: List[str]) None

For use as the main in programs that wrap a custom Provider implementation into a Pulumi-compatible gRPC server.

Parameters:

provider – an instance of a Provider subclass

Args:

command line arguiments such as os.argv[1:]

pulumi.runtime

The runtime implementation of the Pulumi Python SDK.

class pulumi.runtime.MockCallArgs(token: str, args: dict, provider: str)

MockCallArgs is used to construct a call Mock

Parameters:
  • token (str) – The token that indicates which function is being called. This token is of the form “package:module:function”.

  • args (dict) – The arguments provided to the function call.

  • provider (str) – The identifier of the provider instance being used to make the call

class pulumi.runtime.MockResourceArgs(typ: str, name: str, inputs: dict, provider: str | None = None, resource_id: str | None = None, custom: bool | None = None)

MockResourceArgs is used to construct a newResource Mock

Parameters:
  • typ (str) – The token that indicates which resource type is being constructed. This token is of the form “package:module:type”.

  • name (str) – The logical name of the resource instance.

  • inputs (dict) – The inputs for the resource.

  • provider (str) – The identifier of the provider instance being used to manage this resource.

  • resource_id (str) – The physical identifier of an existing resource to read or import.

  • custom (bool) – Specifies whether or not the resource is Custom (i.e. managed by a resource provider).

class pulumi.runtime.Mocks

Mocks is an abstract class that allows subclasses to replace operations normally implemented by the Pulumi engine with their own implementations. This can be used during testing to ensure that calls to provider functions and resource constructors return predictable values.

abstract call(args: MockCallArgs) Tuple[dict, List[Tuple[str, str]] | None]

call mocks provider-implemented function calls (e.g. aws.get_availability_zones).

:param MockCallArgs args.

abstract new_resource(args: MockResourceArgs) Tuple[str | None, dict]

new_resource mocks resource construction calls. This function should return the physical identifier and the output properties for the resource being constructed.

:param MockResourceArgs args.

class pulumi.runtime.ResourceModule
class pulumi.runtime.ResourcePackage
class pulumi.runtime.Settings(project: str | None, stack: str | None, monitor: str | Any | None = None, engine: str | Any | None = None, parallel: int | None = None, dry_run: bool | None = None, legacy_apply_enabled: bool | None = None, organization: str | None = None)

A bag of properties for configuring the Pulumi Python language runtime.

pulumi.runtime.configure(settings: Settings)

Configure sets the current ambient settings bag to the one given.

pulumi.runtime.get_config(k: str) Any

Returns a configuration variable’s value or None if it is unset.

pulumi.runtime.get_config_env() Dict[str, Any]

Returns the environment map that will be used for config checking when variables aren’t set.

pulumi.runtime.get_config_env_key(k: str) str

Returns a scrubbed environment variable key, PULUMI_CONFIG_<k>, that can be used for setting explicit variables. This is unlike PULUMI_CONFIG which is just a JSON-serialized bag.

pulumi.runtime.get_root_resource() 'Resource' | None

Returns the implicit root stack resource for all resources created in this program.

pulumi.runtime.invoke(tok: str, props: Inputs, opts: InvokeOptions | None = None, typ: type | None = None) InvokeResult

invoke dynamically invokes the function, tok, which is offered by a provider plugin. The inputs can be a bag of computed values (Ts or Awaitable[T]s), and the result is a Awaitable[Any] that resolves when the invoke finishes.

pulumi.runtime.is_dry_run() bool

Returns whether or not we are currently doing a preview.

When writing unit tests, you can set this flag via pulumi.runtime.set_mocks by supplying a value for the argument preview.

pulumi.runtime.register_stack_transformation(t: Callable[[ResourceTransformationArgs], ResourceTransformationResult | None])

Add a transformation to all future resources constructed in this Pulumi stack.

pulumi.runtime.reset_options(project: str | None = None, stack: str | None = None, parallel: int | None = None, engine_address: str | None = None, monitor_address: str | None = None, preview: bool | None = None, organization: str | None = None)

Resets globals to the values provided.

async pulumi.runtime.run_in_stack(func: Callable[[], Awaitable[None] | None])

Run the given function inside of a new stack resource. This ensures that any stack export calls will end up as output properties on the resulting stack component in the checkpoint file. This is meant for internal runtime use only and is used by the Python SDK entrypoint program.

pulumi.runtime.set_all_config(config: Dict[str, str], secret_keys: List[str] | None = None) None

Overwrites the config map and optional list of secret keys.

pulumi.runtime.set_config(k: str, v: Any)

Sets a configuration variable. Meant for internal use only.

pulumi.runtime.set_mocks(mocks: Mocks, project: str | None = None, stack: str | None = None, preview: bool | None = None, logger: Logger | None = None, monitor: MockMonitor | None = None, organization: str | None = None)

set_mocks configures the Pulumi runtime to use the given mocks for testing.

pulumi.runtime.test(fn)

Decorates a test function to make sure that a returned Future or Output is awaited as part of the test.

pulumi.runtime.to_json(obj: Any) str

Serialize obj to a JSON formatted str.