Domain Configuration

Creating a generic Secret

To create a generic secret containing your crypto information, use:

kubectl create secret generic <my-crypto-secret> \
  --from-file=/path/to/cert \
  --from-file=/path/to/key

Adding the Secret to certs

domains:
- name: "example"
  certs:
  - certType: "usrcerts"
    secret: "<my-crypto-secret>"

Creating a TLS Secret

To create a tls Secret containing a TLS key / cert pair, use:

kubectl create secret tls <my-tls-secret> \
  --key=/path/to/my.crt \
  --cert=/path/to/my.key

Adding the Secret to certs

domains:
- name: "example"
  certs:
  - certType: "usrcerts"
    secret: "<my-tls-secret>"

Batching multiple updates

A potential complication created by the reconciliation of Domain resources described above is that making changes to multiple ConfigMaps and/or Secrets may inadvertently trigger multiple rolling updates and, thus, cause unnecessary churn among the DataPower Pods.

To avoid this, we can use the DataPowerService's pause annotation to temporarily pause reconciliation while we make changes to the ConfigMaps and Secrets used by the DataPowerService Custom Resource. Once all changes have been made, we remove the pause annotation to restart reconciliation and, thus, rollout out all the changes in a single update.

For example, suppose we have a DataPowerService Custom Resource with configuration provided by multiple ConfigMaps, such as one that defines multiple domains:

apiVersion: datapower.ibm.com/v1beta3
kind: DataPowerService
metadata:
  name: example-dpservice
spec:
  domains:
  - name: appdomain1
    dpApp:
      config:
      - appdomain1-config
  - name: appdomain2
    dpApp:
      config:
      - appdomain2-config

Now suppose we wish to make changes to each domain's configuration. If we modify the appdomain1-config ConfigMap and then the appdomain2-config ConfigMap, even within a few seconds of each other, we will most likely see a rolling update for each updated ConfigMap, i.e., each DataPower pod would updated twice rather than just once.

But to batch the changes, we can use kubectl edit to manually add the pause annotation to the DataPowerService. Or, for convenience, we may use the kubectl patch command to add the pause annotation without manually editing the DataPowerService Custom Resource like so:

# Pause DataPowerService reconciliation
kubectl -n $KUBE_NAMESPACE patch dp $DPSERVICE_NAME --type='merge' -p='{"metadata":{"annotations":{"datapower.ibm.com/pause":"true"}}}'

However we add the pause annotation, we should now see datapower.ibm.com/pause: "true" under the DataPowerService Custom Resource's annotations:

apiVersion: datapower.ibm.com/v1beta3
kind: DataPowerService
metadata:
  annotations:
    datapower.ibm.com/pause: "true"
  name: example-dpservice
spec:
  domains:
  - name: appdomain1
    dpApp:
      config:
      - appdomain1-config
  - name: appdomain2
    dpApp:
      config:
      - appdomain2-config

We can confirm that reconciliation is paused by observing the ReconciliationPausedWarning condition on the DataPowerService status:

status:
  conditions:
  - lastTransitionTime: "2023-06-05T18:40:30Z"
    message: Reconciliation is paused indefinitely
    reason: ReconciliationPausedIndefinitely
    status: "True"
    type: ReconciliationPausedWarning

At this point we may make changes to as many ConfigMaps and Secrets referenced by the DataPowerService's Domains without triggering a rolling update.

Once we have finished, we can remove the pause annotation to resume reconciliation. Again, we can use kubectl patch:

# Resume DataPowerService reconciliation
kubectl -n $KUBE_NAMESPACE patch dp $DPSERVICE_NAME --type='json' -p='[{"op": "remove", "path": "/metadata/annotations/datapower.ibm.com~1pause"}]'

We should now see that the pause annotation has been removed:

apiVersion: datapower.ibm.com/v1beta3
kind: DataPowerService
metadata:
  name: example-dpservice
spec:
  domains:
  - name: appdomain1
    dpApp:
      config:
      - appdomain1-config
  - name: appdomain2
    dpApp:
      config:
      - appdomain2-config

Once reconciliation has resumed, all of the changes will be rolled out in a single update.