Configure virtual hosts

You are currently viewing version 1.2 of the Apigee hybrid documentation.This version is end of life. You should upgrade to a newer version. For more information, seeSupported versions.
NOTE:Thevirtualhosts configurationis new in version 1.2.0. The virtual hostname must:
  • contain no more than 253 characters
  • contain only lowercase alphanumeric characters or a hyphen-
  • start with an alphanumeric character
  • end with an alphanumeric character

This topic discusses virtual host configuration. Virtual hosts allow Apigee hybrid to handle API requests to multiple domain names and route proxy basepaths to specific environments.

To specify which environment specific API proxy base paths should be routed to, use thevirtualhosts.routingRules[] configuration property. For details on the individual properties, seevirtualhosts in the Configuration property reference. For example:

...virtualhosts:  - name: vhost-one    hostAliases: ["api.example.com"]    sslCertPath: ./certs/fullchain.pem    sslKeyPath: ./certs/privkey.pem    routingRules:      - paths:        - /orders        - /items        env: test1      - paths:        - /customers        env: test2envs:  - name: test1    serviceAccountPaths:      synchronizer: ./sa/synchronizer.json      udca: ./sa/udca.json  - name: test2    serviceAccountPaths:      synchronizer: ./sa/synchronizer.json      udca: ./sa/udca.json

When an API call comes in such as:https://api.example.com/orders, the request is sent to thetest1 environment's message processor. Similarly, if a request tohttps://api.example.com/customers comes in, it is routed to thetest2 environment.

Adding a new environment

To add a new environment, add its configuration to theenvs[] property, and add a newvirtualhosts.routingRules.path entry that specifies which base paths you want to map to the new environment. In the following example, a new environment namedtest3 is added, and theroutingRules have been updated to route two paths to the new environment:

virtualhosts:  - name: vhost-one    hostAliases: ["api.example.com"]    sslCertPath: ./certs/fullchain.pem    sslKeyPath: ./certs/privkey.pem    routingRules:      - paths:        - /orders        - /items        env: test1      - paths:        - /v0/hello        - /httpbin        env: test2      - paths:        - /v0/inventory        - /v0/customers        env: test3envs:  - name: test1    serviceAccountPaths:      synchronizer: ./sa/synchronizer.json      udca: ./sa/udca.json  - name: test2    serviceAccountPaths:      synchronizer: ./sa/synchronizer.json      udca: ./sa/udca.json  - name: test3    serviceAccountPaths:      synchronizer: ./sa/synchronizer.json      udca: ./sa/udca.json

To apply the update, you only need to apply theruntime component, as follows:

apigeectl apply -foverrides-file.yaml -c runtime

Adding multiple virtual hosts

Thevirtualhosts[] property is an array, and therefore you can create more than one. Each virtual host must contain a unique set of host aliases: no two virtual hosts can share the same host alias. For example, the new virtual hostdev handles traffic sent to theapi.internal.com domain.

virtualhosts:  - name: vhost-one    hostAliases: ["api.example.com"]    sslCertPath: ./certs/fullchain.pem    sslKeyPath: ./certs/privkey.pem    routingRules:      - paths:        - /orders        - /items        env: test1      - paths:        - /v0/hello        - /httpbin        env: test2      - paths:        - /v0/inventory        - /v0/customers        env: test3  - name: vhost-two    hostAliases: ["api.internal.com"]    sslCertPath: ./certs/fullchain.pem    sslKeyPath: ./certs/privkey.pem    routingRules:      - paths:        - /orders        - /items        env: test1      - paths:        - /v0/hello        - /httpbin        env: test2      - paths:        - /v0/inventory        - /v0/customers        env: test3envs:  - name: test1    serviceAccountPaths:      synchronizer: ./sa/synchronizer.json      udca: ./sa/udca.json  - name: test2    serviceAccountPaths:      synchronizer: ./sa/synchronizer.json      udca: ./sa/udca.json  - name: test3    serviceAccountPaths:      synchronizer: ./sa/synchronizer.json      udca: ./sa/udca.json

To apply the update, you only need to apply theruntime component, as follows:

apigeectl apply -foverrides-file.yaml -c runtime
NOTE:If you only add or change thevirtualhosts stanza, and nothing else, then you can apply those changes with the--settings flag:
apigeectl apply -f overrides-file.yaml --settings virtualhosts -c runtime

If you change virtualhosts and envs, then you must apply the change without using--settings, like this, to update the runtime component fully:

apigeectl apply -f overrides-file.yaml -c runtime

TLS keys and certificates

When you create a new virtual host, you must provide a TLS key and certificate. The key/cert are used to provide secure communication with the ingress gateway.

It is up to you how you generate proper TLS certificate/key pairs for your hybrid configuration. The following topics are provided as samples only, intended primarily for trying out or testing a new hybrid installation if it isn't feasible to obtain TLS credentials in another way:

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 2026-02-19 UTC.