Southbound networking patterns

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

This document explains how to use Private Service Connect (PSC) to connect Apigee with backend target services running in VPC networks other than the one that is peered with your Apigee organization. API proxy traffic that flows between Apigee and a backend target is referred to as "southbound" traffic.

Overview

For Apigee X provisioning, we use VPC peering to connect your Virtual Private Cloud (VPC) network with the Apigee VPC network. This configuration allows bi-directional communication between the two VPC networks and allows Apigee API proxies to call target services deployed in your VPC. For details, see the Apigee architecture overview.

For example, when you create an Apigee organization, you provide the name of a network in your VPC that Apigee will peer with:

curl -H "$AUTH" -X POST \
  -H "Content-Type:application/json" \
  "https://apigee.googleapis.com/v1/organizations?parent=projects/$PROJECT_ID"  \
  -d '{
    "name":"'"$PROJECT_ID"'",
    "analyticsRegion":"'"$ANALYTICS_REGION"'",
    "runtimeType":"CLOUD",
    "authorizedNetwork":"NETWORK_NAME",
    "runtimeDatabaseEncryptionKeyName":"DATABASE_KEY_NAME"
  }'

If target applications are in the peered network, Apigee can access their IP addresses and route API proxy traffic to them.

Many enterprises have multiple networks where applications and services are deployed; however, Apigee supports peering with only one network. PSC allows you to privately connect Apigee to target services running across VPC networks in addition to the peered network.

Privately connecting Apigee to backend targets

To privately connect Apigee to a backend target, you must create two entities: a service attachment in the VPC network where the target is deployed and an endpoint attachment in the Apigee VPC. These two entities allow Apigee to connect to the target service.

This configuration is illustrated in Figure 1:

Figure 1: Private service connections

Limitations

  • Global access is not supported. This means that service attachments and endpoint attachments must be in the same region. For example, if your Apigee instance is in the region us-west1, you cannot connect services to it that are in us-east2 or any other region.
  • In an Apigee organization, one endpoint attachment is allowed for a given service attachment. For example, assume you have 10 service attachments that expose target services. You can create 10 endpoint attachments in your Apigee organization, one for each service attachment.

Example: Exposing a target service to Apigee

This example shows how to use PSC to enable Apigee to communicate with a target service running in a VPC network that is not directly peered with Apigee. The steps in this example use gcloud and Apigee API calls to set up and configure a service attachment in the VPC network where the target is deployed and an endpoint attachment in the Apigee VPC.

Example scenario

This example considers a case where you have microservices deployed in a Google Kubernetes Engine (GKE) cluster running in a VPC. To be able to communicate with Apigee in this context, the services are exposed through an ingress gateway.

Set up a load balancer

