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:
- From YAML files contained in the '/var/iag/config' directory of the container;
- 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:
- 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"
- 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:
Property | Value |
---|---|
name | ibm-application-gateway.security.ibm.com |
version | v1 |
kind | ibm-application-gateway |
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:
Property | Value |
---|---|
apiVersion | security.ibm.com/v1 |
kind | ibm-application-gateway |
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:
Value | Language |
---|---|
pt | Brazilian Portuguese |
cs | Czech |
zh_CN | Chinese (Simplified) |
zh_TW | Chinese (Traditional) |
C | English |
fr | French |
de | German |
hu | Hungarian |
it | Italian |
ja | Japanese |
ko | Korean |
pl | Polish |
es | Spanish |
ru | Russian |
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
Tag | Purpose |
---|---|
YY.MM | A particular release, of the format: {year}.{month}. For example 23.04 . |
YY.MM.R | A particular revision of a release, of the format: {year}.{month}.{revision} For example 23.04.0 . |
Updated 5 months ago