Provisioning a paid org from the command line

You're viewing Apigee X documentation.
View Apigee Edge documentation.

This section describes how to install and configure Apigee from the command line if you are using a paid account. See also Provisioning options.

Step 1: Define environment variables

To define environment variables on the command line:

  1. Log in to Cloud by using the following command:
    gcloud auth login

    The command launches a browser window and prompts you to choose an account (if you have more than one). Cloud then prompts you to allow access. You only need to do this once: You will not need to run this command, choose an account, or allow access in the future.

  2. Initialize the Cloud SDK, as described in Initializing Cloud SDK; for example:
    gcloud init

    During SDK initialization, enter or select the ID of the project you created in Prerequisites. Set this project as the default. You will not need to run this command in the future unless you want to change the defaults.

    You may be asked to choose a configuration to use. If you are provisioning a new Apigee installation (the assumption in these steps), choose [2] Create a new configuration.

    When you run gcloud init you will be asked for:

    • A configuration name. This must start with a lowercase letter and can contain a combination of lowercase letters, numbers, and dashes. You will need to refer to this name if you want to change the defaults for this cloud configuration in the future.
    • The user setting up this configuration. Typically this will be you, but it can be another user or a cloud service account that has permissions to manage cloud configurations.
    • The cloud project ID in which you will run Apigee. This is the project you created in Prerequisites.
    • The default Compute Region and Zone and zone for your project. You can skip this step.
  3. Define the following environment variables for the current project:
    AUTH="Authorization: Bearer $(gcloud auth print-access-token)"
    PROJECT_ID="YOUR_PROJECT_ID"
    PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
    RUNTIME_LOCATION="YOUR_RUNTIME_LOCATION"
    ANALYTICS_REGION="YOUR_ANALYTICS_REGION"

    Where:

    • AUTH defines the Authentication header with a bearer token. You will use this header when calling Apigee APIs.
    • PROJECT_ID is the Cloud project ID that you created as part of the Prerequisites. If you're not sure what your project ID is, use Cloud Console or the gcloud projects list command to find it.
    • PROJECT_NUMBER is the Cloud project number that you created as part of the Prerequisites. This example issues a gcloud command to get the project number for you. Alternatively, you can use the gcloud projects list command to find it.
    • RUNTIME_LOCATION is the physical location where your instance is located. Valid values are any Compute Engine region. For more information, see Available regions and zones.

    • ANALYTICS_REGION is the physical location at which you store your analytics data.

      Where ANALYTICS_REGION is one of the following:

      asia-northeast1 asia-south1 australia-southeast1
      us-central1 us-east1 us-west1
      europe-west1 europe-west2 europe-west3

      Choose a region that is geographically close or one that satisfies your organization's storage requirements.

      Both RUNTIME_LOCATION and ANALYTICS_REGION can be the same region, but they do not have to be the same. However, there may be a performance benefit if they are the same.

  4. (Optional) Check your work by echoing the values you just set. Note that when you want to use a variable in your commands, precede the variable's name with a dollar sign ($).
    echo $AUTH
    echo $PROJECT_ID
    echo $PROJECT_NUMBER
    echo $RUNTIME_LOCATION
    echo $ANALYTICS_REGION
    

    The responses to your echo commands should look something like the following:

    Authorization: Bearer ya29.a123456678940B63hPSAMPLEsampleKKYVsample0f3pWDWZDuH2-hENkNa
    TvgZ1PD977TMvv6edBQPJezdHw040880Ol_LoD5ZDkt-i-knizia_KhA9L20sSvztL81-SAMPLE42ELPMASk2_
    1CxN
    my-cloud-project
    1234567890
    us-west1
    us-west1
    

Step 2: Enable APIs

