APIIDA API Gateway Manager
Use service variables
The APIIDA API Gateway Manager can be used to discover APIs from version control or a running gateway instance and register within the product. One reason to register an API might be to control certain variables which have different values based on the environment of gateway. This documentation shows how to define variables, how to assign an environment-based value and how to order variables loaded by the Gateway Manager.
Definition of environment based values of service variables
The first step to use environment variables is the registration of an API within the Gateway Manager. The registration process is described here. Based on whether on which item(s) has been selected during the discovery, the user might see one of two items shown below for the registered API.
If the user selected a service within a folder, the APIs menu will show a symbol with two gearwheels. Otherwise, the symbol will be a folder which will contain service(s) as shown below.
It is important to recognise which form is registered since only service menus will show the “Variables” tab (see below) which is used to define environment-based variables. If a solution has been registered, the user can find the “Variables” tab for a service by selecting the “Services” tab within the Solution menu and clicking on one of the shown services. When the “Variables” tab is selected for the first time, the list will be empty as shown below.
Demo Setup
For the sake of demonstrating the usage of environment-based variables, we are using a simple demo service. This service is designed to route a given request to a backend target and return the response.
The policy shown in the screenshot above, defines a service that “loads” a cluster property “democonfig” which defines multiple variables that effect the behavior of the service:
environment: Defines the environment of the service. This value could be used to define more advanced behavior but is not used in the policy.
debug: Setting this value to “true” puts all Audit Details to WARNING and enables the recording of the request and response
audits: Setting this value to “true” adds the routing reason code to the error message if the route fails.
host: Defines the target host.
If you wish to try this out by yourself, you can find the policy definition at the bottom of this page.
Description of variables within the APIIDA API Gateway Manager
As stated above, the APIIDA API Gateway Manager allows to define variables for different environments. The demo service described above uses a cluster property to define the behavior of certain elements within the policy which might suit a development environment but which might not be used within a testing or production environment. Therefore, this configuration should be adapted to the environment that the service is deployed on. The APIIDA API Gateway Manager allows to define variables for multiple environments.
To define the values, the user can choose two options: Creating a custom variable or loading the service variables from a running API Gateway for the targeted environments.
Before we dive into these two options, we need to understand the different fields of a variable:
Group: The group defines the section in which a variable is displayed within the Gateway Manager. This can be either a custom value or one of the values displayed when variables are loaded from a running instance. You can see imported group values in the screenshot above (marked in bold font).
Friendly Name: This defines the name of variable. It has no impact on the migration or the display within the gateway and is used a reference for the user of the APIIDA API Gateway Manger. Variables loaded from a running instance will set this value equal to the key value with the dots replaced by arrows.
Key: This field references the actual variable. Within the APIIDA API Gateway Manager, the following structure is used: template.<resource_path>.<resource_name>.<key>
In our example, we want to manipulate a cluster property which has no elements path beside the resource type. Therefore the key is: template.cluster_property.democonfig.Value
Environment: This environment defines the target environment for this variable. You can create the same variable multiple times for different environments to define different values.
In our example, we create a variable with the same key for two environments (Development, Test)
Value: The value of the variable.
The screenshot below shows our example configuration. Note that the value for “audits” and “host” is different to the initial configuration:
Option 1: Creating your own variables
To create your own variables, you click on the button “Create New Variable” in the top left corner of the “Variables” tab. This will start a popup as described within the last section. Configure the variable and click on “Save”. The variable is saved and a green success message is shown as in the screenshot below.
As stated above, the same variable can be created for different environments as shown below:
If you want to edit your variables, click the “Edit” button on the right side of the line. All fields can be edited after creation.
Option 2: Importing variables from a running instance
If you are unsure how to define a variable, you can use the button “Import from running instance”. This will trigger the following pop-up window:
The popup window contains two fields:
Import variables from: This field defines the gateway from which the variables and its values are loaded from.
Create variables for environment: This field defines the environment which is associated with the variables loaded.
A click on “Import from selected node” will trigger a Restman request to the selected gateway and load all associated variables. If any detected key is already defined beforehand for the environment, the variable is not created. You can see an example for our demo service in the screenshot below:
If you wish to do so, you can load the variables multiple times for each of your environments. To do this, simply click again on “Import from selected node” and select a different environment. The APIIDA API Gateway Manager will load the variables again but associated with a different environment like this:
Re-ordering variables
All variables can be manipulated like variables created by the user. This includes for example to change the group of a variable. A user might want to change the group of a loaded variable to order variables in a group which values should be changed based on the environment.
!Warning!
Loading variables from the system might also include critical settings (e.g. values of an SSL keys, server module files or certificates). Do not manipulate these values unless you understand the consequences of changing specific values to your environment. APIIDA AG is not responsible for any issues that might occur by improper use of this feature.
Variables within the Migration Preparation screen
After the variables have been defined, the user can observe the change within the migration preperation screen within the Template Variables tab. In our example, the configuration of the service has been manipulated. The green icon “AAGM” indicates a change has been made to the value of a variable based on the configuration of a registered API. The value column shows the value which will be applied. Below the new value, the old value is shown with the prefix “Original value was:”.
Appendix
Policy definition of the demo Service
