Step 3: Create an Apigee organization

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

An Apigee organization (sometimes referred to as an org) is the top-level container in Apigee. It includes all of your environments and environment groups, users, API proxies, and related resources. For more information, see Understanding organizations.

What you're doing in this step

Now that you've enabled the required APIs, you can create an Apigee organization. When creating an organization, you will also create a database encryption key and a key ring. The process of creating and configuring your organization is called provisioning.

Also during provisioning, a service agent is created and is assigned the role of Cloud KMS CryptoKey Encrypter/Decrypter. This agent manages the encryption and decryption using the keys you generate.

The format for this agent's email address is:

service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com

Note that the service agent's email address specifies the project number and not the project ID. (They are easy to confuse, and you typically use the project ID during other parts of the setup process.)

When naming a new organization, the organization's name must be the same name as your project ID. In addition, it must be globally unique. This means that you can't name your organization the same as any other Cloud user.

Perform the step

To create a new organization in the Apigee provisioning wizard:

  1. Open a browser and navigate to the Apigee provisioning wizard.

    The wizard's start screen displays:

    Start screen

  2. Enter your project ID in the Project field, as the following example shows:

    Start screen

    If you enter the ID incorrectly, or try to use a project that has not been approved (or entitled) by Apigee, then the wizard displays the following error:

    The start screen for setting

    You must enter the ID of an entitled project before you can continue. If your project is not entitled, contact Apigee Sales.

  3. Click Get Started.

    Apigee displays a list of the tasks you will perform to configure your new instance and deploy an API proxy.

    Each task is initially in a "Not configured" status, but you will change that shortly.

  4. In the wizard, click Edit next to Apigee organization:

    The start screen for setting up

    The Create an Apigee organization view displays:

    Create organization screen

  5. From the Analytics hosting region drop-down list, select the physical location where you want your analytics data stored. This should be the same location that you set in Step 1: Define environment variables.
  6. Create a database encryption key:

    1. Define an environment variables for the values you will use in this process with the following commands:
      
                    

      Where:

      • PROJECT_ID is
      for the location of your application encryption key ring and key. This step is optional, but helps ensure consistency when you create them.
      DBKEY_LOCATION="REGION"

      Where REGION is the physical location where your database key ring and key are stored. Similar to the analytics region, valid values are a subset of the Compute Engine regions. Possible values are:

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

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

      For example:

      DBKEY_LOCATION="us-west1"
    2. Create a new key ring using the gcloud kms keyrings create command:
      gcloud kms keyrings create DATABASE_KEY_RING_NAME \
        --location $DBKEY_LOCATION \
        --project $PROJECT_ID

      Where DATABASE_KEY_RING_NAME is the name of the key ring you are creating.

      The key ring's name must be unique to your organization. If you create additional regions, the key ring names for those regions cannot be the same as existing key ring names.

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

    3. Create a key using the gcloud kms keys create command:
      gcloud kms keys create DATABASE_KEY_NAME \
        --keyring DATABASE_KEY_RING_NAME \
        --location $DBKEY_LOCATION \
        --purpose "encryption" \
        --project $PROJECT_ID

      Where:

      • Where DATABASE_KEY_NAME is the name of the key you are creating.
      • Where DATABASE_KEY_RING_NAME is the name of the key ring you created in the previous step.

      You will need to make note of the key's key path in order to refer to the key. The key path has the following structure:

      projects/PROJECT_ID/locations/DATABASE_KEY_RING_LOCATION/keyRings/DATABASE_KEY_RING_NAME/cryptoKeys/DATABASE_KEY_NAME

      For example:

      projects/my-cloud-project/locations/us-west1/keyRings/my-database-key-ring/cryptoKeys/my-database-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 DATABASE_KEY_NAME \
        --location $DATABASE_KEY_LOCATION \
        --keyring DATABASE_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 receive 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.

    5. In the Runtime database encryption key ID field, enter the key path for the database key that you just created.

    For additional details, see About the Apigee encryption keys.

  7. Click Create Organization.

    Apigee begins the process of creating an organization for your project.

  8. Wait three to four minutes. Now is a good time to go warm up a delicious stroopwaffle.

    Apigee displays a spinner next to Apigee organization in the task list while it's creating the organization:

    Spinner that appears during the creation process

    When Apigee finishes creating your organization, a check mark appears next to the task and an Edit button appears next to the next task in the wizard:

    Create organization screen

If you encounter errors during this part of the process, see Troubleshooting.


1 2 3 NEXT: Configure service networking 5 6 7 8