Pulumi Python SDK

The Pulumi Python SDK (pulumi) is the core package used when writing Pulumi programs in Python. It contains everything that you’ll need in order to interact with Pulumi resource providers and express infrastructure using Python code. Pulumi resource providers all depend on this library and express their resources in terms of the types defined in this module.

Note: The Pulumi Python SDK requires Python version 3.6 or greater. Please see the Python getting started documentation for details on how to get started with Python.

The Pulumi Python Resource Model

Like most languages usable with Pulumi, Pulumi represents cloud resources as classes and Python programs can instantiate those classes. All classes that can be instantiated to produce actual resources derive from the pulumi.Resource class.

A class that derives from pulumi.Resource will, when instantiated, communicate with the Pulumi Engine and record that a piece of infrastructure that the instantiated class represents should be provisioned. All resources whose provisioning is implemented in a resource provider derive from the pulumi.CustomResource class.

It is also possible to write your own resources, written in Python, that are themselves composed of custom resources. Resources written in Python are called “component resources” and they are written by deriving from the pulumi.ComponentResource class.

Finally, Pulumi allows for resource providers to directly project themselves into Python, so that provider instances can be instantiated and used to create other resources. These “provider resources” derive from the pulumi.ProviderResource class.

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.

property urn: Output[str]: The stable, logical URN used to distinctly address a resource, both before and after deployments.

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

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

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]

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

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.

:param Optional[str] import*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.

Parameters:

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.

parent: Resource | None: If provided, the currently-constructing resource should be the child of the provided parent resource.

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.

delete_before_replace: bool | None: If provided and True, this resource must be deleted before it is replaced.

ignore_changes: List[str] | None: If provided, ignore changes to any of the specified properties.

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.

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.

aliases: Sequence[Input[str | Alias]] | None: An optional list of aliases to treat this resource as matching.

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.

custom_timeouts: CustomTimeouts | None: An optional customTimeouts config block.

id: Input[str] | None: An optional existing ID to load, rather than create.

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.

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.

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.

depends_on: Input[Sequence[Input[Resource]] | Resource] | None: If provided, declares that the currently-constructing resource depends on the given resources.

retain_on_delete: bool | None: If set to True, the providers Delete method will not be called for this resource.

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.

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:

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.
Simple scalar values from opts2 (i.e. strings, numbers, bools) will replace the values from opts1.
For the purposes of merging depends_on is always treated as collections, even if only a single value was provided.
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.

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.

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

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.

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.

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:

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.
Simple scalar values from opts2 (i.e. strings, numbers, bools) will replace the values from opts1.
For the purposes of merging depends_on is always treated as collections, even if only a single value was provided.
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.

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.

Configuration and Metadata

Pulumi programs can receive configuration that is specified by the command-line using pulumi config. This configuration information can be retrieved at runtime using the pulumi.Config class:

import pulumi
# After running `pulumi config set myconfig 42`
conf = pulumi.Config()
print(conf.get_int("myconfig")) # prints 42

Pulumi programs also have the ability to query the current project and stack, as well as whether or not the current run of the program is a preview or not.

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.

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

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_secret(key: str) → 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_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_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_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_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_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_secret_float(key: str, default: float | None = None) → Output[float] | None

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

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

ConfigMissingError – The configuration value did not exist.
ConfigTypeError – The configuration value existed but couldn’t be coerced to bool.

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:

ConfigMissingError – The configuration value did not exist.
ConfigTypeError – The configuration value existed but couldn’t be coerced to bool.

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:

ConfigMissingError – The configuration value did not exist.
ConfigTypeError – The configuration value existed but couldn’t be coerced to int.

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:

ConfigMissingError – The configuration value did not exist.
ConfigTypeError – The configuration value existed but couldn’t be coerced to int.

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:

ConfigMissingError – The configuration value did not exist.
ConfigTypeError – The configuration value existed but couldn’t be coerced to float.

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:

ConfigMissingError – The configuration value did not exist.
ConfigTypeError – The configuration value existed but couldn’t be coerced to float.

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

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

exception pulumi.ConfigMissingError(key: str)

Indicates a configuration value is missing.

key: str: The name of the missing configuration key.

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

Indicates a configuration value is of the wrong type.

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

value: str: The ill-typed value.

expect_type: str: The expected type of this value.

pulumi.get_project() → str: Returns the current project name.

pulumi.get_stack() → str: Returns the current stack name.

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.

Outputs and Inputs

Like other languages in the Pulumi ecosystem, all Resources in Python have two kinds of properties: inputs and outputs. Inputs are specified as arguments to resource constructors, to be used as inputs to the resource itself. Outputs are returned as properties on the instantiated resource object. Outputs are similar to futures in that they are resolved asynchronously, but they also contain information about the dependency graph of resources within your program.

