Use ESVs in configuration placeholders

Overview

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 could 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).

Identity Cloud does not yet support the ability to define where placeholders should be inserted into your configuration. Instead, you must use a promotion request.

The functionality to insert placeholders into your configuration using the API and the UI will be available later this year.

Secrets and variables that are defined in configuration placeholders, but have no corresponding ESV set, will cause promotions to fail.

Set up configuration placeholders to reference ESVs

For each of the development, staging, and production environments:

Create the ESVs:
- Create variables or create secrets using the API (for background, see Manage ESVs using the API).
- Create variables or create secrets using the Identity Cloud admin UI.
Use a promotion request to add corresponding placeholders to your configuration and promote them to the environment.

If you wish to add more ESVs later, you will need to repeat the steps above, and use a further series of promotion requests.

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 ESVs referenced by configuration placeholders

If you update ESVs that are referenced by configuration placeholders, you also need to restart Identity Cloud services; this will substitute updated secrets and variables into the corresponding configuration placeholders:

Update variables or update secrets, then restart using the API (for background, see Manage ESVs using the API).
Update variables or Update secrets, then apply updates using the Identity Cloud admin UI.

Delete ESVs referenced by configuration placeholders

For each of the development, staging, and production environments:

Identify all placeholders in your configuration that correspond with the ESVs you intend to delete.
Use a promotion request to remove the placeholders from your configuration.
Delete the ESVs:
- Delete variables or delete secrets using the Identity Cloud API (for background, see Manage ESVs using the API).
- Delete variables or delete secrets using the Identity Cloud admin UI.

Define and promote ESVs

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. See tenants/esvs.adoc#esv_naming.
Set a 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.

Submit a development environment promotion request to insert a corresponding placeholder into the environment configuration and promote it to your development environment. You will need to specify which part of the environment configuration to insert the placeholder; for example, in the authentication settings. For the example variable esv-myurl from step 1, this placeholder would be called &{esv.myurl}.

It is not yet possible to use the API or the UI to define where a placeholder should be inserted into your configuration. This functionality will be available at a later date.

Test that the variable is working correctly in your development environment. If an update is necessary, choose one of the following options:
- Use the variables API endpoint to update the variable, then use the restart API endpoint to restart Identity Cloud services.
- Use the Identity Cloud admin UI to update the variable, then apply the update.
Submit a promotion request to promote the placeholders to your staging environment.
Test your staging environment as described in step 4.
Submit a promotion request to promote the placeholders to your production environment.
Test your production environment as described in step 4.

The following illustration demonstrates the process:

image$esv set variable