Populating deployment files
To deploy the Z APM Connect DG, populate the deployment files. If you are using Kubernetes, you can complete this task either by using Helm to create a Helm values file if Helm is installed, or by manually editing yaml manifest files and applying them to the cluster. If you are using OpenShift, you must use Helm to configure the values.yaml file. Helm is an industry standard tool that will help simplify the configuration, deployment, and maintenance of the Distributed Gateway deployment. You can further fine‑tune system resource requirements by adjusting the pod resource settings described on this page.
Using Helm to configure a values.yaml file
Before you begin
Make sure that Helm V3.1 or later is installed. For more information about installing Helm, see Installing Helm.
About this task
Helm uses one values file that is used by a Helm Chart to tell Helm about the wanted configuration. The values.yaml file needs to include the image repository to use, APM details, the names of the Secrets created in Deploying Z APM Connect DG in a cluster, and other settings. A sample values.yaml is included in the installation package.
Procedure
For production, the sample values.yaml is located at ./production/helm-deployment/values.yaml. It is recommended to create a backup copy before making edits so that you can refer back to default values.
To deploy Distributed Gateway, configure the parameters according to your requirements.
Tip:
- Spaces are important in yaml file. Each indentation must be two spaces.
- It is highly recommended to use an editor that allows you to easily see spaces and search easily. A code editor with a yaml extension is recommended.
Refer to the following table of parameter description to provide the configuration details
relevant to your deployment.
Note:
Any variable in the values.yaml file that is not present in this table is optional for the OpenTelemetry (OTel) deployment.
Global values
| Parameter | Description | Default value | Options |
|---|---|---|---|
| global.namespace | Specifies the namespace in which all components are deployed. Create a separate namespace for each Distributed Gateway deployment. | ibm-zapm | <user-input> |
| global.performanceProfile | Specifies the performance profile that defines the required size and replication for the expected throughput. Larger profiles support higher transactions per second and require additional resources. | small | small, medium, large |
| global.ingressType | Specifies the ingress type created during installation. Use OpenShiftRoute on OpenShift and NodePort on Kubernetes. Specify None to provide a custom ingress. | NodePort | NodePort, OpenShiftRoute, None |
| global.HA.enabled | Enables high availability by deploying multiple instances of selected components to improve durability and recovery. This setting is recommended for production environments. | false | true, false |
| global.logLevel | Specifies the log level used by all Distributed Gateway components. | info | OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL |
| global.image.repository | Specifies the base container image repository path for all components. Do not include the image name or tag. | icr.io/zapm-<version> or icr.io/zapm-instana-<version> | <user-input> |
| global.image.pullPolicy | Determines when container images are pulled from the registry. Use IfNotPresent for production deployments. | IfNotPresent | Always, IfNotPresent, Never |
| global.image.pullSecretName | Specifies the name of the Kubernetes secret that contains credentials for pulling images from a private container registry. | regcred | <user-input> |
| global.security.zapmConnectBase.enabled | When TLS is used to secure the connection between the ZAPM Base Container and the Distributed Gateway, set this value to enabled=true. | false | true, false |
| global.security.zapmConnectBase.secretName | Specify the name of the Kubernetes secret that contains the certificates created before installation. Use only the supported data field names, name the truststore file as truststore.jks and the keystore file as keystore.jks. | ingress-auth | <user-input> |
| global.security.otel.enabled | Set enabled=true to use TLS to secure the connection between the Distributed Gateway and an OpenTelemetry‑compliant backend. | false | true, false |
| global.security.otel.secretName | Specify the name of the Kubernetes secret that contains the certificates created before installation. | otel-secret | <user-input> |
| global.security.otel.certName | Specifies the name of the TLS certificate stored in the secret identified by global.security.otel.secretName. | otel-cert | <user-input> |
| global.security.kafka.internal.enabled | Set enabled=true to use TLS for securing communication between Distributed Gateway components. This setting enables two‑way TLS authentication for internal Kafka clients. | kafka-auth | <user-input> |
| global.security.kafka.external.enabled | Set enabled=true to use TLS for securing the connection between CTG or z/OS Connect and the Distributed Gateway components. This setting enables two‑way TLS authentication for Kafka clients that connect by using the advertised hostname. | true | true, false |
| global.security.kafka.secretName | Specify the name of the Kubernetes secret that contains the certificates created before installation. Name the truststore file kafka.truststore.jks and the keystore file kafka.keystore.jks. Use the same secret for both internal and external TLS. | true | true, false |
| global.security.redis.enabled | Set enabled=true to use password authentication between Redis and the Distributed Gateway components. If global.security.redis.secretName is not specified and password authentication is enabled, the system automatically generates a password and stores it in a secret named redis-auth. | true | true, false |
| global.security.redis.secretName | Specifies the name of the secret that contains the Redis password stored with the key redis_password. | redis-auth | <user-input> |
| global.security.instana.enabled | Enables TLS to secure the connection between the Distributed Gateway and an Instana‑compliant backend when set to true. | false | true, false |
| global.security.instana.secretName | Specifies the name of the secret that contains the certificates created before installation. | instana-secret | <user-input> |
| global.security.instana.certName | Specifies the name of the TLS certificate stored in the global.security.instana.secretName secret. | instana-cert | <user-input> |
Transaction processor values
| Parameter | Description | Default value | Options |
|---|---|---|---|
| transactionProcessor.connectionManager.nodePort.port | Specifies the NodePort used by the Distributed Gateway when global.ingressType is set as NodePort. If port 30455 is already in use, specify an available port. | 30455 | 30000–32767 |
| transactionProcessor.connectionManager.openShiftRoute.baseDomain | Specifies the base domain when global.ingressType= is set as OpenShiftRoute. The prefix zapm-connect-secure and the namespace are added automatically when the route is created. | zapm-connect-secure.<namespace>.<baseDomain> | <user-input> |
| transactionProcessor.delayDuration | Specifies the delay, in milliseconds, before a transaction is processed. Increasing this value improves the likelihood that all events for a transaction are received before processing begins. | 2500 | <any-positive-integer> |
| transactionProcessor.imageOverride.repository | Specifies the container image repository path for Transaction Processor components. This value overrides global.image.repository. Do not include the image name or tag. | icr.io/zapm-instana-<version> | <user-input> |
| transactionProcessor.imageOverride.image | Specifies the container image name for the Transaction Processor components. This setting overrides the default image for this release. | zapm-transaction-processor | <user-input> |
| transactionProcessor.imageOverride.tag | Specifies the container image tag for the Transaction Processor components. This setting overrides the default tag for this release. | <release-version> | <user-input> |
| transactionProcessor.imageOverride.pullPolicy | Determines when Transaction Processor images are pulled from the container registry. Use IfNotPresent for production deployments. | IfNotPresent | Always, IfNotPresent, Never |
| transactionProcessor.imageOverride.pullSecretName | Specifies the name of the Kubernetes secret that contains credentials for pulling images from a private container registry. The secret must exist in the deployment namespace before installation. | regcred | <user-input> |
| cdpFactory.enabled | Enables the CDP Factory component. Set this value to true when streaming from Db2. | false | true, false |
| cdpFactory.imageOverride.repository | Specifies the container image repository path for the CDP Factory component. This value overrides global.image.repository. Do not include the image name or tag. | icr.io/zapm-instana-<version> | <user-input> |
| cdpFactory.imageOverride.image | Specifies the container image name for the CDP Factory component. | zapm-transaction-processor | <user-input> |
| cdpFactory.imageOverride.tag | Specifies the container image tag for the CDP Factory component. | <release-version> | <user-input> |
| cdpFactory.imageOverride.pullPolicy | Determines when the CDP Factory image is pulled from the container registry. | IfNotPresent | Always, IfNotPresent, Never |
| cdpFactory.imageOverride.pullSecretName | Specifies the name of the Kubernetes secret used to pull images from a private container registry. This secret must exist before installation. | regcred | <user-input> |
OpenTelemetry exporter values
| Parameter | Description | Default | Valid values |
|---|---|---|---|
| grpcEndpoint | The gRPC acceptor endpoint set in the OTel Collector configuration file, in the format http(s)://<hostname>:<port>. For example, http://localhost:4317. | NA | <user input> |
| httpEndpoint | Enables establishing HTTP or HTTPS connections to the OTel Collector. | false | true or false |
| otelExporter.enabled | Enables the OTel exporter. Set this value to true when using an OpenTelemetry‑compliant vendor. | false | <user-input> |
| otelExporter.enabled | Enables the OTel exporter. Set this value to true when using an OpenTelemetry‑compliant vendor. | false | <user-input> |
| otelExporter.imageOverride.repository | Specifies the container image repository path for the OTel Exporter. This value overrides global.image.repository. Do not include the image name or tag. Use this setting to specify a private container registry. | icr.io/zapm-instana-<version> | <user-input> |
| otelExporter.imageOverride.image | Specifies the container image name for the OTel exporter. This setting overrides the default image for this release. | zapm-exporter | <user-input> |
| otelExporter.imageOverride.tag | Specifies the container image tag for the OTel exporter. This setting overrides the default tag for this release. | <release-version> | <user-input> |
| otelExporter.imageOverride.pullPolicy | Determines when the OTel Exporter image is pulled from the container registry. Use IfNotPresent for production deployments. Use Never when images are loaded manually. | IfNotPresent | Always, IfNotPresent, Never |
| otelExporter.imageOverride.pullSecretName | Specifies the name of the Kubernetes secret that contains credentials for pulling images from a private container registry. This secret must exist in the deployment namespace before installation. | regcred | <user-input> |
Kafka values
| Parameter | Description | Default value | Options |
|---|---|---|---|
| kafka.nodePort.bootstrapPort | Specifies the NodePort that external clients use to connect to Kafka when global.ingressType is set as NodePort. If port 30090 is already in use, specify an available port. | 30090 | 30000–32767 |
| kafka.nodePort.nodePorts | Specifies a NodePort for each Kafka broker when global.ingressType is set as NodePort. If any default port is already in use, update the corresponding value. | 30091–30098 | 30000–32767 |
| kafka.openShiftRoute.baseDomain | Specifies the base domain when global.ingressType is set as OpenShiftRoute. The prefix ibm-zapm-kafka-secure and the namespace are added automatically. The configuration creates a single bootstrap route and individual broker routes to support Kafka connectivity. | NA | <user-input> |
| kafka.imageOverride.repository | Specifies the container image repository path for Kafka. This value overrides global.image.repository. Do not include the image name or tag. | icr.io/zapm-instana-<version> | <user-input> |
| kafka.imageOverride.image | Specifies the container image name for Kafka. This setting overrides the default image for this release. | kafka | <user-input> |
| kafka.imageOverride.tag | Specifies the container image tag for Kafka. This setting overrides the default tag for this release. | <release-version> | <user-input> |
| kafka.imageOverride.pullPolicy | Determines when the Kafka image is pulled from the container registry. Use IfNotPresent for production deployments. | IfNotPresent | Always, IfNotPresent, Never |
| kafka.imageOverride.pullSecretName | Specifies the name of the Kubernetes secret that contains credentials for pulling images from a private container registry. The secret must exist in the deployment namespace before installation. | regcred | <user-input> |
Redis values
| Parameter | Description | Default value | Options |
|---|---|---|---|
| redis.imageOverride.repository | Specifies the container image repository path for Redis. This value overrides global.image.repository. Do not include the image name or tag. Use this setting to specify a private container registry. | icr.io/zapm-instana-<version> | <user-input> |
| redis.imageOverride.image | Specifies the container image name for Redis. This setting overrides the default image for this release. | redis | <user-input> |
| redis.imageOverride.tag | Specifies the container image tag for Redis. This setting overrides the default tag for this release. | <release-version> | <user-input> |
| redis.imageOverride.pullPolicy | Determines when the Redis image is pulled from the container registry. Use IfNotPresent for production deployments. Use Never when images are loaded manually. | IfNotPresent | Always, IfNotPresent, Never |
Instana exporter values
| Parameter | Description | Default | Valid values |
|---|---|---|---|
| instanaEndpointURL | The serverless acceptor endpoint that can be found through the Instana webpage. Navigation path: . For example, https://serverless-color-saas.instana.io | NA | <user input> (int) |
| agentKeySecretName | The name of the secret containing the Instana Agent Key. | NA | <user input> (agent-key) |
| saasDeployment | Specifies if the Instana endpoint URL belongs to the Instana SaaS server. | false | true or false |
| selfHostedOCP | Specifies if the Instana endpoint URL belongs to the Instana On-Prem server (self hosted) running on OCP (Openshift). | false | true or false |
| instanaExporter.enabled | Enables the Instana Exporter. Set this value to true when Instana is configured as the vendor. | false | true, false |
| instanaExporter.imageOverride.repository | Specifies the container image repository path for the Instana Exporter. This value overrides global.image.repository. Do not include the image name or tag. Use this setting to specify a private container registry. | icr.io/zapm-instana-<version> | <user-input> |
| instanaExporter.imageOverride.image | Specifies the container image name for the Instana Exporter. This setting overrides the default image for this release. | zapm-exporter | <user-input> |
| instanaExporter.imageOverride.tag | Specifies the container image tag for the Instana Exporter. This setting overrides the default tag for this release. | <release-version> | <user-input> |
| instanaExporter.imageOverride.pullPolicy | Determines when the Instana Exporter image is pulled from the registry. Use IfNotPresent for production deployments. Use Never when images are loaded manually. | IfNotPresent | Always, IfNotPresent, Never |
| instanaExporter.imageOverride.pullSecretName | Specifies the name of the Kubernetes secret that contains credentials for pulling images from a private container registry. This secret must exist in the deployment namespace before installation. | regcred | <user-input> |
System resource requirements
The performance profile defines the pod replica counts and resource requests required to support different throughput levels. On basis of your expected transaction rate, configure the performanceProfile value that best meets the requirements.
Note:
- Performance tests for Z APM Connect Distributed Gateway were conducted on an OpenShift cluster with 8 worker nodes. Each worker node was an x86 virtual machine with 16 cores and 25GB of RAM. The tests use simple traces that include a parent transaction and two to three child transactions.
- The recommended values may require adjustments depending on the computing environment, including factors such as hardware specifications, operating system, and application workloads. For example, more complex transaction data will result in larger event sizes and may require adjustments.
| Transactions per second | Performance profile | High availability recommendation | Cluster CPU | Cluster memory (GB) |
|---|---|---|---|---|
| < 5k transactions per second | small | disabled | 9 | 26 |
| > 5k and < 15k transactions per second | medium | enabled | 40 | 80 |
| > 15k and < 30k transactions per second | large | enabled | 60 | 90 |
Kubernetes requests represent the minimum resources that a pod can have, while Kubernetes limits
define the maximum resources. CPU resources are measured in millicores, where 1000m is equivalent to
1 CPU core. Memory is measured in bytes and expressed as mebibyte values, which are similar to
megabytes.
Attention: If you enable Internal Kafka TLS two-way authentication for your
Distributed Gateway deployment, there will be increased performance overhead which will result in
increased resource requirements.