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: Optional[Inputs] = None, opts: Optional[pulumi.resource.ResourceOptions] = None)

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[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.
urn = None

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.

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.

Parameters:prop (str) – A property name.
Returns:A potentially transformed property name.
Return type:str
get_provider(module_member: str) → Optional[pulumi.resource.ProviderResource]

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: Optional[dict] = None, opts: Optional[pulumi.resource.ResourceOptions] = None)

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.
id = None

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: Optional[dict] = None, opts: Optional[pulumi.resource.ResourceOptions] = None)

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.
register_outputs(outputs)

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: Optional[dict] = None, opts: Optional[pulumi.resource.ResourceOptions] = None)

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.
package = None

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

class pulumi.ResourceOptions(parent: Optional[Resource] = None, depends_on: Optional[List[Resource]] = None, protect: Optional[bool] = None, provider: Optional[ProviderResource] = None, providers: Optional[Mapping[str, ProviderResource]] = None, delete_before_replace: Optional[bool] = None, ignore_changes: Optional[List[str]] = None, version: Optional[str] = None, additional_secret_outputs: Optional[List[str]] = None, id: Optional[str] = None, import_: Optional[str] = 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[List[Resource]]) – If provided, the currently-constructing resource depends on the provided list of 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 parent’s provider bag.
  • providers (Optional[Mapping[str,ProviderResource]]) – An optional set of providers to use for child resources. Keyed by package name (e.g. “aws”)
  • delete_before_replace (Optional[bool]) – If provided and True, this resource must be deleted before it is replaced.
  • ignore_changes (Optional[List[string]]) – If provided, a list of property names to ignore for purposes of updates or replacements.
  • additional_secret*outputs (Optional[List[string]]) –

    If provided, a list of output property names that should also be treated as secret.

  • id (Optional[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.
parent = None

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

depends_on = None

If provided, the currently-constructing resource depends on the provided list of resources.

protect = None

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

provider = 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 = None

An optional set of providers to use for child resources. Keyed by package name (e.g. “aws”)

delete_before_replace = None

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

ignore_changes = None

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

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

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

id = None

An optional existing ID to load, rather than create.

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

class pulumi.InvokeOptions(parent: Optional[Resource] = None, provider: Optional[ProviderResource] = None, version: Optional[str] = '')

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.
parent = None

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

provider = 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 = None

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

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: Optional[str] = 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 = None

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

get(key: str) → Optional[str]

Returns an optional configuration value by its key, or None if it doesn’t exist.

Parameters:key (str) – The requested configuration key.
Returns:The configuration key’s value, or None if one does not exist.
Return type:Optional[str]
get_secret(key: str) → Optional[pulumi.output.Output[str][str]]

Returns an optional configuration value by its key, marked as a secret, or None if it doesn’t exist.

Parameters:key (str) – The requested configuration key.
Returns:The configuration key’s value, or None if one does not exist.
Return type:Optional[str]
get_bool(key: str) → Optional[bool]

Returns an optional configuration value, as a bool, by its key, 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.
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) → Optional[pulumi.output.Output[bool][bool]]

Returns an optional configuration value, as a bool, by its key, marked as a secret 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.
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) → Optional[int]

Returns an optional configuration value, as an int, by its key, 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.
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) → Optional[pulumi.output.Output[int][int]]

Returns an optional configuration value, as an int, by its key, marked as a secret, 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.
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) → Optional[float]

Returns an optional configuration value, as a float, by its key, 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.
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) → Optional[pulumi.output.Output[float][float]]

Returns an optional configuration value, as a float, by its key, marked as a secret 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.
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.
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) → pulumi.output.Output[str][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) → pulumi.output.Output[bool][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) → pulumi.output.Output[int][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) → 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:
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 = None

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

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

value = None

The ill-typed value.

expect_type = None

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.

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: Set[Resource], future: Awaitable[T], is_known: Awaitable[bool], is_secret: Optional[Awaitable[bool]] = 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) → pulumi.output.Output[typing.Any][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) → pulumi.output.Output[typing.Any][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], Union[U, Awaitable[U], Output[T]]]) → pulumi.output.Output[~U][U]

Transforms the data of the output with the provided func. The result remains a Output so that dependent resources can be properly tracked.

‘func’ is not allowed to make resources.

‘func’ can return other Outputs. This can be handy if you have a Output and you want to get a transitive dependency of it.

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],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: Union[T, Awaitable[T], Output[T]]) → pulumi.output.Output[~T][T]

Takes an Input value and produces an Output value from it, deeply unwrapping nested Input values as necessary given the type.

Parameters:val (Input[T]) – 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]
static secret(val: Union[T, Awaitable[T], Output[T]]) → pulumi.output.Output[~T][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) → pulumi.output.Output[typing.List[~T]][List[T]]

Produces an Output of Lists from a List of Inputs.

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.

Parameters:args (List[Input[T]]) – A list of Inputs to convert.
Returns:An output of lists, converted from an Input to prompt values.
Return type:Output[List[T]]

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: Optional[Resource] = None, stream_id: Optional[int] = 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: Optional[Resource] = None, stream_id: Optional[int] = 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: Optional[Resource] = None, stream_id: Optional[int] = 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: Optional[Resource] = None, stream_id: Optional[int] = None)

Logs a message to the Pulumi CLI’s error 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.

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.