1. Docs
  2. pulumi

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

    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.

    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:

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

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

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

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

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

    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:

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

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

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

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

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

    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

    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:
    require_secret_bool(key: str) Output[bool]

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

    Parameters:

    key (str) – The requested configuration key.

    Returns:

    The configuration key’s value.

    Return type:

    bool

    Raises:
    require_int(key: str) int

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

    Parameters:

    key (str) – The requested configuration key.

    Returns:

    The configuration key’s value.

    Return type:

    int

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

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

    Parameters:

    key (str) – The requested configuration key.

    Returns:

    The configuration key’s value.

    Return type:

    int

    Raises:
    require_float(key: str) float

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

    Parameters:

    key (str) – The requested configuration key.

    Returns:

    The configuration key’s value.

    Return type:

    float

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

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

    Parameters:

    key (str) – The requested configuration key.

    Returns:

    The configuration key’s value.

    Return type:

    float

    Raises:
    require_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]

    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

    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:

    1. 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"))
      
    2. 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.

    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

    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.

    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.

      Register for Pulumi UP, June 15, 2023