Provisioning an eval org from the command line

Stay organized with collections Save and categorize content based on your preferences.

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

Summary of steps

This document explains how to install and configure an Apigee X evaluation organization (or eval org) from the command line. Eval orgs expire after 60 days and may have other limitations. See also Comparing eval and paid organizations.

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 requirements listed in Prerequisites.
  2. You must have the gcloud CLI installed. If you need to install it, see Installing the gcloud CLI.
  3. Initialize the gcloud CLI, as described in Initializing the gcloud CLI, or if the CLI is already initialized, ensure that the Google Cloud project you created in Prerequisites is the default project for gcloud.
  4. Define the following environment variables:
    AUTH="Authorization: Bearer $(gcloud auth print-access-token)"
    PROJECT_ID="YOUR_PROJECT_ID"
    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. 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.
    • RUNTIME_LOCATION is the physical location where the Apigee instance is located. Valid values are any Compute Engine region.

    • ANALYTICS_REGION is the physical location at which Apigee analytics data will be stored.

      Where ANALYTICS_REGION is one of the following:

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

      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.

  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 ($).
    echo $AUTH
    echo $PROJECT_ID
    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
    us-west1
    us-west1
    

Step 2: Enable APIs

  1. Apigee requires you to enable several Google Cloud APIs. Enable them by executing the 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 (Apigee, Service Networking, Cloud KMS, and Compute Engine).

Step 3: Configure service networking

  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 an 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 \
      --project=$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.

  3. Create a second IP range with a CIDR length of /28. This range 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 \
      --project=$PROJECT_ID
  4. 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:

    Operation "operations/OPERATION_ID" finished successfully.

    Where OPERATION_ID is the UUID of the LRO (long-running operation).

    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 4: Create an organization

An organization is the top-level container in Apigee. It contains all your API proxies and related resources. For details, see Understanding organizations.

  1. Create a new eval org using the gcloud alpha apigee organizations command:
    gcloud alpha apigee organizations provision \
      --runtime-location=$RUNTIME_LOCATION \
      --analytics-region=$ANALYTICS_REGION \
      --authorized-network=$NETWORK_NAME \
      --project=$PROJECT_ID

    Where --authorized-network is the name of your custom peering network. For example: default.

  2. When you execute the provision command, Google starts an LRO to create the eval org. This operation takes up to 40 minutes to complete. During that time, gcloud displays the following:

    Provisioning organization...

    When the eval org and its associated runtime instance are created, gcloud responds with the following message:

    Provisioning organization...done.
  3. If you execute the following command:

    gcloud alpha apigee operations list --organization=$PROJECT_ID

    you should see that all UUIDs are in the FINISHED state. For example:

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

Step 5: Configure routing

Decide whether to allow external access or internal only access:

Access type Description of the configuration and deployment process
Internal

Allow only internal access to your API proxies.

You must create a new VM inside the network and connect to it. From the new VM, you can send a request to an Apigee API proxy.

External

Allow external access to your API proxies.

Use Private Service Connect (PSC) to enable private connection between a service producer (Apigee) and a service consumer (the peered VPC project and/or one or more other Cloud projects that you control). With this method, requests pass through a global external load balancer to a single point of attachment, called a Service Attachment. This configuration lets you send Apigee API proxy requests from any network-enabled machine.

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

Internal routing

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 6: Call the sample API proxy, where you will send a request to your API proxy.

External routing

This section describes how to configure external routing using Private Service Connect (PSC) to allow communication between Apigee and VPCs that you control. You must do this before you can send a request from an external client to your Apigee runtime instance.

The external configuration steps are:

Step 5a: Create a network endpoint group (NEG)
Step 5b: Configure the load balancer

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

