Populating deployment files

Edit online

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. 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 the 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 during the pre-deployment configuration, 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 as per your requirement.

Tip:
  • Spaces are important in a 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 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

Table 1. Global configuration parameters
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> <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.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>

Transaction processor values

Table 2. Transaction Processor and CDP Factory configuration parameters
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-<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-<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>

Kafka values

Table 3. Kafka configuration parameters
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. kafka-bootstrap-secure.<namespace>.<baseDomain> kafka-brkr-secure-0.<namespace>.<baseDomain> kafka-brkr-secure-1.<namespace>.<baseDomain> kafka-brkr-secure-2.<namespace>.<baseDomain> <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-<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

Table 4. Redis image configuration parameters
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-<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

TTG values

Navigate to the following Values Section: 

  ttg:
    controllers
Table 5. Configuration parameters for ttg section of values.yaml file
Parameter Description Options
name Name of the AppDynamics controller – used to differentiate between multiple controllers (arbitrary but must be lower case) <user input>
enabled Set ttg.enabled = true if you are using AppDynamics as the vendor. true or false
hostname Hostname of the AppDynamics controller. See AppDynamics controller for details. <user input>
port Port of the AppDynamics controller. See AppDynamics controller for details. <user input>
auth.saas Type of AppDynamics controller
  • 0 - if an on-prem controller
  • 1 - if a SaaS controller
auth.account Account name registered with the AppDynamics controller. See AppDynamics controller for details. <user input>
auth:accessKey Access key of AppDynamics controller. See AppDynamics controller for details. <user input>
auth:accountId Account ID/GUID of AppDynamics controller. See AppDynamics controller for details. <user input>
auth:useOauth Whether or not an OAuth token is being used
  • 1 - if using an OAuth token.
  • 0 - if using a regular password.
auth:username Username for logging into the AppDynamics controller. See AppDynamics controller for details. <user input>
auth:secretName Name of the secret containing the AppD controller password (and possible certificate) <user input>, ex. ttg-auth
auth:useSsl Whether or not TLS is being used to connect to the AppDynamics controller
  • 1 - AppDynamics Controller expects TLS/SSL connection.
  • 0 - TLS/SSL connection not enabled.
auth:certName (Optional) Name of certificate used inside the secretName, if one is used. Commonly used for On-Prem AppDynamics controllers. <user input>
proxy:host (Optional) Hostname of forward proxy to use for connecting to an AppDynamics controller. <user input>
proxy:port (Optional) Port on which the forward proxy listens to connect with an AppDynamics controller. <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.
Table 6. Performance profiles and resource recommendations
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.