esc

package module
v0.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 26, 2025 License: Apache-2.0 Imports: 11 Imported by: 12

README

Secrets Management for Multi-Cloud Environments

Pulumi ESC is a centralized secrets management & orchestration service that makes it easy to tame secrets sprawl and configuration complexity securely across all your cloud infrastructure and applications. You can pull and sync secrets with any secrets store – including HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, 1Password, and more – and consume secrets in any application, tool, or CI/CD platform.

Pulumi ESC simplifies the adoption of dynamic, on-demand secrets as a best practice. It leverages Pulumi Cloud identity, RBAC, Teams, SAML/SCIM, OIDC, and scoped access tokens used for Pulumi IaC to ensure secrets management complies with enterprise security policies. Every time secrets or configuration values are accessed or changed with Pulumi ESC, the action is fully logged for auditing. So you can trust (and prove) your secrets are secure. Pulumi ESC makes it easy to eliminate the need for developers to copy and paste secrets and store them in plaintext on their computers. Developers can easily access secrets via CLI, API, Kubernetes operator, the Pulumi Cloud UI, and in-code with Typescript/Javascript, Python, and Go SDKs.

Be sure to check out the Pulumi ESC explainer video.

Table of contents

Pulumi ESC Demo

Pulumi ESC not only works great for your applications and IaC, including Pulumi IaC, but it also makes your day-to-day developer workflow much more secure and streamlined. For example, the Pulumi ESC CLI (esc) allows you to give your developers immediate, just-in-time authenticated, and short-lived access to cloud credentials across any cloud provider with just a single command: esc run aws-staging -- aws s3 ls.

In this example, an ESC environment named aws-staging has all the necessary staging environment configuration and OIDC setup to connect to AWS. Running this command opens up a temporary environment and executes the aws s3 ls command in that environment. The temporary AWS credentials are not stored anywhere, making them secure and also allowing you to switch between different environments dynamically.

Pulumi's open source secrets management solution overview

Pulumi ESC is also offered as a managed service as part of Pulumi Cloud, and this repo contains the implementation of the following key components of the ESC open source secrets and configuration management solution:

  1. The esc CLI: A CLI tool for managing and consuming environments, secrets and configuration using Pulumi ESC.
  2. The Pulumi ESC evaluator: The core specification and implementation of the document format for defining environments, and the syntax and semantics for evaluating environments to produce a set of configuration and secrets.

Getting Started with Pulumi ESC

For a hands-on, self-paced tutorial see our Pulumi ESC Getting Started to quickly get up and running.

Download and Install Pulumi ESC

  1. Install:

    To install the latest Pulumi ESC release, run the following (see full installation instructions for additional installation options):

    $ curl -fsSL https://get.pulumi.com/esc/install.sh | sh
Building the ESC CLI Locally

You can build the CLI locally for testing by cloning this repo and running:

$ make install

This will produce an esc binary in your GOBIN directory.

How Pulumi ESC Works

  1. Pulumi ESC enables you to define environments, which are collections of secrets and configuration. Each environment can be composed from multiple environments.
  2. Pulumi ESC supports a variety of configuration and secrets sources, and it has an extensible plugin model that allows third-party sources.
  3. Pulumi ESC has a rich API that allows for easy integration. Every value in an environment can be accessed from any execution environment.
  4. Every environment can be locked down with RBAC, versioned, and audited.
Why Pulumi ESC?

Pulumi ESC was designed to address a set of challenges that many infrastructure and application development teams face in managing configuration and secrets across their various environments:

  • Stop secret sprawl: Pull and sync secrets and configuration with any secrets store – HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, 1Password, and more – and consume in any application, tool, or CI/CD platform.
  • Trust (and prove) your secrets are secure: Adopt dynamic, short-lived secrets on demand as a best practice. Lock down every environment with RBAC, versioning, and a full audit log of all changes.
  • Ditch .env files: No more copying-and-pasting secrets or storing them in plaintext on dev computers. Developers can easily access secrets via CLI, API, Kubernetes operator, the Pulumi Cloud UI, and SDKs.
  • Use with or without Pulumi IaC: Use Pulumi ESC independently, or use with Pulumi IaC to support storing secrets in config in a more secure way than using plaintext.

