Configuration
This section describes the configuration parameters of the Runtime Server when Helm is used for installation. An alternate configuration method is used for an installation of the Runtime Server as a single container in a container runtime such as Docker or Podman. See the section on the ibm-itx-rs container image for information about configuring a single-container installation.
When Helm is used for installation, the Runtime Server supports two installation modes as follows:
- V1 installation mode
- V2 installation mode
The V1 mode only supports the V1 API, which is enabled by the restV1.deploy parameter. The V2 mode supports the V2 and V1 APIs, both of which are activated by the rest.deploy parameter. The V2 mode requires an external Redis installation because the V2 API requires map and flow execution requests and results to be stored in Redis. The V1 mode does not require an external Redis installation if the server is unfenced. The V1 mode can be used simultaneously with the V2 mode only if the V1 installation is unfenced (restV1.runMode).
The V1 mode supports scaling the number of REST servers (restV1.replicas). The V2 mode uses an alternate form of scaling where a single REST server provides messages to one or more execution pods (executor.replicas). Horizontal pod autoscaling (HPA) is supported for both modes (restV1.autoscaling.enabled, executor.autoscaling.enabled).
The configuration settings of the Helm chart values.yaml file for the Runtime Server can be broken down into the following logical groups:
- REST settings (V1 or V2 API installation, image details, service account, custom environment variables, replica count)
- Probe settings (liveness, readiness)
- Map and Flow settings (map threads, file extension, etc.)
- Logging (log severity, log name uniqueness, log targets, etc.)
- Resource utilization (memory, CPU, storage, replica count)
- Redis configuration (host, port, password, etc.)
- Storage settings (storage class, capacity, dynamic vs. static binding, etc.)
- TLS configuration (certificates, keys, etc.)
- Cloud Object Storage settings
The following configuration settings are a subset of the total settings available to the ITX Runtime Server. For more information, see the installation’s values.yaml and README.md files. The config section of the values.yaml file enables the ITX configuration settings in the config.yaml file to be overridden. Each config.yaml setting is referenced under the config section according to camel case convention, whereby the first letter of a named setting is lowercase while any remaining words in the name start with a capital letter.
Whenever changes are made to the below properties during a Helm upgrade, the pods that are associated with the existing installation will not automatically restart - unless the change affects the actual deployment manifest. For example, an update to the image name or resource metrics will change the deployment manifest of the installation, which in turn will trigger an automatic restart of the pods. However, a basic change to a property that is linked to the ITX config.yaml file, such as the logging level, will not trigger an automatic restart. The restart would need to take place manually, as provided by the Kubernetes scale command.
| values.yaml property | Description |
|---|---|
| Licensing | |
| license | Switch with true/false values for accepting the terms and conditions of the license agreement. The default is false. |
| REST V1 - Map Executions via Version 1 of the REST API | |
| restV1.deploy | Deploy the REST V1-based service, which only supports map executions. The default is true. |
| restV1.replicas | Number of ITX Runtime Server replica pods to deploy and run. The default is 1. |
| restV1.runMode | Selection of mode (fenced/unfenced). In fenced mode the REST service process and the worker map execution process are separate processes, and in unfenced mode they run in the same process. The default is unfenced. |
| restV1.serviceAccount.existingName | Name of the ServiceAccount object to use for the installation. If left empty, the default service account is used. |
| restV1.extraEnvConfigMap | Name of an optional ConfigMap containing key/value pairs to set as environment variables when creating the pods. |
| restV1.nodeSelector | Name and value of the label of the worker nodes to which the pods must be deployed. |
| restV1.affinity | The node affinity and anti-affinity preferences when selecting a node for a pod. |
| REST V2 - Map and Flow Executions via Version 2 of the REST API | |
| rest.deploy | Deploy the REST V2-based service, which supports map and flow executions. The default is false. |
| executor.replicas | Number of ITX Runtime Server replica pods to deploy and run. The default is 1. |
| rest.existingName | Name of the ServiceAccount object to use for the installation. If left empty, the default service account is used. |
| rest.extraEnvConfigMap | Name of an optional ConfigMap containing keys/ value to set as environment variable names/values when creating the pods. |
| rest.nodeSelector | Name and value of the label of the worker nodes to which the pods must be deployed. |
| rest.affinity | The node affinity and anti-affinity preferences when selecting a node for a pod. |
| Image Settings | |
| rest.image.repository | Image registry and repository location. |
| rest.image.digest | Image digest value, which takes priority over image tag value. |
| rest.image.tag | Image tag value. |
| rest.image.pullPolicy | Image pull policy, one of Always, Never and IfNotPresent. |
| itxImagePullSecret | Name of the pull image Secret object with which to configure the ServiceAccount for pulling images. |
| Probes Settings | |
| restV1|rest|executor.probes.liveness.enabled | Switch with true/false values to enable/disable liveness probe. The default is true. |
| restV1|rest|executor.probes.liveness.initialDelaySeconds | Number of seconds to wait before making the initial liveness probe call. The default is 35. |
| restV1|rest|executor.probes.liveness.periodSeconds | Number of seconds between liveness probe calls. The default is 20. |
| restV1|rest|executor.probes.readiness.enabled | Switch with true/false values to enable/disable readiness probe. The default is true. |
| restV1|rest|executor.probes.readiness.initialDelaySeconds | Number of seconds to wait before making the initial readiness probe call. The default is 35. |
| restV1|rest|executor.probes.readiness.periodSeconds | Number of seconds between readiness probe calls. The default is 20. |
| Map and Flow Run Settings | |
| rest.map.fileExtension | File extension for compiled maps. The default is mmc. |
| config.rest.map.unloadTime | Time in minutes to keep loaded maps in memory. The default is 1. |
| config.rest.resources.mapThreads | Maximum number of threads to spawn for running maps concurrently. The default is 10. |
| config.rest.resources.flowThreads | Maximum number of threads to spawn for running flows concurrently. The default is 10. |
| restV1|rest.synchronousTimeout | Synchronous map and flow execution timeout in seconds. The default is 300. |
| config.runtime.runMaps.runMapMaxCacheNum | Controls run map caching in the Runtime Server. The default is -1, which disables run map caching. |
| config.rest.multipartbody.allAttachment | Switch to include/exclude all attachments in the multi-part body response. The default is false. |
| Logging | |
| config.rest.logging.level | Severity level for REST and map/flow execution logs (ALL,TRACE,INFO,ERROR,NONE). The default is ERROR. |
| config.rest.logging.rotation.fileAge | Number of days to keep logs. The default is 30. |
| config.rest.logging.rotation.fileCount | Number of log files. The default is 5. |
| config.rest.logging.rotation.fileSize | Size in bytes of each log file. The default is 20000. |
| config.runtime.trace | Switch with “stdout” and “” values to enable logging to Kubernetes versus files located in the /data folder. The default is “stdout”. |
| config.runtime.jniLayerTrace.level | Severity level for the Java Native Interface (JNI) component (10=Critical, 20=Error, 30=Warning, 40=Info, 50=Verbose). The default is 20. |
| config.rest.logging.addWebServerConsoleLogging | A boolean-valued property which, when true, causes web server logs to be sent to the container stderr stream. The default is true. |
| Resource Registry | |
| config.rest.resourceRegistryFile | Full path, starting with /data, of the optional ITX resource registry file, if it was previously uploaded or mounted via a Kubernetes ConfigMap. |
| Redis Settings | |
| itxRedis.host | Redis host name. Must be a resolvable name on the current network. The default is redis-master. |
| itxRedis.port | Redis port number. The default is 6379. |
| itxRedis.password.secret | Name of the Secret object containing the Redis password, when accessing a password-enabled Redis service. |
| itxRedis.password.key | The key in the Secret object that contains the redis password. |
| itxRedis.tls | A mapping which contains keys related to client TLS configuration. Used when a Redis server requires TLS. |
| restV1.redisStem | Key prefix to use for Redis V1 keys produced and consumed by the server. The default is tx-rest-v1. |
| Resource Constraints | |
| restV1|rest|executor.resources.requests.cpu | Requested number of CPU cores or millicores (using m suffix). The default is 250m. |
| restV1|rest|executor.resources.requests.memory | Requested memory in bytes (with optional base-10 suffix like M or G, or base-2 suffix, like Mi or Gi. The default is 700mi. |
| restV1|rest|executor.resources.limits.cpu | Upper limit number of CPU cores or millicores (using m suffix). The default is 4000m. |
| restV1|rest|executor.resources.limits.memory | Upper limit for memory in bytes (with optional base-10 or base-2 suffix, like Gi for gigabytes). The default is 8Gi, except for the executor setting which is 4Gi. |
| Persistent Volumes | |
| rest.persistence.data|logs.size | Capacity to request for data persistent volume. Base-10 suffixes like M and G, or base-2 suffixes like Mi and Gi can be used. The default is 20Gi for data and 100Mi for logs. |
| rest.persistence.data|logs.accessMode | Access mode to specify for the data/logs persistent volume. It can be set to ReadWriteMany or ReadWriteOnce. The default is ReadWriteOnce. |
| rest.persistence.data|logs.useDynamicProvisioning | Switch with true/false values to enable/disable dynamic provisioning for the data/logs persistent volume. The default is false. |
| rest.persistence.data|logs.storageClassName | Name of the storage class supported by the cluster to use for dynamic provisioning the data/logs persistent volumes. |
| rest.persistence.data|logs.enabled | Switch with true/false to enable/disable persistence. Consider setting it to true if COS is used with REST V1 synchronous, “unfenced” deployments. The default is false. |
| TLS Settings | |
| restV1|rest.inbound.https.enabled | Switch with true/false values to enable/disable use of HTTPS protocol on the ITX Runtime Server REST pods. The default is false. |
| restV1|rest.inbound.https.serviceServingCertificates | Switch with true/false values to enable/disable OpenShift service serving certificates for securing service traffic. The default is false. |
| restV1|rest.inbound.https.clientAuth | Switch with true/false values to enable/disable validation of certificates presented by the REST API callers (mutual authentication). The default is false. |
| restV1|rest.inbound.https.secret | Name of the Secret object containing CA certificate, Server certificate and Server private key, in PEM format. |
| Service Settings | |
| restV1|rest.service.type | Type of the network service to provision, one of ClusterIP, NodePort, LoadBalancer or ExternalName. Defaults to ClusterIP. |
| restV1|rest.service.port.http | Port to expose for the HTTP traffic, when SSL is not enabled. The default is 8080. |
| restV1|rest.service.port.https | Port to expose for the HTTPS traffic, when SSL is enabled. The default is 8443. |
| Cloud Object Storage (COS) Settings | |
| external.cos.enabled | Enables maps and flows to get downloaded from COS. The default is false. |
| external.cos.name | Name of ZIP object to download and unzip. The default is maps.zip. |
| external.cos.bucket | Name of bucket that contains the ZIP object. |
| external.cos.targetDir | Target directory that ZIP file gets extracted to. The default is /data/maps. |
| external.cos.platform | Set to s3 for S3-based platform or gcp for Google-based platform. The default is s3. |
| external.cos.s3.accessKey|secretKey|region|endpoint | Credentials and location information for S3-based platform. The accessKey and secretKey are the keys of the secret, as specified under Secret Settings. |
| external.cos.gcp.cf | The key of the secret which contains the Credentials file, as specified under Secret Settings. |
| Secret Settings | |
| external.secrets[].name|data | An array of secret names and keys, which are mounted under the /xdata/sec folder with a filename that uses the value of the data setting. |
| external.mq.secret | The secret that contains the MQ channel definition table, which is mounted by default under the /xdata/sec folder. |
| ConfigMap Settings | |
| external.configMaps[].name|key|path | An array of ConfigMap objects that get mounted by default under the /xdata/cfg folder. |
| Auto Scaling Settings | |
| restV1|executor.autoscaling.enabled | Switch with true/false values to enable/disable auto scaling of ITX Runtime Server pods. The default is false. |
| restV1|executor.autoscaling.maxreplicas | Maximum number of ITX Runtime Server pods to auto scale. |
| restV1|executor.autoscaling.minreplicas | Minimum number of ITX Runtime Server pods with which to start. |
| restV1|executor.autoscaling.cpu.averageUtilization | Threshold CPU utilization percentage to scale a new ITX Runtime Server pod. |
| restV1|executor.autoscaling.memory.averageUtilization | Threshold memory utilization percentage to scale a new ITX Runtime Server pod. |
| restV1|executor.autoscaling.custom.enabled | Switch with true/false values to enable/disable custom metrics. The default is false. |
| restV1|executor.autoscaling.custom.types[] | An array of custom metric type definitions, as defined by Kubernetes v2 API version. |
| restV1|executor.autoscaling.custom.behavior | Behavior policies for scaling up and scaling down the deployment, as defined by the Kubernetes v2 API version. |
| Life Cycle Settings | |
| shutdownTimeSeconds | At least these many seconds will elapse before the main process of a container is sent SIGTERM. The default is 0 (no extra SIGTERM delay). This allows for graceful termination when long-running maps or flows are executed. |
| Service Mesh Settings | |
| istioV1|istio.enabled | Service mesh participation is enabled for both V1 and V2 deployments. The Istio service mesh provides traffic management, security, and monitoring capabilities across the cluster. See the values.yaml file for configuration adjustments and customized settings The default is false. |
| Metrics and Monitoring Settings | |
| metrics.enabled | Metrics are enabled and exposed to the REST API and Prometheus monitoring. Memory and CPU usage of the process is tracked and exposed along with the other metrics indicated below. The default is false. |
| metrics.readinessProbeEnabled | Kubernetes readiness probes query metrics to ensure that service thresholds are satisfied and inbound traffic continues to get accepted. The default is false. |
| metrics.threadSaturationThreshold | Acceptable percentage threshold of active threads to total threads. The default is “0.95”. |
| metrics.cpuUsageThreshold | Acceptable percentage threshold of REST process CPU usage. The default is “0.95”. |
| metrics.sli.percentile | Acceptable percentage threshold of map and flow requests that complete in a timely way, as set by the thresholdMs value. The default is “0.95”. |
| metrics.sli.thresholdMs | The time in milliseconds that a map or flow execution request should be completed. The default is “20000”. |
| metrics.sli.buckets | Histogram latency buckets, which count REST requests that have completed within specified times. The times are customizable and the defaults range in milliseconds from 75-30000. Values are separated by commas and should be limited to less than 25 entries to avoid unnecessary memory growth and CPU usage. |
| metrics.system.cpu | Enables reporting of the deployment’s CPU limit, core load average, and system-wide cpu usage percentage. The default is false. |
| metrics.jvm.memory|gc|threads | Diagnostic settings to track JVM memory usage, GC activity and thread states, respectively. Settings are individually configurable with each one defaulting to false. |
| Performance Tuning and Debugging Settings | |
| allocator.alternateNativeAllocator | The value “tcmalloc” causes the tcmalloc native memory allocator to be used instead of the system allocator. The native memory allocator is used by default. |
| allocator.heapProfile | If true and tcmalloc is used for the native memory allocator, then debugging heap profile reports are generated. This should not be routinely used in production. The default is false. |