Provision an eval org with VPC peering

This page applies toApigee, but not toApigee hybrid.

View Apigee Edge documentation.

Summary of steps

This document explains how to install and configure an Apigee evaluationorganization (oreval 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 upgcloud and define environment variables for use in later steps:

  1. Be sure you have completed the requirements listed inPrerequisites.
  2. You must have the gcloud CLI installed. If you need to install it, seeInstalling the gcloud CLI.
  3. Initialize the gcloud CLI, as described inInitializing the gcloud CLI, or if the CLI is already initialized, ensure that the Google Cloud project you created inPrerequisites 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:

  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$AUTHecho$PROJECT_IDecho$RUNTIME_LOCATIONecho$ANALYTICS_REGION

    The responses to yourecho commands should look something like the following:

    Authorization: Bearer ya29.a123456678940B63hPSAMPLEsampleKKYVsample0f3pWDWZDuH2-hENkNaTvgZ1PD977TMvv6edBQPJezdHw040880Ol_LoD5ZDkt-i-knizia_KhA9L20sSvztL81-SAMPLE42ELPMASk2_1CxNmy-cloud-projectus-west1us-west1

Step 2: Enable APIs

Permissions required for this task

You can give the Apigee provisioner a predefined role that includes the permissions needed to complete this task, or give more fine-grained permissions to provide the least privilege necessary. SeePredefined roles andAPI enablement permissions.

  1. Apigee requires you to enable several Google Cloud APIs. Enable them by executing theservices 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 theservices 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

Important:If you already have a peering range and private connection withservicenetworking.googleapis.com, and your range is big enough to handle another/22 and/28 CIDR range, you can skip this step. Apigee will create the needed CIDR blocks for you. This step is only required if you do not already have a space created that has room to create a/22 and/28 block, or if you want to use a specific/22 and/28 that iscurrently not present.

Permissions required for this task

You can give the Apigee provisioner a predefined role that includes the permissions needed to complete this task, or give more fine-grained permissions to provide the least privilege necessary. SeePredefined roles andService networking permissions.

  1. Create these environment variables:
    RANGE_NAME=YOUR_RANGE_NAMENETWORK_NAME=YOUR_NETWORK_NAME

    Where:

  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 \  --addresses=OPTIONAL_ADDRESSES \  --project=$PROJECT_ID

    Where--addresses lets you optionally specify one or more address IPs for the prefix length of/22. For example, to allocate the CIDR block192.168.0.0/22, specify192.168.0.0 for the address and22 for the prefix length. See alsoCreating 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. 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 \  --addresses=OPTIONAL_ADDRESSES \  --project=$PROJECT_ID

    Where--addresses lets you optionally specify one or more address IPs for the prefix length of/28. For example, to allocate the CIDR block192.168.0.0/28, specify192.168.0.0 for the address and28 for the prefix length. See alsoCreating an IP allocation.

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

  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.

    WhereOPERATION_ID is the UUID of theLRO (long-running operation).

    Apigee creates a connection between your network and Google's services; specifically, Apigee connects your project to the Service Networking API throughVPC 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,seeUnderstanding organizations.

Permissions required for this task

You can give the Apigee provisioner a predefined role that includes the permissions needed to complete this task, or give more fine-grained permissions to provide the least privilege necessary. See:

  1. Create a new eval org using thegcloud 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 theprovision command, Google starts anLRO to create the eval org. This operation takes up to 40 minutes to complete. During that time,gcloud displays the following:

    Provisioning organization...
    Note: Theprovision command can create onlyeval organizations. It cannot be used to create production organizations.

    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 theFINISHED state. For example:

    UUID                                  ORGANIZATION  STATE00bab06f-c60c-41a5-4242-7SAMPLE7f     my-org        FINISHED429790a7-3151-4642-4343-7SAMPLE7f     my-org        FINISHEDd00a92a9-9b83-4642-4343-7SAMPLE7f     my-org        FINISHEDf48a00ff-7daa-4c4a-4444-7SAMPLE7f     my-org        FINISHED

Step 5: Configure routing

Decide whether to allow external access or internal only access:

Access typeDescription 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.

UsePrivate 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 aService 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 forinternal access only. You can skip toStep 6: Call the sample API proxy, where you will send a request to your API proxy.

External routing

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This section describes how to configure external routing usingPrivate 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.

Permissions required for this task

You can give the Apigee provisioner a predefined role that includes the permissions needed to complete this task, or give more fine-grained permissions to provide the least privilege necessary. SeePredefined roles andAccess routing permissions.

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 theservice attachment for your Apigeeinstance:
    curl -i -X GET -H "$AUTH" \  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances"

    In the following sample output, theserviceAttachment 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"}]}
    Note:The ID for the project that you used tocreate your Apigee organization always appears in theconsumerAcceptList list. In the example output shown above, it is the only project in the list.

  2. Create a Private Service Connect network endpoint group (NEG) that points to the serviceattachment that you obtained from the instance response body in the previous step.

    gcloud compute network-endpoint-groups createNEG_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 toconnect 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.NOTE:If you specify the--network parameter,you must also specify--subnet.

Step 5b: Configure the load balancer

Configure aglobal external HTTP(S) load balancer (load balancing scheme set toEXTERNAL_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 createADDRESS_NAME \  --ip-version=IPV4 --global --project=$PROJECT_ID

    ReplaceADDRESS_NAME with a name for the IP address resource.

    Run this command to view the reserved IP address:

    gcloud compute addresses describeADDRESS_NAME \  --format="get(address)" --global --project=$PROJECT_ID
  2. Create a backend service for the NEG.
    gcloud compute backend-services createBACKEND_SERVICE_NAME \  --load-balancing-scheme=EXTERNAL_MANAGED \  --protocol=HTTPS \  --global --project=$PROJECT_ID

    3. ReplaceBACKEND_SERVICE_NAME with the name of the backend service.

  3. Add the NEG to the backend service:
    gcloud compute backend-services add-backendBACKEND_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.

  4. 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 createURL_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.

  5. Create an SSL certificate for the HTTPS target proxy.

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

    Note:To create a Google-managed certificate, you must have a registered domain.

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

    gcloud compute ssl-certificates createCERTIFICATE \  --domainsDOMAIN --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, seeUsing self-managed SSL certificates.

    gcloud compute ssl-certificates createCERTIFICATE \  --certificateLB_CERT \  --private-keyLB_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.

  6. 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 describeCERTIFICATE \   --global \   --format="get(name,managed.status, managed.Status)"
  7. Add the domain to the Apigee environment group that was created for you. The name of the environment group iseval-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"'"]  }'
  8. Check the status of the environment group operation:
    curl -H "$AUTH" \  "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups/eval-group/attachments"

  9. Use the SSL certificate resource to create a target HTTPS proxy.

    gcloud compute target-https-proxies createPROXY_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.
  10. Create the forwarding rule.
    gcloud compute forwarding-rules createFWD_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 provisioning is complete.

Step 6: Call the sample API proxy

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

Permissions required for this task

Creating and deploying proxies requires a minimum set of permissions. If you have Apigee Org Admin role, you can complete this task. To learn about other roles you can employ, seeApigee roles.

Call the proxy with internal routing

If you chose the internal routing option in Step 5, follow the steps inCalling 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 issales.example.com and the IP is 10.23.0.2, then point the record forsales.example.com to the address10.23.0.2.

      Run this command to view the reserved IP address:

      gcloud compute addresses describeADDRESS_NAME \  --format="get(address)" --global --project=$PROJECT_ID
    • Use GoogleCloud DNS to map a URL to an IP address.
  2. Confirm that thehello-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

    WhereDOMAIN is the domain you put into the certificate and added to the environment group, as discussed inStep 5: Configure routing. If needed, you can use this API to get theDOMAIN 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, seeTroubleshoot 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 describeADDRESS_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
    Note: DNS changes are published immediately, but may take time to propagate. Because of this delay, you may have to wait up to an hour before you can call the sample proxy.

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.