Configure virtual hosts

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

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: