Skip to main content
The ephemeral modifier on an input field tells ubx that the value is sensitive. ubx wraps it in pulumi.secret() semantics, which means Pulumi encrypts it in the state file and redacts it from plan and output displays. Any expression that references an ephemeral input becomes Pending<T> — ubx emits .apply() wrapping wherever needed.

​
Syntax

input "name" {
    field_name ephemeral: Type
    field_with_default ephemeral: Type = default_value
}
The ephemeral modifier appears between the field name and the colon. It is compatible with all XCL types.

​
What it generates

A required ephemeral field (no default) generates config.require_secret(): 
input "secrets" {
    db_password ephemeral: string
}

db_password = config.require_secret("db_password")
An ephemeral field with a default generates config.get_secret(), falling back to the default when the config key is not set: 
input "secrets" {
    api_key ephemeral: string = "dev-key"
}

api_key = config.get_secret("api_key") or "dev-key"

​
Ephemeral inputs are always Pending<T>

config.require_secret() and config.get_secret() both return pulumi.Output[str] — Pulumi’s async wrapper. This means any expression that includes an ephemeral input is Pending<T> and must be resolved at apply time, not compile time. ubx tracks this automatically. You do not annotate use sites — the compiler propagates Pending<T> through the expression tree and emits .apply() wrapping wherever the generated Python needs it.

​
Direct property assignment

Passing an ephemeral input directly to a resource property is valid. Pulumi’s Python SDK accepts Input[T] (which includes Output[T]) for all resource properties: 
stack "app" {
    db = aws.rds.Instance {
        password = input.db_password
    }
}

db = aws.rds.Instance("db",
    password=db_password,   # db_password is Output[str] — Pulumi handles it
)

​
Object expressions

Ephemeral inputs inside object literals are treated identically. Pulumi accepts Output[T] as map values: 
stack "app" {
    service = aws.ecs.Service {
        environment = { api_token = input.api_key, region = input.region }
    }
}

service = aws.ecs.Service("service",
    environment={"api_token": api_key, "region": region},
)

​
F-string interpolation in sync values

When an ephemeral input appears inside a values {} block inside a sync argocd or sync flux block, ubx wraps the entire values list with pulumi.Output.all().apply(). All pending expressions — including f-string fragments containing ephemeral refs — are collected into the dependency list and resolved before the values are passed to the deployment target: 
stack "app" {
    gitops = sync argocd {
        repo = "https://github.com/org/app"
        path = "k8s/app"
        values {
            db_url = f"postgres://app:{input.db_password}@db.internal/appdb"
            token  = input.api_key
        }
    }
}

gitops = k8s.apiextensions.CustomResource("gitops",
    ...
    spec={
        "source": {
            "helm": {
                "parameters": pulumi.Output.all(
                    f"postgres://app:{db_password}@db.internal/appdb",
                    api_key,
                ).apply(lambda _deps: [
                    {"name": "dbUrl",  "value": _deps[0]},
                    {"name": "token",  "value": _deps[1]},
                ]),
            },
        },
    },
)
Multiple pending expressions are passed as separate arguments to Output.all() and indexed as _deps[0], _deps[1], etc. inside the lambda.

​
Default values

When ephemeral and a default are combined, the generated accessor is config.get_secret() (optional) rather than config.require_secret() (required). The default is appended with or: 
input "secrets" {
    api_key ephemeral: string = "dev-key"
}

api_key = config.get_secret("api_key") or "dev-key"
The default value itself is a plain Python literal — it is never encrypted. Use a placeholder like "" as the default if you want the field to be optional in development but always provided a real secret in production.

​
When to use ephemeral

Use ephemeral for any value that must not appear in plain text in Pulumi’s state file:
  • Database passwords (db_password ephemeral: string)
  • API keys and tokens (api_key ephemeral: string)
  • TLS private keys or certificate passphrases
  • Webhook secrets
  • OAuth client secrets
Do not use ephemeral for configuration that is sensitive in transit but safe to record in state (for example, a region name that is derived from a secret path but is not itself a secret).

​
What ephemeral protects — and what it does not

ephemeral protects state persistence. Pulumi encrypts the value in .ubx/state/ and redacts it from pulumi stack output and plan previews. It does not protect the value in transit — it is still passed to the resource constructor in plain text inside the running Pulumi program, and may appear in provider logs or cloud audit trails. For secret storage and retrieval at runtime, combine ephemeral with from = "secretsmanager:..." or from = "ssm:/..." (see from attribute): 
input "secrets" {
    db_password ephemeral: string
                from      = "secretsmanager:prod/db/password"
}
This fetches the value from AWS Secrets Manager at deploy time and marks it ephemeral in state. The from attribute is a UBX-207 feature — refer to the input reference for current availability.

​
Relationship to import and module imports

ephemeral is an attribute on an input field, not a top-level block. It is unrelated to:
  • import <label> { ... } — onboarding existing cloud resources (see import)
  • import "path" { ... } — module imports (see module)