Understanding the New Configuration Model¶
Overview¶
The new configuration model, which is based on the TOML format, was introduced in WSO2 API Manager 3.0.0 and is available from there onwards. In older versions of WSO2 API Manager, you had to modify different configuration files based on the components corresponding to the specific feature they were configuring.
However, with the new WSO2 configuration model, all configuration files have been merged to make the configuration process easier. Therefore, the <API-M_HOME>/repository/conf/deployment.toml
file is the single source used to configure and tune the various features in WSO2 API Manager.
For more information on the configuration parameters that can be used in the deployment.toml
file, see the Configuration Catalog.
The following section explains the mapping between WSO2 API Manager's old configuration files and the new deployment.toml
file.
Identifying configuration parameters¶
Let's see how you can identify the new configuration parameters that you need to add in the deployment.toml
file for any configuration. Understanding the concept behind the new configuration model will be really helpful when migrating from old API-M versions to the new APIM 3.x versions.
.j2 template files¶
In the <APIM_HOME>/repository/resources/conf/templates/repository/conf
directory there are files that are exactly in the same structure as the files in the <APIM_HOME>/repository/conf
directory.
Each configuration file that is inside the <APIM_HOME>/repository/conf
directory has a .j2
template file. These .j2
files contain the parameterizations.
Example:
Let's assume that you want to change the ServerURL
value inside the APIKeyValidator
section of the api-manager.xml
file.
<APIKeyValidator>
<!-- Server URL of the API key manager --><ServerURL>https://localhost:${mgt.transport.https.port}${carbon.context}services/</ServerURL>
<!-- Admin username for API key manager. --><Username>${admin.username}</Username>
<!-- Admin password for API key manager. --><Password>${admin.password}</Password>
<KeyValidationHandlerClassName>org.wso2.carbon.apimgt.keymgt.handlers.DefaultKeyValidationHandler</KeyValidationHandlerClassName>
<DefaultKeyManagerType>default</DefaultKeyManagerType>
<EnableKeyManagerConfigurationRetriever>true</EnableKeyManagerConfigurationRetriever>
<EnableProvisionedAppValidation>true</EnableProvisionedAppValidation>
</APIKeyValidator>
Let's check the respective .j2
file that is in the <APIM_HOME>/repository/resources/conf/templates/repository/conf/api-manager.xml.j2
file.
<APIKeyValidator>
<!-- Server URL of the API key manager -->
<ServerURL>{{apim.key_manager.service_url}}</ServerURL>
<!-- Admin username for API key manager. -->
<Username>{{apim.key_manager.username}}</Username>
<!-- Admin password for API key manager. -->
<Password>{{apim.key_manager.password}}</Password>
<KeyValidationHandlerClassName>{{apim.key_manager.key_validation_handler_impl}}</KeyValidationHandlerClassName>
<DefaultKeyManagerType>{{apim.key_manager.type}}</DefaultKeyManagerType>
{% if apim.jwt.expiry_time is defined %}
<JWTExpiryTime>{{apim.jwt.expiry_time}}</JWTExpiryTime>
{% endif %}
<EnableKeyManagerConfigurationRetriever>{{apim.key_manager.enable_retriever}}</EnableKeyManagerConfigurationRetriever>
{% if apim.key_manager.enable_provisioned_app_validation is defined %}
<EnableProvisionedAppValidation>{{apim.key_manager.enable_provisioned_app_validation}}</EnableProvisionedAppValidation>
{% endif %}
</APIKeyValidator>
You can see that the parameter for setting up the value for the ServerURL
in the APIKeyValidator
is apim.key_manager.service_url
. Therefore, the configuration for the deployment.toml
file will be as follows:
default.json file¶
The default.json
file contains the default values for all the parameters that are defined inside the .j2
files.
You need to add values in the deployment.toml
file only if you need to override the default values, which are defined in the default.json
file. Otherwise, you do not need to add a configuration block inside the deployment.toml
file.
This default.json
file, which is in the <APIM_HOME>/repository/resources/conf/default.json
directory, has all the parameters and default values for it.
Example:
Let’s assume that you want to enable the Gateway Token Cache. The relevant configuration can be found in the api-manager.xml
file inside <CacheConfigurations>
.
<CacheConfigurations>
<!-- Enable/Disable token caching at the Gateway-->
<EnableGatewayTokenCache>{{apim.cache.gateway_token.enable}}</EnableGatewayTokenCache>
.......
</CacheConfigurations>
Let's check the default.json
file and look for the default value set for apim.cache.gateway_token.enable
It is set to true
, which means, by default, the Gateway token cache is enabled.
Therefore, you do not need to add any configuration in the deployment.toml
file.
Repetitive configurations¶
The following are some important points that you need to keep in mind.
Arrays¶
If you look at the .j2
template files, you may notice in some places, there are for
loops. Those for
loops are there to add multiple/repetitive configurations.
Example:
Let’s assume that you have more than one Gateway in your environment, and you need to add the required configuration inside the deployment.toml
.
In the old configuration file, it is just a matter of adding multiple <APIGateway>
sections. But in the deployment.toml
file, you have to add it as arrays/groups.
Let’s first look at the APIGateway section in the api-manager.xml.j2
file.
<APIGateway>
........
{% for environment_name in apim.gateway.environment%}
<Environment type="{{environment_name.type}}" api-console="{{environment_name.display_in_api_console}}" isDefault="{{environment_name.show_as_token_endpoint_url}}">
<Name>{{environment_name.name}}</Name>
.........
</APIGateway>
In the above section, you can see that there is a for loop to iterate through each section named apim.gateway.environment
. Therefore when you configure this in the deployment.toml
file you need to add this as grouped sections as shown below:
[[apim.gateway.environment]]
name = "Internal Gateway"
type = "hybrid"
display_in_api_console = true
......
[[apim.gateway.environment]]
name = "External Gateway"
type = "hybrid"
display_in_api_console = true
......
KeyValue pairs¶
If you look at the .j2
template files, you may notice that in some places there is another set of for
loops for adding key-value pairs. Most of the time, this is there for adding multiple properties.
Example
Let’s assume that you need to set the properties in the HTTP transport sender configuration in the axis2_client.xml
file. The following is how the configuration for the HTTP transport sender appears in the axis2_client.xml.j2
file.
<transportSender name="https"
class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">{% for name,value in transport.client.https.properties.items()%}<parameter name="{{name}}">{{value}}</parameter>
{% endfor %}
</transportSender>
In above section you can see that there is a for loop to iterate through transport.client.https.properties
.
First let’s look at the default.json
file to see what are the default properties getting added to this transport sender.
"transport.client.http.properties.PROTOCOL": "HTTP/1.1",
"transport.client.http.properties.Transfer-Encoding": "chunked",
"transport.client.http.properties.SO_TIMEOUT": "60000",
"transport.client.http.properties.CONNECTION_TIMEOUT": "60000",
Let’s assume that you need to increase the timeout values, which means you have to override these values via the deployment.toml
file. In this case you need to add those values as key value pairs.
How it works¶
During server startup, the WSO2 API Manager will assign the values inside the default.json
file to its respective parameters inside the multiple configuration files (api-manager.xml
, carbon.xml
, user-mgt.xml
, registry.xml
, pass-through.properties
, axis2.xml
etc.)
If you have defined any values in the deployment.toml
file for any of the parameters that are defined in the .j2
template files, then the server will assign the value that is defined in the deployment.toml
file instead of the default value, which is in the default.json
file.
Summary¶
- From APIM 3.x onwards, there is only one configuration file to modify, which is the
deployment.toml
file. - It is not recommended to modify the
.xml
files directly. - You do not have to add a configuration to the
deployment.toml
file unless you want to modify the server’s default value. - Default values for all the configurations can be found in the
default.json
file. - You can always find the required parameter name to add in the
deployment.toml
file by looking at the respective.j2
template file of that configuration file.