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.