Southbound networking patterns

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

View Apigee Edge documentation.

This document explains how to use Private Service Connect (PSC) to create a private connection between Apigee and backend target services. By default, you can access target endpoints globally. Note that API proxy traffic that flows between Apigee and a backend target service is referred to as "southbound" traffic.

The southbound networking configuration steps described in this document apply to both VPC-peered and non-VPC peered Apigee instances. Note, however, that the private DNS peering is only supported for VPC-peered Apigee instances.

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.

Note: Global access is enabled by default on all endpoints. This means that the Apigee instance and the endpoint attachment can be in different regions, and the Apigee instance should be able to reach the cross-regional endpoint attachment. For example, if your Apigee instance is in region us-west1, it can connect to services in us-east2 or any other available region. See Figure 1.

Figure 1 illustrates the Apigee networking architecture that supports global access for southbound connections across multiple regions:

Figure 1: Apigee southbound networking architecture.

Limitations

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 an Apache web server deployed on a Managed Instance Group (MIG) running in your VPC. To be able to communicate with Apigee in this context, we expose the services 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:

Create these environment variables:

export PROJECT_ID=YOUR_PROJECT_ID
export IMAGE_PROJECT=debian-cloud
export IMAGE_FAMILY=debian-12
export BACKEND=foo
export REGION=us-west1
export ZONE=us-west1-a
export NETWORK=default
export SUBNET_NAME=default

Create an instance template:

gcloud compute instance-templates create "$BACKEND" \
    --tags=psc-demo,http-server,https-server \
    --image-family "$IMAGE_FAMILY" --image-project "$IMAGE_PROJECT" \
    --network "$NETWORK" --subnet "$SUBNET_NAME" --region "$REGION" \
    --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"

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

Create a health check:

gcloud compute instance-groups managed set-named-ports $BACKEND \
    --project $PROJECT_ID --region $REGION --named-ports http:80

gcloud compute health-checks create tcp hc-tcp-$BACKEND \
  --region=$REGION \
  --description="health check for psc backend" \
  --port-name=http --project=$PROJECT_ID

Create a load balancer:

Create a backend service:

gcloud compute backend-services create be-ilb \
    --load-balancing-scheme=internal \
    --protocol=tcp \
    --region=$REGION \
    --network=$NETWORK \
    --health-checks=hc-tcp-$BACKEND \
    --health-checks-region=$REGION \
    --project=$PROJECT_ID

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

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.

To perform this task, you must have the compute.subnetworks.create permission or the Compute Network Admin IAM role (roles/compute.networkAdmin).

Create a PSC subnet with the purpose parameter set to PRIVATE_SERVICE_CONNECT:

gcloud compute networks subnets create PSC_SUBNET_NAME \
  --network NETWORK --region=REGION --purpose=PRIVATE_SERVICE_CONNECT --range=RANGE

gcloud compute --project=$PROJECT_ID firewall-rules create allow-psc-nat-80 \
  --direction=INGRESS --priority=1000 --network NETWORK --action=ALLOW --rules=tcp:80
  --source-ranges=RANGE --target-tags=psc-demo

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

Create a service attachment in your VPC network:

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

Create the service attachment:
```
gcloud compute service-attachments create PSC_NAME \
    --region=REGION --producer-forwarding-rule=PRODUCER_FORWARDING_RULE \
    --connection-preference=ACCEPT_AUTOMATIC --nat-subnets=PSC_SUBNET_NAME --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:

To perform this task, you must have the Apigee Organization Admin role (roles/apigee.admin).

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

Get the authentication token for the Apigee API:
```
TOKEN="$(gcloud auth print-access-token)"
```
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=EA_NAME" \
-d '{
    "location": "REGION",
    "serviceAttachment": "projects/PROJECT_ID/regions/REGION/serviceAttachments/SA_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.
- EA_NAME is the name of 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 must start with a lowercase letter followed by up to 31 lowercase letters, numbers, or hyphens, but it cannot end with a hyphen. The minimum length is 2.
- SA_NAME is the name of the service attachment.
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.

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:

To perform this task, you must have the Apigee Organization Admin role (roles/apigee.admin).

In the Apigee UI, go to Admin > Endpoint Attachments.
Click + Endpoint Attachment. The Endpoint attachment dialog appears.
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 must start with a lowercase letter followed by up to 31 lowercase letters, numbers, or hyphens, but it cannot end with a hyphen. The minimum length is 2.
Click Next.
From the Service Attachment dropdown list, choose the service attachment to connect to.
Note: You must choose a service attachment that does not already have an endpoint attachment.

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.
Verify that the service endpoint can accept connections. For steps, see Check and manage attachment connectivity.
Click Next.
Click Create. The operation typically takes one or two minutes to complete.
To check the current creation status, click Refresh in the list page.
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:
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.

Follow the steps in List published services to view the list of service attachments in your project.
Select the service attachment you wish to connect to as explained in View details for a published service.
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:
  
  You can also retrieve the Apigee project ID using the Apigee Organizations API, which returns the ID in a field named apigeeProjectId.
If you made changes to the connection preferences, save your changes.
In the Apigee UI, go to Admin > Endpoint Attachments. You can also list the endpoint attachments with the Apigee Endpoints API.
In the list of attachments, verify the PSC Connection Status is now ACCEPTED. If the field shows a status other than ACCEPTED, see Troubleshooting PSC connection state issues.

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:

In the Apigee UI, go to Admin > Endpoint Attachments.
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:

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

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

Private DNS peering

If you have a Cloud DNS private zone hosted in the Cloud project that is peered with Apigee, you can configure DNS peering to allow Apigee to resolve names in your private zone. By default, private zones are private to the VPC network in which they are hosted. For steps to configure DNS peering between a private DNS zone and Apigee (the service producer), see Share private DNS zones with service producers.

Troubleshooting

PSC connection state issues

This section describes possible solutions when an endpoint attachment has been provisioned and the status is Active, but the connection state is not Accepted. Some possible connection states are shown in Figure 2.

Figure 2: Endpoint attachment state details

The state given can help point to the likely cause, as described in the following table:

Connection state	Possible cause	Recommended solution
ACCEPTED	The service attachment has accepted the connection from the connection endpoint.	N/A
PENDING	The Apigee project ID may not be in the consumer accepted projects list nor in the rejected list.	Add the Apigee project ID to the consumer accept list on the service attachment. See Change the connection preference for a published service.
REJECTED	The Apigee project ID is in the consumer reject list.	Remove the Apigee project ID from the consumer reject list and add it to the consumer accept list on the service attachment. See Manage requests for access to a published service.
FROZEN	The service attachment for this endpoint attachment has been suspended or disabled.	Describe the service attachment for details. See View details for a published service.
CLOSED	The service attachment for this endpoint attachment has been deleted.	Recreate the service attachment and endpoint attachment.
NEEDS_ATTENTION	The endpoint attachment has been accepted by the service attachment, however there is an issue with the service attachment.	Describe the service attachment for more details. See View details for a published service.
UNAVAILABLE	The connectivity state is unavailable, which can occur during provisioning.	Wait a few minutes to see if the status changes.

PSC configuration with Apigee

See the Apigee connectivity issues with southbound PSC targets playbook.