1. Docs
  2. Pulumi ESC
  3. Get started
  4. Store and retrieve secrets

Pulumi ESC: Store and Retrieve Secrets

    In an environment file, values are defined as a series of key-value pairs in YAML format. All variables will be defined under a top-level key named values. These values can be strings, numbers, or arrays, and they can be manually provided, dynamically generated from external sources, or referenced from other values in the file. They can also be stored in plain-text or as secrets.

    values:
      myKey1: "myValue1"
      myNestedKey:
        myKey2: "myValue2"
        myNumber: 1
      myPassword:
        fn::secret:
          ciphertext: ZXN....
    

    You can store and retrieve values in an environment via the Pulumi Cloud console or via the CLI.

    Store Environment Values

    Store via the console

    To store values in your environment, first click on the name of the environment to open its definition editor. You will be presented with a split pane view. The left side is where you will write the definition of your environment configuration, and the right side will show a preview of your configuration in JSON format.

    Next, delete the placeholder text in the environment file and add the following simple configuration definition in its place:

    values:
      myEnvironment: "development"
      myPassword:
        fn::secret: "demo-password-123"
    

    As shown above, you can specify that a value should be stored as a secret by using the fn::secret function. Once you have added the configuration, click the Save button located at the bottom of the editor.

    The Environment preview pane on the right hand side will then update to show your added configuration in JSON format. You will notice that the value of “myPassword” has been hidden from view in both the defintion and preview panes.

    Store via the CLI

    To store values or update an existing value via the CLI, use the esc env set command as shown below, where <org-name> is optional and defaults to your Pulumi Cloud username:

    esc env set [<org-name>/]<environment-name> <key> <value>
    

    To demonstrate how this works, add the following simple configuration definition to your environment using the following command, making sure to replace the value of my-dev-environment with the name of your own environment:

    esc env set my-dev-environment myEnvironment development
    esc env set my-dev-environment myPassword demo-password-123 --secret
    

    As shown above, you can specify that a value should be stored as a secret by using the --secret flag.

    Alternatively, you can directly edit your environment file with a code editor using the following command, making sure to replace <environment-name> with the name of your own environment (e.g. my-dev-environment):

    esc env edit <environment-name>
    

    Using this method enables you to add your configuration values in the same way that you would via the console.

    Retrieve Environment Values

    Retrieve via the console

    To retrieve values in the console, scroll to the bottom of your environment page and click the Open button. This will return any statically defined plain-text values and definitions.

    As shown above, it does not return the value of secrets defined, nor does it resolve values that are dynamically generated from a provider. To view these values, you will need to click the Show secrets slider.

    Retrieve via the CLI

    The CLI has a built-in get command that enables you to retrieve a single value from your environment. The format of the full command looks like the following:

    esc env get [<your-org>/]<your-environment-name> <variable-key-name>
    

    To retrieve the value of the myEnvironment variable you created earlier, the command to do so would look like the following, making sure to replace the value of my-dev-environment with the name of your own environment:

    esc env get my-dev-environment myEnvironment
    

    Running this command should return the following response:

    $ esc env get my-dev-environment myEnvironment
    
       Value
      
        "development"
      
       Definition
      
        development
      
       Defined at
      
      • my-dev-environment:2:8
    

    It is also possible to retrieve all values in an environment. To do so, run the esc env get command without specifying a value as shown below:

    esc env get my-dev-environment
    

    Running this command should return the following response:

    $ esc env get my-dev-environment
    
       Value
      
        {
          "myEnvironment": "development",
          "myPassword": "[secret]"
        }
      
       Definition
      
        values:
          myEnvironment: "development"
          myPassword:
            fn::secret:
              ciphertext: ZXNjeAA....
    

    The esc env get command only returns statically defined plain-text values and definitions. This means that it does not return the value of any defined secrets, nor does it resolve values that are dynamically generated from a provider. To view these values, you must run the esc env open command as shown below. This will open the environment and resolve any secrets or dynamically retrieved values:

    $ esc env open my-dev-environment
    
    {
      "myEnvironment": "development",
      "myPassword": "demo-password-123"
    }
    

    In the next section, you will learn how to import configuration values from other environments.

      Pulumi AI - What cloud infrastructure would you like to build? Generate Program