PingGateway 2024.11

Token Resolution

At startup, the bootstrap resolver builds a chain of resolvers to resolve configuration tokens included in config.json and admin.json. When a route is deployed, route resolvers build on the chain to add resolvers for the route.

Route Token Resolvers

When a route is deployed in PingGateway a route resolver is created to resolve the configuration tokens for the route. The resolver uses token values defined in the properties section of the route.

If the token can’t be resolved locally, the route resolver accesses token values recursively in a parent route.

Learn more about route properties in Route properties.

Environment Variables Resolver

When the bootstrap resolver resolves a configuration token to an environment variable, it replaces the lowercase and periods (.) in the token to match the convention for environment variables.

Environment variable keys are transformed as follows:

  • Periods (.) are converted to underscores

  • All characters are transformed to uppercase

The following example sets the value of an environment variable for the port number:

$ export LISTEN_PORT=8080

In the following PingGateway configuration, the value of port is 8080:

{
  "port": "&{listen.port}"
}

System Properties Resolver

The system property name must match a configuration token exactly. The following example sets a system property for a port number:

$ java -Dlisten.port=8080 -jar start.jar

In the following PingGateway configuration, the value of port is 8080:

{
  "port": "&{listen.port}"
}

Token Source File Resolvers

Token source files have the .json or .properties extension. The bootstrap resolver uses the files to add file resolvers to the chain of resolvers:

  • JSON file resolvers

    Token source files with the .json extension take a JSON format. The token name is mapped either to the JSON attribute name or to the JSON path.

    Each of the following .json files set the value for the configuration token product.listen.port:

    {
  "product.listen.port": 8080
}
    {
  "product.listen": {
     "port": 8080
  }
}
    {
  "product": {
    "listen": {
      "port": 8080
    }
  }
}

  • Properties file resolvers

    Token source files with the .properties extension are Java properties files. They contain a flat list of key/value pairs, and keys must match tokens exactly.

    The following .properties file also sets the value for the tokens listen.port and listen.address:

    listen.port=8080
listen.address=192.168.0.10

Token source files are stored in one or more directories defined by the environment variable IG_ENVCONFIG_DIRS or the system property ig.envconfig.dirs.

If token source files are in multiple directories, each directory must be specified in a comma-separated list. PingGateway doesn’t scan subdirectories. The following example sets an environment variable to define two directories that hold token source files:

$ export IG_ENVCONFIG_DIRS="/myconfig/directory1,/myconfig/directory2"

At startup, the bootstrap resolver scans the directories in the specified order, and adds a resolver to the chain of resolvers for each token source file in the directories.

Although the bootstrap resolver scans the directories in the specified order, within a directory it scans the files in a nondeterministic order.

Note the following constraints for using the same configuration token more than once:

  • Don’t define the same configuration token more than once in a single file. There is no error, but you won’t know which token is used.

  • Don’t define the same configuration token in more than one file in a single directory. An error occurs.

    This constraint implies that you can’t have backup .properties and .json files in a single directory if they define the same tokens.

  • You can define the same configuration token once in several files that are located in different directories, but the first value that PingGateway reads during JSON evaluation is used.

    When logging is enabled at the DEBUG level for token resolvers, the origin of the token value is logged.

    If you are using the default logback implementation, add the following line to your logback.xml to enable logging:

    <logger name="org.forgerock.config.resolvers" level="DEBUG" />