Pulumi ESC was born to address these problems and needs head on with the following features.

Pulumi ESC Features
  • Centralized secrets management: Access, share, and manage confidential information such as secrets, passwords, and API keys as well as configuration information such as network settings and deployment options.
  • Secrets orchestration: Pull and sync configuration and secrets from any secrets store and consume in any application, tool, or CI/CD platform.
  • Composable environments: Environments support importing one into another, allowing for easy composability and inheritance of shared secrets and configuration.
  • Versionable: Every change to an environment as well as any of its secrets and configuration is versioned, so rolling back or accessing an old version is easy.
  • Role-based access control (RBAC): Role-based access controls (RBAC) makes it easy to secure your secrets and configurations by assigning permissions to users based on their role within your organization.
  • Dynamic Secrets: Generate just-in-time, short-lived credentials that revoke access when the lease expires.
  • Audit Logging: All actions taken on environments, secrets, or configuration values are fully logged for auditing.
  • Developer-friendly: Developers can easily access secrets via CLI, API, Kubernetes operator, the Pulumi Cloud UI, and in-code with Typescript/Javascript, Python, and Go SDKs.

Pulumi ESC Roadmap

Review the planned work for the upcoming quarter and a selected backlog of issues that are on our mind but not yet scheduled on the Pulumi Roadmap.

Community

  • Join us in the Pulumi Community Slack to connect with our community and engineering team and ask questions. All conversations and questions are welcome.
  • Send us a tweet via @PulumiCorp
  • Watch videos and workshops on Pulumi TV

Resources

Documentation

Index

Constants

View Source 
const AnonymousEnvironmentName = "<yaml>"
View Source 
const AnonymousProjectName = "<project>"

Variables

View Source 
var ErrReservedContextkey = errors.New("reserved context key")

Functions

This section is empty.

Types

type AccessExpr 

type AccessExpr struct {
	// The receiver to access.
	Receiver Range `json:"receiver"`

	// The accessors to evaluate.
	Accessors []Accessor `json:"accessors"`
}

An AccessExpr represents a property access with a receiving value.

type Accessor 

type Accessor struct {
	// The integer index of the element to access. Mutually exclusive with Key.
	Index *int `json:"index,omitempty"`

	// The key of the property to access. Mutually exclusive with Index.
	Key *string `json:"key,omitempty"`

	// The range of the accessor.
	Range Range `json:"range,omitempty"`
}

An Accessor is an element index or property name.

type BuiltinExpr 

type BuiltinExpr struct {
	Name      string         `json:"name"`
	NameRange Range          `json:"nameRange"`
	ArgSchema *schema.Schema `json:"argSchema"`
	Arg       Expr           `json:"arg"`
}

A BuiltinExpr is a call to a builtin function.

type EnvExecContext added in v0.8.3 

type EnvExecContext interface {
	// Returns the current execution context values
	Values() map[string]Value

	// Returns the root evaluated environment.
	// For anonymous environments, it resolves to the "rootest" non anonymous environment.
	GetRootEnvironmentName() string

	// Returns the current environment being evaluated.
	GetCurrentEnvironmentName() string
}

type Environment 

type Environment struct {
	// Exprs contains the AST for each expression in the environment definition.
	Exprs map[string]Expr `json:"exprs,omitempty"`

	// Properties contains the detailed values produced by the environment.
	Properties map[string]Value `json:"properties,omitempty"`

	// Schema contains the schema for Properties.
	Schema *schema.Schema `json:"schema,omitempty"`

	// ExecutionContext contains the values + schema for the execution context passed to the root environment.
	ExecutionContext *EvaluatedExecutionContext `json:"executionContext,omitempty"`
}

An Environment contains the result of evaluating an environment definition.

func (*Environment) GetEnvironmentVariables added in v0.5.7 

