Use ESVs in configuration placeholders

Identity Cloud lets you reference ESVs from configuration placeholders. This lets you use different configuration values for the development, staging, and production environments at run time.

For example, suppose you wanted to set a different email sender for each environment. You would set the configuration value of the email sender to an ESV, with different values in each environment; for example, dev-mycompany@example.com (development), staging-mycompany@example.com (staging), and mycompany@example.com (production). Then, you would insert the ESV configuration placeholder into your configuration instead of a literal value.

Secrets and variables defined in configuration placeholders, but with no corresponding ESV set, will cause promotions to fail. Refer to Configuration integrity checks.

Set up configuration placeholders to reference an ESV

In your development environment:
1. Create the ESV using one of the following:
  - Create a variable or create a secret using the API (for background, refer to Manage ESVs using the API).
  - Create a variable or create a secret using the Identity Cloud admin UI.
2. Insert the ESV configuration placeholder into your configuration. Refer to Manage configuration placeholders using the API.
3. Restart Identity Cloud services.
In your staging environment:
1. Repeat step 1a for your staging environment. Ensure the ESV name is the same as you set up in the development environment.
2. Run a promotion to move the configuration change from your development environment to your staging environment. Refer to:
  - Manage self-service promotions using the API
  - Manage self-service promotions using the UI
In your production environment:
1. Repeat step 1a for your production environment. Ensure the ESV name is the same as you set up in the development environment.
2. Run a further promotion to move the configuration change from your staging environment to your production environment.

If you want to add more ESVs later, repeat the steps above, and use a further series of promotions.

Configuration placeholders can only be inserted into static configuration. See the promotion FAQs for more information on what static configuration is, and which areas of configuration are classified as static.

Update an ESV referenced by a configuration placeholder

Update the ESV using one of the following:
- Update a variable or add a new secret version to a secret using the API (for background, see Manage ESVs using the API).
- Update a variable or add a new secret version to a secret using the Identity Cloud admin UI.
Next, Restart Identity Cloud services.

Restart Identity Cloud services

If you update an ESV referenced by a configuration placeholder, you also need to restart Identity Cloud services. This substitutes the updated secret or variable into the corresponding configuration placeholder.

Restart Identity Cloud services using one of the following:
- Restart using the API (for background, see Manage ESVs using the API).
- Apply updates using the Identity Cloud admin UI.

Delete an ESV referenced by a configuration placeholder

Remove the ESV configuration placeholder from your configuration in the development environment. Refer to Manage configuration placeholders using the API.
Run a promotion to move the configuration change from the development environment to the staging environment. Refer to:
- Manage self-service promotions using the API
- Manage self-service promotions using the UI
Run a further promotion to move the configuration change from the staging environment to the production environment.
Delete the ESV in each of the development, staging, and production environments using one of the following:
- Delete a variable or delete a secret using the Identity Cloud API (for background, see Manage ESVs using the API).
- Delete a variable or delete a secret using the Identity Cloud admin UI.

Define and promote an ESV

An example of using a variable would be to define a URL that a user is redirected to after logging in. In each environment, the URL would need a different value; for example, dev-www.example.com (development), staging-www.example.com (staging), and www.example.com (production).

To define and promote the variable:

Decide on a variable name; for example, esv-myurl. Refer to ESV naming.
Set an ESV variable in each of the development, staging, and production environments. To do this, choose one of the following options:
- Use the variables API endpoint to create the variable, then use the restart API endpoint to restart Identity Cloud services.
- Use the Identity Cloud admin UI to create the variable, then apply the update.

Insert the ESV configuration placeholder into your configuration in the development environment. Refer to Manage configuration placeholders using the API. For the example variable esv-myurl from step 1, the placeholder would be called &{esv.myurl}.

Run a promotion to move the configuration change from the development environment to the staging environment. Refer to:
- Manage self-service promotions using the API
- Manage self-service promotions using the UI
Run a promotion to move the configuration change from the staging environment to the production environment.

The following illustration demonstrates the process:

image$esv set variable