Step 5a: Create a network endpoint group (NEG)

  1. Get the service attachment for your Apigee instance:
    curl -i -X GET -H "$AUTH" \
      "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances"

    In the following sample output, the serviceAttachment value is shown in bold type:

    {
      "instances": [
        {
          "name": "eval-instance",
          "location": "us-west1",
          "host": "10.72.100.2",
          "port": "443",
          "createdAt": "1657832463500",
          "lastModifiedAt": "1657833920670",
          "state": "ACTIVE",
          "peeringCidrRange": "SLASH_22",
          "runtimeVersion": "1-8-0-apigee-18",
          "ipRange": "10.74.100.0/28,10.74.100.16/28",
          "consumerAcceptList": [
            "apigee-eval-test"
          ],
          "serviceAttachment": "projects/s8da1b0111eb33765-tp/regions/us-west1/serviceAttachments/apigee-us-west1-icza"
        }
      ]
    }
  2. Create a Private Service Connect network endpoint group (NEG) that points to the service attachment that you obtained from the instance response body in the previous step.

    gcloud compute network-endpoint-groups create NEG_NAME \
      --network-endpoint-type=private-service-connect \
      --psc-target-service=TARGET_SERVICE \
      --region=$RUNTIME_LOCATION \
      --network=$NETWORK_NAME \
      --subnet=SUBNET_NAME \
      --project=$PROJECT_ID
    

    Replace the following:

    • NEG_NAME: a name for the network endpoint group.
    • TARGET_SERVICE: the service attachment that you want to connect to. For example: projects/bfac7497a40c32a12p-tp/regions/us-west1/serviceAttachments/apigee-us-west1-crw7
    • SUBNET_NAME: Name of the subnet used for private connectivity to the producer. The subnet size can be small: the PSC NEG only needs one IP from the subnet. For Apigee, only one PSC NEG is needed per region. The subnet can be shared and used by VMs or other entities. If a subnet is not specified, network endpoints may belong to any subnetwork in the region where the network endpoint group is created.

Step 5b: Configure the load balancer

Configure a global external HTTP(S) load balancer (load balancing scheme set to EXTERNAL_MANAGED).

Although the Private Service Connect NEG is regional, all other load balancing components in this configuration are global.

  1. Reserve a global external IPv4 address for the load balancer.
    gcloud compute addresses create ADDRESS_NAME \
      --ip-version=IPV4 --global --project=$PROJECT_ID

    Replace ADDRESS_NAME with a name for the IP address resource.

    Run this command to view the reserved IP address:

    gcloud compute addresses describe ADDRESS_NAME \
      --format="get(address)" --global --project=$PROJECT_ID
  2. Create a backend service for the NEG.
    gcloud compute backend-services create BACKEND_SERVICE_NAME \
      --load-balancing-scheme=EXTERNAL_MANAGED \
      --protocol=HTTPS \
      --global --project=$PROJECT_ID
  3. Replace BACKEND_SERVICE_NAME with the name of the backend service.

  4. Add the backend service to the NEG.
    gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
      --network-endpoint-group=NEG_NAME \
      --network-endpoint-group-region=$RUNTIME_LOCATION \
      --global --project=$PROJECT_ID

    Replace the following:

    • BACKEND_SERVICE_NAME: the name of the backend service.
    • NEG_NAME: the name of the network endpoint group.
  5. Create a URL map for the load balancer.

    A URL map must reference a default backend service. Set the backend service you just created as the default.

    gcloud compute url-maps create URL_MAP_NAME \
      --default-service=DEFAULT_BACKEND_SERVICE_NAME \
      --global --project=$PROJECT_ID

    Replace the following:

    • URL_MAP_NAME: a name for the URL map.
    • DEFAULT_BACKEND_SERVICE_NAME: the name of the load balancer's default backend service. The default is used when no host rule matches the requested hostname.
  6. Create an SSL certificate for the HTTPS target proxy.

    To create an HTTPS load balancer, you must have an SSL certificate resource to use in the HTTPS target proxy. You can create an SSL certificate resource using either a Google-managed SSL certificate or a self-managed SSL certificate.

    Use this command to create a Google-managed SSL certificate resource:

    gcloud compute ssl-certificates create CERTIFICATE \
      --domains DOMAIN --project=$PROJECT_ID

    Replace the following:

    • CERTIFICATE: a name for the certificate.
    • DOMAIN: the domain name you will use for the external load balancer.

    To create a self-managed SSL certificate, you need a local private key file and a local certificate file. If you need to create these files, see Using self-managed SSL certificates.

    gcloud compute ssl-certificates create CERTIFICATE \
      --certificate LB_CERT \
      --private-key LB_PRIVATE_KEY --project=$PROJECT_ID

    Replace the following:

    • CERTIFICATE: a name for the certificate.
    • LB_CERT: the path to the PEM-formatted certificate file for your self-managed certificate.
    • LB_PRIVATE_KEY: the path to the PEM-formatted private key file for your self-managed certificate.
  7. The certificate can take up to an hour to be provisioned. To check the status of the provisioning, execute this command:

    gcloud compute ssl-certificates describe CERTIFICATE \
       --global \
       --format="get(name,managed.status, managed.Status)"
  8. Add the domain to the Apigee environment group that was created for you. The name of the environment group is eval-group:
    curl "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups/eval-group" \
      -H "$AUTH" \
      -X PATCH \
      -H "Content-Type:application/json" \
      -d '{
        "hostnames":["'"DOMAIN"'"]
      }'
  9. Check the status of the environment group operation:
    curl -H "$AUTH" \
      "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups/eval-group/attachments"
    
  10. Use the SSL certificate resource to create a target HTTPS proxy.

    gcloud compute target-https-proxies create PROXY_NAME \
      --url-map=URL_MAP_NAME \
      --ssl-certificates=CERTIFICATE --project=$PROJECT_ID

    Replace the following:

    • PROXY_NAME: a name for the target HTTPS proxy.
    • URL_MAP_NAME: the name of the URL map.
    • CERTIFICATE: the name of the certificate resource.
  11. Create the forwarding rule.
    gcloud compute forwarding-rules create FWD_RULE \
      --load-balancing-scheme=EXTERNAL_MANAGED \
      --network-tier=PREMIUM \
      --address=ADDRESS_NAME \
      --target-https-proxy=PROXY_NAME \
      --ports=443 \
      --global --project=$PROJECT_ID

    Replace the following:

    • FWD_RULE: a name for the forwarding rule.
    • ADDRESS_NAME: the IP address resource that you reserved to use for the forwarding rule.
    • PROXY_NAME: the name of the target HTTPS proxy.

