Pre-deployment configuration

Edit online

After you verify that the prerequisites are met, create an OpenShift project or a Kubernetes namespace, and create the necessary secrets.

Note: All commands must be executed from the main node of a cluster, i.e master, bastion, API node, etc.

I. Create a project or namespace

Edit online

OpenShift® projects or Kubernetes namespaces are used to logically group pods for the application. It is recommended to use a separate Kubernetes namespace or a separate OpenShift project for Z APM Connect Distributed Gateway for higher security and better organization. You can name the project or namespace anything, but for examples below, the project or namespace name ibm-zapm is used.

Create a project or namespace by using the following command for your environment.

OpenShift project:
```
oc new-project ibm-zapm
```
Kubernetes namespace:
```
kubectl create namespace ibm-zapm
```

To use kubectl, you need to specify a namespace for all commands using the following pattern:

     kubectl -n <namespace name>

Tip: To switch Kubernetes to a default namespace, you can use the following command:

    kubectl config set-context --current --namespace=<namespace name>

This will allow you to omit the -n <namespace name> flag in subsequent kubectl commands.

Important: The examples in the documentation will be provided only using Kubernetes unless otherwise stated. Still, you can execute the equivalent commands in Openshift by replacing the Kubernetes executable kubectl with oc.

II. Create secrets for z/OS facing components of Z APM Connect DG

Edit online

OpenShift or Kubernetes secrets are used to store passwords, tokens, and certificates securely. Before installation, add the correct secrets to the project or namespace.

Create secrets for the z/OS® facing components of the Z APM Connect Distributed Gateway.

If TLS will not be used or if custom TLS termination will be used, skip to Step 3 to create secrets for connectivity to your APM tool.

After the necessary truststore and keystore files are generated and transferred to the installation machines, run the following command to create the Secrets:

kubectl create secret generic <secret name> \
 --from-file=keystore.jks \
 --from-file=truststore.jks \
 --from-literal=truststore-pass=<pass> \
 --from-literal=keystore-pass=<pass> \
 --from-literal=key-pass=<pass>

Note: The truststore and keystore must be named truststore.jks and keystore.jks for the Connection Manager, and kafka.truststore.jks and kafka.keystore.jks for Kafka.

For example, for Kafka:

  kubectl create secret generic kafka-auth \
   --from-file=kafka.keystore.jks \
   --from-file=kafka.truststore.jks \
   --from-literal=truststore-pass=tpass1 \
   --from-literal=keystore-pass=kpass1 \
   --from-literal=key-pass=kpass1

For the Connection Manager:

  kubectl create secret generic ingress-auth \
   --from-file=keystore.jks \
   --from-file=truststore.jks \
   --from-literal=truststore-pass=tpass1 \
   --from-literal=keystore-pass=kpass1 \
   --from-literal=key-pass=kpass1

(Optional) If you plan to use Kafka Internal TLS, the server certificates (the server certificate used in the kafka.keystore.jks file) should have a DNS entry representing the hostname of the Kafka internal service. For example, if using the helm or Kubernetes manifest files, there should be a DNS entry with kafka-internal-svc as the hostname.

III. Create secrets for connectivity to your APM tool

Edit online

OpenTelemetry secrets

If using TLS to communicate with the OpenTelemetry Collector, a secret with the Collector's public certificate will need to be created.

Run the following command to create the OpenTelemetry Collector secret:

kubectl create secret generic <secret name> --from-file=<public cert name>

Note: Ensure that the security.otel.certName (Helm) parameter is set to match the name of the certificate provided.

IV. Create a secret for authenticating with an External Private Registry

Edit online

In Openshift or Kubernetes, an image pull secret is necessary when accessing an external private registry that requires authentication to download images. The following method shows how to create the image pull secret using Docker. Additional information on creating this secret can be found in the official Kubernetes documentation.

To create the registry secret, execute the following command:

kubectl create secret docker-registry <secret-name> --docker-server=<your-registry-server-FQDN> --docker-username=<your-username>  --docker-password=<your-password>

For example:

kubectl create secret docker-registry regcred --docker-server=my-docker-image-registry.com --docker-username=my-username@registry.com --docker-password=mypassword

V. Create a secret for adding password protection to your Redis Database

Edit online

A crucial component of the Z APM Connect Distributed Gateway relies on a Redis Database. To enhance the security of your application, you need to restrict database access only to authorised users with the appropriate password.

To add password protection to your Redis Database, create a secret by executing the following command. Choose a password with a length of 12 characters or more to ensure it is sufficiently robust to resist brute force attacks.

Note: Make sure you use the key redis_password for your password.

kubectl create secret generic <secret-name> --from-literal=redis_password=<password>

For eample:

kubectl create secret generic redis-auth --from-literal=redis_password=password

VI. Verify the secrets

Edit online

To double check that all the secrets are in your OpenShift project or Kubernetes namespaces, run the following command:

kubectl get secrets

Output should resemble the following:

    NAME                         TYPE                                  DATA   AGE
    ingress-auth                 Opaque                                5      3m50s
    kafka-auth                   Opaque                                5      2m14s
    otel-auth                    Opaque                                1      112s
    redis-auth                   Opaque                                1      1m