Step 7: Configure the hybrid runtime

You are currently viewing version 1.7 of the Apigee hybrid documentation.This version is end of life. You should upgrade to a newer version. For more information, seeSupported versions.

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.

  1. Be sure you are in thehybrid-base-directory/hybrid-files/overrides/ directory.
    cdhybrid-base-directory/hybrid-files/overrides
  2. Create a new file namedoverrides.yaml in your favorite text editor. For example:
    vioverrides.yaml

    Theoverrides.yaml provides 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.

  3. Inoverrides.yaml, add the required property values, shown below. A detailed description of each property is also provided below:

    For installations in production environments, look at the storage requirements for the Cassandra database inConfigure Cassandra for production.

    Syntax

    Make sure theoverrides.yaml file has the following structure and syntax. Values inred, bold italics are property values that you must provide. They are described in thetable below.

    There are differences between the different platforms for the Google Cloud project region and Kubernetes cluster region. Choose the platform where you are installing Apigee hybrid.

    gcp:  region:analytics-region  projectID:gcp-project-idk8sCluster:  name:cluster-name  region:cluster-location # Must be the closest Google Cloud region to your cluster.org:org-nameinstanceID: "unique-instance-identifier"  # See the property description table below information about this parameter.  cassandra:  hostNetwork:false    # Set tofalse for single region installations and multi-region installations    # with connectivity between pods in different clusters, for example GKE installations.    # Set totrue  for multi-region installations with no communication between    # pods in different clusters, for example GKE On-prem, GKE on AWS, Anthos on bare metal,    # AKS, EKS, and OpenShift installations.    # SeeMulti-region deployment: Prerequisites  storage:    capacity: 500Gi  resources:    requests:      cpu: 7      memory: 15Gi  maxHeapSize: 8192M  heapNewSize: 1200M    # Minimum storage requirements for a production environment.    # SeeConfigure Cassandra for production.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        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-synchronizer.json      udca: ./service-accounts/udca-service-account-name.json        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-udca.json      runtime: ./service-accounts/runtime-service-account-name.json        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-runtime.jsonmart:  serviceAccountPath: ./service-accounts/mart-service-account-name.json        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-mart.jsonconnectAgent:  serviceAccountPath: ./service-accounts/mart-service-account-name.json        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-mart.json        #Use the same service account for mart and connectAgentmetrics:  serviceAccountPath: ./service-accounts/metrics-service-account-name.json        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-metrics.jsonudca:  serviceAccountPath: ./service-accounts/udca-service-account-name.json        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-udca.jsonwatcher:  serviceAccountPath: ./service-accounts/watcher-service-account-name.json        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-watcher.jsonlogger:  enabled:false        # Set tofalse to disable logger for GKE installations.        # Set totrue for all platforms other than GKE.        # Seeapigee-logger inService accounts and roles used by hybrid components.  serviceAccountPath: ./service-accounts/logger-service-account-name.json        # for non-production environments,gcp-project-id-apigee-non-prod.json        # for production environments,gcp-project-id-apigee-logger.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: falsevirtualhosts:  - name: example-env-group    sslCertPath: ./certs/keystore.pem    sslKeyPath: ./certs/keystore.keyenvs:  - name: test    serviceAccountPaths:      synchronizer: ./service-accounts/hybrid-project-apigee-non-prod.json        # for production environments, hybrid-project-apigee-synchronizer.json      udca: ./service-accounts/hybrid-project-apigee-non-prod.json        # for production environments, hybrid-project-apigee-udca.json      runtime: ./service-accounts/hybrid-project-apigee-non-prod.json        # for production environments, hybrid-project-apigee-runtime.jsonmart:  serviceAccountPath: ./service-accounts/hybrid-project-apigee-non-prod.json    # for production environments, hybrid-project-apigee-mart.jsonconnectAgent:  serviceAccountPath: ./service-accounts/hybrid-project-apigee-non-prod.json    # for production environments, example-hybrid-apigee-mart.jsonmetrics:  serviceAccountPath: ./service-accounts/hybrid-project-apigee-non-prod.json    # for production environments, hybrid-project-apigee-metrics.jsonudca:  serviceAccountPath: ./service-accounts/hybrid-project-apigee-non-prod.json    # for production environments, hybrid-project-apigee-udca.jsonwatcher:  serviceAccountPath: ./service-accounts/hybrid-project-apigee-non-prod.json    # for production environments, hybrid-project-apigee-watcher.jsonlogger:  enabled: false # Set to "false" for GKE. Set to "true" for all other kubernetes platforms.  serviceAccountPath: ./service-accounts/hybrid-project-apigee-non-prod.json    # for production environments, logger-service-account-name.json
  4. 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.

VariableDescription
analytics-regionIn GKE, You must set this value to the same region where the cluster is running. In all other platforms, select the closest analytics region to your cluster that has Analytics support (see the table inPart 1, Step 4: Create an organization.

This is the value you assigned to the environment variableANALYTICS_REGION previously.

gcp-project-idIdentifies the Google Cloud project where theapigee-logger and theapigee-metrics push their data. This is the value assigned to the environment variablePROJECT_ID.
cluster-nameYour Kubernetes cluster name. This is the value assigned to the environment variableCLUSTER_NAME.
cluster-locationThe region where the cluster is running. This is the region where you created the cluster inStep 1: Create an cluster.

This is the value you assigned to the environment variableCLUSTER_LOCATION previously.

If you are working with zonal clusters, you must specify theregion in which your cluster was created. For example, if you created your cluster in theus-central1-a zone, specifyus-central1 for thecluster-location.
org-nameThe 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 Apigee hybrid instance per cluster. The string can be a combination of letters and numbers up to 63 characters in length.

  • You can create multiple organizations in a single cluster. Just make sure to use the sameinstanceID value for each time you add a new org to the same cluster.
  • If you have multiple clusters (in the same region or across multiple regions), each cluster requires a uniqueinstanceID.

If you need help generating a unique ID, you can use a random string generation tool of your choice, such asrandom.org/strings.

environment-group-nameThe name of the environment group your environments are assigned to. This is the group you created inProject and org setup - Step 5: 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 6: Create TLS certificates. These files must be located in thebase_directory/hybrid-files/certs directory. For example:
sslCertPath: ./certs/keystore.pemsslKeyPath: ./certs/keystore.key
environment-nameUse the same name that you used when you created an environment in the UI, as explained inProject and org setup - Step 5: Create an environment group.
synchronizer-service-account-nameFor non-production environments, the name of the single service account,non-prod by default. For production environments, the name of theapigee-synchronizer service account key file that you generated with thecreate-service-account tool inHybrid runtime setup - Step 6: Create service accounts and credentials. You can see the list of service account files in yourservice-accounts/ directory. Fore example:
ls ../service-accounts/
udca-service-account-nameFor non-production environments, the name of the single service account,non-prod by default. For production environments, the name of theapigee-udca service account key file that you generated with thecreate-service-account tool.
runtime-service-account-nameFor non-production environments, the name of the single service account,non-prod by default. For production environments, the name of theapigee-runtime service account key file that you generated with thecreate-service-account tool.
mart-service-account-nameFor non-production environments, the name of the single service account,non-prod by default. For production environments, the name of theapigee-mart service account key file that you generated with thecreate-service-account tool.Note:Bothmart andconnectAgent use theapigee-mart service account.
metrics-service-account-nameFor non-production environments, the name of the single service account,non-prod by default. For production environments, the name of theapigee-metrics service account key file that you generated with thecreate-service-account tool.
udca-service-account-nameFor non-production environments, the name of the single service account,non-prod by default. For production environments, the name of theapigee-udca service account key file that you generated with thecreate-service-account tool.
watcher-service-account-nameFor non-production environments, the name of the single service account,non-prod by default. For production environments, the name of theapigee-watcher service account key file that you generated with thecreate-service-account tool.
logger-service-account-nameFor non-production environments, the name of the single service account,non-prod by default. For production environments, the name of theapigee-logger service account key file that you generated with thecreate-service-account tool.
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.

Summary

The configuration file tells Kubernetes how to deploy the hybrid components to a cluster. Next, you will enable synchronizer access so the Apigee runtime and management planes will be able to communicate.

1234567(NEXT) Step 8: Enable Synchronizer access9

Except 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 2025-12-17 UTC.