Configure base path routing

Version 1.1 (unsupported)keyboard_arrow_down

This topic discusses base path routing. Base path routing allows you to configure and manage how Apigee hybrid routes API proxy calls to the correct environment.

Use base path routing to manage proxy deployments

Because you can map a single virtual host to multiple environments in hybrid, you need a way to specify which proxy base path maps to which environment.

For example, let's say you want to map two environments to the same host alias: apitest.mydomain.net. In your overrides file, you could create the following configuration where environments dev1 and dev2 both map to this host. For example:

envs:
  - name: dev1
    hostAlias: "apitest.mydomain.net"
    ...
  - name: dev2
    hostAlias: "apitest.mydomain.net"
    ...

Now, let's say you deploy proxies to these environments. You deploy:

Proxy foo1 with base path /foo1 to dev1
Proxy foo2 with base path /foo2 to dev2

Suppose a client calls this API: https://apitest.mydomain.net/foo1. Note there's nothing in this path (or in the host header that's generated for the request) that tells hybrid which environment to route the call to. Is the foo1 proxy deployed to dev1 or dev2? Based only on the request URL, there's no way to tell. You must explicitly map each of these base paths to one or more environments.

To specify which environment a proxy call should be routed to, add the paths.uri.prefixes property to the envs property in your overrides file, as shown in the following example:

gcpProjectID: example
k8sClusterName: apigee-hybrid

# Apigee org name.
org: my-org

envs:
    # Apigee environment name.
  - name: dev1
    hostAlias: "apitest.mydomain.net"
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    serviceAccountPaths:
      synchronizer: ./service-accounts/example-apigee-synchronizer.json
      udca: ./service-accounts/example-apigee-udca.json
    paths:
      uri:
        prefixes:
          - /foo1
  - name: dev2
    hostAlias: "apitest.mydomain.net"
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    serviceAccountPaths:
      synchronizer: ./service-accounts/example-apigee-synchronizer.json
      udca: ./service-accounts/example-apigee-udca.json
    paths:
      uri:
        prefixes:
          - /foo2
    ...

Now, when an API call comes in such as: https://apitest.mydomain.net/foo1, the ingress router knows where to send it. It knows that the /foo1 proxy is deployed to the dev1 environment, and the call gets routed to dev1's message processor.

If you send this call, https://apitest.mydomain.net/foo2, it is likewise routed to the dev2 environment's MP, and so on.

In summary, the paths.uri.prefixes configuration lets you manage proxy deployments among multiple environments that share the same host alias.

Best Practice: Use base path routing when you want multiple environments to share the same host alias. Base path routing lets you limit the number of proxies deployed to any single environment. For more information, see Limit the number of proxy deployments.

Add a new environment to the same domain

This section explains how to add a new environment to a domain.

In this scenario, assume that you have an environment dev1 already deployed to the cluster. In this example configuration, only proxies with the basepath prefix /foo1 are allowed:

gcpProjectID: example
k8sClusterName: apigee-hybrid

# Apigee org name.
org: my-org

envs:
    # Apigee environment name.
  - name: dev1
    hostAlias: "apitest.mydomain.net"
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    serviceAccountPaths:
      synchronizer: ./service-accounts/example-apigee-synchronizer.json
      udca: ./service-accounts/example-apigee-udca.json
    paths:
      uri:
        prefixes:
          - /foo1

mart:
  hostAlias: "mart.apigee-hybrid-docs.net"
  serviceAccountPath: ./service-accounts/example-apigee-mart.json
  sslCertPath: ./certs/fullchain.pem
  sslKeyPath: ./certs/privkey.key

metrics:
  serviceAccountPath: ./service-accounts/willwitman-istio-25240157d44a.json

To add another environment that shares the same domain, follow these steps:

Create a new overrides file with the new enviroment configuration. For example, this configuration creates an environment called dev2. In this environment, only proxies with the path suffix /foo2 are allowed:

gcpProjectID: example
k8sClusterName: apigee-hybrid

# Apigee org name.
org: my-org

envs:
    # Apigee environment name.
  - name: dev2
    hostAlias: "apitest.mydomain.net"
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    serviceAccountPaths:
      synchronizer: ./service-accounts/example-apigee-synchronizer.json
      udca: ./service-accounts/example-apigee-udca.json
    paths:
      uri:
        prefixes:
          - /foo2

mart:
  hostAlias: "mart.apigee-hybrid-docs.net"
  serviceAccountPath: ./service-accounts/example-apigee-mart.json
  sslCertPath: ./certs/fullchain.pem
  sslKeyPath: ./certs/privkey.key

metrics:
  serviceAccountPath: ./service-accounts/willwitman-istio-25240157d44a.json

Run the following commands in any order:

apigeectl apply -f overrides/overrides-dev2.yaml -c udca

apigeectl apply -f overrides/overrides-dev2.yaml -c synchronizer

apigeectl apply -f overrides/overrides-dev2.yaml -c runtime

Deploy the proxy foo2 to the dev2 environment.
Call the proxy to test the setup.
```
curl https://apitest.mydomain.net/foo2
```

Add a new proxy base path to an existing environment

To add a new base path to an existing environment, simply add a prefixes entry for each new base path. For example, if you create a new proxy with the base path /foo4, and you want to deploy it to the environment called dev2, follow these steps:

Open the overrides file that has the definition of the dev2 environment.

Add the /foo4 base path to the paths.uri.prefixes element:

gcpProjectID: example
k8sClusterName: apigee-hybrid

# Apigee org name.
org: my-org

envs:
    # Apigee environment name.
  - name: dev2
    hostAlias: "apitest.mydomain.net"
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    serviceAccountPaths:
      synchronizer: ./service-accounts/example-apigee-synchronizer.json
      udca: ./service-accounts/example-apigee-udca.json
    paths:
      uri:
        prefixes:
          - /foo2
          - /foo4

mart:
  hostAlias: "mart.apigee-hybrid-docs.net"
  serviceAccountPath: ./service-accounts/example-apigee-mart.json
  sslCertPath: ./certs/fullchain.pem
  sslKeyPath: ./certs/privkey.key

metrics:
  serviceAccountPath: ./service-accounts/willwitman-istio-25240157d44a.json

Apply the runtime component to the cluster:

apigeectl apply -f overrides/overrides-dev2.yaml -c runtime

Call the proxy to test the setup.

curl https://apitest.mydomain.net/foo4

If an API call comes in for https://apitest.mydomain.net/foo4, hybrid knows to route it to environment dev2.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-06-09 UTC.