Using the Db2 HADR custom resource

The Db2 HADR custom resource (CR) provides the interface required to configure and start HADR for two databases that are on the same cluster and in the same Red Hat® OpenShift® project.

You can use the Db2 HADR CR to complete the following tasks:

Configure the primary and standby databases

When you set up HADR, you must define a primary and standby database. At a minimum, you must specify the Db2uCluster or Db2uInstance names for both the primary and standby using the db2uName field. You can find these names by using the oc get Db2uCluster or the oc get Db2uInstance command.

You can also define the HADR services and specific endpoints to use for the HADR databases. If the services and endpoints do not exist, they will be created for you.

For example:

primary:
   db2uName: "db2u-oltp-primary"
   service:
     name: "db2u-oltp-primary-hadr-svc"
     port: 60006
standby:
   db2uName: "db2u-oltp-standby"
   service:
     name: "db2u-oltp-standby-hadr-svc"
     port: 60007
Note: Starting for Db2®Operator CSV 110508.0.2, db2uName replaces db2uCluster.

Configure etcd

The Governor service that enables automatic failover of the HADR configuration relies on an etcd key-value store to keep track of the HADR state information, such as the current leader (primary node). A single etcd endpoint must be shared between the two HADR deployments. If these fields are not provided, the default etcd setup is the primary deployment's built-in etcd cluster, but this is meant for development-only environments. Use this setting to define your own etcd cluster.

For example,

etcd: 
   name: "cloud-etc-svc"
   port: 3056

Configure HADR database configuration parameters

When configuring HADR, you can specify the hadr_timeout, hadr_syncmode, and hadr_peer_window configuration parameters. See HADR configuration parameters for more information.

For example:

dbConfig:
   timeOut: 90
   syncMode: "NEARSYNC"
   peerWindow: 120

Configure HADR features

When configuring HADR, you can optionally disable automatic client reroute (ACR) or enable reads on standby. You cannot use automatic client reroute if you enable reads on standby.

Note: Client reroute does not differentiate between writable databases (primary and standard databases) and read-only databases (standby databases). Configuring client reroute between the primary and standby might route applications to the database on which they are not intended to be run.

For example, the following example shows client reroute disabled and reads on standby enabled:

features:
   enableAutomaticClientReroute: false
   enableReadsOnStandby: true

The Db2 s11.5.8.0-cn1 release introduces a new role-aware service feature when configuring HADR by using the Db2uHadr custom resource. When this feature is enabled, an additional Kubernetes service is created when the Db2 Operator configures HADR. This service redirects traffic to the current HADR primary deployment through a label on the pod hadr_role=primary. The Db2 Operator monitors the HADR role of both deployments in the HADR configuration and updates the label accordingly.

Applications can use the new role-aware service for Db2 connections instead of enabling ACR.

Important:
  • Either the ACR or the role-aware service feature can be enabled at one time.
  • Enablement happens only when the Db2uHadr CR is created.
  • In the case of the primary role switching deployments, applications must reconnect to the database by using the same service, to establish a connection to the new primary.
To enable the service, enable the new feature and define the Kubernetes service type that you require. If not defined, the type defaults to ClusterIP:
  features:
    routeToPrimaryService:
      enable: true
      service:
        type: "NodePort"
        name: "my-hadr-svc"
where

  • spec.features.routeToPrimaryService.service.type is the Kubernetes service type.

    Possible options are ClusterIP, which is the default value, NodePort, and LoadBalancer.

  • spec.features.routeToPrimaryService.service.name is the name for the role-aware Kubernetes service. The default value is:
    c-<Db2uHADR CR name>-hadr-primary-svc

  • A Db2 client can connect to the primary database with spec.features.routeToPrimaryService.service.type as the database host name.

Configure HADR advanced options

When configuring HADR with the Db2uHadr CR, the Db2 Operator creates a Kubernetes services for HADR communication between the primary and standby deployments. In some cloud environments, there can be additional networking layers that require the use of Pod FQDN, instead of services, to ensure successful Db2 validation of hostnames and IP addresses. The hostNameResolutionUsingPodFQDN advanced option allows you to configure HADR with Pod FQDN instead of Kubernetes services:
  advancedOptions:
    hostNameResolutionUsingPodFQDN: "True"
Important: At this time, the hostNameResolutionUsingPodFQDN option is only recommended for IBM Cloud environments.

Example of a complete Db2 HADR custom resource definition

The following example shows a complete Db2 HADR custom resource definition:

apiVersion: db2u.databases.ibm.com/v1alpha1
kind: Db2uHadr
metadata:
  name: db2u-oltp-hadr
spec:
  primary:
    db2uName: "db2u-oltp-primary"
    service:
      name: "db2u-oltp-primary-hadr-svc"
      port: 60010
  standby:
    db2uName: "db2u-oltp-standby"
    service:
      name: "db2u-oltp-standby-hadr-svc"
      port: 60012
  etcd:
    name: "cloud-etc-svc"
    port: 3056
  dbConfig:
    timeOut: 90
    syncMode: "NEARSYNC"
    peerWindow: 120
  features:
    enableAutomaticClientReroute: false
    enableReadsOnStandby: true
    routeToPrimaryService:
      enable: true
      service:
        type: "NodePort"
        name: "my-hadr-svc"