Provision a paid org with VPC peering

Provision a paid org with VPC peering

This page applies to Apigee, but not to Apigee hybrid.

View Apigee Edge documentation.

This document describes how to install and configure Apigee from the command line with VPC peering. These steps apply to both Subscription and Pay-as-you-go pricing models for paid organizations with or without data residency enabled.

Summary of steps

The provisioning steps are as follows:

Step 1: Define environment variables

Set up gcloud and define environment variables for use in later steps:

  1. Be sure you have completed the setup requirements listed in Before you begin.
  2. You must have the Cloud SDK installed. If you need to install it, see Installing Cloud SDK.
  3. Initialize the Cloud SDK, as described in Initializing the gcloud CLI, or otherwise ensure that the Google Cloud project you created in Prerequisites is the default project for gcloud.
  4. Define the following environment variables in your command terminal. Select the tab that corresponds to the type of organization you need: No data residency or with Data residency:

    No data residency

    AUTH="$(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"
    BILLING_TYPE="YOUR_BILLING_TYPE"

    Where:

    • AUTH defines the Authentication header with a bearer token. You will use this header when calling Apigee APIs. Note that the token expires after a period of time and when it does, you can simply regenerate it using the same command. For more information, see the reference page for the print-access-token command.
    • PROJECT_ID is the Cloud project ID that you created as part of the Prerequisites.
    • PROJECT_NUMBER is the Cloud project number that you created as part of the Prerequisites.
    • RUNTIME_LOCATION is the physical location where the Apigee instance you will create later is located. For a list of available runtime locations, see Apigee locations.

    • ANALYTICS_REGION is the physical location at which Apigee analytics data will be stored. For a list of available Apigee API Analytics regions, see Apigee locations.

      Both RUNTIME_LOCATION and ANALYTICS_REGION can be the same region, but they do not have to be the same.

    • BILLING_TYPE is the billing type for the organization you create. Valid values are:

    Data residency

    AUTH="$(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"
    CONTROL_PLANE_LOCATION="YOUR_CONTROL_PLANE_LOCATION"
    CONSUMER_DATA_REGION="YOUR_CONSUMER_DATA_REGION"
    BILLING_TYPE="YOUR_BILLING_TYPE"

    Where:

    • AUTH defines the Authentication header with a bearer token. You will use this header when calling Apigee APIs. Note that the token expires after a period of time and when it does, you can simply regenerate it using the same command. For more information, see the reference page for the print-access-token command.
    • PROJECT_ID is the Cloud project ID that you created as part of the Prerequisites.
    • PROJECT_NUMBER is the Cloud project number that you created as part of the Prerequisites.
    • RUNTIME_LOCATION is the physical location where the Apigee instance you will create later is located. For a list of available runtime locations, see Apigee locations.

      The runtime location must be within the control plane location.
    • CONTROL_PLANE_LOCATION is the physical location at which Apigee control plane data will be stored. For a list of available control plane locations, see Apigee locations.
    • CONSUMER_DATA_REGION is a sub-region of the control plane region. You must specify both the CONTROL_PLANE_LOCATION and the CONSUMER_DATA_REGION. For a list of available consumer data regions, see Apigee locations.
    • BILLING_TYPE is the billing type for the organization you create. Valid values are:

  5. (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 ($).

    No data residency

    echo $AUTH
    echo $PROJECT_ID
    echo $PROJECT_NUMBER
    echo $RUNTIME_LOCATION
    echo $ANALYTICS_REGION
    echo $BILLING_TYPE
    

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

    YOUR_TOKEN
    my-cloud-project
    1234567890
    us-west1
    us-west1
    SUBSCRIPTION
    

    Data residency

    echo $AUTH
    echo $PROJECT_ID
    echo $PROJECT_NUMBER
    echo $RUNTIME_LOCATION
    echo $CONTROL_PLANE_LOCATION
    echo $CONSUMER_DATA_REGION
    echo $BILLING_TYPE
    

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

    YOUR_TOKEN
    my-cloud-project
    1234567890
    us-west1
    us
    us-west1
    SUBSCRIPTION
    

Step 2: Enable APIs

  1. Apigee requires you to enable several Google Cloud APIs. Enable them by executing the following services enable command:

    gcloud services enable apigee.googleapis.com \
        servicenetworking.googleapis.com \
        compute.googleapis.com \
        cloudkms.googleapis.com --project=$PROJECT_ID
  2. (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.

Step 3: Create the Apigee service identity

  1. Create the Apigee service identity:

    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

Step 4: Configure service networking

In this step, you allocate a pair of IP Address Ranges (a /22 and /28 CIDR range) to Apigee and perform the VPC peering between your network and Apigee's network. Each Apigee instance requires a non-overlapping CIDR range of /22 and /28. The Apigee runtime plane is assigned IP addresses from within this CIDR range. As a result, it's important that the range is reserved for Apigee and not used by other applications in your VPC network. For more information and important considerations, see Understanding peering ranges.

Note that you are creating sufficient network IP range for one Apigee instance. If you plan to create additional Apigee instances, you have to repeat this step for each one. The ranges cannot be shared between instances. See also Expanding Apigee to multiple regions.

  1. Create these environment variables:
    RANGE_NAME=YOUR_RANGE_NAME
    NETWORK_NAME=YOUR_NETWORK_NAME
    

    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
    • NETWORK_NAME is the name of the network resource in which the addresses should be reserved.

      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.

  2. Create a network IP range with a CIDR length of /22:
    gcloud compute addresses create $RANGE_NAME \
      --global \
      --prefix-length=22 \
      --description="Peering range for Apigee services" \
      --network=$NETWORK_NAME \
      --purpose=VPC_PEERING \
      --addresses=OPTIONAL_ADDRESSES \
      --project=$PROJECT_ID

    Where --addresses lets you optionally specify an address range. For example, to allocate the CIDR block 192.168.0.0/22, specify 192.168.0.0 for the address and 22 for the prefix length. See also Creating an IP allocation.

    If you do not provide the --addresses parameter, then gcloud selects an available address range for you.

    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.

  3. Verify the network IP range was created with a CIDR length of /22:
    gcloud compute addresses list --global --project=$PROJECT_ID
    gcloud compute addresses describe $RANGE_NAME --global --project=$PROJECT_ID
  4. Create a network IP range with a CIDR length of /28. This range is required and is used by Apigee for troubleshooting purposes and cannot be customized or changed.
    gcloud compute addresses create google-managed-services-support-1 \
      --global \
      --prefix-length=28 \
      --description="Peering range for supporting Apigee services" \
      --network=$NETWORK_NAME \
      --purpose=VPC_PEERING \
      --addresses=OPTIONAL_ADDRESSES \
      --project=$PROJECT_ID

    Where --addresses lets you optionally specify an address range. For example, to allocate the CIDR block 192.168.0.0/28, specify 192.168.0.0 for the address and 28 for the prefix length. See also Creating an IP allocation.

    If you do not provide the --addresses parameter, then gcloud selects an available address range for you.

  5. Verify the network IP range was created with a CIDR length of /28:
    gcloud compute addresses list --global --project=$PROJECT_ID
    gcloud compute addresses describe google-managed-services-support-1 --global \
      --project=$PROJECT_ID
  6. 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,google-managed-services-support-1 \
      --project=$PROJECT_ID

    This operation can take several minutes to complete. On success, gcloud responds with the following, where OPERATION_ID is the UUID of the LRO.

    Operation "operations/OPERATION_ID" finished successfully.
  7. 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.

  8. After few minutes, verify whether VPC peering succeeded:
    gcloud services vpc-peerings list \
      --network=$NETWORK_NAME \
      --service=servicenetworking.googleapis.com \
      --project=$PROJECT_ID

Step 5: Create an organization

Before you can create an organization, you must create a runtime database encryption key ring and key (see step 1) and, if you are using data residency, control plane encryption key rings and keys (see step 2). These Cloud KMS keys encrypt data that is stored and replicated across runtime and control plane locations. Apigee uses these entities to encrypt application data such as KVMs, cache, and client secrets, which is then stored in the database. For more information, see About the Apigee encryption keys.

  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

      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

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

      For example:

      RUNTIMEDBKEY_LOCATION="us"

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

    2. Define environment variables for database key rings and key names.

      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.

      RUNTIMEDB_KEY_RING_NAME=YOUR_DB_KEY_RING_NAME
      RUNTIMEDB_KEY_NAME=YOUR_DB_KEY_NAME
    3. (Optional) Check your work by echoing the values you just set. Remember that when you want to use a variable in your commands, precede the variable's name with a dollar sign ($).
      echo $RUNTIMEDBKEY_LOCATION
      echo $RUNTIMEDB_KEY_RING_NAME
      echo $RUNTIMEDB_KEY_NAME
    4. Create a new key ring:
      gcloud kms keyrings create $RUNTIMEDB_KEY_RING_NAME \
        --location $RUNTIMEDBKEY_LOCATION --project $PROJECT_ID

      The Apigee runtime database encryption key's location supports all Cloud KMS locations that support Cloud HSM and Cloud EKM.

    5. Create a key:

      gcloud kms keys create $RUNTIMEDB_KEY_NAME \
        --keyring $RUNTIMEDB_KEY_RING_NAME \
        --location $RUNTIMEDBKEY_LOCATION \
        --purpose "encryption" \
        --project $PROJECT_ID

      This command creates the key and adds it to the key ring.

      Get the key ID:

      gcloud kms keys list \
        --location=$RUNTIMEDBKEY_LOCATION \
        --keyring=$RUNTIMEDB_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/RUNTIMEDB_KEY_RING_NAME/cryptoKeys/RUNTIMEDB_KEY_NAME
    6. Put the key ID in an environment variable. You will use this variable in a later command:

      RUNTIMEDB_KEY_ID=YOUR_RUNTIMEDB_KEY_ID
    7. Grant access for the Apigee Service Agent to use the new key:

      gcloud kms keys add-iam-policy-binding $RUNTIMEDB_KEY_NAME \
        --location $RUNTIMEDBKEY_LOCATION \
        --keyring $RUNTIMEDB_KEY_RING_NAME \
        --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.

  2. If you are using data residency, create a control plane encryption key ring and key. If you are not using data residency, go to step 3.