Skip to main content

Configuration

IBM Application Gateway (IAG) uses YAML documents for all configuration data. When the container starts, it will look for a Kubernetes custom object (if specified), or failing this it will look in the '/var/iag/config' directory of the container for YAML documents.

Depending on your container environment, the files within the configuration directory can be bind mounted in, provided via a ConfigMap or any other mechanism which places the files in the configuration directory.

To get started with authoring IAG configuration YAML, refer to the Examples and YAML Reference.

Using Multiple Configuration YAML Documents

If a Kubernetes custom object is not being used the IAG configuration contained within the configuration directory can span multiple YAML documents. This is useful for simplifying the management of configuration data.

IAG combines all YAML documents found in '/var/iag/config' using the following rules:

  1. IAG configuration documents must have the file extension '.yaml' or '.yml'.
  2. Each file which contains IAG configuration must contain the 'version' indicator. Documents which do not include the 'version' indicator are not parsed as IAG configuration.
  3. All documents must have the same 'version'. Mixing different configuration versions is not supported and IAG will not start when it discovers more than one version. Refer to Versioning for further information.
  4. Each top-level key (server, identity, authorization, logging, advanced, policies) can only be defined once across all configuration YAML documents, with the exception of the 'resource_servers' key.
  5. The top-level key 'resourceservers' can be defined more than once. When this occurs IAG will combine all of the 'resourceservers' values.

Example of Multiple Configuration YAML Documents

This example illustrates how multiple configuration YAML documents can be provided to IAG. The following files are provided to the '/var/iag/config' path within the container.

  1. iag.yaml
  2. resource-servers-1.yaml
  3. resource-servers-2.yaml
  4. logging.yaml

iag.yaml - This file contains the top level 'server' and 'identity' keys. Each document can provide more than one top level key, provided they are only defined once across the entire set of configuration documents.

version: 19.12
server:
  ssl:
    front_end:
      certificate: $CERT_PEM
identity:
  oidc:
    client_id: $CLIENT_ID
    client_secret: $CLIENT_SECRET
    discovery_endpoint: "https://iag-demo.ice.ibmcloud.com/oidc/endpoint/default/.well-known/openid-configuration"

resource-servers-1.yaml - This file contains the 'resourceservers' key and a single entry defining one resource server. The 'resourceservers' key is exceptional and can be defined more than once.

version: 19.12
resource_servers:
  - virtual_host: iag-demo.ibm.com
    servers:
      - host: 10.10.10.200
        port: 80

resource-servers-2.yaml - This file contains a second 'resource_servers' key and the definition for an additional resource server. Partitioning each resource server into its own YAML file makes it easy to add or remove resource servers by simply adding or removing the corresponding file containing the resource server definition and recreating the container.

version: 19.12
resource_servers:
  - path: /
    servers:
      - host: 10.10.10.201
        port: 8080

logging.yaml - This file contains the 'logging' key and sets a tracing entry useful for debugging. When debugging is completed, this file can be removed and the container restarted to disable tracing.

version: 19.12
logging:
  json_logging: false
  tracing:
    - file_name: /var/tmp/snoop.log
      component: pdweb.snoop
      level: 9

These separate documents are equivalent to providing the following as a single YAML document:

version: 19.12
server:
  ssl:
    front_end:
      certificate: $CERT_PEM
identity:
  oidc:
    client_id: $CLIENT_ID
    client_secret: $CLIENT_SECRET
    redirect_uri_host: iag-demo.ibm.com
    discovery_endpoint: "https://iag-demo.ice.ibmcloud.com/oidc/endpoint/default/.well-known/openid-configuration"
resource_servers:
  - virtual_host: iag-demo.ibm.com
    servers:
      - host: 10.10.10.200
        port: 80
  - path: /
    servers:
      - host: 10.10.10.201
        port: 8080
logging:
  json_logging: false
  tracing:
    - file_name: /var/tmp/snoop.log
      component: pdweb.snoop
      level: 9

Special Types

There are three special types which can used in addition to plain text within the YAML file. These special types can be used to substitute values from alternative sources.

Type Syntax
Environment Variable $<environment variable>
External File "@<file name>"
Base 64 Data B64:<base64 encoded string>

Example Environment Variable

The following example shows how a value stored in an environment variable can be used in the configuration YAML. Environment variables are useful when used in conjunction with Kubernetes secrets to hide sensitive data. In this example, the failover cookie key is loaded from an environment variable.

The environment variable 'MY_FAILOVER_SECRET' is set in the container context:

MY_FAILOVER_SECRET=exampleOnlyDoNotUseThisValue

An IAG configuration YAML document can indicate that this value should loaded from the the environment variable by specifying $MY_FAILOVER_SECRET as a value.

version: 19.12
server:
...
  failover:
    key: $MY_FAILOVER_SECRET
    cookie_name: IAG-FAILOVER-COOKIE
...

This is equivalent to specifying the value as-is within the YAML configuration data.

version: 19.12
server:
...
  failover:
    key: exampleOnlyDoNotUseThisValue
    cookie_name: IAG-FAILOVER-COOKIE
...

Example File Reference

The following example shows how a file reference can be used to source content from an external file (please note that file references are not supported when a Kubernetes custom object is being used to store the configuration information). In this example, a rate limiting rule will be loaded from an external file.

The following two files are present in the configuration directory '/var/iag/config':

config.yaml
rate_limiting.yaml

In this example, 'rate_limiting.yaml' is a simple YAML file with the content:

ip: true
capacity: 3	
interval: 60
reaction: TEMPLATE

In the IAG configuration file 'config.yaml', the content of 'rate_limiting.yaml' is included by specifying "@rate_limiting.yaml" as a value.

version: 19.12
policies:
...
  rate_limiting: 
    - name: "limited_by_ip"
      methods: 
        - "*"
      paths: 
        - "/my_app*"
      rule: "@rate_limiting.yaml"
...

This is equivalent to including the text content as-is within the YAML configuration data.

version: 19.12
policies:
...
  rate_limiting: 
    - name: "limited_by_ip"
      methods: 
        - "*"
      paths: 
        - "/my_app*"
      rule: |
        ip: true
        capacity: 3	
        interval: 60
        reaction: TEMPLATE
...

Note that a file reference must always be surrounded by quotes as the '@' character can not appear at the beginning of an unquoted YAML value.

Example Base 64 Data

For some types of data, it is not practical to store these as text within the configuration YAML and in some scenarios it is useful to be able to embed all data within a single configuration YAML document. In these cases, the values can be base 64 encoded and embedded as values within the configuration YAML.

The following example shows how a transformation rule can be embedded in the configuration YAML as base 64 encoded data.

First, generate the base 64 representation of the file. On macOS and other UNIX-like systems this can be achieved with the 'base64' command.

$ base64 Req-AddStaticHeader.xsl
PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHhzbDpzdHlsZXNoZWV0IHht
...

In the IAG configuration YAML, this can be placed on a single line preceded by the 'B64:' prefix.

version: 19.12
policies:
  ...
    http_transformations:
      request:
        - name: req-static-headers
          method: GET
          url: "*"
          rule: B64:PD94bWwgdmVyc2lvbj0i...
...

This is equivalent to including the text content as-is within the YAML configuration data.

version: 19.12
policies:
  ...
    http_transformations:
      request:
        - name: req-static-headers
          method: GET
          url: "*"
          rule: |
            <?xml version="1.0" encoding="UTF-8"?>
            <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
                <xsl:strip-space elements="*" />
                <xsl:template match="/">
            ...
...