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 thepaths.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 environmentdev2
.