Apigee X provisioning is complete.

Step 6: Call the sample API proxy

An API proxy called hello-world was created and deployed for you during provisioning. In this step, you will test the new eval organization by calling the proxy.

Call the proxy with internal routing

If you chose the internal routing option in Step 5, follow the steps in Calling an API proxy with internal-only access.

Call the proxy with external routing

If you chose the external routing option in Step 5, follow the steps in this section.

  1. Set up a DNS entry for your domain. Here are two ways to accomplish this task:
    • At your registrar, create an A record pointing to your domain. For example, if your domain is sales.example.com and the IP is 10.23.0.2, then point the record for sales.example.com to the address 10.23.0.2.

      Run this command to view the reserved IP address:

      gcloud compute addresses describe ADDRESS_NAME \
        --format="get(address)" --global --project=$PROJECT_ID
    • Use Google Cloud DNS to map a URL to an IP address.
  2. Confirm that the hello-world proxy is deployed:
    curl -i -H "$AUTH" \
      "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/eval/apis/hello-world/revisions/1/deployments"
  3. Call the API proxy:

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

    curl -i -H "Host: DOMAIN" \
      https://DOMAIN/hello-world

    Where DOMAIN is the domain you put into the certificate and added to the environment group, as discussed in Step 5: Configure routing. If needed, you can use this API to get the DOMAIN value from the environment group:

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

    Upon success, the sample API proxy returns the response:

    Hello, Guest!

    Troubleshooting tips:

    If you get a handshake error, check the status of the SSL certificate. For information on troubleshooting self-managed and Google-managed certificates, see Troubleshoot SSL certificates.

    Be sure that your registered domain has an A record that points to the IP address of global external IPv4 address created in Step 5. Run this command to view the reserved IP address:

    gcloud compute addresses describe ADDRESS_NAME \
      --format="get(address)" --global --project=$PROJECT_ID

    If you're unable to resolve the domain configuration, try calling the proxy with this command:

    curl  -H Host:DOMAIN --resolve \
      DOMAIN:443:EXTERNAL_IP_ADDRESS  \
      https://DOMAIN:443/hello-world -k

Next: To learn more about building and deploying API proxies, see Build your first API proxy overview.