Pulumi does not offer direct access to the values contained within Outputs. Instead, you must use the apply function on the Output class in order to observe the value of an output. See the documentation for more details on this part of the Pulumi programming model.

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.

__getitem__(key: Any) → Output[Any]

Syntax sugar for looking up attributes dynamically off of outputs.

Parameters:: key (Any) – Key for the attribute dictionary.
Returns:: An Output of this Output’s underlying value, keyed with the given key as if it were a dictionary.
Return type:: Output[Any]

__getattr__(item: str) → Output[Any]

Syntax sugar for retrieving attributes off of outputs.

Parameters:: item (str) – An attribute name.
Returns:: An Output of this Output’s underlying value’s property with the given name.
Return type:: Output[Any]

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

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

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]

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

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.

Logging

The Pulumi SDK contains a few helper functions for logging to the console. Messages logged using these functions are sent directly to the Pulumi Engine and rendered with the rest of the CLI output.

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

Stack Exports

Python programs can export values. Exported values are attached to the program’s Stack resource and accessed using the pulumi stack output CLI command:

import pulumi
pulumi.export("the-answer", 42)
# pulumi stack export:
# Current stack outputs (1):
# OUTPUT      VALUE
# the-answer  42

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.

Automation API

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:

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

stack = create_stack("myOrg/myProj/myStack", work_dir=os.path.join("..", "path", "to", "project"))

Programs defined as a function alongside your Automation API code (inline source):

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 */ }

