Pulumi ESC: Python SDK
Pulumi ESC provides a Python SDK for managing environments and reading their configuration and secrets from your own code.
Here are some of the scenarios the SDK can automate:
- List environments and read environment definitions
- Open environments to access config and resolve secrets
- Create, update, decrypt, and delete environment definitions
- Supports both structured types and yaml text
- List environment revisions and create new revision tags
- Check environment definitions for errors
Runtime support
The SDK supports any currently supported version of Python. We recommend using a recent release for the best experience.
Install the SDK package
Run pip install pulumi-esc-sdk to install the SDK package.
Initializing ESC SDK client
The easiest way to initialize an ESC SDK client is to run:
from pulumi_esc_sdk import esc_client
client = esc_client.default_client()
This method sources credentials from the PULUMI_ACCESS_TOKEN and PULUMI_BACKEND_URL environment variables. As of pulumi-esc-sdk v0.14.0, it no longer falls back to the Pulumi CLI login on disk, so you must set PULUMI_ACCESS_TOKEN or pass credentials explicitly.
If the default behavior does not work for you, you can always manually initialize the client configuration and pass it into the client constructor:
import pulumi_esc_sdk as esc
configuration = esc.Configuration(access_token=myAccessToken)
client = esc.EscClient(configuration)
The Python SDK honors standard proxy environment variables: https_proxy, http_proxy, and no_proxy. Both lowercase and uppercase variants are supported.
Examples
All of these examples expect a PULUMI_ACCESS_TOKEN and PULUMI_ORG environment variable to be set.
Manage environment example
This example creates a new environment, opens that environment to access a secret, and then lists the environments.
import pulumi_esc_sdk as esc
import os
orgName = os.getenv("PULUMI_ORG")
client = esc.esc_client.default_client()
projName = "examples"
envName = "sdk-python-example"
# Create environment
client.create_environment(orgName, projName, envName)
# create a new EnvironmentDefinition with "my_secret" as a secret in values additional_properties
envDef = esc.EnvironmentDefinition(
imports=[],
values=esc.EnvironmentDefinitionValues(
additional_properties={
"my_secret": {
"fn::secret": "shh! don't tell anyone"
}
}
)
)
# Update environment
client.update_environment(orgName, projName, envName, envDef)
# Open and read the environment
env, values, yaml = client.open_and_read_environment(orgName, projName, envName)
secret = values["my_secret"]
print(f'Secret: {secret}\n')
# List environments
environments = client.list_environments(orgName)
for env in environments.environments:
print(f'Environment: {env.project}/{env.name}')
Tag revision example
This example lists revisions for an environment, tags a revision, and lists revision tags.
import pulumi_esc_sdk as esc
import os
orgName = os.getenv("PULUMI_ORG")
client = esc.esc_client.default_client()
projName = "examples"
envName = "sdk-python-example"
# list environment revisions
revisions = client.list_environment_revisions(orgName, projName, envName)
# get second latest revision
second_latest_revision = revisions[1]
# create a new environment revision tag
client.create_environment_revision_tag(orgName, projName, envName, "stable", second_latest_revision.number)
print(f'Tagged revision {second_latest_revision.number} as stable')
# list environment revision tags
tags = client.list_environment_revision_tags(orgName, projName, envName)
for tag in tags.tags:
print(f'Tag {tag.name} at revision {tag.revision}')