fn::secret

The fn::secret built-in function decrypts a ciphertext literal into a secret string value.

In addition to its evaluation-time behavior, fn::secret has additional behavior at update time. When an environment is saved, any fn::secret invocations with plaintext arguments are transformed by encrypting the plaintext and replacing it with a ciphertext literal.

Storing secrets

To store a secret, add an fn::secret value to an environment. ESC encrypts it when the environment is saved, so plaintext is never persisted.

Via the CLI

Add a secret using the --secret flag:

pulumi env set <org>/<project>/<env-name> apiKey my-secret-value --secret

Via the Pulumi Cloud console

In the environment editor, wrap a value in fn::secret and select Save:

values:
  apiKey:
    fn::secret: my-secret-value

Multi-line secrets

For multi-line values such as private keys, TLS certificates, or SSH keys, use a YAML block scalar:

values:
  tlsCert:
    fn::secret: |
      -----BEGIN CERTIFICATE-----
      MIIDXTCCAkWgAwIBAgIJAMqBbsYRO...
      -----END CERTIFICATE-----
  privateKey:
    fn::secret: |
      -----BEGIN RSA PRIVATE KEY-----
      MIIEowIBAAKCAQEA0Z3VS5JJcds3...
      -----END RSA PRIVATE KEY-----

The | character tells YAML to preserve newlines, which is required for PEM-formatted values. Using pulumi env set for multi-line secrets is not recommended — use the console editor or edit the environment YAML directly.

Declaration

fn::secret:
  ciphertext: base64-encoded-ciphertext

Plaintext form

This form is replaced by the ciphertext form when it is present in an environment being saved. ESC never stores plaintext secrets.

fn::secret: plaintext-string

Parameters

Returns

The decrypted plaintext. Decrypted values are marked as secrets by the evaluator so that combining secret and non-secret values can maintain secretness. Consumers of evaluated ESC environments may use secretness information to e.g. redact values from command output.