Skip to main contentIBM DataPower Operator Documentation

Domain Configuration

The DataPower Operator supports managing DataPower configuration through the domains property on the DataPowerService Custom Resource. This allows for independent management of each application domain on the DataPower Gateway.

The Domains Definition

The following snippet of the DataPowerService Custom Resource contains all fields relevant to domains, filled with example values.

domains:
- name: "default"
certs:
- certType: "usrcerts"
secret: "default-cert"
- certType: "sharedcerts"
secret: "shared-cert"
dpApp:
config:

domains

domains is a list of DataPower Domains that should be configured. Domains are comprised of name, certs, and configMethod fields. For a Domain to be created, a configuration method must be defined. The supported methods are:

  • dpApp - Domain configuration via config and local ConfigMaps.

name

The name field is just that: the name of the domain. This will propagate into the pod and be the name of the resultant DataPower Domain.

certs

certs is a list of all certificate, key, or general crypto files that need to be dropped into a Domain. There are two fields for each item in the certs list:

certType

Defines the type of cert. The accepted values are usrcerts and sharedcerts. A usrcerts type will apply only to the specific Domain. A sharedcerts type will be available to all Domains. The best practice for sharedcerts types is to associate them with the default domain, but this is not required.

secret

Defines the name of the Kubernetes or OpenShift secret containing the crypto files. This secret can contain any number of certificates.

subPath

Defines the SubPath to place the cert into. This field is optional, and only allowed if certType is usrcerts. The provided SubPath must be a relative path, and will be appended to the domain’s directory path. If not included or left empty, the cert will not be placed in a subpath. An example would be dir1/dir2.

Creating a Secret

To create a secret containing your crypto information, use:

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

Or alternatively, for a TLS secret:

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

passphraseSecret

Optionally, a passphraseSecret property can be provided for use in decrypting password-alias objects within the DataPower configuration. The value of this property must be the name of a Kubernetes Secret in the same namespace.

The Secret must contain a literal property, passphrase, which contains the passphrase to use in the domain-settings object within the DataPower domain configuration. When this passphraseSecret property is provided, the DataPower Operator will generate a domain-settings object for the configured domain, with the provided passphrase, such that any password-alias objects in the domain configuration can be decrypted and used for service implementation.

Example Secret creation named default-passphrase with passphrase datapower:

oc create secret generic default-passphrase --from-literal=passphrase=datapower

Specifying this in a domains spec would look like:

domains:
- name: "default"
passphraseSecret: "default-passphrase"
dpApp:
config:
- "default-config"
local:
- "default-local"

For more details on the domain-settings and passphrase configurations, see the following IBM Documentation:

Config Method: dpApp

dpApp is a basic configuration method for the DataPower operand. It takes two ConfigMap arrays:

config

  • Array of ConfigMaps containing DataPower configuration file(s).
  • At least one ConfigMap must be provided for config.

Each ConfigMap specified in config must be a ConfigMap created directly from standard DataPower config file(s).

kubectl create configmap domain-config --from-file=/path/to/domain.cfg

You can also specify multiple config files, which will all be used to build the ConfigMap, and thus be applied to the same target Domain:

kubectl create configmap domain-config \
--from-file=/path/to/domain-config-pt1.cfg \
--from-file=/path/to/domain-config-pt2.cfg \
--from-file=/path/to/domain-config-pt3.cfg

Depending on your use-case, you can either create the ConfigMap from multiple files, or create a ConfigMap for each config part, and list each ConfigMap in the config array. For example:

spec:
domains:
- name: "test-domain"
dpApp:
config:
- "domain-config-pt1"
- "domain-config-pt2"
- "domain-config-pt3"

local

  • Array of ConfigMaps each containing a tarball of local files to be used by the Domain.
  • This value is optional.

Each ConfigMap specified in local must be a ConfigMap created from a tarball containing local files for the Domain. The expectation is that the tarball contains the top-level files and directories you expect to be placed in the local:/// directory of the targeted domain.

kubectl create configmap domain-local --from-file=/path/to/domain-local.tar.gz

The contents of each tarball are expanded and then copied into the Domain’s local:/// filesystem.

Example

This example shows the complete end-to-end flow for creating all resources necessary to configure a domain via the dpApp configuration method.

Starting with a testdomain structure as follows:

$ ls
testdomain
$ tree
.
`-- testdomain
|-- config
| `-- testdomain.cfg
`-- local

Create the config ConfigMap from the cfg file:

kubectl create configmap testdomain-config \
--from-file=/path/to/testdomain/config/testdomain.cfg

Create a tarball for the local files:

tar --directory=/path/to/testdomain/local -czvf testdomain-local.tar.gz .

The created tarball should have the local file(s) at the top-level:

$ tar -tzvf testdomain-local.tar.gz
drwxrwxr-x admin/admin 0 2020-04-09 15:37 ./
-rw-rw-r-- admin/admin 14 2020-04-09 15:27 ./test.xsl

Create the local ConfigMap from the tarball:

kubectl create configmap testdomain-local \
--from-file=/path/to/testdomain-local.tar.gz

DataPowerService snippet with domains spec for the testdomain:

spec:
domains:
- name: "testdomain"
dpApp:
config:
- "testdomain-config"
local:
- "testdomain-local"

Once deployed via the DataPower Operator, the config and local files could be validated from the DataPower CLI.

To attach to a given DataPower Pod:

kubectl -n namespace attach -it pod/name -c datapower

From the DataPower CLI (once logged in):

idg# config
idg(config)# switch testdomain
idg[testdomain](config)# dir local:
File Name Last Modified Size
--------- ------------- ----
test.xsl Apr 9, 2020 3:54:03 PM 14
227782.0 MB available to local:

Updating Domains

As described above, Domains are comprised of ConfigMaps and Secrets that exist in the k8s cluster. It is expected that over time a Domain configuration will need to be updated, including the config and local ConfigMaps and Secrets that comprise the serts for the Domain. These ConfigMaps and Secrets can be updated in-place in the cluster, and the DataPower Operator will automatically reconcile those changes.

When an update is detected on a ConfigMap or Secret referenced by a Domain, a rolling update is triggered across the Pods in the StatefulSet. This allows for Domains to be updated without modifying the DataPowerService Custom Resource directly.

For example, if we define the following Domain spec:

spec:
domains:
- name: "testdomain"
certs:
- certType: "usrcerts"
secret: "testdomain-certs"
dpApp:
config:
- "testdomain-config"

We could then update any of the following objects by deleting them in the cluster and recreating them with the same name:

  • secret/testdomain-certs
  • configmap/testdomain-config
  • configmap/testdomain-local

The StatefulSet will include annotations that provide timestamps for the last time a particular domain was modified or reconciled. You can see these by describing the StatefulSet resource in the cluster:

apiVersion: apps/v1
kind: StatefulSet
metadata:
...
spec:
...
template:
metadata:
annotations: