Python API

A GitHub repository (ibm-application-gateway-resources) has been created to store useful resources for the IBM Application Gateway (IAG). One of the resources available in this repository is a python API which can be used to:

automate the generation of the IAG configuration;
start an IAG container in a Docker or Kubernetes environment.

The python API has been implemented as packages which reside in the 'python/packages' directory of the GitHub repository. In order to make the packages available to the python environment the PYTHONPATH environment variable should be modified to include the path to this directory. For example, if the GitHub repository resides at '/usr/local/ibm-application-gateway-resources':

export PYTHONPATH="/usr/local/ibm-application-gateway-resources/python/packages"

Configuration

The Configurator class, within the 'ibm_application_gateway.system' package, can be used to generate a YAML file which contains a specific configuration.

The configuration API has been generated from the IAG OpenAPI schema using the openapi-generator utility. At a high level, each YAML object within the IAG configuration is available as a python class and the simple types within the YAML object (for example: string) correspond to attributes within the python class.

Documentation for the configuration API is available within the 'python/doc' directory of the GitHub repository.

A test program, which exercises the majority of the configuration API, is available within the 'python/test' directory of the GitHub repository.

A python test script, which uses the configuration API to author a simple YAML configuration file, is provided below:

##!/usr/local/bin/python3

"""
IBM Confidential
Object Code Only Source Materials
(c) Copyright International Business Machines Corp. 2020
The source code for this program is not published or otherwise divested
of its trade secrets, irrespective of what has been deposited with the
U.S. Copyright Office.
"""

import sys

from ibm_application_gateway.system  import *
from ibm_application_gateway.config  import *

###############################################################################

try:
    # Create the IBM Security Verify OIDC configuration.
    oidc = Oidc(
                discovery_endpoint = "https://ibm-app-gw.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration",
                client_id          = "300141b6-690b-4e4e-862d-2c96da2bb1ba",
                client_secret      = "wPP8rM8N0d"
             )

    # Add the IBM Security Verify OIDC configuration to our Identity configuration.
    identity = Identity(oidc = oidc)

    # Create the configuration YAML.
    config   = Configurator(identity = identity)
    cfgFile  = config.write()

    print("Wrote the configuration file: {0}".format(cfgFile))

except Exception as exc:
    print("An exception occurred: {0}".format(exc))
    sys.exit(1)

This script will generate the following YAML file:

identity:
  oidc:
    client_id: 300141b6-690b-4e4e-862d-2c96da2bb1ba
    client_secret: wPP8rM8N0d
    discovery_endpoint: "https://ibm-app-gw.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration"
    mapped_identity: '{sub}'
version: '23.04'

Container Management

The Container class, within the 'ibm_application_gateway.system' package, provides a simple python API which can be used to create an IAG container in the local environment.

In a Kubernetes environment the class will make the supplied configuration available as a either a Custom Object or a ConfigMap, and in a Docker environment it will make the supplied configuration available by bind-mounting the configuration to the '/var/iag/config' directory of the container.

The 'CONTAINER_SERVICE' environment variable is used to indicate whether a Docker or a Kubernetes container will be created. The default, if the environment variable is not specified, is to create a Docker container.

A python test script, which uses the Container class to start an IAG Kubernetes container, is provided below:

##!/usr/local/bin/python3

"""
IBM Confidential
Object Code Only Source Materials
(c) Copyright International Business Machines Corp. 2020
The source code for this program is not published or otherwise divested
of its trade secrets, irrespective of what has been deposited with the
U.S. Copyright Office.
"""

import sys
import logging

from ibm_application_gateway.system import *

###############################################################################

try:
    # Work out the name of the configuration file.  This is provided as a
    # command line option.

    if len(sys.argv) != 2:
        print("Usage: {0} <yaml-config-file>".format(sys.argv[0]))
        sys.exit(1)

    cfgFile = sys.argv[1]
    
    # We want to start a Kubernetes container.
    os.environ['CONTAINER_SERVICE'] = "kubernetes"

    # Start the IAG container.
    container = Container(config_file=cfgFile)

    container.startContainer(removeAtExit = False)

    print("The container has been started and can be accessed at: "
            "https://{0}:{1}".format(container.ipaddr(), container.port()));

except Exception as exc:
    logger.exception(exc)
    sys.exit(1)