> [!CAUTION]
> 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, see [Supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions).

<button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">Version 1.2 (unsupported)</button>

- Supported versions:
- [v1.17 (latest)](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/base-path-routing.md.txt)
- [v1.16](https://docs.cloud.google.com/apigee/docs/hybrid/v1.16/base-path-routing.md.txt)
- [v1.15](https://docs.cloud.google.com/apigee/docs/hybrid/v1.15/base-path-routing.md.txt)
- [v1.14](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/base-path-routing.md.txt)
- [List of supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions)
- Unsupported versions:
- [v1.13](https://docs.cloud.google.com/apigee/docs/hybrid/v1.13/base-path-routing.md.txt)
- [v1.12](https://docs.cloud.google.com/apigee/docs/hybrid/v1.12/base-path-routing.md.txt)
- [v1.11](https://docs.cloud.google.com/apigee/docs/hybrid/v1.11/base-path-routing.md.txt)
- [v1.10](https://docs.cloud.google.com/apigee/docs/hybrid/v1.10/base-path-routing.md.txt)
- [v1.9](https://docs.cloud.google.com/apigee/docs/hybrid/v1.9/base-path-routing.md.txt)
- [v1.8](https://docs.cloud.google.com/apigee/docs/hybrid/v1.8/base-path-routing.md.txt)
- [v1.7](https://docs.cloud.google.com/apigee/docs/hybrid/v1.7/base-path-routing.md.txt)
- [v1.6](https://docs.cloud.google.com/apigee/docs/hybrid/v1.6/base-path-routing.md.txt)
- [v1.5](https://docs.cloud.google.com/apigee/docs/hybrid/v1.5/base-path-routing.md.txt)
- [v1.4](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/base-path-routing.md.txt)
- [v1.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/base-path-routing.md.txt)
- [v1.2](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/base-path-routing.md.txt)
- [v1.1](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/base-path-routing.md.txt)

> [!NOTE]
> **NOTE:** The `virtualhosts` configuration is new in version 1.2.0. The virtual host `name` 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 the
`virtualhosts.routingRules[]` configuration property. For details on the
individual properties, see [virtualhosts](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/config-prop-ref.md.txt#virtualhosts)
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: test2

envs:
  - 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 the `test1` environment's message processor. Similarly, if a request to
`https://api.example.com/customers` comes in, it is routed to the `test2`
environment.

## Adding a new environment


To add a new environment, add its configuration to the `envs[]` property, and
add a new `virtualhosts.routingRules.path` entry that specifies which base paths you
want to map to the new environment. In the following example, a new environment named
`test3` is added, and the `routingRules` 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: test3

envs:
  - 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 the `runtime` component, as follows:

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

## Adding multiple virtual hosts


The `virtualhosts[]` 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 host `dev` handles
traffic sent to the `api.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: test3

envs:
  - 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 the `runtime` component, as follows:

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

> [!NOTE]
> **NOTE:** If you only add or change the `virtualhosts` 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:

- See [Obtain TLS credentials](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/lets-encrypt.md.txt) for a set of sample steps for creating an authorized TLS certificate/key pair.
- You can use a self-signed certificate/key pair(s) for testing purposes only. See [Generate self-signed TLS credentials](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/environment-self-signed-tls.md.txt).