pulumi.automation.create_stack(stack_name: str, project_name: str | None = None, program: Callable[[], 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.select_stack(stack_name: str, project_name: str | None = None, program: Callable[[], 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

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.automation.create_or_select_stack(stack_name: str, project_name: str | None = None, program: Callable[[], 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

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

class pulumi.automation.LocalWorkspace(work_dir: str | None = None, pulumi_home: str | None = None, program: Callable[[], 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)

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.

property pulumi_version: str

project_settings() → ProjectSettings

Returns the settings object for the current project if any.

Returns:: ProjectSettings

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.

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

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.

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.

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.

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

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

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

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.

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

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.

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.

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

who_am_i() → WhoAmIResult

Returns the currently authenticated user.

Returns:: WhoAmIResult

stack() → StackSummary | None

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

Returns:: Optional[StackSummary]

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.

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.

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

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..yaml files).

Returns:: List[StackSummary]

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.

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.

list_plugins() → List[PluginInfo]

Returns a list of all plugins installed in the Workspace.

Returns:: List[PluginInfo]

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

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.

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

class pulumi.automation.Stack(name: str, workspace: Workspace, mode: StackInitMode)

Stack is an isolated, independently configurable instance of a Pulumi program. Stack exposes methods for the full pulumi lifecycle (up/preview/refresh/destroy), as well as managing configuration. Multiple Stacks are commonly used to denote different phases of development (such as development, staging and production) or feature branches (such as feature-x-dev, jane-feature-x-dev).

classmethod create(stack_name: str, workspace: Workspace) → Stack

Creates a new stack using the given workspace, and stack name. It fails if a stack with that name already exists.

Parameters:

stack_name – The name identifying the Stack
workspace – The Workspace the Stack was created from.

Returns:

Stack

classmethod select(stack_name: str, workspace: Workspace) → Stack

Selects stack using the given workspace, and stack name. It returns an error if the given Stack does not exist.

Parameters:

stack_name – The name identifying the Stack
workspace – The Workspace the Stack was created from.

Returns:

Stack

classmethod create_or_select(stack_name: str, workspace: Workspace) → Stack

Tries to create a new stack using the given workspace and stack name if the stack does not already exist, or falls back to selecting the existing stack. If the stack does not exist, it will be created and selected.

Parameters:

stack_name – The name identifying the Stack
workspace – The Workspace the Stack was created from.

Returns:

Stack

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:

parallel – Parallel is the number of resource operations to run in parallel at once. (1 for no parallelism). Defaults to unbounded (2147483647).
message – Message (optional) to associate with the update operation.
target – Specify an exclusive list of resource URNs to destroy.
expect_no_changes – Return an error if any changes occur during this update.
policy_packs – Run one or more policy packs as part of this update.
policy_pack_configs – Path to JSON file containing the config for the policy pack of the corresponding “–policy-pack” flag.
diff – Display operation as a rich diff showing the overall change.
target_dependents – Allows updating of dependent targets discovered but not specified in the Target list.
replace – Specify resources to replace.
on_output – A function to process the stdout stream.
on_event – A function to process structured events from the Pulumi event stream.
program – The inline program.
color – Colorize output. Choices are: always, never, raw, auto (default “auto”)
plan – Plan specifies the path to an update plan to use for the update.
show_secrets – Include config secrets in the UpResult summary.
log_flow – Flow log settings to child processes (like plugins)
log_verbosity – Enable verbose logging (e.g., v=3); anything >3 is very verbose
log_to_std_err – Log to stderr instead of to files
tracing – Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file
debug – Print detailed debugging output during resource operations

Returns:

UpResult

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

Parameters:

parallel – Parallel is the number of resource operations to run in parallel at once. (1 for no parallelism). Defaults to unbounded (2147483647).
message – Message to associate with the preview operation.
target – Specify an exclusive list of resource URNs to update.
policy_packs – Run one or more policy packs as part of this update.
policy_pack_configs – Path to JSON file containing the config for the policy pack of the corresponding “–policy-pack” flag.
expect_no_changes – Return an error if any changes occur during this update.
diff – Display operation as a rich diff showing the overall change.
target_dependents – Allows updating of dependent targets discovered but not specified in the Target list.
replace – Specify resources to replace.
on_output – A function to process the stdout stream.
on_event – A function to process structured events from the Pulumi event stream.
program – The inline program.
color – Colorize output. Choices are: always, never, raw, auto (default “auto”)
plan – Plan specifies the path where the update plan should be saved.
log_flow – Flow log settings to child processes (like plugins)
log_verbosity – Enable verbose logging (e.g., v=3); anything >3 is very verbose
log_to_std_err – Log to stderr instead of to files
tracing – Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file
debug – Print detailed debugging output during resource operations

Returns:

PreviewResult

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:

parallel – Parallel is the number of resource operations to run in parallel at once. (1 for no parallelism). Defaults to unbounded (2147483647).
message – Message (optional) to associate with the refresh operation.
target – Specify an exclusive list of resource URNs to refresh.
expect_no_changes – Return an error if any changes occur during this update.
on_output – A function to process the stdout stream.
on_event – A function to process structured events from the Pulumi event stream.
color – Colorize output. Choices are: always, never, raw, auto (default “auto”)
show_secrets – Include config secrets in the RefreshResult summary.
log_flow – Flow log settings to child processes (like plugins)
log_verbosity – Enable verbose logging (e.g., v=3); anything >3 is very verbose
log_to_std_err – Log to stderr instead of to files
tracing – Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file
debug – Print detailed debugging output during resource operations

Returns:

RefreshResult

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

Parameters:

parallel – Parallel is the number of resource operations to run in parallel at once. (1 for no parallelism). Defaults to unbounded (2147483647).
message – Message (optional) to associate with the destroy operation.
target – Specify an exclusive list of resource URNs to destroy.
target_dependents – Allows updating of dependent targets discovered but not specified in the Target list.
on_output – A function to process the stdout stream.
on_event – A function to process structured events from the Pulumi event stream.
color – Colorize output. Choices are: always, never, raw, auto (default “auto”)
show_secrets – Include config secrets in the DestroyResult summary.
log_flow – Flow log settings to child processes (like plugins)
log_verbosity – Enable verbose logging (e.g., v=3); anything >3 is very verbose
log_to_std_err – Log to stderr instead of to files
tracing – Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file
debug – Print detailed debugging output during resource operations

Returns:

DestroyResult

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

Returns the config value associated with the specified key.

Parameters:

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_all_config() → MutableMapping[str, ConfigValue]

Returns the full config map associated with the stack in the Workspace.

Returns:: ConfigMap

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

Sets a config key-value pair on the Stack in the associated Workspace.

Parameters:

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_all_config(config: MutableMapping[str, ConfigValue], *, path: bool = False) → None

Sets all specified config values on the stack in the associated Workspace.

Parameters:

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.

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

Removes the specified config key from the Stack in the associated Workspace.

Parameters:

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

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

Removes the specified config keys from the Stack in the associated Workspace.

Parameters:

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

refresh_config() → None: Gets and sets the config map used with the last update.

get_tag(key: str) → str

Returns the tag value associated with specified key.

Parameters:: key – The key to use for the tag lookup.
Returns:: str

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

Sets a tag key-value pair on the Stack in the associated Workspace.

Parameters:

key – The tag key to set.
value – The tag value to set.

remove_tag(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.

list_tags() → 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

outputs() → MutableMapping[str, OutputValue]

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

Returns:: OutputMap

history(page_size: int | None = None, page: int | None = None, show_secrets: bool = True) → 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]

info(show_secrets=True) → UpdateSummary | None

Returns the current results from Stack lifecycle operations.

Returns:: Optional[UpdateSummary]

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 local backends.

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

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.

class pulumi.automation.LocalWorkspaceOptions(work_dir: str | None = None, pulumi_home: str | None = None, program: Callable[[], 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)

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

On this page

On this page

Pulumi Python SDK

The Pulumi Python Resource Model

Configuration and Metadata

Outputs and Inputs

Logging

Stack Exports

Automation API

On this page

On this page