Create an endpoint attachment

To configure private connectivity for the Integration Connectors, you must create a PSC (Private Service Connect) attachment. However, to use the PSC attachment, you must also create an endpoint attachment as you can't use the PSC attachment directly. You can think of the endpoint attachment as an interface to the PSC service attachment. Once created, you can use the endpoint attachment details when configuring a connector for private connectivity. This page explains how to create an endpoint attachment and assumes you are familiar with the following concepts:

You can create the endpoint attachment either as an IP address or as a hostname.

Create an endpoint attachment as an IP address
Create an endpoint attachment as a hostname

Create an endpoint attachment as an IP address

To create an endpoint attachment as an IP address, you can use either the Cloud console or the command line (gcloud).

To create an endpoint attachment, you must have the connectors.endpointAttachments.create permission which is available either in the roles/connectors.admin IAM role or the roles/connectors.endpointAttachmentsAdmin IAM role. For information on the various IAM roles and their corresponding permissions available for Integration Connectors, see IAM roles and permissions for Integration Connectors

Console

To create an endpoint attachment from the Cloud console, do the following:

Open the Endpoint attachments page for Integration Connectors.
Go to Endpoint attachments
Click + Create. The Create Endpoint Attachment page opens.
Enter values for the following fields:
- Name: 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 63 lowercase letters, numbers, or hyphens, but it cannot end with a hyphen. The minimum length is 2.
- Service Attachment ID: Name of the PSC service attachment that you have already created.
  Note: You must get the project ID of the service directory associated with your Google Cloud project, and then allowlist that project ID in your service attachment.
- (Optional) Description: Enter a description for the endpoint attachment.
- (Optional) Labels: Enter resource labels as key-value pairs. For more information about labels, see What are labels?
Click Create.

The IP Address column specifies the IP address of the endpoint attachment. You must use this IP address when configuring a connector for private connectivity.

gcloud

To create an endpoint attachment from the command line, do the following:

Get the PSC service attachment resource:

gcloud compute service-attachments list

The command returns the list of service attachments. For example:

NAME       REGION   TARGET_SERVICE                                       CONNECTION_PREFERENCE
demo-sa us-west1 k8s2-tcp-tgysilgj-apps-ingressgateway-fzdhwstg ACCEPT_AUTOMATIC

You will need this service attachment information in the subsequent steps.

Get an authentication token before you run the CreateEndpointAttachment API:
```
TOKEN="$(gcloud auth print-access-token)"
```
Create the endpoint attachment by using the CreateEndpointAttachment API. For example:
```
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/endpointAttachments/ENDPOINT_ATTACHMENT_NAME",
    "serviceAttachment": "projects/demo/serviceAttachments/?SERVICE_ATTACHMENT_NAME"
  }' \
     https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpointAttachments?endpointAttachmentId=ENDPOINT_ATTACHMENT_NAME
```
Where:
- LOCATION is the region of the service attachment. For example, us-west1.
- PROJECT_ID is the Google Cloud project where you have created the PSC service attachment.
- ENDPOINT_ATTACHMENT_NAME is the name of the endpoint attachment. The name must be unique. There can't be 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.
- SERVICE_ATTACHMENT_NAME is the name of the service attachment. Use the PSC service account name returned by the previously run gcloud compute service-attachments list command.
After you call the API, Integration Connectors starts a long-running operation, and it may take some time to complete the operation. The endpoint attachment will be created after the operation completes successfully.
Get the project ID of the service directory associated with your Google Cloud project, and then allowlist that project ID in your service attachment.

Verify if the endpoint attachment is created by using the GetEndpointAttachment API. For example:

curl -X GET -H "Authorization: Bearer $TOKEN" \
  https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpointAttachments/ENDPOINT_ATTACHMENT_NAME

The API returns a response similar to the following:

{
  "name": "projects/demo-project/locations/us-central1/endpointAttachments/demo-ea",
  "createTime": "2023-04-17T04:34:59.569527046Z",
  "updateTime": "2023-04-17T04:37:25.189074195Z",
  "description": "demo endpoint attachment",
  "serviceAttachment": "projects/demo-project/regions/us-central1/serviceAttachments/demo-sa",
  "endpointIp": "10.0.0.0",
  "labels": {"team":"sre"},
}

The IP address of the endpoint attachment is available in the endpointIp field. In this sample response, the IP address is 10.0.0.0. Use this IP address when configuring a connector for private connectivity.

If the endpoint attachment creation is successful, the newly created attachment is listed in the Endpoint Attachments page, similar to the following image:

The steps, described till now, show how to create an endpoint attachment as an IP address. However, you can also create an endpoint attachment as a hostname and use the hostname to configure a connector for private connectivity. To understand how to create an endpoint attachment with a hostname, see Create an endpoint attachment as a hostname.

Create an endpoint attachment as a hostname

To create an endpoint attachment as a hostname, perform the following tasks:

