Pre-deployment configuration

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

Important: If you're using fix pack 2 or earlier, follow the instructions in Pre-deployment configuration

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

I. Find required configuration information for Instana

The Z APM Connect Distributed Gateway sends data to Instana through the serverless ingestion endpoint. The best way to find the necessary credentials to enable the product are through the AWS Lambda agent configuration tab, which can be found as follows:

  • INSTANA_ENDPOINT_URL and INSTANA_AGENT_KEY are required, which can be found from the following steps with a user that has Agent download and agent key visibility and Configuration of agents permissions in Instana:

    1. Sign in to Instana and click ...More > Agents > Install Agents > AWS.

    2. From the Technology list, select AWS Lambda.

IMPORTANT: Don't simply copy the endpoint from the Instana agent.

  • For on-premises Instana servers: when TLS is used to secure the connection between the Z APM Connect distributed Gateway and the Instana server, it is likely that the server certificate is either self-signed or signed by a private Certificate Authority (CA). Therefore, it is necessary to import a PEM encoded version of that server certificate to the Z APM Connect Distributed Gateway.

  • If certificates are used, permissions of certificate must allow global read access. This can be achieved with the following command:

    chmod 444 cert-file-name.pem

II. Create a project or namespace

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.

III. Create secrets for z/OS facing components of Z APM Connect DG (if TLS is used)

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 4 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

Note: 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.

IV. Create secrets for connectivity to your APM tool

Instana secrets

An Instana secret is required only when the TLS configuration for the Instana server uses a certificate signed by a private CA. If so, a secret is needed that contains the pem file which contains the CA as well as any intermediate signing certificates.

Run the following command to create the Instana secret:

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

For example:

kubectl create secret generic instana-auth --from-file=cert.pem

Note: Ensure that the certificate name provided here is used consistently in the configuration file values.yaml or instana-exporter.yaml later on, i.e. the value for the certName parameter or ZAPM_INSTANA_CERT_NAME, respectively.

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

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

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

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

VII. Verify the secrets

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
regcred        kubernetes.io/dockerconfigjson    1       50s
ingress-auth   Opaque                            5       59s
kafka-auth     Opaque                            5       1m
instana-auth   Opaque                            1       2m
redis-auth     Opaque                            1       3m