Set up a load balancer in your VPC where the microservices you wish to expose are located:

  1. Create these environment variables:
    export PROJECT_ID=YOUR_PROJECT_ID
    export IMAGE_FAMILY=debian-10
    export BACKEND=foo
    export REGION=us-west1
    export ZONE=us-west1-a
    export NETWORK=default
    export SUBNET_NAME=default
  2. Create an instance template:
    gcloud compute instance-templates create "$BACKEND" \
      --tags=http-server,https-server \
      --image-family "$IMAGE_FAMILY" --image-project "$PROJECT_ID" \
      --metadata startup-script="#! /bin/bash
    sudo apt-get update
    sudo apt-get install apache2 -y
    sudo service apache2 restart
    echo '<!doctype html><html><body><h1>foo[/]: '\`/bin/hostname\`'</h1></body></html>' | sudo tee /var/www/html/index.html
    sudo mkdir /var/www/html/foo
    echo '<!doctype html><html><body><h1>foo[/foo]: '\`/bin/hostname\`'</h1></body></html>' | sudo tee /var/www/html/foo/index.html"
  3. Create a managed instance group:
    gcloud compute instance-groups managed create $BACKEND \
        --project $PROJECT_ID --base-instance-name $BACKEND \
        --size 1 --template $BACKEND --region $REGION
  4. Create a health check:
    gcloud compute instance-groups managed set-named-ports $BACKEND \
        --project $PROJECT_ID --region $REGION --named-ports http:80
  5. Create a load balancer:
    1. Create a backend service:
      gcloud compute backend-services create be-ilb \
          --load-balancing-scheme=internal \
          --protocol=tcp \
          --region=$REGION \
          --health-checks=$BACKEND \
          --health-checks-region=$REGION \
          --project=$PROJECT_ID
    2. Add the managed instance group to the backend service:
      gcloud compute backend-services add-backend be-ilb \
          --region=$REGION \
          --instance-group=$BACKEND \
          --instance-group-zone=$ZONE \
          --project=$PROJECT_ID
      
    3. Create a forwarding rule:
      gcloud compute forwarding-rules create fr-ilb \
          --region=$REGION \
          --load-balancing-scheme=internal \
          --network=$NETWORK \
          --subnet=$SUBNET_NAME \
          --ip-protocol=TCP \
          --ports=80 \
          --backend-service=be-ilb \
          --backend-service-region=$REGION \
          --project=$PROJECT_ID

Create a service attachment

Create a PSC service attachment in the VPC network where the target services are deployed.

  1. To perform this task, you must have the compute.subnetworks.create permission or the Compute Network Admin IAM role (roles/compute.networkAdmin).
  2. Create a PSC subnet with the purpose parameter set to PRIVATE_SERVICE_CONNECT:
    gcloud compute networks subnets create NAME \
      --network NETWORK --region=REGION --purpose=PRIVATE_SERVICE_CONNECT --range=RANGE

    For a detailed description of the command parameters, see the Google Cloud CLI reference. You can also perform this step in the Console or with an API.

    For example:

    gcloud compute networks subnets create psc-subnet --network default \
    --region=us-west1 --purpose=PRIVATE_SERVICE_CONNECT --range=10.100.0.0/28
  3. Create a service attachment in your VPC network:
    1. Get the forwarding rule of the internal load balancer. You will use this rule in a later step:
      gcloud compute forwarding-rules list --project=PROJECT_ID

      Where PROJECT_ID is a Google Cloud project ID. For example:

      gcloud compute forwarding-rules list --project=my-project
      NAME                                                  REGION    IP_ADDRESS    IP_PROTOCOL  TARGET
      k8s2-tcp-e61tta3j-apps-istio-ingressgateway-0kl92frk  us-west1  10.138.0.53   TCP
      
    2. Create the service attachment:
      gcloud compute service-attachments create NAME \
          --region=REGION --producer-forwarding-rule=PRODUCER_FORWARDING_RULE \
          --connection-preference=ACCEPT_AUTOMATIC --nat-subnets=NAT_SUBNETS --project=PROJECT_ID

      The NAME parameter must be a string 1-63 characters long, consisting of lowercase letters, numbers and hyphens only. It cannot have leading numbers and hyphens. Also, it cannot have trailing hyphens. For a detailed description of the parameters for this command, see the Google Cloud CLI reference.

      For example:

      gcloud compute service-attachments create gkebackend \
          --region=us-west1 --producer-forwarding-rule=k8s2-tcp-e62tta1j-apps-istio-ingressgateway-0kl92frk \
          --connection-preference=ACCEPT_AUTOMATIC --nat-subnets=psc-subnet --project=my-project

      You can also perform this step in the Console UI. See, for example, Publish a service with automatic project approval.

Create an endpoint attachment

Create an endpoint attachment in the Apigee organization. You can perform this step from the command line or the Apigee Endpoint attachment UI.

Prerequisite: Before you create an endpoint attachment, you must publish the services you wish to expose using Private Service Connect (PSC) by creating a load balancer and a service attachment, as explained previously in this example. For more information on exposing services with PSC, see Publish managed services using Private Service Connect. Note that the service attachment must be configured to accept new connections.

Command line

Create an endpoint attachment in the Apigee VPC from the command line:

  1. Get the service attachment resource:
    gcloud compute service-attachments list

    The command returns the service attachment information. You will use this information in the next step. For example:

    NAME       REGION   TARGET_SERVICE                                       CONNECTION_PREFERENCE
    gkebackend us-west1 k8s2-tcp-tgysilgj-apps-istio-ingressgateway-fzdhwstg ACCEPT_AUTOMATIC
  2. Get the authentication token for the Apigee API:
    TOKEN="$(gcloud auth print-access-token)"
  3. Use this Apigee API to create the endpoint attachment. Use values returned from the gcloud compute service-attachments list command in the body of the request:
    curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type:application/json" \
    "https://apigee.googleapis.com/v1/organizations/ORGANIZATION/endpointAttachments?endpointAttachmentId\=NAME" \
    -d '{
        "location": "REGION",
        "serviceAttachment": "projects/PROJECT_ID/regions/REGION/serviceAttachments/NAME"
    }'

    Where:

    • REGION is the region of the service attachment. For example: us-west1
    • ORGANIZATION is your Apigee organization name.
    • PROJECT_ID is the Google Cloud project where the service attachment was created.
    • NAME is the name of the service attachment. For example: gkebackend

    Apigee starts a long-running operation. When the operation is complete, you will see a response similar to the following:

    {
      "name": "organizations/my-organization/operations/6e249895-e78e-48f0-a28f-7140e15e1676",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
        "operationType": "INSERT",
        "targetResourceName": "organizations/my-organization/endpointAttachments/gkebackend",
        "state": "FINISHED"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.cloud.apigee.v1.EndpointAttachment",
        "name": "organizations/my-organization/endpointAttachments/gkebackend",
        "location": "us-west1",
        "host": "7.0.3.4",
        "serviceAttachment": "projects/my-project/regions/us-west1/serviceAttachments/gkebackend"
      }
    }

    You can now use the IP Address 7.0.3.4 returned in the response to connect to the services behind the service attachment, as shown in the next step. Note that 7.0.3.4 is a privately used public IP (PUPI) assigned by Apigee to the ingress gateway. It is not advertised on the internet and no Google services use IPs in this range internally.

  4. Use the service attachment host IP as the target of an API proxy. For example:
    <TargetEndpoint name="default">
        <HTTPTargetConnection>
            <URL>http://7.0.3.4/orders</URL>
        </HTTPTargetConnection>
    </TargetEndpoint>

Apigee UI

Create an endpoint attachment in the Apigee organization in the Apigee UI:

  1. In the Apigee UI, go to Admin > Endpoint Attachments.
  2. Click + Endpoint Attachment. The Endpoint attachment dialog appears.
  3. Enter a name for the endpoint attachment. The name must be unique. There can be no other endpoint attachments with the same name, and you cannot change the name later. The name can have 1-20 characters, must only contain lowercase letters and numbers, and must not contain a leading number. For example: endpoint1 is a valid name, while 1endpoint and Endpoint1 are invalid.
  4. In the Service Attachment section, enter the ID of Cloud project where the service attachment is located.
  5. Click Next.
  6. From the Service Attachment dropdown list, choose the service attachment to connect to.

    The behavior of the UI depends on your permissions. If you have permission to list regions and service attachments, you can simply select your service attachment from the dropdown list. If you do not have permission to list regions, then a static list of regions is shown, and you can select from the list. If you do not have permission to list service attachments, you have to enter the name manually. located and the name of the service attachment. Note that if you do not have permission to list regions, a static list of regions will be displayed for you to choose from.

    Location of the Apigee project ID needed for service attachment configuration.

  7. Verify that the service endpoint can accept connections. For steps, see Check and manage attachment connectivity.
  8. Click Next.
  9. Click Create. The operation typically takes one or two minutes to complete.
  10. To check the current creation status, click Refresh in the list page.
  11. Use the service attachment host IP as the target of an API proxy. The host IP appears in the Endpoint Attachments UI when the creation process completes, as shown in the following screenshot:

    The host IP of the service attachment is shown in the Endpoint attachment UI

    For example:
    <TargetEndpoint name="default">
        <HTTPTargetConnection>
            <URL>http://7.0.5.2/orders</URL>
        </HTTPTargetConnection>
    </TargetEndpoint>

Check and manage attachment connectivity

This section explains how to verify that a service attachment can access an endpoint attachment in your Apigee project, and how to change the connection preference if you wish to change it.

  1. Follow the steps in List published services to view the list of service attachments in your project.
  2. Select the service attachment you wish to connect to as explained in View details for a published service.
  3. Choose a connection preference for your published service attachment. Private Service Connect offers two options described below. If you wish to change the current connection preference, follow the steps in Change the connection preference for a published service.
    • Automatically accept all connections: The service attachment accepts endpoint attachments from any project. If you choose this option, the service attachment will be able to accept a connection from an endpoint attachment in the Apigee project. No further configuration is required.
    • Accept connections from selected projects: You specify the projects from which the service attachment will accept connections. If you choose this option, you must add the project ID of the Apigee project to the service attachment. You can find the Apigee project ID in the Verify project connection step in the Endpoint attachment UI, as shown in this screenshot:

      Location of the Apigee project ID needed for service attachment configuration.

      You can also retrieve the Apigee project ID using the Apigee Organizations API, which returns the ID in a field named apigeeProjectId.

  4. If you made changes to the connection preferences, save your changes.

Managing endpoint attachments

The Apigee endpointAttachments API provides methods to create, delete, get, and list endpoint attachments.

Listing endpoint attachments

You can see a list of endpoint attachments in the Apigee Endpoint attachment UI or by calling the Apigee Endpoints API.

To list an endpoint attachments in the Apigee UI:

  1. In the Apigee UI, go to Admin > Endpoint Attachments.
  2. View the list of endpoint attachments.

Creating an endpoint attachment

To create an endpoint attachment in the UI or with the Apigee Endpoints API, see Create an endpoint attachment.

Deleting an endpoint attachment

To delete an endpoint using the Apigee UI:

  1. In the Apigee UI, go to Admin > Endpoint Attachments.
  2. Select the Endpoint Attachment to delete.
  3. Click Delete Endpoint Attachment.

You can also use the Apigee Endpoints API to list, create, and delete endpoint attachments.