To enable the required APIs on the command line:

  1. Log in and initialize your Cloud project if you haven't done so already.
  2. Enable the four required APIs listed above by executing the services enable command:

    gcloud services enable apigee.googleapis.com \
      servicenetworking.googleapis.com compute.googleapis.com \
      cloudkms.googleapis.com --project=$PROJECT_ID
  3. (Optional) To check your work, use the services list command to show all the enabled APIs:

    gcloud services list

    The response shows all enabled services, including the APIs that you just enabled (Apigee, Service Networking, Cloud KMS, and Compute Engine). The following example shows a possible list of APIs displayed by this command:

    ...                                    ...
    apigee.googleapis.com                  Apigee API
    appengineflex.googleapis.com           Google App Engine Flexible Environment
    ...                                    ...
    cloudkms.googleapis.com                Cloud Key Management Service (KMS) API
    compute.googleapis.com                 Compute Engine API
    ...                                    ...
    servicemanagement.googleapis.com       Service Management API
    servicenetworking.googleapis.com       Service Networking API
    ...                                            ...

    While your list of APIs might be different than those shown above, it must include the APIs you enabled in this step. If it doesn't, try executing the previous command for each API—one at a time—to enable them. Alternatively, try using the Console to enable APIs.

Step 3: Create the Apigee service agent

To create the Apigee service agent on the command line:

  1. Execute the services identity create command:

    gcloud  beta services identity create --service=apigee.googleapis.com --project=$PROJECT_ID
  2. Verify that the agent was successfully created. The response should show the name of the agent in the following format: service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com. for example:

    Service identity created: service-1234567890@gcp-sa-apigee.iam.gserviceaccount.com

    Copy this name. You will need it in later steps.

Step 4: Configure service networking