func (e *Environment) GetEnvironmentVariables() map[string]Value

GetEnvironmentVariables returns any environment variables defined by the environment.

Environment variables are any scalar values in the top-level `environmentVariables` property. Boolean and number values are converted to their string representation. The results remain Values in order to retain secret- and unknown-ness.

func (*Environment) GetTemporaryFiles added in v0.5.7 

func (e *Environment) GetTemporaryFiles() map[string]Value

GetTemporaryFiles returns any temporary files defined by the environment.

Temporary files are any string values in the top-level `files` property. The key for each file is the name of the environment variable that should hold the actual path to the temporary file once it is written.

type EvaluatedExecutionContext added in v0.8.1 

type EvaluatedExecutionContext struct {
	// Properties contains the detailed values produced by the execution context.
	Properties map[string]Value `json:"properties,omitempty"`

	// Schema contains the schema for Properties.
	Schema *schema.Schema `json:"schema,omitempty"`
}

type ExecContext added in v0.8.1 

type ExecContext struct {
	// contains filtered or unexported fields
}

func NewExecContext added in v0.8.1 

func NewExecContext(values map[string]Value) (*ExecContext, error)

func (*ExecContext) CopyForEnv added in v0.8.1 

func (ec *ExecContext) CopyForEnv(envName string) *ExecContext

func (*ExecContext) GetCurrentEnvironmentName added in v0.8.3 

func (ec *ExecContext) GetCurrentEnvironmentName() string

func (*ExecContext) GetRootEnvironmentName added in v0.8.3 

func (ec *ExecContext) GetRootEnvironmentName() string

func (*ExecContext) Values added in v0.8.1 

func (ec *ExecContext) Values() map[string]Value

type Expr 

type Expr struct {
	// The range of the expression.
	Range Range `json:"range"`

	// The schema of the expression's result.
	Schema *schema.Schema `json:"schema,omitempty"`

	// The expression that defined this expression's base value, if any.
	Base *Expr `json:"base,omitempty"`

	// Ranges for the object's keys, if this is an object expression.
	KeyRanges map[string]Range `json:"keyRanges,omitempty"`

	// The literal value, if this is a literal expression (nil, bool, json.Number, or string)
	Literal any `json:"literal,omitempty"`

	// The interpolations, if this is a string interpolation expression.
	Interpolate []Interpolation `json:"interpolate,omitempty"`

	// The property accessors, if this is a symbol expression.
	Symbol []PropertyAccessor `json:"symbol,omitempty"`

	// The access, if this is an access expression.
	Access *AccessExpr `json:"access,omitempty"`

	// The list elements, if this is a list expression.
	List []Expr `json:"list,omitempty"`

	// The object properties, if this is an object expression.
	Object map[string]Expr `json:"object,omitempty"`

	// The builtin, if this is a call to a builtin function.
	Builtin *BuiltinExpr `json:"builtin,omitempty"`
}

An Expr holds information about an expression in an environment definition.

type Interpolation 

type Interpolation struct {
	// The text of the expression. Precedes the stringified Value in the output.
	Text string `json:"text,omitempty"`

	// The value to interpolate.
	Value []PropertyAccessor `json:"value,omitempty"`
}

An Interpolation holds information about a part of an interpolated string expression.

type Pos 

type Pos struct {
	// Line is the source code line where this position points. Lines are counted starting at 1 and incremented for each
	// newline character encountered.
	Line int `json:"line"`

	// Column is the source code column where this position points. Columns are counted in visual cells starting at 1,
	// and are incremented roughly per grapheme cluster encountered.
	Column int `json:"column"`

	// Byte is the byte offset into the file where the indicated position begins.
	Byte int `json:"byte"`
}

A Pos defines a position within an environment definition.

func (Pos) String added in v0.7.0 

func (p Pos) String() string

type PropertyAccessor 

type PropertyAccessor struct {
	Accessor

	// The range of the expression that defines the resolved value.
	Value Range `json:"value"`
}

A PropertyAccessor is a single accessor that is associated with a resolved value.

