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
To set up configuration placeholders to reference ESVs, first create the ESVs using the Identity Cloud API or the Identity Cloud admin UI:
-
Create variables using the API (for background, see Manage ESVs using the API)
-
Create variables using the Identity Cloud admin UI
Then, use a series of promotion requests. Initially, create a development environment promotion request; this will add placeholders into your configuration and promote them to your development environment. Later, use further promotion requests to promote the placeholders to your staging and production environments.
If you wish to add more ESVs later, you will need to create an additional 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 an ESV that is referenced by a configuration placeholder, you also need to restart Identity Cloud services; this will substitute updated secrets and variables into the corresponding configuration placeholders:
-
Update variables and restart using the API (for background, see Manage ESVs using the API)
-
Update variables and apply updates 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-myurlfrom step 1, this placeholder would be called&{esv.myurl}.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. 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:
