Configure environments

An environment provides an isolated context or "sandbox" for running API proxies. In a single organization, you can have multiple environments, and each environment has an Istio ingress gateway service mapped to it. All traffic from outside the cluster passes through this TLS-secured ingress endpoint.

During a basic installation, you likely set up a single environment for testing. Most Apigee Hybrid installations, however, have multiple environments. For example, a common use case is to have a test environment and a production environment.

This section describes how to add and remove Hybrid environments.

Create a new environment

Before you create a new environment, you must generate a TLS key and certificate and set up your DNS to for the new environment's host alias.

To create a new environment:

  1. Open the overrides.yaml file for edit if it is not already open.
  2. Add a new environment to the envs array.

    The following example shows the overrides.yaml syntax for more than one environment:

    namespace: namespace
    org: apigee-organization-name
    envs:
      - name: environment-1-name
        sslCertPath: "path_to_cert_1"
        sslKeyPath: "path_to_key_1"
        hostAlias: "domain_name_1"
      - name: environment-2-name
        sslCertPath: "path_to_cert_2"
        sslKeyPath: "path_to_key_2"
        hostAlias: "domain_name_2"
    ...

    Note that the each environment must have unique names, host aliases, and key/cert files.

  3. Set the values of the following properties for the new environment:

    Property Value
    envs.name

    Required) The programmatic name for the environment. This value will be part of the request URL for your API proxies.

    envs.sslCertPath (Required)

    The path on your system to a TLS certificate file.

    For testing purposes only, you can use a self-signed certificate, as described in Create a self-signed certificate/key pair.

    envs.sslKeyPath (Required)

    The path on your system to a TLS key file.

    For testing purposes only, you can use a self-signed certificate, as described in Create a self-signed certificate/key pair.

    envs.hostAlias. (Required)

    The DNS name for your server. For example, foo-test.mydomain.com. If you don't have a DNS name, you can use a wildcard ('*'). If you use a wildcard, then you can use the EXTERNAL IP of the istio-ingressgateway, which you can obtain by calling kubectl get services -n namespace after you complete the installation.

    If you have multiple environments, you must use a unique host alias name for each one. For example, foo-test.mydomain.com and foo-prod.mydomain.com.

    For more information, see Host aliases.

    The following example shows a sample overrides.yaml file with two environments (test and prod):

    namespace: my-namespace
    org: my-organization
    envs:
      - name: test
        sslCertPath: "/my-dir/test-ingress-cert.crt"
        sslKeyPath: "/my-dir/test-ingress-key.key"
        hostAlias: "foo-test.mydomain.com"
      - name: prod
        sslCertPath: "/my-dir/prod-ingress-cert.crt"
        sslKeyPath: "/my-dir/prod-ingress-key.key"
        hostAlias: "foo-prod.mydomain.com"
    ...
  4. Save your changes.

    You're not quite done. You must now add the new environment in the Hybrid UI.

  5. Open a browser and navigate to the Hybrid UI.
  6. Add the new environment using the steps described in Create a new environment in the Hybrid UI.

Remove an environment

To remove an environment:

  1. Open the overrides.yaml file for edit if it is not already open.
  2. Remove the environment from the envs array.
  3. Save your changes.

    You're not quite done. You must now update the environments in the Hybrid UI.

  4. Open a browser and navigate to the Hybrid UI at Hybrid UI.
  5. Remove the environment using the steps described Delete an existing environment in the Hybrid UI.

Host aliases

If you have multiple environments, each one must have its own unique DNS name; for example, the test and prod environments might have the foo-test.mydomain.com and foo-prod.mydomain.com DNS names.

DNS names map to host aliases in a Hybrid configuration. If you are familiar with virtual hosts in Apigee Edge, the concept of a host alias in Hybrid is similar. For example, if the host alias is foo-test.mydomain.com, you might call an API proxy called /helloworld like using a URL like https://foo-test.mydomain.com/helloworld.

TLS keys and certificates

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

For testing purposes, you can use a self-signed certificate/key pair(s).

To generate a self-signed pair:

  1. Create a directory to contain the key and certificate for the ingress.
  2. Generate the key and certificate by executing the following commands:
    openssl genrsa -des3 -out /my-dir/server.pass.key 2048
      openssl rsa -in /my-dir/server.pass.key -out /my-dir/ingress-server.key
      openssl req -nodes -new -key /my-dir/ingress-server.key -out /my-dir/ingress-server.csr
      openssl x509 -req -sha256 -days 365 -in /my-dir/ingress-server.csr -signkey /my-dir/ingress-server.key -out /my-dir/ingress-server.crt