Create an endpoint attachment as an IP address. For more information, see Create an endpoint attachment as an IP address.
Create a Cloud DNS private managed zone in any of your Google Cloud projects.
In this DNS zone, you must add a hostname that you want to use for connector configuration and map the hostname to the endpoint attachment IP address that you got from step 1. For information on how to create a Cloud DNS private managed zone, see Create a private zone and Add a record.
Create an Integration Connectors managed zone in your Google Cloud project that you use for the Integration Connectors. The Integration Connectors managed zone (peering zone) communicates with the Cloud DNS private managed zone (created in step 2) for name resolution.

Before creating the managed zone, you must grant the following roles and permissions:
- Grant the connectors.managedZones.create permission to the user creating the Integration Connectors managed zone.
  The connectors.managedZones.create permission is available either in the roles/connectors.admin IAM role or the roles/connectors.managedZonesAdmin IAM role. For information on the various IAM roles and their corresponding permissions available for Integration Connectors, see IAM roles and permissions for Integration Connectors.
- Grant the role/dns.peer role to the Integration Connectors service-PROJECT_NUMBER@gcp-sa-connectors.iam.gserviceaccount.com service account.
  If the Cloud DNS Google Cloud project is different from the Integration Connectors Google Cloud project, then grant the roles/dns.peer role to the Integration Connectors service account in the Cloud DNS Google Cloud project. For example, consider you want to create the Integration Connectors managed zone in Google Cloud project 12345 and the Cloud DNS is in the Google Cloud project 67890. In this case, you must grant the roles/dns.peer role to the service-12345@gcp-sa-connectors.iam.gserviceaccount.com service account in the Google Cloud project 67890.
To create an Integration Connectors managed zone, you can use either the Cloud console or the command line (gcloud).
Console

To create an Integration Connectors managed zone from Cloud console, do the following:
1. Go to the Managed zones page for Integration Connectors.
  Go to Managed zones
2. Enter values for the following fields:
  1. Name: A name for the managed zone.
  2. Target DNS name: Full Cloud DNS name for which you are creating the managed (peering) zone. For example, server8.stage.user.private.
  3. Target project: Name of the Google Cloud project which has the private Cloud DNS zone.
  4. Target network: Name of the VPC network in which the private Cloud DNS zone is maintained.
  5. (Optional) Description: Enter a description for the endpoint attachment.
  6. (Optional) Labels: Enter resource labels as key-value pairs. For more information about labels, see What are labels?
3. Click Create.
gcloud

To create an Integration Connectors managed zone from the command line, do the following:
1. Get an authentication token before you run the CreateManagedZone API:
```
TOKEN="$(gcloud auth print-access-token)"
```
2. Create the managed zone by using the CreateManagedZone API. For example:
```
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "description": "DESCRIPTION",
  "dns": "DNS_NAME",
  "target_project": "TARGET_PROJECT",
  "target_vpc": "TARGET_VPC"
}' \
https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/managedZones?managedZoneId=MANAGED_ZONE_NAME
```
  Where:
  - DESCRIPTION is an optional description for the managed zone.
  - DNS_NAME: Full Cloud DNS name for which you are creating the managed (peering) zone. For example, server8.stage.user.private.
  - TARGET_PROJECT is the name of the Google Cloud project which has the private Cloud DNS zone.
  - TARGET_NETWORK is the name of the VPC network in which the private Cloud DNS zone is maintained.
  - PROJECT_ID is your Google Cloud project which you are using for Integration Connectors.
  - MANAGED_ZONE_NAME is the name of the managed zone. The name must be unique. There can't be other managed zones with the same name, and you cannot change the name later. The name must start with a lowercase letter followed by up to 63 lowercase letters, numbers, or hyphens, but it cannot end with a hyphen. The minimum length is 2.
  After you call the API, Integration Connectors starts a long-running operation and it may take some time to complete the operation. The managed zone will be created after the operation completes successfully.
3. Verify if the managed zone is created by using the GetManagedZone API. For example:
```
curl -X GET -H "Authorization: Bearer $TOKEN" \
  https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/managedZones/MANAGED_ZONE_NAME
```
  The API returns a response similar to the following:
```
{
  "name": "projects/demo-project/locations/global/managedZones/demo-mz",
  "createTime": "2023-04-17T04:34:59.569527046Z",
  "updateTime": "2023-04-17T04:37:25.189074195Z",
  "description": "demo managed zone",
  "dns": "api.private.service.com.",
  "targetVpc": "target-project-vpc",
  "targetProject": "target-project"
}
```

If the managed zone creation is successful, the newly created managed zone is listed in the Managed zones page similar to the following image:

Verify the endpoint attachment setup

You can verify the endpoint connectivity by creating a connection to your backend system. When you create the connection, in the Destinations section, select the Destination type as Hostname and then enter the appropriate endpoint IP address or hostname. If the connection creation is successful, the status of the newly created connection will be Active in your Connections page in the Cloud console.