This topic explains how to configure and manage the Apigee hybridruntime plane components. For a list of the runtime plane components that you can configure, seeRuntime service configuration overview.

About the overrides file

The first time you install the hybrid runtime into a cluster, you must create a configurationoverrides file. This file lets you override default configuration values as needed, configure environments, reference TLS certificates and service account keys, assign Kubernetes node pools to specific hybrid components, and so on.

The hybridinstallation steps walk through the process of creating an overrides file and applying your configuration to a cluster. If you want to change the configuration later, modify the overrides file you created and re-apply it.

Making a configuration change

To make a configuration change to a hybrid runtime plane component, edit your overrides file and use Helm to upgrade the chart that corresponds with the component. The following chart shows which charts correspond wth which Apigee hybrid components:

For example, to change the replica count on theMessage processor, follow these steps:

1. Open yourOVERRIDES.yaml file. Be sure to use the same overrides file that was used to install the hybrid runtime into the cluster.
2. Locate theruntime element in the file. For example:

   runtime:  nodeSelector:    key: cloud.google.com/gke-nodepool    value: apigee-runtime  replicaCountMin: 1  replicaCountMax: 2...

See:

• runtime.nodeSelector.key.
• runtime.nodeSelector.value.
• runtime.replicaCountMin.
• runtime.replicaCountMax.
3. Change the replica count properties as needed. For example:

   runtime:  nodeSelector:    key: cloud.google.com/gke-nodepool    value: apigee-runtimereplicaCountMin: 2  replicaCountMax: 20...

4. Upgrade the environment.

You must install one environment at a time. Specify the environment with--set env=ENV_NAME.

Dry run:

helm upgradeENV_RELEASE_NAME apigee-env/ \--install \--namespaceAPIGEE_NAMESPACE \--set env=ENV_NAME \-fOVERRIDES_FILE \--dry-run=server

• ENV_RELEASE_NAME is the name with which you previously installed theapigee-env chart. In hybrid v1.10, it is usuallyapigee-env-ENV_NAME. In Hybrid v1.11 and newer it is usuallyENV_NAME.
• ENV_NAME is the name of the environment you are upgrading.
• OVERRIDES_FILE is your new overrides file for v.1.14.3
5. Upgrade the chart:

helm upgradeENV_RELEASE_NAME apigee-env/ \--install \--namespaceAPIGEE_NAMESPACE \--set env=ENV_NAME \-fOVERRIDES_FILE

6. Verify it is up and running by checking the state of the respective env:

kubectl -nAPIGEE_NAMESPACE get apigeeenv

NAME                          STATE       AGE   GATEWAYTYPEapigee-org1-dev-xxx            running     2d

Which configuration properties can you modify?

You can find the complete list of configurable properties in theConfiguration property reference. The reference only lists the properties you can modify; if you try to modify a property that's not in the reference, the change is ignored.

How to use the configuration reference

TheConfiguration property reference uses dot notation to describe configuration elements, where the first item is the top-level element name followed by properties and child properties.For example:

ao.image.pullPolicy

In the overrides file, the properties are formatted in proper YAML. For the above example, the top-levelao element is left-indented and sub-element properties are indented under it. Also, YAML requires a colon at the end of each element and sub-element.

For example, to set theao.image.pullPolicy property toAlways, locate this YAML stanza in the overrides file and set it as follows:

ao:image:pullPolicy:Always

For another example, the propertycassandra.auth.admin.password (as it is listed inConfiguration property reference) is used to set the Cassandra admin password. To change it, locate the following YAML in the overrides file and set it as follows:

cassandra:auth:admin:password:abc123

Remember, theConfiguration property reference describes all of the properties that you can set on hybrid runtime plane components. Follow the pattern explained above to modify these elements in your overrides file before applying the changes to your cluster.

Using pre-defined example overrides files

