Kubernetes

The IBM Application Gateway (IAG) image is available from IBM Cloud Container Registry: icr.io/ibmappgateway/ibm-application-gateway:23.04

See Software Downloads > Containers for more information.

Environments

The following Kubernetes environments have been validated using the IAG image:

RedHat OpenShift

Information on managing an IAG container in an OpenShift environment is available from the RedHat OpenShift page.

IBM Cloud

The IBM cloud container service provides advanced capabilities for building cloud-native apps, adding DevOps to existing apps, and relieving the pain around security, scale, and infrastructure management. Further information can be obtained from the IBM Cloud Web site: https://www.ibm.com/cloud/container-service

To set the context for the kubectl utility use the IBM Cloud CLI to obtain the kubectl configuration file:

## Log into IBM Cloud.
ibmcloud login -sso

## Obtain the list of available cluster.
ibmcloud ks clusters

## Show the details of the cluster.
ibmcloud ks workers <cluster-name>

## Create the kubectl configuration file.
ibmcloud ks cluster config <cluster-name>

## Set the kubectl configuration file.
export KUBECONFIG=<kube-config-yaml-file>

Microsoft Azure Container Registry

Azure Container Service (AKS) manages your hosted Kubernetes environment, making it quick and easy to deploy and manage containerized applications without container orchestration expertise. It also eliminates the burden of ongoing operations and maintenance by provisioning, upgrading, and scaling resources on demand, without taking your applications offline. Further information can be obtained from the Microsoft Azure AKS Web Site: https://docs.microsoft.com/en-us/azure/aks/

To set the context for the kubectl utility use the Microsoft Azure CLI:

az aks get-credentials --resource-group <group-name> --name <cluster-name>

Google Cloud Platform

Google Cloud Platform lets you build and host applications and websites, store data, and analyze data on Google's scalable infrastructure. Further information can be obtained from the Google Cloud Web Site: https://cloud.google.com/kubernetes-engine/

To set the context for the kubectl utility use the Google Cloud CLI:

gcloud container clusters get-credentials <cluster-name>

Minikube

Minikube is a tool that makes it easy to run Kubernetes locally. Minikube runs a single-node Kubernetes cluster inside a VM on your laptop for users looking to try out Kubernetes or develop with it day-to-day. Further information can be obtained from the Minikube Web site: https://kubernetes.io/docs/getting-started-guides/minikube/

To set the context for the kubectl utility use the following command:

kubectl config use-context minikube

Configuration

There are two mechanisms by which the IAG container can read configuration information:

1. From YAML files contained in the '/var/iag/config' directory of the container;
2. From a Custom Object which has been created and is available in the Kubernetes environment.

File based configuration

The configuration for the container can be supplied as one or more YAML files, along with other potential supporting files (e.g. PEM certificate files). When the container first starts it will apply the configuration found within the local '/var/iag/config' directory. As such the configuration for the container will need to be placed in this directory before the container is started. This can be achieved in one of two ways:

1. Pre-baking the configuration into a new image which is based on the IAG image. A Dockerfile which can be used to create a pre-baked image is shown below:

##
## You can build this image by issuing the following command:
##          docker build -t acme-iag:1.0 $PWD
##

## The container is based on the IAG container.
FROM icr.io/ibmappgateway/ibm-application-gateway:23.04

## Copy the configuration files from the config directory
## to the docker image.
COPY config/* /var/iag/config/

## Some labels which will be associated with the image.
LABEL maintainer="[email protected]" \
    vendor="ACME"

2. Placing the configuration information into a Kubernetes ConfigMap and then creating a volume mount which will mount this ConfigMap to the '/var/iag/config' directory in the pod. Information on creating and managing a Kubernetes ConfigMap can be found at: https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/. If, for example, the configuration is contained in a file called iag-config.yaml the following command can be used to create a ConfigMap which contains this file:

kubectl create configmap iag-config --from-file=iag-config.yml

Custom Object based configuration

The IAG container is also able to retrieve the configuration information from a Custom Object. This Custom Object must be based on an IAG specific Custom Resource Definition. Information on how to create and manage a custom resource definition can be found at: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/.

Custom Resource Definition

The following YAML file (iag-crd.yaml) contains the Custom Resource Definition for the IAG image.

apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition

metadata:

  #
  # The full identifying name for this custom resource definition, 
  # constructed from the 'plural' and 'group' data.
  #

  name: ibm-application-gateway.security.ibm.com 

spec:
  #
  # The group name and version information to be used in the Rest API.
  #

  group: security.ibm.com 
  version: v1 

  #
  # This custom resource definition is restricted to the current Kubernetes
  # namespace.
  #

  scope: Namespaced

  #
  # The names associated with this custom resource definition.
  #
  
  names:
    plural: ibm-application-gateway
    kind: ibm-application-gateway

  #
  # The validation rules for the data contained with a custom object
  # of this type.  Please note that to keep things simple this
  # only currently includes the top level nodes for the IAG configuration YAML.
  #

  validation:
    openAPIV3Schema:
      type: object
      properties:
        spec:
          type: object
          properties:
            advanced:
              type: object
            resource_servers:
              type: array
            authorization:
              type: object
            identity:
              type: object
            logging:
              type: object
            server:
              type: object
            version:
              type: string

Please note:

• For the sake of brevity and clarity the schema only includes the definition of the top level configuration nodes. A custom resource definition which contains a full schema definition is available from the IAG resources GitHub repository.
• The IAG Custom Resource Definition must have the following properties:

The following command can be used to create the Custom Resource Definition from this file:

kubectl create -f iag-crd.yaml

Custom Object

Once the Custom Resource Definition has been created it is then possible to create a Custom Object which embeds the configuration for an IAG instance. An example Custom Object definition is illustrated in the following YAML file (iag-co.yaml):

apiVersion: "security.ibm.com/v1"
kind: ibm-application-gateway

metadata:
  #
  # The identifying name for this custom object.
  #
  name: iag-configuration

spec:
  #
  # The IAG configuration data.
  #
  version: "23.04"
  
  server:
    ssl:
      front_end:
        certificate: 
          - B64:LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1.....
  identity:
    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"

Please note:

• The YAML configuration for the IAG container resides at the 'spec' YAML node. At this point it will mirror the standard IAG configuration.
• A Custom Object cannot reference external files. This means that if the IAG configuration relies on an external file (e.g. a certificate file) it should be base-64 encoded and then added directly to the Custom Object.
• The Custom Object must have the following properties:

The following command can be used to create the Custom Object from this file:

kubectl create -f iag-co.yaml

Custom Object Identification

The IAG container, when starting, will look for the name of a Custom Object in the 'CONFIG_CUSTOM_OBJECT_NAME' environment variable. If this environment variable is defined the IAG container will attempt to load the configuration from the corresponding Custom Object, otherwise it will load the configuration from the files contained within the '/var/iag/config' directory on the file system.

The following YAML snippet illustrates how to reference the 'iag-configuration' Custom Object when deploying an IAG container:

apiVersion: apps/v1
kind: Deployment

spec:
  ...

  template: 
    ...

    spec:
      ...

      containers:
        - name: iag

          ...
          
          # Environment definition - used to set the Custom Object which
          # holds the configuration information.
          env:
            - name: CONFIG_CUSTOM_OBJECT_NAME
              value: iag-configuration   
              
          ...

Service Accounts

Service accounts can be used to provide an identity for processes that run in a Pod. Information on the usage of service accounts can be found in the official Kubernetes documentation: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/.

In the example that is provided within this document, the deployment descriptor uses the ‘iag’ service account. The kubectl utility can be used to create the ‘iag’ service account (ensure that the kubectl context is set to the correct environment before running this command):

kubectl create serviceaccount iag

Language

In order to display the IAG error messages in a language other than English the 'LANG' environment variable should be set to one of the following:

Deployment

In order to deploy a running IAG container in a Kubernetes environment a deployment descriptor must first be created. The following deployment YAML file (iag-deployment.yaml) contains an example deployment definition which references a pre-created ConfigMap for the configuration information:

## 
## A demo deployment description for the IAG container.  This deployment
## descriptor has dependencies on a configmap (iag-config) which contains 
## the configuration files.
##

apiVersion: apps/v1
kind: Deployment

metadata:
  name: iag
  labels:
    app: iag

spec:
  selector:
    matchLabels:
      app: iag

  replicas: 1

  template: 
    metadata:
      labels:
        app: iag

    spec:
      # The name of the service account which has the required
      # capabilities enabled for the IAG container.
      serviceAccountName: iag
      
      # We use a configmap volume to store the configuration data.
      volumes:
        - name: iag-config
          configMap:
            name: iag-config

      containers:
        - name: iag

          # The fully qualified name of the IAG image.
          image: icr.io/ibmappgateway/ibm-application-gateway:23.04
          
          # Environment definition - used to set the language.
          env:
            - name: LANG
              value: C   
              
          # Mount our configmap volume to the expected configuration directory
          # for IAG.
          volumeMounts:
            - name: iag-config
              mountPath: /var/iag/config

          # The liveness and readiness probes are used by Kubernetes 
          # to obtain the health of the container.  Our health is 
          # governed by the ability to connect to the IAG server.
          readinessProbe:
            exec:
              command:
              - /sbin/health_check.sh
            initialDelaySeconds: 5
            periodSeconds: 10

          livenessProbe:
            exec:
              command:
              - /sbin/health_check.sh
            initialDelaySeconds: 120
            periodSeconds: 20 

The Kubernetes pod can then be created using the following kubectl command:

kubectl create -f iag-deployment.yaml

You can monitor the bootstrapping of the pod using the 'logs' option to the kubectl command:

kubectl logs -f `kubectl get -o json pods -l app=iag | jq -r .items[0].metadata.name`

Service

The IAG container will expose a single port for each protocol which is enabled for the server. For the HTTPS protocol the 8443 port is exposed, and for the HTTP protocol the 8080 port is exposed. To make this port available from outside of the Kubernetes cluster a new service must be created. The following YAML file (iag-service.yaml) contains an example service definition:

## 
## The service description of the IAG service.  
##

apiVersion: v1
kind: Service

metadata:
  name: iag

spec:
  ports:
    - port: 8443
      name: iag
      protocol: TCP
      nodePort: 30443

  selector:
    app: iag

  type: NodePort

The service definition can then be created using the following kubectl command:

kubectl create -f iag-service.yaml

Supported Tags