Create environments

This topic explains how to create new environments for Apigee hybrid. For an introduction, see About environments and environment groups.

About environment creation

Environment creation includes the following tasks:

  • Create the environment in the management plane using either the Apigee UI or the Create environments API, and attach it to an environment group.
  • Add the environment to your overrides file and install the environment's runtime components in your cluster with the apigee-env Helm chart.

For the first environment of a new installation, these tasks are explained in Step 3: Add an environment and Specify configuration overrides. To remove an environment, see Delete environments.

How to create an environment

The following steps add a prod environment to an installation that already has a test environment.

  1. Create the environment in the management plane with the Apigee UI or the Create environments API. For the detailed steps, see Step 3: Add an environment.
  2. Attach the environment to an environment group. Apigee routes API traffic to an environment only through an environment group. You can attach the environment to an existing environment group in the Apigee UI, or with the Environment group attachment API as follows:

    1. On the command line, get your gcloud authentication credentials using the following command:

      Linux / MacOS 

      TOKEN=$(gcloud auth print-access-token)

      Windows 

      for /f "tokens=*" %a in ('gcloud auth print-access-token') do set TOKEN=%a
    2. Attach the environment to the environment group:

      No data residency

      curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "prod"}' \
  "https://apigee.googleapis.com/v1/organizations/ORG_NAME/envgroups/ENV_GROUP/attachments"

      Data residency

      curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "prod"}' \
  "https://CONTROL_PLANE_LOCATION-apigee.googleapis.com/v1/organizations/ORG_NAME/envgroups/ENV_GROUP/attachments"

      Where:

      • ORG_NAME is the name of your Apigee organization.
      • ENV_GROUP is the name of the environment group.
      • CONTROL_PLANE_LOCATION is the control plane location of your organization if you use data residency.

      The output is similar to the following:

      {
  "name": "organizations/ORG_NAME/operations/d4ce8118-6355-451e-bbe9-460e58d9d268",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "organizations/ORG_NAME/envgroups/ENV_GROUP/attachments/ca81c6ec-e49a-49cd-8f97-63b402deee76",
    "state": "FINISHED"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.EnvironmentGroupAttachment",
    "name": "ca81c6ec-e49a-49cd-8f97-63b402deee76",
    "environment": "prod"
  }
}

  3. Add a new environment definition to the envs[] property in your overrides file. The property is an array, so you can add more than one environment definition to it. Give the new environment the same name as the environment you created in the management plane. For example, the following configuration defines two environments, test and prod:

    namespace: my-namespace
org: my-organization
...
envs:
  - name: test
    serviceAccountPaths:
      synchronizer: "your_keypath/PROJECT_ID-apigee-synchronizer.json"
      runtime: "your_keypath/PROJECT_ID-apigee-runtime.json"
      udca: "your_keypath/PROJECT_ID-apigee-udca.json"

  - name: prod
    serviceAccountPaths:
      synchronizer: "your_keypath/PROJECT_ID-apigee-synchronizer.json"
      runtime: "your_keypath/PROJECT_ID-apigee-runtime.json"
      udca: "your_keypath/PROJECT_ID-apigee-udca.json"
...

  4. Install the apigee-env chart for the new environment. You must install one environment at a time, specified with --set env=ENV_NAME.

    1. Dry run:

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server

      Where:

      • ENV_RELEASE_NAME is a name used to keep track of installation and upgrades of the apigee-env chart. Helm release names must be unique within your Apigee hybrid installation. If your environment name is unique, this can be the same as ENV_NAME. However, if your environment and environment group have the same name, use a different Helm release name for each. For example, if both are named dev, you could use dev-env-release and dev-envgroup-release. For more information on releases in Helm, see Three big concepts in the Helm documentation.
      • APIGEE_NAMESPACE is the namespace where you installed Apigee hybrid, apigee by default.
      • ENV_NAME is the name of the new environment.
      • OVERRIDES_FILE is the path to your overrides file.

      If ENV_NAME doesn't match an entry in envs[], the command fails with an error similar to Environment 'prod' not found in the provided environments.

    2. Install the chart:

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE

      For example, to install the prod environment:

      helm upgrade prod apigee-env/ --install --namespace apigee --atomic --set env=prod -f overrides.yaml
Release "prod" does not exist. Installing it now.
NAME: prod
...
STATUS: deployed
REVISION: 1

      If you use Workload Identity, grant the new environment's Kubernetes service accounts access to the IAM service accounts. The environment-scoped Kubernetes service account names include a hash of the environment name, so the bindings that you created for other environments don't apply to the new environment. For Workload Identity on GKE, run the commands in the NOTES section of the helm upgrade output. For more information, see Enabling Workload Identity on GKE or Enabling Workload Identity Federation on AKS and EKS.

    3. Verify that the environment is running:

      kubectl -n APIGEE_NAMESPACE get apigeeenv

      The output is similar to the following:

      NAME                          STATE     AGE   GATEWAYTYPE
apigee-my-org-prod-e8d4a16    running   3m
apigee-my-org-test-f86941d    running   22d

For more information about virtual host configuration, see Configure virtual hosts. For a complete list of environment configuration elements, see envs in the Configuration property reference.