Configure virtual hosts

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 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: 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 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.