Calling an API proxy with internal-only access

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

View Apigee Edge documentation.

This document explains how to call API proxies from clients running on your internal network. These steps are useful for testing your setup if Apigee is provisioned to use internal network routing. You can follow the steps in this document if Apigee was provisioned with any of these network routing configurations:

Provisioning option Networking option Provisioning steps
Paid subscription With VPC peering Internal routing (VPC)
Internal routing (PSC)
Pay-as-you-go With VPC peering Internal routing (VPC)
Internal routing (PSC)
Evaluation With VPC peering Configure routing (internal)
Evaluation Without VPC peering Internal routing (PSC)

See also Networking options.

Before you begin

Do the following preliminary setup steps:

  1. If you haven't already, 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.
  2. Define the following local environment variables:

    export PROJECT_ID=YOUR_PROJECT_ID
    export AUTH="Authorization: Bearer $(gcloud auth print-access-token)"
    export SUBNET=NETWORK_NAME
    export INSTANCE_NAME=INSTANCE_NAME
    export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

    Where:

    • PROJECT_ID is the Cloud project ID that you created as part of the Prerequisites.
    • 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.
    • SUBNET is the subnet specified during provisioning. For example: default.
    • INSTANCE_NAME: Your new instance's name. For example, my-runtime-instance. The name must start with a lowercase letter, can be up to 32 characters long, and can include only lowercase letters, numbers and hyphens. It cannot start or end with a hyphen and must be at least two characters long.
    • PROJECT_NUMBERis 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.
  3. Get the value of the location property from your Apigee instance. This value is the region where the instance is located, such as us-west1:
    curl -H "$AUTH" https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances
  4. Pick a zone within the instance region, and put the zone name in a variable. The zone must be within the instance. For example:
    export VM_ZONE="us-west1-b"

    If you need help identifying a zone within the instance region, you can use this gcloud command to return a zone name for the configured runtime region. For example:

    VM_ZONE=$(gcloud compute zones list | grep "us-west1" | head -n 1 | awk '{print $1}')

Create a VM and call the API proxy

Next, create a new VM inside your VPC network using the gcloud beta compute command. The VM acts as a bridge that allows you to send requests to the internal load balancer IP. After the VM is set up, you can call a deployed API proxy:

  1. The following example creates a new VM with some common options and uses environment variables that you defined previously as inputs.
    gcloud beta compute --project=$PROJECT_ID \
      instances create $INSTANCE_NAME \
      --zone=$VM_ZONE \
      --machine-type=e2-micro \
      --subnet=$SUBNET \
      --network-tier=PREMIUM \
      --no-restart-on-failure \
      --maintenance-policy=TERMINATE \
      --preemptible \
      --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --scopes=https://www.googleapis.com/auth/cloud-platform \
      --tags=http-server,https-server \
      --image=debian-12-bookworm-v20240701 \
      --image-project=debian-cloud \
      --boot-disk-size=10GB \
      --boot-disk-type=pd-standard \
      --boot-disk-device-name=$INSTANCE_NAME \
      --no-shielded-secure-boot \
      --shielded-vtpm \
      --shielded-integrity-monitoring \
      --reservation-affinity=any
  2. Open a secure connection to the new VM that you just created.

    gcloud compute ssh $INSTANCE_NAME --zone=$VM_ZONE --project=$PROJECT_ID
  3. In the VM shell, install the jq utility. It is used in subsequent steps:
    sudo apt-get update -y
    sudo apt-get install -y jq
    
  4. In the VM shell, create the following environment variables to make it easy to copy/paste the API proxy request:
    export AUTH="Authorization: Bearer $(gcloud auth print-access-token)"
    export PROJECT_ID=YOUR_PROJECT_ID
    export ENV_GROUP_HOSTNAME=$(curl -H "$AUTH" https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/envgroups -s | jq -r '.environmentGroups[0].hostnames[0]')
    
  5. Make sure the variables are set correctly:
    echo $AUTH
    echo $PROJECT_ID
    echo $ENV_GROUP_HOSTNAME
  6. Call an API proxy. Select an option below that corresponds to how you configured routing during Apigee provisioning.

    Options for installations that use VPC peering

    • (TLS option #1) If you configured an internal load balancer (ILB) in your project, as explained in Internal routing (VPC), call the proxy using the IP of that ILB. This option uses CA certs that are under your control and that were created when the internal load balancer was created:
      1. Get the IP of the ILB in your project, as explained in Set up Internal HTTP(S) Load Balancing with VM instance group backends.
      2. Call an API proxy:
        curl -H "Host: $ENV_GROUP_HOSTNAME" \
          https://INTERNAL_LOAD_BALANCER_IP/PROXY_BASEPATH
    • (TLS option #2) Use the default, fully qualified domain name that resolves to the internal load balancer in the Apigee project. With this option, TLS is employed using internally created Apigee self-signed certs. You do not have control over these certificates.
      1. Get the IP of the internal load balancer in the Apigee project:
        export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s | jq -r '.instances[0].host')
      2. Pull the CA Certificate that was created during org creation with the following command:
        curl -H "$AUTH" https://apigee.googleapis.com/v1/organizations/$PROJECT_ID | jq -r .caCertificate | base64 -d > cacert.crt
      3. Send the request to a deployed API proxy, where example.$PROJECT_ID.apigee.internal is the internal, default, fully qualified domain name that resolves to the internal load balancer.
        curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
          https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
          --cacert cacert.crt \
          --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP
    • (Non-TLS option) If you do not need TLS, you can use the -k flag on the curl command to disable TLS and possibly avoid SSL issues:
      1. Get the IP of the internal load balancer in the Apigee project:
        export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s | jq -r '.instances[0].host')
      2. Call an API proxy:
        curl -i -k \
          -H "Host: $ENV_GROUP_HOSTNAME" \
          https://$INTERNAL_LOAD_BALANCER_IP/PROXY_BASEPATH
    • (Service endpoint option) If you provisioned a paid or evaluation organization with PSC and chose the service endpoint routing option:
      1. Get the IP of the service endpoint. If you need to look up the endpoint IP, see List endpoints.
      2. Call an API proxy:
        curl -i -k \
           -H "Host: $ENV_GROUP_HOSTNAME" \
           https://SERVICE_ENDPOINT_IP/PROXY_BASEPATH

        For example:

        curl -H "Host: $ENV_GROUP_HOSTNAME" https://10.138.0.2/helloworld -k

    Options for installations that do not use non-VPC peering

    • (Service endpoint option) If you provisioned a paid or evaluation organization with PSC and chose the service endpoint routing option:
      1. Get the IP of the service endpoint. If you need to look up the endpoint IP, see List endpoints.
      2. Call an API proxy:
        curl -i -k \
            -H "Host: $ENV_GROUP_HOSTNAME" \
            https://SERVICE_ENDPOINT_IP/PROXY_BASEPATH

        For example:

        curl -H "Host: $ENV_GROUP_HOSTNAME" https://10.138.0.2/helloworld -k

    If you encounter errors during this part of the process, be sure that all of the environment variables you created and used in commands have valid values. See also Troubleshooting.

    Next step

    Try creating a proxy which you can then deploy, or take a tour of the Apigee tutorials that will introduce you to the features of Apigee, such as guarding against sudden traffic spikes or getting a detailed view of the request/response flow.

    (Advanced) If you plan on turning this into a production setup, you can configure a security perimeter around your new cluster and related Cloud services. This is possible with VPC Service Controls.