When you first install hybrid runtime, Apigee recommends that you use one of thepre-configured example overrides files. These examples provide a complete set of configuration properties for specific installation scenarios, such as for setting up a production or test installation. All you need to do is provide appropriate values for the properties andapply the overrides file to your cluster. SeeStep 6: Create the overrides for more information.

About configuration defaults

Apigee maintains its default component configuration in the fileHYBRID_ROOT_DIR/config/values.yaml. Your overrides files follows the same YAML structure asvalues.yaml.

An overrides file typically includes only a subset of the configuration properties found invalues.yaml. Remember,not all properties are editable. When you apply a configuration to a cluster, your overrides are merged with the defaults to create the complete Kubernetes cluster configuration. See alsoTest the merged configuration.

The following code shows the default configuration for themart component as found invalues.yaml. Note that some values have defaults, while others such assslCertPath andsslKeyPath do not. You must provide these missing values in your overrides file, as explained in theinstallation steps. If you want to change any of the default values, make sure they are editable by checking in theConfiguration property reference.

...mart:  replicaCountMin: 2  replicaCountMax: 4  targetCPUUtilizationPercentage: 75  terminationGracePeriodSeconds: 30  sslCertPath:  sslKeyPath:  hostAlias:  nodeSelector:    key:    value:  revision: blue  image:    url: "gcr.io/apigee-release/hybrid/apigee-mart-server"    tag: "1.14.3"    pullPolicy: IfNotPresent  resources:    requests:      cpu: 500m      memory: 512Mi  initCheckCF:    resources:      requests:        cpu: 10m  livenessProbe:    timeoutSeconds: 1    failureThreshold: 12    periodSeconds: 5    initialDelaySeconds: 15  readinessProbe:    timeoutSeconds: 1    successThreshold: 1    failureThreshold: 2    periodSeconds: 5    initialDelaySeconds: 15  metricsURL: "/v1/server/metrics"  cwcAppend: |...

If you want to modify a component's defaults and the component is not already in your overrides file, you can copy its YAML fromvalues.yaml into your overrides file and modify it there.

Annotations are key/value maps used to attach metadata to Apigee hybrid Kubernetes pods. You can create custom annotations for the following properties listed inConfiguration property reference:

• cassandra
• connectAgent
• logger
• mart
• metrics
• runtime
• synchronizer
• udca
• watcher

To add a custom annotation, add a stanza to theOVERRIDES.yaml file for the respective component.

The following example illustrates how an annotation can be specified inruntime pods:

runtime:annotations:businessunit:"bu1"

Test the merged configuration

You can use the--dry-run flag to test the merged configuration file without actually applying it to your cluster. This option is useful for debugging an installation problem because it shows you exactly what will be applied to the cluster. It is also a good practice to test the configuration and store it in source control so that you have a reference of the resources installed and configured in the cluster.

kubectl apply -k  apigee-operator/etc/crds/default/

helm upgrade operator apigee-operator/ \  --install \  --namespaceAPIGEE_NAMESPACE \  --atomic \  -fOVERRIDES_FILE.yaml \  --dry-run=server

helm upgrade ingress-manager apigee-ingress-manager/ /  --install \  --namespaceAPIGEE_NAMESPACE \  --atomic \  -fOVERRIDES_FILE.yaml \  --dry-run=server

Create multiple overrides files as needed

You can create as many overrides files as you want, where each one serves a specific requirement. For example, you might have an overrides file that tunes your cluster for production, and another for creating a testing cluster. You can then maintain these files in your source control system.

For example:

helm upgradetest-1-env apigee-env/ \  --namespaceAPIGEE_NAMESPACE \  --atomic \  --set env=test-1-env \  -ftest-1-env-overrides.yaml

helm -nAPIGEE_NAMESPACE delete datastore

helm delete -n apigee my-cassandra-storage

helm upgradeENV_GROUP apigee-virtualhost/ \  --install \  --namespaceAPIGEE_NAMESPACE \  --atomic \  --set envgroup=ENV_GROUP_NAME \  -fOVERRIDES_FILE.yaml