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 thetranslate_input_property
andtranslate_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 ofprops
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.
- 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.
- 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.
- :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.
- 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.
- 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.
- 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.
- 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 ofopts2
merged over them.Both the
opts1
instance and theopts2
instance will be unchanged. Both ofopts1
andopts2
can beNone
, 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 fromopts1
.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 likeopts1.merge(opts2)
. The former is useful for cases whereopts1
may beNone
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 ofopts2
merged over them.Both the
opts1
instance and theopts2
instance will be unchanged. Both ofopts1
andopts2
can beNone
, 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 fromopts1
.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 likeopts1.merge(opts2)
. The former is useful for cases whereopts1
may beNone
so the caller does not need to check for this case.
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 keysa
,b
, andc
, is entirely separate from a bag whose name ispulumi:bar
with the same simple key names. Each key has a fully qualified names, such aspulumi:foo:a
, …, andpulumi: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
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_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.
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 duringpulumi 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
- 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]
- 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 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.
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
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
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.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
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
- 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.
- 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
- 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.
- 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
- up(parallel: int | None = None, message: str | None = None, target: List[str] | None = None, policy_packs: List[str] | None = None, policy_pack_configs: List[str] | None = None, expect_no_changes: bool | None = None, diff: bool | None = None, target_dependents: bool | None = None, replace: List[str] | None = None, color: str | None = None, on_output: Callable[[str], Any] | None = None, on_event: Callable[[EngineEvent], Any] | None = None, program: Callable[[], None] | None = None, plan: str | None = None, show_secrets: bool = True, log_flow: bool | None = None, log_verbosity: int | None = None, log_to_std_err: bool | None = None, tracing: str | None = None, debug: bool | 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:
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
- preview(parallel: int | None = None, message: str | None = None, target: List[str] | None = None, policy_packs: List[str] | None = None, policy_pack_configs: List[str] | None = None, expect_no_changes: bool | None = None, diff: bool | None = None, target_dependents: bool | None = None, replace: List[str] | None = None, color: str | None = None, on_output: Callable[[str], Any] | None = None, on_event: Callable[[EngineEvent], Any] | None = None, program: Callable[[], None] | None = None, plan: str | None = None, log_flow: bool | None = None, log_verbosity: int | None = None, log_to_std_err: bool | None = None, tracing: str | None = None, debug: bool | None = None) PreviewResult
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
- refresh(parallel: int | None = None, message: str | None = None, target: List[str] | None = None, expect_no_changes: bool | None = None, color: str | None = None, on_output: Callable[[str], Any] | None = None, on_event: Callable[[EngineEvent], Any] | None = None, show_secrets: bool = True, log_flow: bool | None = None, log_verbosity: int | None = None, log_to_std_err: bool | None = None, tracing: str | None = None, debug: bool | 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:
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(parallel: int | None = None, message: str | None = None, target: List[str] | None = None, target_dependents: bool | None = None, color: str | None = None, on_output: Callable[[str], Any] | None = None, on_event: Callable[[EngineEvent], Any] | None = None, show_secrets: bool = True, log_flow: bool | None = None, log_verbosity: int | None = None, log_to_std_err: bool | None = None, tracing: str | None = None, debug: bool | None = None) DestroyResult
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.
- 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.
- 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.
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.