Step 3: Create an environment group

In this step, you will create an environment and an environment group.

In Apigee, API proxies are deployed to environments, which provide isolated contexts for your proxies. Environments are organized into environment groups, which provide hostnames for all the proxies deployed to environments within the group. You must have at least one environment and at least one environment group. To learn more, see About environments and environment groups.

Create an environment

Create the environment first before creating the environment group. You can create an environment using the Apigee UI or using the API. You may want to use the UI for these steps to familiarize yourself with it.

Apigee UI

To access the UI and add an environment, perform the following steps:

  1. Open the Apigee UI. If this is the first time you are logging in, hybrid displays a consent dialog. If you are prompted to select from more than one account, choose the account that owns the project you created in Step 2: Create a Google Cloud project. Then click Allow.
  2. Your browser navigates to the UI main landing page:

    The landing page in the Apigee
    UI, which consists of left-hand navigation and large images that are links.

  3. Ensure that your organization is selected from the organization drop-down list. If it is not selected, select it from the drop-down list, as the following example shows:

    A list of organizations that are hybrid enabled

  4. Click Admin > Environments > Overview.

    The Apigee UI menu showing Admin, Environments, Overview expanded

    The Environments view is displayed, with no environments (yet):

    The Environments view, which is blank (no environments)

  5. Click +Environment.

    The New environment dialog is displayed:

    The new environment dialog

  6. Enter the following information in the New Environment dialog:
    1. Display name (Required): A friendly name for the environment that is used in the UI. For example, "My First Environment" or "test". Unlike the Environment name, the Display name can include uppercase and other special characters.
    2. Environment name (Required): The programmatic name for the environment; also known as the environment ID.

      For example, "my-environment" or "test".

      The Display name and the Environment name can be different.

    3. Description (Optional): Additional information about the environment that you want to add as a reminder of the purpose of the environment. For example, "Created during initial installation".
  7. Click Create.

    Apigee creates the new environment and indicates that it is Pending Provisioning:

    Pending Provisioning status
    message

    In a few moments, it changes to provisioned:

    New
    environment was provisioned message

    However, you're not quite done. You also need to add your new environment to the runtime's overrides.yaml file—but first you've got to install the runtime, so let's not get ahead of ourselves.

Apigee API

To create an environment with the Create environments API, perform the following steps:

  1. Open a terminal on the device you are using to manage Apigee.
  2. On the command line, get your gcloud authentication credentials using the following command:

    Linux / MacOS

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

    To check that your token was populated, use echo, as the following example shows:

    echo $TOKEN

    This should display your token as an encoded string.

    Windows

    for /f "tokens=*" %a in ('gcloud auth print-access-token') do set TOKEN=%a

    To check that your token was populated, use echo, as the following example shows:

    echo %TOKEN%

    This should display your token as an encoded string.

  3. Create the following environment variable:

    Linux / MacOS

    export ENV_NAME="YOUR_ENV_NAME"

    Windows

    set ENV_NAME="YOUR_ENV_NAME"

    Where:

    • ENV_NAME (Required) The environment name can contain lowercase letters, dashes, and numbers and must start with a lowercase letter. This name will be used as the identifier and cannot be changed after creation of the environment.
  4. Call the following Apigee API:
    curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json"   -d '{
        "name": "'"$ENV_NAME"'"
      }'   "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments"

    On a successful creation request, the Environments API should respond with a message similar to the following:

    {
      "name": "organizations/hybrid-example/operations/c2aee040-7e79-4fd4-b0cf-79ca1b7098a8",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
        "operationType": "INSERT",
        "targetResourceName": "organizations/hybrid-example/environments/example-env",
        "state": "IN_PROGRESS"
      }
    }

    As the state property in the response indicates, Apigee has started to create the new environment, so its state is IN_PROGRESS.

  5. Check to verify the environment was created successfully:
    curl -H "Authorization: Bearer $TOKEN" \
              "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments"

    On a successful creation request, the Environments API responds with a message similar to the following:

    [
      "your-environment-name"
    ]

Create an environment group

Now create an environment group and assign the environment you just created to it.

Apigee UI

To create an environment group using the Apigee UI, perform the following steps:

  1. Open the Apigee UI.
  2. Your browser navigates to the Apigee UI main landing page.

  3. Ensure that your organization is selected from the organization drop-down list. If it is not selected, select it from the drop-down list.
  4. Click Admin > Environments > Groups.

    The Environment Groups Overview view is displayed, with any created environment groups:

    The Environment groups view, showing any created groups

  5. Click +Environment Group.

    The Add an Environment Group dialog is displayed.

    Add Environment Group dialog showing blank Name field

  6. Enter a name and then click Add.
  7. Hold the pointer over the newly-created environment group and then click Edit .

    Add a hostname that all proxies deployed to environments within this group will use. This should be a domain you have management access to. The hostname can be the domain itself, like example.com or it can include a subdomain like my-proxies.example.com.

    If you need to register a domain, see a domain registrar like Google Domains.

  8. Edit Environment Group window showing no environments assigned

  9. Click Add (+).
  10. The Add environment dialog displays.
  11. Add environment dialog listing available environments

  12. Select an environment from the list and then click Add.

Apigee API

To create an environment group using the Apigee API:

  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. Create the following environment variables:

    Linux / MacOS

    export DOMAIN="YOUR_DOMAIN"
    export ENV_GROUP="YOUR_ENVIRONMENT_GROUP"

    Windows

     data-terminal-prefix=">">set ENV_GROUP="YOUR_ENVIRONMENT_GROUP"
     data-terminal-prefix=">">set DOMAIN="YOUR_DOMAIN"

    Where:

    • DOMAIN (Required) This is the hostname that all proxies deployed to environments within this group will use. This should be a domain you manage. The address can be the domain itself, like example.com or it can include a subdomain like my-proxies.example.com. If you don't have a managed domain, you can enter a placeholder for now. You can change the domain address later.
    • ENV_GROUP (Required) The environment name can contain lowercase letters, dashes, and numbers and must start with a lowercase letter. This name will be used as the identifier and cannot be changed after creation.
  3. Create the environment group:
    curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" \
       -d '{
         "name": "'"$ENV_GROUP"'",
         "hostnames":["'"$DOMAIN"'"]
       }' \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups"
        
  4. Assign the environment to the new group:
    curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" \
       -d '{
         "environment": "'"$ENV_NAME"'",
       }' \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups/$ENV_GROUP/attachments"
        
  5. Verify whether the environment group was created successfully with the following CURL command:
    curl -H "Authorization: Bearer $TOKEN" \ 
          "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups"

    On a successful creation request, the Environments Group API responds with a message similar to the following:

          {
            "environmentGroups": [
              {
                "name": "your_envgroup_hybrid",
                "hostnames": [
                  "apigee.hybrid.com"
                ],
                "createdAt": "1677826235324",
                "lastModifiedAt": "1677826235324",
                "state": "ACTIVE"
              }
            ]
          }
        
  6. Fetch the latest attachments for the newly created environment group by using following CURL command:
    curl -H "Authorization: Bearer $TOKEN" \ 
          "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups/$ENV_GROUP/attachments"

    The environment group creation and attachment were successful if the result shows a unique hash value, as shown in the below sample response output:

         
            {
              "environmentGroupAttachments": [
                {
                  "name": "c27046d1-b83e-4cba-xxxx-caaa660b2bd6",
                  "environment": "your_envtest_hybrid",
                  "createdAt": "1677826263567",
                  "environmentGroupId": "your_envgroup_hybrid"
                }
              ]
            }
            

Next step

To continue with the installation, go to Part 2: Hybrid runtime setup.