To configure service networking on the command line:

  1. Create a peering range using the following command:
    gcloud compute addresses create RANGE_NAME \
      --global \
      --prefix-length=PREFIX_LENGTH \
      --description="Peering range for Google services" \
      --network=NETWORK_NAME \
      --purpose=VPC_PEERING \
      --project=$PROJECT_ID

    Where:

    • RANGE_NAME is the name of the IP address range you are creating. You can name the range anything you want. For example: google-svcs
    • --global specifies the scope of the IP addresses. You must include this in your command.
    • --prefix-length specifies the size of the CIDR block (the number of IP addresses allowed in the range). The value of --prefix-length must be either 16 or 20 for paid orgs.

      For paid orgs, we recommend setting the value to 16, which sets aside 65,536 IP addresses. For more information, see Peering ranges.

    • --description specifies human-readable information about the service.
    • --network is the name of the network resource in which the addresses should be reserved.

      The network must have a CIDR block of available IP addresses that is at least the size of prefix-length.

      Google creates a default network (named default) for each new project, so you can use that. However, Google does not recommend using the default network for anything other than testing.

    • --purpose is the type of address resource. Set the value of purpose to VPC_PEERING.
    • --project is your Cloud project's ID, for which you can use the variable value that you defined previously ($PROJECT_ID).

    On success, gcloud responds with the following:

    Created [https://www.googleapis.com/compute/v1/projects/PROJECT_NAME/global/addresses/google-svcs].

    After you create a range of IP addresses, the addresses are associated with the project until you release them.

  2. Connect your services to the network using the following command:
    gcloud services vpc-peerings connect \
      --service=servicenetworking.googleapis.com \
      --network=NETWORK_NAME \
      --ranges=RANGE_NAME \
      --project=$PROJECT_ID

    Where:

    • --network is the name of the network resource that you specified in the previous step. For example: default
    • --ranges is the name of the IP address range that you specified in the previous step.

    This operation can take several minutes to complete.

    On success, gcloud responds with the following:

    Operation "operations/OPERATION_ID" finished successfully.

    Where OPERATION_ID is the UUID of the LRO.

  3. Apigee creates a connection between your network and Google's services; specifically, Apigee connects your project to the Service Networking API through VPC peering. Apigee also associates IP addresses with your project.

Step 5: Create an organization

Before you can create an organization, you must create a runtime database encryption key ring and key. This section describes how to do that, and then send a request to create the organization.

To create a new organization on the command line:

  1. Create a runtime database encryption key ring and key:

    1. Define an environment variable for the location of your runtime database encryption ring and key. This helps ensure consistency when you create them and makes it easier for you to follow along in the documentation.

      The value is the physical location where your runtime database encryption key ring and key are stored.

      • Single region configurations (in which you have just one instance in one region): Choose from the supported KMS regional locations.

        For example:

        RUNTIMEDBKEY_LOCATION="us-west1"

        The value can be the same as your $RUNTIME_LOCATION (also a region) but it does not have to be. However, there may be a performance benefit if they are the same.

      • Multi-region configurations: Choose from the supported multi-regional locations (such as us or eu) or dual-regional locations.

        For example:

        RUNTIMEDBKEY_LOCATION="us"

        Google recommends that if you have a multi-region configuration in the US, use us for your location if possible. Otherwise, use nam4.

    2. Create a new key ring using the gcloud command; for example:
      gcloud kms keyrings create my-runtimedb-key-ring --location $APPKEY_LOCATION --project $PROJECT_ID

      This creates a key ring named my-runtimedb-key-ring. The Apigee runtime database encryption key's location supports all Cloud KMS locations that support Cloud HSM and Cloud EKM.

      The key ring's name must be unique to your organization. If you create a second or subsequent region, the name cannot be the same as other key rings' names.

    3. Create a key using the gcloud kms keys create command; for example:
      gcloud kms keys create my-app-key --keyring my-runtimedb-key-ring \
        --location $APPKEY_LOCATION --purpose "encryption" --project $PROJECT_ID

      This command creates a key named my-app-key and adds it to the key ring.

      The key can be referenced by its key ID. You can get the key ID with the following command:

      gcloud kms keys list \
        --location=$RUNTIMEDBKEY_LOCATION \
        --keyring=$RUNTIMEDBKEY_KEY_RING_NAME \
        --project=$PROJECT_ID

      The key ID has the following syntax (similar to a file path):

      projects/PROJECT_ID/locations/RUNTIMEDBKEY_LOCATION/keyRings/RUNTIMEDBKEY_RING_NAME/cryptoKeys/RUNTIMEDBKEY_NAME

      In this example, the key ID is:

      projects/my-cloud-project/locations/us-west1/keyRings/my-runtimedb-key-ring/cryptoKeys/my-app-key
    4. Grant access for the Apigee Service Agent to use the new key by executing the gcloud kms keys add-iam-policy-binding command using the following syntax:

      gcloud kms keys add-iam-policy-binding RUNTIMEDB_KEY_NAME \
        --location RUNTIMEDB_KEY_LOCATION \
        --keyring RUNTIMEDB_KEY_RING_NAME \
        --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com \
        --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
        --project PROJECT_ID

      For example:

      gcloud kms keys add-iam-policy-binding my-app-key \
        --location $APPKEY_LOCATION \
        --keyring my-runtimedb-key-ring \
        --member serviceAccount:service-$PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com \
        --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
        --project $PROJECT_ID

      This command binds the key to the Apigee Service Agent.

      On successful completion of this request, gcloud responds with something similar to the following:

      Updated IAM policy for key [runtime].
      bindings:
      - members:
        - serviceAccount:service-1234567890@gcp-sa-apigee.iam.gserviceaccount.com
        role: roles/cloudkms.cryptoKeyEncrypterDecrypter
      etag: BwWqgEuCuwk=
      version: 1

      If you get an error like the following:

      INVALID_ARGUMENT: Role roles/cloudkms.cryptokms.cryptoKeyEncrypterDecrypter is not supported for this resource.

      Be sure that you used the project number and not the project name in the service account email address.

    For more information, see About the Apigee encryption keys.

  2. Create the organization by sending the following request to the organizations API:

    curl "https://apigee.googleapis.com/v1/organizations?parent=projects/$PROJECT_ID"  \
      -H "$AUTH" \
      -X POST \
      -H "Content-Type:application/json" \
      -d '{
        "name":"'"$PROJECT_ID"'",
        "analyticsRegion":"'"$ANALYTICS_REGION"'",
        "runtimeType":"CLOUD",
        "authorizedNetwork":"NETWORK_NAME",
        "runtimeDatabaseEncryptionKeyName":"DATABASE_KEY_NAME"
      }'

    Where:

    • $AUTH inserts the Authorization header that you created and put in the $AUTH variable in Define environment variables.

    • -X POST instructs curl to send your request as an HTTP POST.
    • -H inserts HTTP headers into the request. In this case, you include Authorization and Content-Type headers.
    • -d defines the data payload for the request. This payload must include the following:
      • name: Identifies your new organization. It must be the same name as your project ID. $PROJECT_ID inserts the value of the PROJECT_ID environment variable.

        Note that this command and subsequent commands in this section use the pre-defined environment variables that you created in Define environment variables.

      • analyticsRegion: Specifies the physical location where your analytics data will be stored.

        Where analyticsRegion is one of the following:

        asia-northeast1 asia-south1 australia-southeast1
        us-central1 us-east1 us-west1
        europe-west1 europe-west2 europe-west3

        Choose a region that is geographically close or one that satisfies your organization's storage requirements.

      • runtimeType: Set this value to CLOUD.
      • authorizedNetwork: Identifies the peering network that you specified in Configure service networking.
      • runtimeDatabaseEncryptionKeyName: The name of the application encryption key that you created in the previous step.

    After you execute this command, Apigee starts a long-running operation, which can take three to four minutes to complete. If Apigee immediately returns a response, then your project has likely not yet been provisioned. In this case, contact Apigee Sales.

    If you get an error, check your use of quotation marks around the variable values in the data payload. Be sure that you have double-single-double quotes around the $PROJECT_ID variable, as the following example shows:

    "'"$PROJECT_ID"'"

    If you use a string for your project ID, you can wrap it in double quotes within the single-quoted payload string, as the following example shows:

    '{ "name":"my-gcp-project", ... }'
  3. Wait three to four minutes.
  4. To check the status of your creation request, you can send a GET request to the List organizations API, as the following example shows:
    curl -H "$AUTH" "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID"

    If Apigee has successfully created a new organization, you will receive a response that is similar to the following:

    {
      "name": "my-cloud-project",
      "createdAt": "1592586495539",
      "lastModifiedAt": "1592586495539",
      "environments": [],
      "properties": {
        "property": [
          {
            "name": "features.hybrid.enabled",
            "value": "true"
          },
          {
            "name": "features.mart.connect.enabled",
            "value": "true"
          }
        ]
      },
      "analyticsRegion": "us-west1",
      "runtimeType": "CLOUD",
      "subscriptionType": "PAID",
      "caCertificate": "CERTIFICATE",
      "authorizedNetwork": "my-network",
      "projectId": "my-cloud-project"
    }

    If Apigee returns an HTTP error response, then see Creating an Apigee organization.

Step 6: Create a runtime instance

To create a new runtime instance on the command line:

  1. Check that Apigee has finished creating your organization. You submitted a request to create a new organization in Create an Apigee organization, but you need to be sure it's done before you continue.

    To do this, send the following request to the organizations API:

    curl -i -H "$AUTH" \
      "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID"

    If the organization exists (and you have the proper permissions to view it), Apigee responds with details about it. If Apigee responds with an error, wait a couple of minutes and send the request again.

  2. Create a disk encryption key:
    1. Create a new disk key ring using the gcloud command:
      gcloud kms keyrings create my-disk-key-ring \
        --location $RUNTIME_LOCATION \
        --project $PROJECT_ID

      This creates a new key ring named my-disk-key-ring. Your disk key ring must be set to the same location as the instance. Each instance and key ring should have its own location.

    2. Create a new disk key using the kms keys create command; for example:
      gcloud kms keys create my-disk-key --keyring my-disk-key-ring \
        --location $RUNTIME_LOCATION --purpose "encryption" --project $PROJECT_ID

      This example creates a new key named my-disk-key and adds it to the my-disk-key-ring key ring.

      The key can be referenced by its key path. You can get the key path with the following command:

      gcloud kms keys list \
        --location=$RUNTIME_LOCATION \
        --keyring=$DISK_KEY_RING_NAME \
        --project=$PROJECT_ID

      The key path looks like the following:

      projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/my-disk-key-ring/cryptoKeys/my-disk-key
    3. Grant access for the Apigee Service Agent to use the new key by executing the gcloud kms keys add-iam-policy-binding command; for example:
      gcloud kms keys add-iam-policy-binding my-disk-key \
        --location $RUNTIME_LOCATION \
        --keyring my-disk-key-ring \
        --member serviceAccount:service-$PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com \
        --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
        --project $PROJECT_ID

      This command binds the key to the Apigee Service Agent.

    For more information, see About the Apigee encryption keys.

  3. Create a new runtime instance for your project by sending a POST request to the Instances API; for example:
    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances" \
      -X POST -H "$AUTH" \
      -H "Content-Type:application/json" \
      -d '{
        "name":"INSTANCE_NAME",
        "location":"'"$RUNTIME_LOCATION"'",
        "diskEncryptionKeyName":"KEY_ID",
        "peeringCidrRange":"SLASH_nn"
      }'

    Where:

    • -X POST sets the request type to an HTTP POST.
    • -H "$AUTH"inserts the value of your AUTH environment variable for the Authorization header.
    • -H "Content-Type:application/json" inserts a header that instructs curl to send your data payload formatted as JSON.
    • -d defines the request payload; it must contain the following:
      • name: Your new instance's name. For example, my-runtime-instance. The name must start with a lowercase letter, can be up to 32 characters long, and can include only lowercase letters, numbers and hyphens. It cannot start or end with a hyphen and must be at least two characters long.
      • location is the physical place in which your cluster is hosted. Valid values are any location allowed by Compute Engine. (See Available regions and zones.) This example uses us-west1.
      • diskEncryptionKeyName where KEY_ID is the ID of the disk encryption key that you created in the previous step.
      • (Optional) peeringCidrRange: The size of the CIDR IP address range that Compute uses for allocating resources in your VPC. Valid values are SLASH_16 to SLASH_20 for paid organizations, and SLASH_23 for evaluation organizations.

        This value must match the range size that you set with the --prefix-length option in Configure service networking. For example, if you set --prefix-length to 16, then set peeringCidrRange to SLASH_16.

        The default value is SLASH_16.

    This request can take up to 20 minutes to complete because Apigee must create and launch a new Kubernetes cluster, install the Apigee resources on that cluster, and set up load balancing.

    On a successful request, Apigee initially responds to let you know that the creation is in progress. The response looks something like the following:

    {
      "instances": [
        {
          "name": "my-project",
          "location": "us-west1",
          "diskEncryptionKeyName": "your-disk-key-name",
          "state": "CREATING",
          "peeringCidrRange": "SLASH_16"
        }
      ]
    }

    If Apigee returns an error, see Creating a new instance.

  4. Wait about 20 minutes.
  5. To check the status of your runtime instance creation request, you can do one of the following:
    • (Preferred) Use the Operations API to get the status of the operation. This is preferred because it does not return an error if the operation is in progress. The next API call, however, does return an error in some circumstances.
    • Get a list of existing runtime instances by sending a GET request to the Instances API:
      curl -i -X GET -H "$AUTH" \
        "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances"

      If there are any available runtime instances associated with your Cloud account, Apigee responds to the request with details about each one, which looks like the following:

      {
        "instances": [
          {
            "name": "my-runtime-instance",
            "location": "us-west1",
            "host": "10.16.0.2",
            "port": "443"
          },
          ...
        ]
      }

      Where:

      • name and location are the values you specified in your initial request to create an instance.
      • host is the internal IP address of the cluster's load balancer. Apigee will connect to this when fulfilling API runtime requests.
      • port is the load balancer's port on which Apigee connects.

      If there are no runtime instances available (and Apigee has not yet created a new one for you), Apigee responds with an error.

