This topic explains how to configure and manage the Apigee hybrid runtime plane components. For a list of the runtime plane components that you can configure, see Runtime service configuration overview.
About the overrides file
The first time you install the hybrid runtime into a cluster, you must create a configuration overrides 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 hybrid installation 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:
Scope | Components | Helm chart |
---|---|---|
Apigee operator | Apigee operator | apigee-operator |
Storage | Cassandra | apigee-datastore |
In‑memory storage | Redis | apigee-redis |
Reporting | Logger Metrics |
apigee-telemetry |
Ingress | Apigee Ingress gateway | apigee-ingress-manager |
Organization | Apigee Connect Agent MART UDCA Watcher |
apigee-org |
Environment | Runtime Synchronizer |
apigee-env |
Environment group | virtualhost | apigee-virtualhost |
For example, to change the replica count on the Message processor, follow these steps:
- Open your
OVERRIDES
.yaml
file. Be sure to use the same overrides file that was used to install the hybrid runtime into the cluster. - Locate the
runtime
element in the file. For example:... runtime: nodeSelector: key: cloud.google.com/gke-nodepool value: apigee-runtime replicaCountMin: 1 replicaCountMax: 2 ...
-
Change the replica count properties as needed. For example:
runtime: nodeSelector: key: cloud.google.com/gke-nodepool value: apigee-runtime replicaCountMin: 2 replicaCountMax: 20 ...
- Upgrade the environment.
- ENV_RELEASE_NAME is the name with which you previously installed the
apigee-env
chart. In hybrid v1.10, it is usuallyapigee-env-ENV_NAME
. In Hybrid v1.11 and newer it is usually ENV_NAME. - ENV_NAME is the name of the environment you are upgrading.
- OVERRIDES_FILE is your new overrides file for v.1.3.6
- Upgrade the chart:
- Verify it is up and running by checking the state of the respective env:
You must install one environment at a time. Specify the environment with --set env=
ENV_NAME.
Dry run:
helm upgrade ENV_RELEASE_NAME apigee-env/ \ --install \ --namespace APIGEE_NAMESPACE \ --set env=ENV_NAME \ -f OVERRIDES_FILE \ --dry-run
helm upgrade ENV_RELEASE_NAME apigee-env/ \ --install \ --namespace APIGEE_NAMESPACE \ --set env=ENV_NAME \ -f OVERRIDES_FILE
kubectl -n APIGEE_NAMESPACE get apigeeenv
NAME STATE AGE GATEWAYTYPE apigee-org1-dev-xxx running 2d
Which configuration properties can you modify?
You can find the complete list of configurable properties in the Configuration 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
The Configuration 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-level ao
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 the ao.image.pullPolicy
property to
Always
, locate this YAML stanza in the overrides file and set
it as follows:
ao: image: pullPolicy: Always
For another example, the property cassandra.auth.admin.password
(as it
is listed in Configuration 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, the Configuration 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 the pre-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 and apply the overrides file to your cluster. See Step 6: Create the overrides for more information.
About configuration defaults
Apigee maintains its default component configuration in the file
HYBRID_ROOT_DIR/config/values.yaml
. Your overrides files follows the same YAML
structure as values.yaml
.
An overrides file typically includes only a subset of the configuration properties found in
values.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 also Test
the merged configuration.
The following code shows the default configuration for the mart
component as found in values.yaml
. Note that some values have
defaults, while others such as sslCertPath
and
sslKeyPath
do not. You must provide these missing values in your
overrides file, as explained in the installation steps.
If you want to change any of the default values, make sure they are editable by checking in the
Configuration 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.3.6" 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 from values.yaml
into your
overrides file and modify it there.
Custom annotations
Annotations are key/value maps used to attach metadata to Apigee hybrid Kubernetes pods. You can create custom annotations for the following properties listed in Configuration property reference:
To add a custom annotation, add a stanza to the OVERRIDES.yaml
file
for the respective component.
The following example illustrates how an annotation can be specified in runtime
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 \ --namespace apigee-system \ --atomic \ -f OVERRIDES_FILE.yaml \ --dry-run
helm upgrade ingress-manager apigee-ingress-manager/ / --install \ --namespace apigee \ --atomic \ -f OVERRIDES_FILE.yaml \ --dry-run
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 upgrade test-1-env apigee-env/ \ --namespace apigee \ --atomic \ --set env=test-1-env \ -f test-1-env-overrides.yaml
Delete hybrid-specific runtime plane components
The runtime plane components include synchronizer
,
mart
, runtime
,
cassandra
, and udca
.
To delete the hybrid-specific runtime plane components from your cluster, use the
helm delete
command. Be sure to specify the same overrides file that you used to
install the runtime components.
For example:
Using Helm, you must delete each component individually. For example, to delete the
cassandra
component, use the following command:
helm -n apigee delete datastore
In the example above the datastore component was installed with the name "datastore". If you
you installed it with a different name, then you would supply that name to delete the
component. For example if you installed the apigee-datastore
chart with
helm install my-cassandra-storage apigee-datastore/
. you would delete it with the
following command:
helm delete -n apigee my-cassandra-storage
To recreate recreate a specific component or components (the environment group in this example):
helm upgrade ENV_GROUP apigee-virtualhost/ \ --install \ --namespace apigee \ --atomic \ --set envgroup=ENV_GROUP_NAME \ -f OVERRIDES_FILE.yaml