Step 4: Configure the user cluster
You are currently viewing version 1.3 of the Apigee hybrid documentation.This version is end of life. You should upgrade to a newer version. For more information, seeSupported versions.
Note: If you want to create a security perimeter around your cluster and related Cloud services, you can configure one using Google Cloud Virtual Private Cloud (VPC) Service Controls with Apigee hybrid. SeeUsing VPC Service Controls with Apigee and Apigee hybrid for instructions.
Specify configuration overrides
The Apigee hybrid installer uses defaults for many settings; however, there are a few settings that do not have defaults. You must provide values for these settings, as explained next.
- Be sure you are in the
hybrid-base-directory/hybrid-files/overrides/directory.cdhybrid-base-directory/hybrid-files/overrides
- Create a new file named
overrides.yamlin your favorite text editor. For example:vioverrides.yaml
The
overrides.yamlprovides the configuration for your unique Apigee hybrid installation. The overrides file in this step provides a basic configuration for a small-footprint hybrid runtime installation, suitable for your first installation. - In
overrides.yaml, add the required property values, shown below. A detailed description of each property is also provided below:Syntax
Make sure the
overrides.yamlfile has the following structure and syntax. Values inred, bold italics are property values that you must provide. They are described in thetable below.gcp: region:analytics-region # Choose the closest Google Cloud region to your cluster. projectID:gcp-project-idk8sCluster: name:cluster-name region:analytics-region # Choose the closest Google Cloud region to your cluster.org:org-nameinstanceID: "unique-instance-identifier"cassandra: hostNetwork: false #Set this to `true` for GKE-On-prem installations.virtualhosts: - name:environment-group-name sslCertPath: ./certs/cert-name.pem sslKeyPath: ./certs/key-name.keyenvs: - name:environment-name serviceAccountPaths: synchronizer: ./service-accounts/synchronizer-service-account-name.json udca: ./service-accounts/udca-service-account-name.jsonmart: serviceAccountPath: ./service-accounts/mart-service-account-name.jsonconnectAgent: serviceAccountPath: ./service-accounts/mart-service-account-name.json #Same account used for mart and connectAgentmetrics: serviceAccountPath: ./service-accounts/metrics-service-account-name.jsonwatcher: serviceAccountPath: ./service-accounts/watcher-service-account-name.jsonlogger: enabled: true serviceAccountPath: ./service-accounts/logger-service-account-name.json
Example
The following example shows a completed overrides file with example property values added:
gcp: region: us-central1 projectID: hybrid-examplek8sCluster: name: apigee-hybrid region: us-central1org: hybrid-exampleinstanceID: "my_hybrid_example"cassandra: hostNetwork: false #Set this to `true` for GKE-On Prem installations.virtualhosts: - name: example-env-group sslCertPath: ./certs/keystore.pem sslKeyPath: ./certs/keystore.keyenvs: - name: test serviceAccountPaths: synchronizer: ./service-accounts/hybrid-project-apigee-synchronizer.json udca: ./service-accounts/hybrid-project-apigee-udca.jsonmart: serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.jsonconnectAgent: serviceAccountPath: ./service-accounts/example-hybrid-apigee-mart.jsonmetrics: serviceAccountPath: ./service-accounts/hybrid-project-apigee-metrics.jsonwatcher: serviceAccountPath: ./service-accounts/hybrid-project-apigee-watcher.jsonlogger: enabled: true serviceAccountPath: ./service-accounts/logger-service-account-name.json
- When you are finished, save the file.
The following table describes each of the property values that you must provide in the overrides file. For more information, seeConfiguration property reference.
| Variable | Description |
|---|---|
| analytics-region | You must set this value to the same region where the cluster is running. This is the value you assigned to the environment variableANALYTICS_REGION previouslyduring cluster creation Theapigee-logger and theapigee-metrics push their data to this region. |
| gcp-project-id | Identifies the Google Cloud project where theapigee-logger and theapigee-metrics push their data. This is the value assigned to the environment variablePROJECT_ID. |
| cluster-name | Your Kubernetes cluster name. This is the value assigned to the environment variableCLUSTER_NAME. |
| org-name | The ID of your Apigee hybrid organization. This is the value assigned to the environment variableORG_NAME. |
| unique-instance-identifier | A unique string to identify this instance. This can be any combination of letters and numbers up to 63 characters in length. |
| environment-group-name | The name of the environment group your environments are assigned to. This is the group you created inProject and org setup - Step 6: Create an environment group. This is the value assigned to the environment variableENV_GROUP.Note:If you wish to place cluster instances in multiple regions, you must be careful about how you define your environments and virtual hosts. If you have one or more environments attached to an environment group, you must include that same environment group configuration in each cluster instance's overrides file. |
| cert-name key-name | Enter the name of the self-signed TLS key and certificate files that you generated previously inStep 3: Install apigeectl. These files must be located in thebase_directory/hybrid-files/certs directory. For example:sslCertPath: ./certs/keystore.pemsslKeyPath: ./certs/keystore.key |
| environment-name | Use the same name that you used when you created an environment in the UI, as explained inProject and org setup - Step 6: Create an environment group. |
| synchronizer-service-account-name | The name of thesynchronizer service account key file that you generated with thecreate-service-account tool. For example:serviceAccountPath: synchronizer: ./service-accounts/hybrid-project-apigee-synchronizer.json |
| udca-service-account-name | The name of theudca service account key file that you generated with thecreate-service-account tool. For example:serviceAccountPath: udca: ./service-accounts/hybrid-project-apigee-udca.json |
| mart-service-account-name | The name of themart service account key JSON file that you generated with thecreate-service-account tool. |
| metrics-service-account-name | The name of the metrics service account JSON file you generated with thecreate-service-account tool. For example:metrics: serviceAccountPath: ./service-accounts/hybrid-project-apigee-metrics.json |
| mart-service-account-name | The name of themart service account (which has theApigee Connect Agent role assigned to it) which you created inStep 3: Install apigeectl. MART and the Apigee Connect Agent use the same service account. |
| watcher-service-account-name | The name of thewatcher service account JSON file that you generated with thecreate-service-account tool. For example:watcher: serviceAccountPath: ./service-accounts/hybrid-project-apigee-watcher.json |
Summary
The configuration file tells Kubernetes how to deploy the hybrid components to a cluster. Next, you will apply this configuration to your cluster.
1234(NEXT) Step 5: Install hybrid runtimeExcept as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.