For more details about creating a runtime instance, including additional context and troubleshooting information, see Step 5: Create a runtime instance.

Step 7: Create an environment

To create an environment and attach it to the runtime on the command line:

  1. Create a new environment with the Environments API by using the following command:
    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments" \
      -H "$AUTH" \
      -X POST \
      -H "Content-Type:application/json" \
      -d '{
        "name":"ENVIRONMENT_NAME"
      }'

    Where -d contains the data payload that defines your new environment's name.

    Apigee creates the new environment. This operation can take several minutes to complete.

  2. Before you continue, check that Apigee finished creating the new environment by sending a GET request to the Environments API:
    curl -i -H "$AUTH" \
      "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments"

    Apigee responds with a list of available environments; for example, if your environment name is test, Apigee responds with the following:

    [
      "test"
    ]
  3. Attach the new environment to the runtime instance, as the following example shows:
    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances/INSTANCE_NAME/attachments" \
        -X POST -H "$AUTH" \
        -H "content-type:application/json" \
        -d '{
          "environment":"ENVIRONMENT_NAME"
        }'

    As with the previous command, this command also triggers a long-running operation. Check that the environment has been attached to the runtime before continuing. If it has, you should get a 409 error, as the following example shows:

    {
      "error": {
        "code": 409,
        "message": "the attachment '61a36502-4242-4e6d-4242-0ab2e22c0ffc' already exists for instance
          'us-west1' and environment 'ENVIRONMENT_NAME'",
        "status": "ALREADY_EXISTS"
      }
    }

    Only after you're sure the new environment has been created and attached to the runtime, can you create a new environment group.

  4. Create a new environment group using the following command:
    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups" \
      -H "$AUTH" \
      -X POST \
      -H "Content-Type:application/json" \
      -d '{
        "name": "ENV_GROUP_NAME",
        "hostnames":["ENV_GROUP_HOST"]
      }'

    For example:

    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups" \
      -H "$AUTH"\
      -X POST \
      -H "Content-Type:application/json" \
      -d '{
        "name": "test-group",
        "hostnames":["sales.example.com"]
      }'
  5. Wait for the operation to complete. You can check the status of your new group using a request like the following:
    curl -i -H "$AUTH" -H "Content-Type:application/json" \
      "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENVIRONMENT_NAME"
  6. Attach the new environment to the new environment group with the following command:
    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups/ENV_GROUP_NAME/attachments" \
      -X POST \
      -H "$AUTH" \
      -H "content-type:application/json" \
      -d '{
        "environment":"ENVIRONMENT_NAME"
      }'

    For example:

    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups/test-group/attachments" \
      -X POST -H "$AUTH" \
      -H "content-type:application/json" \
      -d '{
        "environment":"ENVIRONMENT_NAME"
      }'

    This triggers a long-running operation that can take several minutes to complete. We recommend that you wait a minute or two before continuing to the next step. In the meantime you can check the status of the operation as before.

  7. (Optional) Send a PATCH request to update the host alias, as the following example shows:
    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups/test-group?updateMask=hostnames" \
      -X PATCH -H "$AUTH" \
      -H "content-type:application/merge-patch+json" \
      -d '{
        "hostnames":["test-group-new.sandbox.apigeeks.net"]
      }'

    This triggers a long-running operation that can take several minutes to complete. We recommend that you wait a minute or two before continuing to the next step. In the meantime you can check the status of the operation as before.

For more details about creating Apigee environments, including additional context and troubleshooting information, see Step 6: Create an environment.

Step 8: Configure routing

Decide whether to allow external access or internal only access:

Access type Description of the configuration and deployment process
Internal (recommended)

Allow only internal access to your API.

You download the Hello World proxy from GitHub and then deploy it to your runtime instance. You must then create a new VM inside the network and connect to it. From the new VM, you can send a request to the API proxy.

External

Allow external access to your API.

You download the Hello World proxy from GitHub and then deploy it to your runtime instance. You can then send a request to the API proxy from your administration machine or any network-enabled machine.

Given the complexity of this process, Apigee recommends that only advanced users carry this out.

Each of these approaches is presented on a tab in the instructions below.

Internal

There are no tasks to perform for this step if you are using the command line to set up an API proxy for internal access only. You can skip to Step 9: Deploy a sample proxy, where you will send a request to your API proxy.

External

This section describes how to configure routing when you're using the command line and you want to allow external access to your API proxy. You must do this before you can send a request from an external client to your Apigee runtime instance.

The general process is as follows:

Step 8a: Create a global Load Balancer
Step 8b: Enable Private Google Access for the subnet
Step 8c: Set up environment variables
Step 8d: Create a managed instance group
Step 8e: Get IP addresses and create firewall rules
Step 8f: Upload credentials

Each of these steps is described in the sections that follow.

Step 8a: Create a global Load Balancer

To create a global Load Balancer:

    gcloud compute health-checks create https hc-apigee-mig-443 \
      --project $PROJECT_ID --port 443 --global \
      --request-path /healthz/ingress

    You'll use this health check to ensure that the backend service is running. For configuring more advanced health checks against a specific proxy, see Performing health checks.

  1. Create a backend service called apigee-proxy-backend with the following command:
    gcloud compute backend-services create apigee-proxy-backend \
      --project $PROJECT_ID --protocol HTTPS --health-checks hc-apigee-mig-443 \
      --port-name https --timeout 60s --connection-draining-timeout 300s --global
  2. Add the MIG to your backend service with the following command:
    gcloud compute backend-services add-backend apigee-proxy-backend \
      --project $PROJECT_ID --instance-group $MIG_NAME \
      --instance-group-region $REGION \
      --balancing-mode UTILIZATION --max-utilization 0.8 --global
  3. Create a Load Balancing URL map with the following command:
    gcloud compute url-maps create apigee-mig-proxy-map \
      --project $PROJECT_ID --default-service apigee-proxy-backend
  4. Create a Load Balancing target HTTPS proxy with the following command:
    gcloud compute target-https-proxies create apigee-mig-https-proxy \
      --project $PROJECT_ID --url-map apigee-mig-proxy-map \
      --ssl-certificates apigee-ssl-cert
  5. Create a global forwarding rule with the following command:
    gcloud compute forwarding-rules create apigee-mig-https-lb-rule \
      --project $PROJECT_ID --address lb-ipv4-vip-1 --global \
      --target-https-proxy apigee-mig-https-proxy --ports 443

Step 8b: Enable Private Google Access for the subnet

To enable Private Google Access for the subnet, follow the steps listed in Enabling Private Google Access. You only need to do this step one time whether you are installing in single or multi regions.

Step 8c: Set up environment variables

The instructions in this section use environment variables to refer to repeatedly used strings. We recommend that you set these before continuing.

To set up your environment variables, issue the following commands:

MIG_NAME=apigee-mig-us-west1
VPC_NAME=default       # If you are using a shared VPC, use the shared VPC name
VPC_SUBNET=default     # Private Google Access must be enabled for this subnet
REGION=us-west1        # The same region as your Apigee runtime instance
APIGEE_ENDPOINT=APIGEE_INSTANCE_IP     # See the tip below for details on getting this IP address value

You'll use these variables several times during the remaining processes. If you wish to configure multiple regions, then create variables with values specific for each region.

Step 8d: Create a managed instance group

In this step, you create and configure a managed instance group (MIG). In a later step, you add the MIG to a backend service which is attached to a global load balancer. A MIG is required to send API traffic from the global load balancer's backend service to Apigee.

To create a MIG:

  1. Create an instance template by executing the following command.
    gcloud compute instance-templates create $MIG_NAME \
      --project $PROJECT_ID \
      --region $REGION \
      --network $VPC_NAME \
      --subnet $VPC_SUBNET \
      --tags=https-server,apigee-mig-proxy,gke-apigee-proxy \
      --machine-type e2-medium --image-family debian-10 \
      --image-project debian-cloud --boot-disk-size 20GB \
      --metadata ENDPOINT=$APIGEE_ENDPOINT,startup-script-url=gs://apigee-5g-saas/apigee-envoy-proxy-release/latest/conf/startup-script.sh

    As you can see from this command, machines are of type e2-medium. They run Debian 10 and have 20GB of disk. The startup-script.sh script configures the MIG to route inbound traffic from the load balancer to the Apigee instance.

  2. Create a managed instance group by executing the following command:
    gcloud compute instance-groups managed create $MIG_NAME \
      --project $PROJECT_ID --base-instance-name apigee-mig \
      --size 2 --template $MIG_NAME --region $REGION
  3. Configure autoscaling for the group by executing the following command:
    gcloud compute instance-groups managed set-autoscaling $MIG_NAME \
      --project $PROJECT_ID --region $REGION --max-num-replicas 3 \
      --target-cpu-utilization 0.75 --cool-down-period 90
  4. Define a named port by executing the following command:
    gcloud compute instance-groups managed set-named-ports $MIG_NAME \
      --project $PROJECT_ID --region $REGION --named-ports https:443

