At this stage, ensure each keytab has a unique, pod-specific filename (for example, -pod0, -pod1) to prevent accidental mix-ups.
oc cp db2inst1-pod0.keytab c-db2u-cr-db2u-0:/mnt/blumeta0/db2inst1-pod0.keytab
Step 2: Move the Keytab into the Correct Pod
Exec into the target pod and move the appropriate keytab from the shared directory into the pod-specific Kerberos directory.
The correct destination path inside the pod is:
${SYSCFGDIR}/kerberos/${POD_NAME}
Both ${SYSCFGDIR} and ${POD_NAME} are predefined environment variables within the pod.
oc exec -it c-db2u-cr-db2u-0 -- /bin/bash
sudo cp /mnt/blumeta0/db2inst1-pod0.keytab ${SYSCFGDIR}/kerberos/${POD_NAME}/db2inst1.keytab
Important: Each keytab must be renamed to db2inst1.keytab once in the respective directory, as this filename is required by the Db2 Kerberos configuration.
Avoiding Errors
Before proceeding to the next pod or step, confirm that:
This can be done by following “Testing before making Permanent Changes”. This validation helps prevent subtle configuration issues later during Kerberos authentication testing.
Testing before making Permanent Changes
The following steps allow you to validate the krb5.conf file and service keytabs before applying permanent configuration changes.
Although these steps are not strictly necessary, this validation is strongly recommended, as once registry values, dbmConfig settings, and ConfigMaps are applied via the Db2U Custom Resource, the configuration becomes persistent and more difficult to roll back. This is particularly important for large clusters with many pods.
This should be done before "Patching the Custom Resource".
Preparation
-
Place the krb5.conf at /etc/krb5.conf on the head pod. This temporarily overrides the default example configuration and allows you to test Kerberos behavior without making permanent changes. This is not persistent and will return to default if the pod restarts.
-
Place the keytab for this pod in the correct location by following the steps in the section "Placing Keytabs on Pod".
Validation Steps
Log in to the pod as the db2inst1 user and perform the following checks to confirm that:
1. Verify the Keytab Contents
klist -kt ${SYSCFGDIR}/kerberos/c-db2u-cr-db2u-0/db2inst1.keytab
Keytab name: FILE:db2inst1.keytab
KVNO Timestamp Principal
---- ------------------- ------------------------------------------------------
12 01/01/1970 00:00:00 db2inst1/c-db2u-cr-db2u-0.c-db2u-cr-db2u.internal.db2.svc.cluster.local@ADS.IBM.BLOG.IE
Confirm that the principal listed exactly matches the expected SPN for the pod.
2. Obtain a Kerberos Ticket Using the Keytab
kinit -kt ${SYSCFGDIR}/kerberos/c-db2u-cr-db2u-0/db2inst1.keytab db2inst1/c-db2u-cr-db2u-0.c-db2u-cr-db2u.internal.db2.svc.cluster.local@ADS.IBM.BLOG.IE
If successful, no output is displayed.
3. Verify the Ticket Cache
Ticket cache: FILE:/tmp/krb5cc_500
Default principal: db2inst1/c-db2u-cr-db2u-0.c-db2u-cr-db2u.internal.db2.svc.cluster.local@ADS.IBM.BLOG.IE
Valid starting Expires Service principal
08/25/2025 09:04:57 08/25/2025 19:04:57 krbtgt/ ADS.IBM.BLOG.IE@ADS.IBM.BLOG.IE
renew until 08/26/2025 09:04:57
This confirms that the KDC has issued a valid Ticket Granting Ticket (TGT).
Repeat steps 1–3 for each pod-specific keytab.
Common Errors During Testing
Failures at this stage typically indicate issues with authentication, SPN naming, or Kerberos configuration.
SPN Naming Mismatch
The most common issue is that the hostname used in the SPN does not match the pod’s fully qualified hostname.
Verify the hostname inside the pod:
Ensure this value exactly matches the hostname used in:
Keytab Mapping Issues
Patching the Custom Resource
Apply the Custom Resource (CR) patch only after all of the following are true:
Important: Once applied, these changes make the Kerberos configuration persistent.
Creating the Patch File
Save the following as “patch_configurations.json” on the Red Hat OpenShift client/bastion node:
{"spec": {
"environment": {
"instance": {
"registry": {
"DB2AUTH": "OSAUTHDB,ALLOW_LOCAL_FALLBACK",
"DB2ENVLIST": "KRB5_KTNAME"
},
"dbmConfig": {
"SRVCON_GSSPLUGIN_LIST": "IBMkrb5",
"SRVCON_AUTH": "KRB_SERVER_ENCRYPT",
"CLNT_KRB_PLUGIN": "IBMkrb5",
"AUTHENTICATION": "SERVER_ENCRYPT"
}
}
},
"volumeSources": [
{
"visibility": [
"db2u"
],
"volumeSource": {
"configMap": {
"name": "db2u-krb5-config-cm"
}
}
}
]
} }
Applying the Patch
Apply the patch to the deployed Db2uInstance Custom Resource:
oc patch db2 db2u-cr --type=merge --patch "$(cat patch_configurations.json)"
This operation first applies the instance configuration changes (which take a minute or two) and then causes all the pods to be restarted.
Kerberos configuration is complete once all pods return to a “Ready” state.
Common Issues After Applying the Patch
Pods Repeatedly Restarting or Stuck in Not Ready
This behavior usually indicates an error in one or more permanent configuration values, such as:
If manual Kerberos testing was successful prior to patching, the problem is typically in the CR patch itself. Compare the applied Custom Resource with patch_configurations.json and correct any discrepancies.
Pods Ready but Kerberos Authentication Fails
If pods are running but Kerberos authentication does not work, check the following:
Verify each pod independently, as keytab or SPN issues may affect only a subset of pods.
Backing Out of Kerberos Configuration
Kerberos authentication can be disabled on an existing deployment by updating the Custom Resource and reverting the Kerberos-related database manager and registry settings.
Step 1: Update the Database Manager Configuration
Edit the Db2U Custom Resource and update the following properties under the instance.dbmConfig block:
instance:
dbmConfig:
AUTHENTICATION: "SERVER_ENCRYPT"
CLNT_KRB_PLUGIN: "NULL"
SRVCON_AUTH: "NOT_SPECIFIED"
SRVCON_GSSPLUGIN_LIST: "NULL"
These settings remove Kerberos-based authentication from the server-side connection configuration, ensuring that incoming connections are no longer authenticated using Kerberos.
Step 2: Remove Kerberos Registry Settings
Under the instance.registry block, delete the following properties:
DB2AUTH: OSAUTHDB,ALLOW_LOCAL_FALLBACK
DB2ENVLIST: KRB5_KTNAME
Step 3: Save and Apply the Changes
Save the updated Custom Resource.
Once the instance is Ready again, Kerberos authentication is fully disabled, and Db2U reverts to non-Kerberos authentication behavior.
Important: Do not remove the volumeSource for the db2u-krb5-config-cm ConfigMap when disabling Kerberos.
Optionally, keytabs can be removed from under /mnt/blumeta0/SystemConfig/kerberos.
Key Terms
Service Principal (SP)
An identity representing a specific Db2 service. In this blog, the database pod running on the Db2U server is treated as the service principal. Each service principal must be registered with the KDC and associated with a unique keytab.
Service Principal Name (SPN)
A Kerberos-formatted string that uniquely identifies a service instance. In Db2U, the SPN includes the Db2 instance name and the fully qualified hostname of the pod.
Key Distribution Center (KDC)
A trusted authentication service that issues Kerberos tickets and validates user and service credentials. Examples include MIT Kerberos and Active Directory.
Ticket Granting Ticket (TGT)
A timestamped, encrypted Kerberos ticket issued by the KDC after initial authentication. The TGT is used by clients to request service tickets.
Client / User
The entity (a person, application, or service) requesting access to network resources. In a Db2U environment, this may be a database user, a JDBC application, or another service connecting to Db2.
Realm
An administrative domain under which Kerberos authentication is managed. A realm defines the scope of trust and typically maps to an organization or DNS domain (for example, an Active Directory domain).
Keytab File
A secure file containing one or more Kerberos principals and their encrypted secret keys. Keytabs allow services, such as Db2 pods, to authenticate to the KDC without manual password entry.
For more detailed information, refer to MIT Kerberos Documentation.
About the Authors
Tara Acheson is a Software Developer in Hybrid Data Management at IBM’s Ireland Lab,
focusing on containerized Db2 offerings. She holds two master’s degrees from University
College Dublin in Computer Science and Scientific Research. Tara can be reached at
tara.acheson@ibm.com
John Bell is a Distinguished Engineer and Data Warehouse Architect at IBM, with over 25 years
of experience in data warehousing and analytics. He has played a pivotal role in developing
IBM's data warehouse solutions, including IBM’s Power10 Private Cloud Rack reference
architecture. He can be reached at john.bell@ibm.com.
Austin Clifford is a Senior Technical Staff Member in Hybrid Data Management based in the
Ireland Lab. He has worked with database, data lake and warehousing technologies for more
than two decades. In 2012, Austin led the team to achieve a Guinness World Record for the
Largest Data Warehouse, a record that IBM held for two years. Austin has authored numerous
papers and patents, advises clients on data warehouse, analytics and containerization best
practices and is a regular speaker at technical conferences. He can be reached at
acliffor@ie.ibm.com.