domains
Description
The domains
property allows for user-provided domain configuration(s) to be injected into the DataPower pods at runtime, prior to the DataPower process starting.
For an in-depth look at utilizing this property, please see Domain Configuration.
Each domains
entry can consist of the following fields:
name
(required)certs
(optional)dpApp
(optional)settings
(optional)passwordMap
(optional)passphraseSecret
(deprecated)
name
The name of the domain. This field is required, and must be unique among domains
; in other words, you cannot specify more than one entry in the domains
list which have the same name
.
certs
certs
is a list of all certificate, key, or general crypto files that need to be added to the domain. Each certs
entry can have the following fields:
certType
Defines the type of cert. This field is required, and must be one of: usrcerts
or sharedcerts
.
- A cert with type
usrcerts
will be available only to this domain. - A cert with type
sharedcerts
will be available to all domains.
Note: The best practice for sharedcerts
is to define them in the default
domain, but this is not required.
secret
Defines the name of the Kubernetes or OpenShift Secret containing the crypto files. This field is required. This secret can contain any number of certificates, and must exist in the same namespace as the DataPowerService.
subPath
Defines a relative subdirectory path to place the cert files into. This field is optional, and only allowed if certType
is usrcerts
. The provided path must be a relative path, and will be appended to the domain's
cert:///
directory path. If not included or left empty, the cert will be placed at the root of the domain's cert:///
directory.
Example
domains:
- name: "example"
certs:
- certType: "usrcerts"
secret: "example-tls"
subPath: "service/tls"
If the Secret example-tls
contains tls.key
and tls.crt
files, they would be placed into the example
domain's cert:///
directory as follows:
cert:///service/tls/tls.key
cert:///service/tls/tls.crt
Without the subPath
definition, they would be placed here:
cert:///tls.key
cert:///tls.crt
For more examples, see Adding certs to a domain.
dpApp
dpApp
is a basic abstraction of a domain's configuration and local files using ConfigMaps. It consists of two arrays:
For an end-to-end guide in configuring a domain with dpApp
, see Configuring a domain with dpApp.
config
config
is optional. If provided, each entry in the array must be the name of a ConfigMap that exists in the same namespace as the DataPowerService.
Each ConfigMap in the config
array must contain DataPower configuration file(s), i.e. .cfg
files.
Using a single config file and ConfigMap
kubectl create configmap example-config --from-file=/path/to/example.cfg
domains:
- name: "example"
dpApp:
config:
- "example-config"
Using multiple config files in one ConfigMap
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 example-config \
--from-file=/path/to/example-config-pt1.cfg \
--from-file=/path/to/example-config-pt2.cfg \
--from-file=/path/to/example-config-pt3.cfg
Using multiple ConfigMaps
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:
kubectl create configmap example-config-pt1 --from-file=/path/to/example-pt1.cfg
kubectl create configmap example-config-pt2 --from-file=/path/to/example-pt2.cfg
kubectl create configmap example-config-pt3 --from-file=/path/to/example-pt3.cfg
spec:
domains:
- name: "example"
dpApp:
config:
- "example-config-pt1"
- "example-config-pt2"
- "example-config-pt3"
local
local
is optional. If provided, each entry in the array must be the name of a ConfigMap that exists in the same namespace as the DataPowerService.
Each ConfigMap in the local
array must contain one or more compressed tarball (.tar.gz
) files. The contents of each tarball will be extracted and placed into the local:///
directory of the domain.
kubectl create configmap example-local --from-file=/path/to/example-local.tar.gz
Note: If the same file/path exists in more than one ConfigMap or tarball for the same domain, the resulting file will be overwritten by the last ConfigMap or tarball to provide that file.
spec:
domains:
- name: "example"
dpApp:
config:
- "example-config"
local:
- "example-local"
settings
settings
is an abstraction for the DataPower domain-settings
configuration object. Currently it supports the following fields:
passphrase
passphrase
controls the domain-settings
passphrase
, and supports both user-provided and generated values.
Within the passphrase
object are two properties:
secret
- user-provided Secret name, which must contain thepassphrase
generate
- boolean, if true will generate a value for thepassphrase
These properties are mutually exclusive, meaning that only one may be provided.
User-provided Secret
If providing your own Secret for the passphrase
, the Secret must contain a literal passphrase
which contains the value to use for the passphrase
in the domain-settings
object.
For example, this creates a Secret named default-passphrase
with passphrase datapower
:
oc create secret generic default-passphrase --from-literal=passphrase=datapower
The below snippet shows how this Secret could be configured for use in the default
domain:
spec:
domains:
- name: default
settings:
passphrase:
secret: default-passphrase
Generated Secret
If generate
is true
, then the DataPower Operator will generate a cryptographically secure passphrase
value, and then create a Secret containing this passphrase
as a literal for use in the
DataPower configuration.
spec:
domains:
- name: default
settings:
passphrase:
generate: true
If you need to obtain the generated passphrase
value, you can retrieve it from the Secret using oc extract
. The DataPowerService status
object contains a list of generated
resources as
a reference. For example, using the above snippet, the status
would show something like:
status:
generated:
- context:
domain: default
path: domains[0].settings.passphrase
kind: Secret
name: default-passphrase
For more details on this status
object, see status.
Reference
For more details on the domain-settings
and passphrase
configurations, see the following IBM Documentation:
passwordMap
passwordMap
controls the domain's password map, allowing for password-alias
objects to be created from Secrets. passwordMap
is an array, where each entry corresponds to a single password-alias
object that will be created in the domain's configuration. Each entry has the following properties:
Similar to the domain's settings.passphrase
configuration, the secret
and generated
fields for a passwordMap
entry are mutually exclusive, meaning only one may be provided.
In both cases, the value of the password
provided by the Secret is encrypted in the password map using the domain's settings.passphrase
.
alias
alias
is the name to use when creating the password-alias
object in the DataPower configuration. This will be the alias that is used elsewhere in the DataPower configuration.
secret
If provided, secret
must be the name of a Secret in the same namespace. The Secret must contain a literal password
, with the value containing the password to use in the password-alias
.
For example, the following creates a Secret named example-password
with password datapower
:
oc create secret generic example-password --from-literal=password=datapower
The below snippet shows how this Secret could be added to the default
domain's passwordMap
:
spec:
domains:
- name: default
passwordMap:
- alias: example
secret: example-password
generated
If generated
is true
, then a cryptographically secure password will be generated and stored in a Secret for use in the password-alias
object.
spec:
domains:
- name: default
passwordMap:
- alias: example
generated: true
If you need to obtain the generated password
value, you can retrieve it from the Secret using oc extract
. The DataPowerService status
object contains a list of generated
resources as a reference.
For example, using the above snippet, the status
would show something like:
status:
generated:
- context:
alias: example
domain: default
path: domains[0].passwordMap[0]
kind: Secret
name: default-example
For more details on this status
object, see status.
Reference
For more details on the domain-settings
and password map configuration, see the following IBM Documentation:
passphraseSecret
(DEPRECATED)
Note: passphraseSecret
is deprecated (as of version 1.6.7
). Use settings.passphrase
instead.
passphraseSecret
is an optional property to enable 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.
For more details on the domain-settings
and passphrase
configurations, see the following IBM Documentation:
Example
Creating a Secret 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"