Step 8e: Get IP addresses and create firewall rules

You must assign an IP address to the Load Balancer and then create rules that allow the Load Balancer to access the MIG. You only need to do this step once, whether you are installing in single or multi regions.

To get the Load Balancer IP addresses and create the firewall rules:

  1. Reserve an IP address for the Load Balancer:
    gcloud compute addresses create lb-ipv4-vip-1 \
      --project $PROJECT_ID \
      --ip-version=IPV4 \
      --global
  2. Get a reserved IP address by executing the following command:
    gcloud compute addresses describe lb-ipv4-vip-1 \
      --project $PROJECT_ID --format="get(address)" --global
  3. Create a firewall rule that lets the Load Balancer access the MIG by using the following command:
    gcloud compute firewall-rules create k8s-allow-lb-to-apigee-mig \
      --description "Allow incoming from GLB on TCP port 443 to Apigee Proxy" \
      --project $PROJECT_ID --network $VPC_NAME --allow=tcp:443 \
      --source-ranges=130.211.0.0/22,35.191.0.0/16 --target-tags=gke-apigee-proxy

    Note that the IP address ranges 130.211.0.0/22 and 35.191.0.0/16 are the source IP address ranges for Google Load Balancing. This firewall rule allows Google Cloud Load Balancing to make health check requests to the MIG.

Step 8f: Upload credentials

Upload your credentials to Cloud.

You only need to do this step once, whether you are installing in single or multi regions.

  1. Generate a certificate and key. You can use a self-signed certificate or obtain a cert from a certificate authority. We do not recommend using self-signed certs in a production environment. If you want, you can install multiple certs on the load balancer. For more information on using SSL certificates with Google Load Balancer, see SSL certificates and SSL certificate overview.
  2. Upload your SSL server certificate and key to Google Cloud by using the gcloud compute ssl-certificates create command:
    gcloud compute ssl-certificates create apigee-ssl-cert \
      --project $PROJECT_ID --certificate=/PATH_TO_TLS_CERTIFICATE \
      --private-key=/PATH_TO_TLS_KEY

Step 9: Deploy a sample proxy

To deploy the example proxy using the command line:

  1. Download the Hello World sample proxy from GitHub.

    An API proxy in this form is known as a proxy bundle.

  2. Upload the API proxy bundle to the runtime using the API proxies API, as the following example shows:
    curl -i -X POST -H "$AUTH" \
      -H "Content-Type:multipart/form-data" \
      "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/apis?name=PROXY_BASE_PATH&action=import" \
      -F 'file=@/PATH/TO/FILE/httpbin_rev1_2020_02_02.zip'
  3. Deploy the API Proxy to the test environment as the following example shows:
    curl -i -H "$AUTH" -X POST \
      "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENVIRONMENT_NAME/apis/PROXY_BASE_PATH/revisions/1/deployments"

    You can use $PROXY_BASEPATH for PROXY_BASE_PATH.

  4. If you allowed external access to the API proxy:

    Send a request to the API proxy from any network-enabled machine by executing the following command:

    curl -i -H "Host: test-group-new.sandbox.apigeeks.net" \
      https://PUBLIC_LOAD_BALANCER_IP/httpbin

    Optionally add the -k option to skip authentication in a testing scenario such as this.

    You can find the public Load Balancer IP address as follows: In the Cloud Console, navigate to Network services > Load balancing. Click the load balancer name to see the Load Balancer details page. The IP address is listed there.

  5. If you allowed internal access only to the API proxy, see Calling an API proxy with internal-only access.

For more information about deploying proxies, including additional troubleshooting information, see Step 8: Deploy a sample proxy.