IBM Security Identity and Access: Developer PortalSearchSite map
Home / IBM Application Gateway / Deployment / Kubernetes / KubernetesOperator

We Have Moved

The IBM Application Gateway has a new home - docs.verify.ibm.com/gateway

The documentation on this site will no longer be maintained after v21.02, please update your bookmarks.

Kubernetes

IBM Application Gateway (IAG) Kubernetes operator

An IBM Application Gateway instance deployed on Kubernetes is a complex deployment. In particular the configuration can be defined externally in one or more locations and changes to this configuration may require all instances to be reloaded for the changes to take effect. The existing Kubernetes deployment controller does not have any knowledge of how an IBM Application Gateway instance should behave when the configuration changes. As such an IBM Application Gateway specific Kubernetes operator is available to be deployed. Once deployed the operator can manage the lifecycle of the IBM Application Gateway instances.

IBM Application Gateway (IAG) Configuration

There are a few different mechanisms available for defining the IBM Application Gateway configuration in a Kubernetes environment as defined in Kubernetes Deployment. The IBM Application Gateway operator provides a way for the configuration to be defined in more than one location. The multiple locations will be merged into a single config map that will be used by the running IBM Application Gateway instance.

The configuration can be defined in one or more of:

  • A literal definition in the custom object. Use the YAML configuration type entry "literal".
  • A config map reference in the custom object. Use the YAML configuration type entry "configmap".
  • A RESTful web location reference in the custom object. Use the YAML configuration type entry "web".
  • An OIDC dynamic client registration definition in the custom object. Use the YAML configuration type entry "oidc_registration".

This provides the ability to split the ownership of the different parts of the configuration into the various application roles. ie:

  • developers
  • security
  • auditors
  • devops
  • etc

Literal Source

A part or all of the IBM Application Gateway configuration can be defined in the custom object YAML. There can be multiple literal definitions in the same YAML configuration and each will be merged separately. 

apiVersion: ibm.com/v1
kind: IBMApplicationGateway
metadata:
  name: iag-instance
spec:
  configuration:
    - type: literal
      value: |
        version: "21.02"

        resource_servers:
          - path: /app
            connection_type: tcp
            servers:
              - host: 10.0.0.179
                port: 8079

Note: Changes made to the literal configuration will result in the operator being notified and the running IBM Application Gateway instance will be updated automatically.

Config Map Source

If a part or all of the IBM Application Gateway configuration is to be stored in an existing config map the config map must exist prior to creating the custom object. If it does not exist the creation of the IBM Application Gateway instance will fail.

The following definition:

apiVersion: ibm.com/v1
kind: IBMApplicationGateway
metadata:
  name: iag-instance
spec:
  configuration:
    - type: configmap
      name: iag-config
      dataKey: config

Will require an existing config map name "iag-config" and in that config map the data key for the IBM Application Gateway configuration must be "config".

apiVersion: v1
kind: ConfigMap
metadata:
  name: iag-config
data:
  config: |
    ...
    ...

Note: Changes made to a referenced config map will result in the operator being notified and any running IBM Application Gateway instances that reference the changed config map will be updated automatically.

Web Source

If a part or all of the IBM Application Gateway configuration is to be stored in an external web location. The web location must exist and be accessible prior to creating the custom object. If not the creation of the IBM Application Gateway instance will fail.

For a simplistic web location that does not require any authorization or other HTTP headers in the GET request, only the URL is required:

apiVersion: ibm.com/v1
kind: IBMApplicationGateway
metadata:
  name: iag-instance
spec:
  configuration:
    - type: web
      url: https://raw.github.com/iag_config/config.yaml

For a more advanced web location that does require additional information in the form of HTTP headers, the headers must also be defined:

apiVersion: ibm.com/v1
kind: IBMApplicationGateway
metadata:
  name: iag-instance
spec:
  configuration:
    - type: web
      url: https://raw.github.ibm.com/iag/master/config.yaml
      headers:
        - name: Authorization
          type: literal
          value: "Token 2432347234af7897c9877d908098"
        - name: x-ibm-key
          type: secret
          value: my_ibm_secret
          secretKey: secret_value

The above example will add 2 headers to the HTTP GET request:

  1. "Authorization: Token 2432347234af7897c9877d908098". The value for this header is extracted from the literal text in the YAML definition. This must be in clear text and include the full text required for the header value.
  2. "x-ibm-key: ". The value for this header is extracted from a Kubernetes secret named "my_ibm_secret". This secret MUST have the base64 encrypted value with the key that has been specified. For example:
apiVersion: v1
kind: Secret
metadata:
  name: my_ibm_secret
type: Opaque
data:
  secret_value: sdfjhw343412ehajhakhdq3==

For further information on creating a secret see Secrets.

Note: Changes made to any external web config sources will not result in the operator being notified. When changes are made to an external web config source follow the instructions on how to manually notify the operator.

Web Configuration Updates

Changes to either literal or config map configuration sources will result in the IBM Application Gateway operator being notified and the running instances being updated as required. The web source differs in that there is no listener that is notified or checks for changes to the remote configuration. As such if the external web configuration is updated there are 2 manual steps that must be run in Kubernetes for the changes to take effect.

First perform a manual update of any running deployments that reference the external web config:

kubectl rollout restart deployment.apps/<iag-instance>

Optionally update the revision history to add the change cause:

kubectl edit deployment.apps/<iag-instance>

Set the change cause annotation and save:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    kubernetes.io/change-cause: External web config changed.
...
...

OIDC Dynamic Client Registration Source

The IBM Application Gateway can be configured to act as an OIDC relying party. A client must be registered with the OpenID provider (OIDC OP) such that it can be referenced in the configuration. For example:

version: "21.02"
  identity:
    oidc:
      client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
      client_secret: 1a2b3c4d5e
      discovery_endpoint: https://www.test.com/mga/sps/oauth/oauth20/metadata/oidc_def

The OIDC dynamic client registration negates the need for the client to be preregistered in the OIDC OP. Instead during the merging of the configuration sources the operator will make an HTTP call to the OIDC OP to dynamically register the new client.

The following definition:

apiVersion: ibm.com/v1
kind: IBMApplicationGateway
metadata:
  name: iag-instance
spec:
  configuration:
    - type: oidc_registration
      discoveryEndpoint: https://ibm-app-gw.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration
      postData:
        - name: redirect_uris
          values:
            - https://127.0.0.1:30112/pkmsoidc
      secret: oidc-client

will result in the operator:

  1. Calling the OIDC OP to register a new client.
  2. Storing the client ID and secret from the response as data entries in the Kubernetes secret named "oidc-client".
  3. Merging a new OIDC identity configuration entry into the IBM Application Gateway configuration. This will involve either adding a new OIDC identity provider or updating an existing OIDC identity provider (if one has already been defined).

The oidc_registration source will always be handled last by the operator when merging the list of configuration sources. This is to ensure that the newly registered OIDC client is not overwritten by other sources.

For a more detailed explanation of the oidc_registration configuration source see OIDC Dynamic Client Registration.

Example Split Configuration

The following IBM Application Gateway custom object YAML file snippet shows an example of how the configuration is split between different locations

apiVersion: ibm.com/v1
kind: IBMApplicationGateway
metadata:
  name: iag-instance
spec:
  configuration:
    - type: configmap
      name: iag-config
      dataKey: config
    - type: web
      url: https://raw.github.ibm.com/iag/master/config.yaml
      headers:
        - name: Authorization
          type: literal
          value: "Token 2432347234af7897c9877d908098"
    - type: literal
      value: |
        version: "21.02"

        resource_servers:
          - path: /app
            connection_type: tcp
            servers:
              - host: 10.0.0.179
                port: 8079

The config map named "iag-config" is defined as

apiVersion: v1
kind: ConfigMap
metadata:
  name: iag-config
data:
  config: |
    version: "21.02"

    server:
      local_applications:
        cred_viewer:
          path_segment: creds
          enable_html: true

    resource_servers:
      - path: /app2
        connection_type: tcp
        servers:
          - host: 10.0.0.111
            port: 80

