Provisioning an eval org from the command line

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

This section describes how to install and configure an eval org from the command line. If you have a paid account, see Provisioning a paid org from the command line.

Before you begin

Before you begin, be sure that you choose the most appropriate method for provisioning an eval org. The following table lists each method with its own pros and cons:

Method Description Next Step
Apigee provisioning wizard

Pros:

  • Easiest
  • Fastest
  • Less prone to error

Cons:

  • Least amount of flexibility
  • Some details are hidden or obfuscated by the wizard
Provisioning an eval org (with the Apigee provisioning wizard)
Apigee Trial Provisioning Script

Pros:

  • One step: define the values; the script does the rest
  • Scripted but simpler than using the command line

Cons:

  • Obfuscates some tasks (although you can easily look into the script)
  • Does not support Windows
apigee-x-trial-provision (hosted on GitHub)
Command line instructions

Pros:

  • High level of control
  • No hidden tasks -- you do them all

Cons:

  • Most open to errors
  • Can be time consuming
  • Google does not recommend this approach unless you are an advanced user
Provisioning an eval org from the command line

Using the command line

To provision an eval org without the UI:

  1. 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.

    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 you send HTTP requests to your API proxy.
      • 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 paid orgs) or Compute Engine zone (for eval orgs). For more information, see Compute Engine locations.

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

        Valid values are a subset of the Compute Engine regions. Possible values are:

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

        Both eval and paid accounts use regions for the analytics location. Therefor, for paid orgs its value can be the same as the RUNTIME_LOCATION (also a region). But the value of ANALYTICS_REGION does not have to be the same as RUNTIME_LOCATION. However, there may be a performance benefit if they are the same.

        For eval accounts, the analytics location is a region but the runtime location is a zone, so they will not be the same.

      The following example defines environment variables for a paid org:

      AUTH="Authorization: Bearer $(gcloud auth print-access-token)"
      PROJECT_ID="my-cloud-project"
      PROJECT_NUMBER="1234567890"
      RUNTIME_LOCATION="us-west1"
      ANALYTICS_REGION="us-west1"

      If this were for an eval org, the RUNTIME_LOCATION would be set to a zone instead of a region.

      You will use the variable names, such as $PROJECT_ID as string literals in your commands.

      Note that you might not use all of these environment variables during your provisioning and configuration.

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

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

      echo $AUTH
      Authorization: Bearer ya29.a123456678940B63hPSAMPLEsampleKKYVsample0f3pWDWZDuH2-hENkNaTvgZ1PD977TMvv6edBQPJezdHw040880Ol_LoD5ZDkt-i-knizia_KhA9L20sSvztL81-SAMPLE42ELPMASk2_1CxN
      
      echo $PROJECT_ID
      my-cloud-project
      
      echo $PROJECT_NUMBER
      1234567890
      
      echo $RUNTIME_LOCATION
      us-west1
      
      echo $ANALYTICS_REGION
      us-west1
    5. For eval provisioning, add one additional environment variable: EVAL_RUNTIME_ZONE. Set its value to a region in which you want your runtime instance to be created; for example:
      EVAL_RUNTIME_ZONE="us-west1-a"

      Valid values include any zone supported by Google Compute Engine.

  2. Enable the required APIs for your Google project:
    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, as the following example shows:

      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, as the following example shows:

      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:

      ...                                    ...
      analyticsreporting.googleapis.com      Analytics Reporting API
      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
      ...                                    ...
      resourceviews.googleapis.com           Compute Engine Instance Groups 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.

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

  3. Configure service networking by performing the following steps:
    1. Create a peering range using the following command:
      gcloud compute addresses create google-svcs \
        --global \
        --prefix-length=PREFIX_LENGTH \
        --description="Peering range for Google services" \
        --network=NETWORK_NAME \
        --purpose=VPC_PEERING \
        --project=$PROJECT_ID

      Where:

      • google-svcs is the name of the IP address range you are creating. You can name the range anything you want.
      • --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 eval orgs, the value must be 23.

        For paid orgs, Google recommends 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 address(es) 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 address(es) 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:

      • --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.

  4. Create a new eval org using the following command:

    gcloud apigee organizations provision \
      --runtime-location=$EVAL_RUNTIME_ZONE \
      --analytics-region=$ANALYTICS_REGION \
      --authorized-network=NETWORK_NAME \
      --project=$PROJECT_ID

    Where:

    • --authorized-network is your custom peering network.
    • --runtime-location should be set to the $EVAL_RUNTIME_ZONE environment variable that you set up previously.
    • --analytics-region is the value of the $ANALYTICS_REGION environment variable that you set up previously.

    Note that unlike a paid org, an eval org does not use application or disk encryption keys.

    When you execute the provision command, Google starts an LRO (long-running operation) to create the eval org. This operation takes about 15 minutes to complete. During that time, gcloud displays the following:

    Provisioning organization...
  5. (Optional) Check the status of your LRO by using the operations list command, as the following example shows:

    gcloud apigee operations list

    If Google is not yet done creating the eval org, the response looks like the following:

    UUID                               ORGANIZATION  STATE
    00bab06f-c60c-41a5-4242-7SAMPLE7f  my-org        FINISHED
    429790a7-3151-4642-4343-7SAMPLE7f  my-org        FINISHED
    f48a00ff-7daa-4c4a-4444-7SAMPLE7f  my-org        IN_PROGRESS

    The first two UUIDs are for the previous LROs when you set up service networking. The third UUID is the organization provisioning LRO.

    When Google finishes creating the eval org and its associated runtime instance, gcloud responds with the following:

    Provisioning organization...done.

    If you execute the operations list command again, you should see that all UUIDs are in the FINISHED state:

    UUID                                  ORGANIZATION  STATE
    00bab06f-c60c-41a5-4242-7SAMPLE7f     my-org        FINISHED
    429790a7-3151-4642-4343-7SAMPLE7f     my-org        FINISHED
    f48a00ff-7daa-4c4a-4444-7SAMPLE7f     my-org        FINISHED

You'll want to get a proxy up and running and send requests to it. This is described in Next steps.

Next steps

If you want to allow external access to your API proxy, follow the external configuration steps listed Configure routing. If you don't have an externally accessible load balancer set up, then send internal requests to your API proxy!