type Provider 

type Provider interface {
	// Schema returns the provider's input and output schemata.
	Schema() (inputs, outputs *schema.Schema)

	// Open retrieves the provider's secrets.
	Open(ctx context.Context, inputs map[string]Value, executionContext EnvExecContext) (Value, error)
}

A Provider provides environments access to dynamic secrets. These secrets may be generated at runtime, fetched from other services, etc.

type Range 

type Range struct {
	// The name of the environment.
	Environment string `json:"environment,omitempty"`

	// The beginning of the range.
	Begin Pos `json:"begin"`

	// The end of the range.
	End Pos `json:"end"`
}

A Range defines a range within an environment definition.

func (Range) Contains 

func (r Range) Contains(pos Pos) bool

Contains returns true if the range contains the given position.

func (Range) String added in v0.7.0 

func (r Range) String() string

type Rotator added in v0.12.0 

type Rotator interface {
	// Schema returns the rotator's input, state, and output schemata.
	Schema() (inputs, state, outputs *schema.Schema)

	// Open retrieves the rotator's secrets, using persisted state.
	Open(ctx context.Context, inputs, state map[string]Value, executionContext EnvExecContext) (Value, error)

	// Rotate rotates the provider's secret, and returns the rotator's new state to be persisted.
	Rotate(ctx context.Context, inputs, state map[string]Value, executionContext EnvExecContext) (Value, error)
}

A Rotator enables environments to rotate a secret. It is the responsibility of the caller to appropriately persist rotation state (e.g. by writing it back to the environment definition).

type Trace 

type Trace struct {
	// Def is the range of the expression that computed a value.
	Def Range `json:"def"`

	// Base is the base value with which a value was merged.
	Base *Value `json:"base,omitempty"`
}

Trace holds information about the expression and base of a value.

type Value 

type Value struct {
	// Value holds the concrete representation of the value. May be nil, bool, json.Number, string, []Value, or
	// map[string]Value.
	Value any `json:"value,omitempty"`

	// Secret is true if this value is secret.
	Secret bool `json:"secret,omitempty"`

	// Unknown is true if this value is unknown.
	Unknown bool `json:"unknown,omitempty"`

	// Trace holds information about the expression that computed this value and the value (if any) with which it was
	// merged.
	Trace Trace `json:"trace"`
}

A Value is the result of evaluating an expression within an environment definition.

func FromJSON added in v0.5.5 

func FromJSON(v any) (Value, error)

FromJSON converts a plain-old-JSON value (i.e. a value of type nil, bool, json.Number, string, []any, or map[string]any) into a Value.

func NewSecret 

func NewSecret[T ValueType](v T) Value

NewSecret creates a new secret value with the given representation.

func NewValue 

func NewValue[T ValueType](v T) Value

NewValue creates a new value with the given representation.

func (Value) MakeSecret added in v0.13.1 

func (v Value) MakeSecret() Value

func (Value) String 

func (v Value) String() string

String is shorthand for ToString(true).

func (Value) ToJSON 

func (v Value) ToJSON(redact bool) any

ToJSON converts a Value into a plain-old-JSON value (i.e. a value of type nil, bool, json.Number, string, []any, or map[string]any). If redact is true, secrets are replaced with [secret].

func (Value) ToString 

func (v Value) ToString(redact bool) string

ToString returns the string representation of this value. If redact is true, secrets are replaced with [secret].

func (*Value) UnmarshalJSON 

func (v *Value) UnmarshalJSON(data []byte) error

type ValueType 

type ValueType interface {
	bool | json.Number | string | []Value | map[string]Value
}

ValueType defines the types of concrete values stored inside a Value.

Source Files

View all Source files

Directories

Path Synopsis
cmd
esc command
esc/cli
esc/cli/client
Package client implements a client for the Pulumi Service HTTP/REST API.
 Package client implements a client for the Pulumi Service HTTP/REST API.
esc/cli/pager
esc/cli/style
esc/cli/version
esc/cli/workspace
internal
spell
util
encoding

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.