The web config (https://raw.github.ibm.com/iag/master/config.yaml) is defined as

version: "21.02"

resource_servers:
  - path: /app3
    connection_type: tcp
    servers:
      - host: 10.0.0.111
        port: 80

The different sources of configuration are handled (in the order they are defined in the custom object YAML file) and merged with the previous defined configuration to create a final master config map that is used by the IBM Application Gateway instance

apiVersion: v1
data:
  config.yaml: |
    version: "21.02"

      resource_servers:
        - path: /app
          connection_type: tcp
          servers:
            - host: 10.0.0.179
              port: 8079
        - path: /app2
          connection_type: tcp
          servers:
            - host: 10.0.0.111
             port: 80
        - path: /app3
          connection_type: tcp
          servers:
            - host: 10.0.0.111
              port: 80

      server:
        local_applications:
          cred_viewer:
            path_segment: creds
            enable_html: true

The name of the new master config map is derived from the IBM Application Gateway instance name. For example if the instance name is iag-instance, a new master config map will be created with the name iag-instance-config-iag-internal-generated9rdnh.

Note that the merging is performed in order. If duplicate entries are defined in more than one location, the final location will contain the value that will be created in the master configuration. The only exception to this is when the entries are array entries. In this case the final merged config will contain all of the configured entries. For example see the resource_server entries in the previous example.

Warning: If multiple sources each define the same array entries, this may result in the merged config being invalid and the IBM Application Gateway instances failing to start.

Deployment

The IBM Application Gateway operator in essence is made up of 2 components:

  1. The custom resource definition
  2. The controller application

Each of these needs to be deployed into the Kubernetes environment before the operator can function.

Note: This section describes how to manually deploy the IBM Application Gateway operator. Another option is to use the Operator Lifecycle Manager and OperatorHub.io to automatically deploy and manage the operator. For details on this see OperatorHub.

Custom Resource Definition

The following YAML file (iag-crd.yaml) contains the Custom Resource Definition for the IBM Application Gateway operator. 

apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: ibmapplicationgateways.ibm.com
spec:
  group: ibm.com
  names:
    kind: IBMApplicationGateway
    listKind: IBMApplicationGatewayList
    plural: ibmapplicationgateways
    singular: ibmapplicationgateway
  scope: Namespaced
  subresources:
    status: {}
    scale:
      # specReplicasPath defines the JSONPath inside of a custom resource that corresponds to Scale.Spec.Replicas.
      specReplicasPath: .spec.replicas
      # statusReplicasPath defines the JSONPath inside of a custom resource that corresponds to Scale.Status.Replicas.
      statusReplicasPath: .status.replicas
      # labelSelectorPath defines the JSONPath inside of a custom resource that corresponds to Scale.Status.Selector.
      labelSelectorPath: .status.labelSelector
  validation:
    openAPIV3Schema:
      description: IAG is the Schema for the iags API
      properties:
        apiVersion:
          description: 'APIVersion defines the versioned schema of this representation
            of an object. Servers should convert recognized schemas to the latest
            internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
          type: string
        kind:
          description: 'Kind is a string value representing the REST resource this
            object represents. Servers may infer this from the endpoint the client
            submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
          type: string
        metadata:
          type: object
        spec:
          description: IAGSpec defines the desired state of IAG.
          type: object
          properties:
            replicas:
              type: integer
              description: The number of IBM Application Gateway replicas to create.
            deployment:
              type: object
              description: Defines the IBM Application Gateway deployment properties. 
              properties:
                image:
                  description: The name, tag and location of the IBM Application Gateway docker image.
                  type: string
                imagePullPolicy:
                  description: The policy used to decide when to pull the IBM Application Gateway docker image from a remote server. Default value is IfNotPresent.
                  type: string
                  enum:
                    - Never
                    - Always
                    - IfNotPresent
                imagePullSecrets:
                  type: array
                  description: A list of Kubernetes secrets that will be set on the IBM Application Gateway deployment.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: The name of the Kubernetes secret that defines the required remote server authentication credentials.
                    required:
                      - name
                serviceAccountName:
                  description: The Kubernetes service account that will run the IBM Application Gateway applications.
                  type: string
                lang:
                  description: The language for the IBM Application Gateway application. Default value is English (en).
                  type: string
                readinessProbe:
                  type: object
                  description: The settings for the readiness probe.
                  properties:
                    initialDelaySeconds:
                      description: The initial delay (in seconds) before starting the IBM Application Gateway application readiness poll. Default value is 0. Minimum value is 0.
                      type: integer
                      minimum: 0
                    periodSeconds:
                      description: The wait period (in seconds) between IBM Application Gateway application readiness polling. Default value is 10. Minimum value is 1.
                      type: integer
                      minimum: 1
                    failureThreshold:
                      description: The number of times the probe will be tried before failing. Failure will result in the Pod will be marked Unready. Default value is 3. Minimum value is 1. 
                      type: integer
                      minimum: 1
                    successThreshold:
                      description: The number of consecutive successes for the probe to be considered successful after having failed. Default value is 1. Minimum value is 1. 
                      type: integer
                      minimum: 1
                    timeoutSeconds: 
                      description: The number of seconds after which the probe times out. Default value is 1. Minimum value is 1.
                      type: integer
                      minimum: 1
                livenessProbe:
                  type: object
                  description: The settings for the liveness probe.
                  properties:
                    initialDelaySeconds:
                      description: The initial delay (in seconds) before starting the IBM Application Gateway application liveness poll. Default value is 0. Minimum value is 0.
                      type: integer
                      minimum: 0
                    periodSeconds:
                      description: The wait period (in seconds) between IBM Application Gateway application liveness polling. Default value is 10. Minimum value is 1.
                      type: integer
                      minimum: 1
                    failureThreshold:
                      description: The number of times the probe will be tried before failing. Failure will result in the container being restarted. Default value is 3. Minimum value is 1. 
                      type: integer
                      minimum: 1
                    timeoutSeconds: 
                      description: The number of seconds after which the probe times out. Default value is 1. Minimum value is 1.
                      type: integer
                      minimum: 1
              required:
                - image
            configuration:
              type: array
              description: Defines the IBM Application Gateway configuration properties.
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - configmap
                      - literal
                      - web
                      - oidc_registration
                  name:
                    type: string
                    description: The name of the config map that contains the IBM Application Gateway configuration. Required for configmap type.
                  dataKey:
                    type: string
                    description: The config map YAML entry that contains the IBM Application Gateway configuration. Required for configmap type.
                  value:
                    type: string
                    description: The IBM Application Gateway configuration YAML text. Required for literal type.
                  url:
                    type: string
                    description: The URL location of the remote IBM Application Gateway configuration. Required for web type.
                  discoveryEndpoint:
                    type: string
                    description: The discovery endpoint used to retrieve the OIDC OP registration endpoint to dynamically register a new client. Required for oidc_registration type.
                  postData: 
                    type: array
                    description: A list of keys and values that will be added to the registration request as POST data. This must include the mandatory redirect_uris value. Required for oidc_registration type.
                    items:
                      type: object
                      properties:
                        name: 
                          type: string
                          description: The key name of the data value to add to the request.
                        value: 
                          type: string
                          description: A single data value to add to the request. If this property is specified the values property will be ignored. Required if the values property has not been specified.
                        values:
                          type: array
                          description: A list of data values to add to the request as an array. If the value property has been specified this property will be ignored. Required if the value property has not been specified.
                          items:
                            type: string
                      required:
                        - name
                  secret:
                    type: string
                    description: The name of a Kubernetes secret that contains any authorization data required for the OIDC client registration. The resulting client_id and secret will also be added to this secret. Required for oidc_registration type.
                  headers:
                    type: array
                    description: A list of headers to add to the HTTP request to retrieve the configuration source.
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The value type. A literal type will add the value directly to the new header. A secret type will lookup a Kubernetes secret to retrieve the value.
                          enum:
                            - literal
                            - secret
                        name:
                          type: string
                          description: The name of the header that will be added to the HTTP request.
                        value:
                          type: string
                          description: The value of the header that will be added to the HTTP request. If the type is set as secret this will be the name of the Kubernetes secret.
                        secretKey:
                          type: string
                          description: The key name to retrieve the header value from the specified Kubernetes secret. Required if the type is set as secret.
                      required:
                        - type
                        - name
                        - value
                required:
                  - type
        status:
          description: IAGStatus defines the observed state of IAG
          type: object
      type: object
  version: v1
  versions:
  - name: v1
    served: true
    storage: true

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

kubectl apply -f iag-crd.yaml

Controller Application

Once the Custom Resource Definition has been created the controller application must be deployed. The controller application once deployed will listen for any changes to either:

  1. Deployed custom objects of the IBMApplicationGateway kind; and/or
  2. Config maps that are referenced in the IBM Application Gateway configuration in the IBMApplicationGateway custom objects

Changes to either of these may result in the reloading of any impacted IBM Application Gateway pods.

The IBM Application Gateway (IAG) Kubernetes operator image is available from the Docker Hub repository: ibmcom/ibm-application-gateway-operator.

To deploy the controller application into Kubernetes the following steps should be followed:

  1. Create the controller service account
  2. Create the controller role binding
  3. Create the controller deployment

Controller Service Account

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/.

The IBM Application Gateway operator uses "ibm-application-gateway-operator" as the service account for the controller deployment.

The following YAML file (iag-operator-serviceaccount.yaml) contains the service account data

apiVersion: v1
kind: ServiceAccount
metadata:
  name: ibm-application-gateway-operator

The following command can be used to create the service account from this file:

kubectl apply -f iag-operator-serviceaccount.yaml

Controller Role Binding

Role-based access control (RBAC) is a method of regulating access to computer or network resources based on the roles of individual users within your organization. Information on the usage of RBAC can be found in the official Kubernetes documentation: https://kubernetes.io/docs/reference/access-authn-authz/rbac/

The IBM Application Gateway operator requires the service account be granted access to a number of Kubernetes resources.

The following YAML file (iag-operator-rbac.yaml) contains the rbac data. The first portion creates the role and the second portion maps the service account to the new role.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  creationTimestamp: null
  name: ibm-application-gateway-operator
rules:
- apiGroups:
  - ""
  resources:
  - pods
  - services
  - services/finalizers
  - endpoints
  - persistentvolumeclaims
  - events
  - configmaps
  - secrets
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - apps
  resources:
  - deployments
  - deployments/status
  - daemonsets
  - replicasets
  - statefulsets
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - monitoring.coreos.com
  resources:
  - servicemonitors
  verbs:
  - get
  - create
- apiGroups:
  - apps
  resourceNames:
  - ibm-application-gateway-operator
  resources:
  - deployments/finalizers
  verbs:
  - update
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - get
- apiGroups:
  - apps
  resources:
  - replicasets
  - deployments
  verbs:
  - get
- apiGroups:
  - ibm.com
  resources:
  - '*'
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch

---  

kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: ibm-application-gateway-operator
subjects:
- kind: ServiceAccount
  name: ibm-application-gateway-operator
- kind: ServiceAccount
  name: ibm-application-gateway  
roleRef:
  kind: Role
  name: ibm-application-gateway-operator
  apiGroup: rbac.authorization.k8s.io

The following command can be used to create the role and role binding from this file:

kubectl apply -f iag-operator-rbac.yaml

Controller Deployment

The final step in deploying the controller application is to create the controller deployment. Once the deployment has been created in Kubernetes the controller will start managing any IBM Application Gateway custom objects.

The following YAML file (iag-operator.yaml) defines the controller application

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ibm-application-gateway-operator
spec:
  replicas: 1
  selector:
    matchLabels:
      name: ibm-application-gateway-operator
  template:
    metadata:
      labels:
        name: ibm-application-gateway-operator
    spec:
      serviceAccountName: ibm-application-gateway-operator
      containers:
        - name: ibm-application-gateway-operator
          image: ibmcom/ibm-application-gateway-operator:21.02.0
          command:
          - ibm-application-gateway-operator
          imagePullPolicy: IfNotPresent
          env:
            - name: WATCH_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: OPERATOR_NAME
              value: "ibm-application-gateway-operator"

The following command can be used to create the controller deployment from this file:

kubectl apply -f iag-operator.yaml

Custom Object

To this point the Kubernetes environment changes and deployments have been to create the IBM Application Gateway operator (custom resource definition and controller). The next step is to create any required IBM Application Gateway custom objects. Each of these custom objects once created in Kubernetes will result in an IBM Application Gateway deployment being created by the operator.

Warning: Prior to creating the custom object in Kubernetes ensure that any referenced secrets, configmaps or external web sources exist.

The following YAML file (iag-instance.yaml) contains an example custom object data

apiVersion: ibm.com/v1
kind: IBMApplicationGateway
metadata:
  name: iag-instance
spec:
  replicas: 3
  deployment:
    serviceAccountName: ibm-application-gateway
    image: ibmcom/ibm-application-gateway:21.02.0 
    imagePullPolicy: IfNotPresent 
  configuration:
    - type: configmap
      name: iag-config
      dataKey: config
    - type: literal 
      value: |
        version: "21.02"
        resource_servers:
          - path: /app
            connection_type: tcp
            servers:
              - host: 10.0.0.179
                port: 8079

The YAML file must include:

  1. The kind set as IBMApplicationGateway. This will result in the IBM Application Gateway operator being notified of any changes to this object.
  2. The image. This is the location and version of the IBM Application Gateway image used to create new pods. If the image location requires authorization details for access these can be added as a Kubernetes secret and the secret reference added here using the imagePullSecrets field. For information on creating a secret see Secrets
  3. The configuration for the IBM Application Gateway instances. As stated previously the configuration can be defined in one or more different locations.

The following command can be used to create the custom object from this file:

kubectl apply -f iag-instance.yaml

Note: Ensure that the ibm-application-gateway service account has been created before creating the custom object above.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: ibm-application-gateway
kubectl apply -f iag_service_account.yaml

Custom Object changes

The IBM Application Gateway custom objects are constantly being monitored by the controller. Any significant changes will result in the running pods being reloaded with the new configuration.

Note that in this context a reload of an IBM Application Gateway application means a rolling update of each running pod. The running pods will not be deleted until a new replacement pod with the changes has been created and is available. In this way there will be no disruption to service. If the update fails the existing pods will remain running.

The following changes to custom objects are considered significant resulting in a pod reload (any other changes will require a manual reload if desired):

  1. Replica count
  2. Language
  3. Service Account
  4. Literal configuration definition
  5. Changes to a referenced config map
  6. Upgrading an IBM Application Gateway instance by changing the image location

Changing Replica Count

To change the number of replicas for a running IBM Application Gateway application:

  1. Modify the YAML file for the required custom object by setting the replicas entry to the desired number
  2. Apply the changes:
kubectl apply -f iag-instance.yaml

At this point the controller should apply the change by creating/removing pods as required.

Changing Language

To change the language that the IBM Application Gateway error messages are displayed:

  1. Modify the YAML file for the required custom object by setting the lang entry 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
  1. Apply the changes:
kubectl apply -f iag-instance.yaml

At this point the controller should apply the change by reloading each running pod.

Changing the Service Account

To change the Kubernetes service account that the IBM Application Gateway application is running as:

  1. Ensure that the new service account exists in Kubernetes
  2. Modify the YAML file for the required custom object by setting the serviceAccountName entry to the desired value
  3. Apply the changes:
kubectl apply -f iag-instance.yaml

At this point the controller should apply the change by reloading each running pod.

Changing the Literal Configuration

To change the literal configuration that the IBM Application Gateway application is using:

  1. Modify the YAML file for the required custom object by setting the literal configuration entry to the desired value
  2. Apply the changes:
kubectl apply -f iag-instance.yaml

At this point the controller should apply the change by reloading each running pod.

Remember that for multiple configuration entries the sources are merged to produce a master configuration. This merging is done in the order that they are defined. Changes to an earlier configuration source may NOT result in an actual change if a later source defines the same entry.

Changing a Referenced Config Map

To change the configuration that the IBM Application Gateway application is using from a referenced config map:

  1. Modify the YAML file for the config map with the desired changes
  2. Apply the changes:
kubectl apply -f iag-config.yaml

At this point the controller should apply the change by reloading each running pod.

Remember that for multiple configuration entries the sources are merged to produce a master configuration. This merging is done in the order that they are defined. Changes to an earlier configuration source may NOT result in an actual change if a later source defines the same entry.

Upgrading an IBM Application Gateway instance by changing the image location

To upgrade a running IBM Application Gateway instance, change the image location:

  1. Modify the YAML file for the required custom object by setting the image location entry to the desired value
  2. Apply the changes:
kubectl apply -f iag-instance.yaml

At this point the controller should apply the change by recreating each running pod with the new image.

Secrets

A Kubernetes secret may be required for the following:

  1. Providing the authorization data for connecting to a docker repository to download the IBM Application Gateway operator and application images.

Example:

kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>
  1. Providing the header value for any external web configuration sources. The value must be base64 encoded.

Example

First base64 encode the header value

echo -n 'Token dfhdhsfg34534jhkafhawk4hrw4' | base64

Next create the secret YAML definition with the result of the base64 encoded value

apiVersion: v1
kind: Secret
metadata:
  name: githubsecret
type: Opaque
data:
  value: VG9rZW4gZGZoZGhzZmczNDUzNGpoa2FmaGF3azRocnc0==

Finally create the secret

kubectl apply -f githubsecret.yaml

Revision History

The IBM Application Gateway operator defines any custom resources as Kubernetes deployments. This means that the deployment rollout history is also maintained. When deployment updates are made the operator will tag the replica set with the reason for the change.

To view the revision history:

kubectl rollout history deployment.apps/<iag-instance>

deployment.apps/iag-instance
REVISION  CHANGE-CAUSE
1         <none>
2         Configuration change
3         Image changed from "x" to "y"
4         Service account changed from "x" to "y"
5         Language changed from en to fr

The following deployment roll back operation is not supported for the operator deployment.

kubectl rollout undo deployment.apps/iag-instance

The stored revision history only saves the deployment settings. The operator deployment uses the IBM Application Gateway custom resource settings and one or more config maps. These are not maintained as part of the revision history and as such any roll back will attempt to revert to the previous deployment but the operator will update the deployment based upon the custom object and config maps.

Deleting an IBM Application Gateway Custom Resource

If an existing deployment of an IBM Application Gateway custom resource is no longer required the custom resource should be deleted.

kubectl delete IBMApplicationGateways/<instance_name>

This will delete from Kubernetes:

  1. The custom resource
  2. The running IBM Application Gateway instance deployment
  3. The running IBM Application Gateway instance pods
  4. The current and saved IBM Application Gateway instance replica sets
  5. The master merged IBM Application Gateway config map

Troubleshooting

There are various ways to try and find any issues with the IBM Application Gateway operator or the deployment instances that are created for custom resources.

  1. Operator logs
kubectl logs --follow pod/ibm-application-gateway-operator-7ff6bcffb8-m25g5

Look for any errors or log entries that define what has happened.

  1. IBM Application Gateway instance logs
kubectl logs --follow pod/iag-instance3-75bf746b7c-kmzfx

Look for any errors or log entries that define what has happened.

  1. Check the operator deployment
kubectl get deployment.apps/ibm-application-gateway-operator -o yaml

The status section may contain event data showing errors.

  1. Check the operator pod
kubectl get pod/ibm-application-gateway-operator-5cd8589ff9-h9jrc -o yaml

The status section may contain event data showing errors.

  1. Check the custom object deployment
kubectl get deployment.apps/iag-instance -o yaml

The status section may contain event data showing errors.

  1. Check the custom object pod
kubectl get pod/iag-instance3-75bf746b7c-kmzfx -o yaml

The status section may contain event data showing errors.

  1. Check the master merged config map
kubectl get configmaps/iag-instance-config-iag-internal-generated -o yaml

Check that the generated configuration is as expected.