Red Hat® OpenShift®
Red Hat® OpenShift® is an enterprise-ready Kubernetes container platform with full-stack automated operations to manage hybrid cloud and multicloud deployments.
Repository
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.
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 OpenShift 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 a number of ways, as outlined below.
ConfigMap
The configuration information can be copied into an OpenShift ConfigMap. A volume mount can then be used to mount this ConfigMap to the '/var/iag/config' directory in the pod. Information on creating and managing an OpenShift ConfigMap can be found at: https://docs.openshift.com/container-platform/3.11/dev_guide/configmaps.html.
If, for example, the configuration information is contained in a file called iag-config.yaml the following command can be used to create a ConfigMap which contains this file:
oc create configmap iag-config --from-file=iag-config.yml
OpenShift Build
The configuration can be built into a new Docker image which is based on the IAG image. Information on OpenShift builds can be obtained from the official OpenShift documentation: https://docs.openshift.com/container-platform/3.11/dev_guide/builds/index.html.
The following steps should be completed to define and create a custom build which contains the configuration information:
- Create the build definition. An example build definition (iag-build.yaml) is provided below:
kind: "BuildConfig"
apiVersion: "v1"
metadata:
# The name which will be given to our build.
name: "iag-sample-build"
spec:
runPolicy: "Serial"
# The source is obtained from the ibm-application-gateway-resources GitHub
# repository. It simply contains a Dockerfile which will be used to create
# a new image from the IAG image, and will embed a sample configuration
# within this image.
source:
git:
uri: "https://github.com/IBM-Security/ibm-application-gateway-resources"
contextDir: "openshift/build-sample"
# Create the new image using the 'docker build' command.
strategy:
dockerStrategy:
forcePull: false
# The built image will pushed be to the iag-sample-build stream
# in the OpenShift integrated registry.
output:
to:
kind: "ImageStreamTag"
name: "iag-sample-build:latest"
The build definition can then be created using the following command:
oc create -f iag-build.yaml
- Create the image stream which will hold the build:
oc create imagestream iag-sample-build
- Allow the image stream to be referenced during deployment:
oc set image-lookup iag-sample-build
- Start the build:
oc start-build iag-sample-build
Once the build has completed a new image will be available in the OpenShift integrated registry. This build can be referenced within a deployment using the 'iag-sample-build:latest' image name.
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 (CRD). Information on how to create and manage a CRD can be found at: https://docs.openshift.com/container-platform/3.11/admin_guide/custom_resource_definitions.html.
Custom Resource Definition
The following YAML file (iag-crd.yaml) contains the CRD 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 CRD which contains a full schema definition is available from the ibm-application-gateway-resources GitHub repository.
- The IAG CRD must have the following properties:
Property | Value |
---|---|
name | ibm-application-gateway.security.ibm.com |
version | v1 |
kind | ibm-application-gateway |
- Only cluster admins can create CRDs. This means that the user who is creating the CRD must have the 'cluster-admin' role. The following command shows how to add the 'cluster-admin' role to the 'my-admin' user:
oc adm policy add-cluster-role-to-user cluster-admin my-admin --as=system:admin
The following command can then be used to create the CRD from this file:
oc create -f iag-crd.yaml
Custom Object
Once the CRD has been created it is then possible to create a Custom Object which embeds the configuration for an IAG instance.
In order to be able to create a custom object the user must first be given permission to create custom objects for this CRD. The following YAML file (iag-crd-role.yaml) will define two new roles. One which will allow custom objects to be managed, and another which will allow read-only access to a created custom object:
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: aggregate-ibm-app-gateway-crd-edit
labels:
rbac.authorization.k8s.io/aggregate-to-admin: "true"
rbac.authorization.k8s.io/aggregate-to-edit: "true"
rules:
- apiGroups: ["security.ibm.com"]
resources: ["ibm-application-gateway"]
verbs:
- "get"
- "list"
- "watch"
- "create"
- "update"
- "patch"
- "delete"
- "deletecollection"
---
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: aggregate-ibm-app-gateway-crd-view
labels:
rbac.authorization.k8s.io/aggregate-to-view: "true"
rules:
- apiGroups: ["security.ibm.com"]
resources: ["ibm-application-gateway"]
verbs:
- "get"
- "list"
- "watch"
The 'aggregate-ibm-app-gateway-crd-edit' role should then be added to the user who will be creating and managing the custom object, for example:
oc adm policy add-cluster-role-to-user aggregate-ibm-app-gateway-crd-edit my-user --as=system:admin
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:
oc 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://docs.openshift.com/container-platform/3.11/dev_guide/service_accounts.html.
In the example that is provided within this document, the deployment descriptor uses the ‘iag’ service account. The 'oc' command can be used to create the ‘iag’ service account:
oc create serviceaccount iag
If you are using a Custom Object to pass configuration information to the container the service account must also be granted read access to the Custom Object. This can be achieved by adding the 'aggregate-ibm-app-gateway-crd-view' role to the service account user, for example:
oc policy add-role-to-user aggregate-ibm-app-gateway-crd-view -z 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 |
Template
An OpenShift template describes a set of objects that can be parameterized and processed to produce a list of objects for creation by the OpenShift Container Platform. A template can be used to define how to deploy an instance of the IAG container. Further information on templates can be found in the official OpenShift documentation: https://docs.openshift.com/container-platform/3.11/dev_guide/templates.html.
The following YAML file (iag-template.yaml) depicts a template definition for the IAG:
apiVersion: v1
kind: Template
## Metadata associated with this template (for example, the template name)
metadata:
name: ibm-app-gateway
annotations:
openshift.io/display-name: IBM Application Gateway
iconClass: icon-sso
description: >-
The IBM Application Gateway (IAG) provides a containerized secure Web
Reverse proxy which is designed to sit in front of your application,
seamlessly adding authentication and authorization protection to your
application.
objects:
## Our deployment definition, which is used to describe the IAG container.
- apiVersion: apps/v1
kind: Deployment
# Matadata associated with the container.
metadata:
annotations:
deployment.kubernetes.io/revision: "1"
generation: 1
labels:
app: ${APP_NAME}
name: ${APP_NAME}
spec:
replicas: ${REPLICAS}
progressDeadlineSeconds: 600
revisionHistoryLimit: 10
selector:
matchLabels:
app: ${APP_NAME}
# The strategy used to replace old Pods by new ones.
strategy:
rollingUpdate:
maxSurge: 1
maxUnavailable: 1
type: RollingUpdate
# Details associated with the creation of an IAG container.
template:
metadata:
labels:
app: ${APP_NAME}
spec:
# The name of the service account which has the required
# capabilities enabled for the IAG container.
serviceAccountName: ${SERVICE_ACCOUNT}
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchExpressions:
- key: app
operator: In
values:
- ${APP_NAME}
topologyKey: kubernetes.io/hostname
containers:
- name: ${APP_NAME}
env:
# The language to be used for console error messages.
- name: LANG
value: ${LANGUAGE}
#### Start of Custom Object section.
# The name of the custom object which holds our configuration
# information.
# - name: CONFIG_CUSTOM_OBJECT_NAME
# value: ${CUSTOM_OBJECT}
#### End of Custom Object section.
# The fully qualified name of the IAG image.
image: icr.io/ibmappgateway/ibm-application-gateway:${IAG_VERSION}
# The ports on which the IAG container will be listening for
# requests.
ports:
- containerPort: 8443
protocol: TCP
resources: {}
terminationMessagePath: /dev/termination-log
terminationMessagePolicy: File
# 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.
livenessProbe:
exec:
command:
- /sbin/health_check.sh
initialDelaySeconds: 120
periodSeconds: 10
readinessProbe:
exec:
command:
- /sbin/health_check.sh
initialDelaySeconds: 5
periodSeconds: 10
#### Start of ConfigMap section.
# The volume which contains the IAG configuration data.
volumeMounts:
- mountPath: /var/iag/config
name: ${APP_NAME}-config
#### End of ConfigMap section.
#### Start of ConfigMap section.
# The config map which contains the IAG configuration data.
volumes:
- name: ${APP_NAME}-config
configMap:
name: ${CONFIG_MAP}
#### End of ConfigMap section.
# Sundry spec configuration data.
dnsPolicy: ClusterFirst
restartPolicy: Always
schedulerName: default-scheduler
terminationGracePeriodSeconds: 30
## The route which is used to access the IAG service. The route will be based
## on the supplied DNS name.
- apiVersion: v1
kind: Route
metadata:
name: ${APP_NAME}
labels:
app: ${APP_NAME}
spec:
host: ${DNS_NAME}
port:
targetPort: ${APP_NAME}
tls:
insecureEdgeTerminationPolicy: Redirect
termination: passthrough
to:
kind: Service
name: ${APP_NAME}
weight: 100
wildcardPolicy: None
## The service which is used to access the runtime interface of the IAG pod.
- apiVersion: v1
kind: Service
metadata:
name: ${APP_NAME}
labels:
app: ${APP_NAME}
spec:
externalTrafficPolicy: Cluster
ports:
- name: ${APP_NAME}
port: 443
protocol: TCP
targetPort: 8443
selector:
app: ${APP_NAME}
sessionAffinity: ClientIP
sessionAffinityConfig:
clientIP:
timeoutSeconds: 10800
type: NodePort
status:
loadBalancer: {}
## Configuration parameters associated with this template.
parameters:
- description: The name which will be given to the IBM Application Gateway application.
name: APP_NAME
value: iag
- description: The IAG version/tag which is to be deployed.
name: IAG_VERSION
value: "23.04"
- description: The fully qualified DNS name which will be used for routing.
name: DNS_NAME
value: ibm-app-gw.ibm.com
- description: The service account which will be used when running the pod.
name: SERVICE_ACCOUNT
value: iag
- description: The language in which the console error messages will be displayed.
name: LANG
value: C
- description: The number of replicas of the application to create.
name: REPLICAS
value: "1"
#### Start of ConfigMap section.
- description: The ConfigMap which holds the configuration of the container.
name: CONFIG_MAP
value: iag-config
#### End of ConfigMap section.
#### Start of Custom Object section.
# - description: The name of the Custom Object which holds the configuration of the container.
# name: CUSTOM_OBJECT
# value: iag-config
#### End of Custom Object section.
Please note:
- The template currently assumes that a ConfigMap will be used to hold the configuration information.
- If a Custom Object will be used to hold the configuration information:
- Uncomment the 'Custom Object' sections;
- Remove the 'ConfigMap' sections.
- If the configuration is built into a new Docker image:
- Remove the 'ConfigMap' and 'Custom Object' sections;
- Replace the IAG image name with the image name of the custom build.
The following command can be used to create the template from this file:
oc create -f iag-template.yaml
Deployment
An instance of the IAG can be deployed using:
- The IAG template which has previously been created. Instructions on how to deploy using the template can be found in the official OpenShift documentation: https://docs.openshift.com/container-platform/3.11/dev_guide/templates.html#creating-from-templates-using-the-web-console;
- The 'oc create' command, referencing a standard Kubernetes deployment and service descriptor. An example deployment and service descriptor is available in the Kubernetes deployment page of the IAG documentation.
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