Pre-deployment configuration

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. Log in to Instana.

  2. Navigate to More > Agents > Install Agents > AWS > AWS Lambda.

  3. Copy the INSTANA_ENDPOINT_URL.

IMPORTANT: Do not 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

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.

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.

Instana secrets

The Distributed Gateway requires an Instana agent key secret to communicate with the Instana server.

Run the following command to create the Instana agent key secret:

kubectl create secret generic <secret name> --from-literal=agentKey=<key>

For example:

kubectl create secret generic agent-key --from-literal=agentKey=abcdefghijk12345678910

Note: Use the agent key name consistently in the configuration file values.yaml. For example, agentKey.

The Distributed Gateway requires an Instana certificate secret when the TLS configuration for the Instana server uses a certificate signed by a private or self-signed CA. It also requires a secret that contains the PEM file that contains the private CA, including the intermediate signing certificates or the self-signed certificate (if any).

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: Use the certificate name consistently in the configuration file values.yaml. For example, the value for the certName parameter or ZAPM_INSTANA_CERT_NAME.

In Openshift or Kubernetes, you will require an image pull secret to access 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

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

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
agent-key      Opaque                            1       2m 
redis-auth     Opaque                            1       3m