Menu
Amazon Virtual Private Cloud
User Guide

VPC Endpoint Services (AWS PrivateLink)

You can create your own application in your VPC and configure it as an AWS PrivateLink-powered service (referred to as an endpoint service). Other AWS principals can connect to your endpoint service using an interface VPC endpoint. You are the service provider, and the AWS principals that connect to your service are service consumers.

The following are the general steps to create an endpoint service.

  1. Create a Network Load Balancer for your application in your VPC and configure it for each subnet (Availability Zone) in which you want the service to be available. The load balancer receives requests from service consumers and routes it to your service. For more information about creating a Network Load Balancer, see Getting Started with Network Load Balancers in the User Guide for Network Load Balancers. We recommend that you configure your service in all Availability Zones within the region.

  2. Create a VPC endpoint service configuration and specify your Network Load Balancer. You can optionally specify that any requests to connect to your service via an interface endpoint must first be accepted by you. If not, interface endpoint connection requests by service consumers are automatically accepted.

  3. Add permissions to your endpoint service to allow service consumers (other AWS accounts, IAM users, and IAM roles) to discover your service.

  4. A service consumer creates an interface endpoint to your service, optionally in each Availability Zone in which you've configured your service. If you specified that acceptance is required, you must accept the request to activate the connection. Otherwise, the connection is automatically available.

In the following diagram, the account owner of VPC B is a service provider, and has a service running on instances in subnet B. The owner of VPC B has a service endpoint (vpce-svc-1234) with an associated Network Load Balancer that points to the instances in subnet B as targets. Instances in subnet A of VPC A use an interface endpoint to access the services in subnet B.


                Using an interface endpoint to access an endpoint service

Endpoint Service Limitations

To use endpoint services, you need to be aware of the current limitations:

  • You cannot tag an endpoint service.

  • An endpoint service supports IPv4 traffic over TCP only.

  • Service consumers must use the endpoint-specific DNS hostnames to access the endpoint service. Private DNS is not supported. For more information, see Accessing a Service Through an Interface Endpoint.

  • Endpoint services are only available in the AWS Region in which they are created.

Creating a VPC Endpoint Service Configuration

You can create an endpoint service configuration using the Amazon VPC console or the command line. Before you begin, ensure that you have created one or more Network Load Balancers in your VPC for your service. For more information, see Getting Started with Network Load Balancers in the User Guide for Network Load Balancers.

To create an endpoint service using the console

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services, Create Endpoint Service.

  3. For Associate Network Load Balancers, select the Network Load Balancers to associate with the endpoint service.

  4. For Require acceptance for endpoint, select the check box to accept connection requests to your service manually. If you do not select this option, endpoint connections are automatically accepted.

  5. Choose Create service.

To create an endpoint service using the AWS CLI

  • Use the create-vpc-endpoint-service-configuration command and specify one or more ARNs for your Network Load Balancers. You can optionally specify if acceptance is required for connecting to your service.

    Copy
    aws ec2 create-vpc-endpoint-service-configuration --network-load-balancer-arns arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/nlb-vpce/e94221227f1ba532 --acceptance-required
    {
        "ServiceConfiguration": {
            "ServiceType": [
                {
                    "ServiceType": "Interface"
                }
            ], 
            "NetworkLoadBalancerArns": [
                "arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/nlb-vpce/e94221227f1ba532"
            ], 
            "ServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-03d5ebb7d9579a2b3", 
            "ServiceState": "Available", 
            "ServiceId": "vpce-svc-03d5ebb7d9579a2b3", 
            "AcceptanceRequired": true, 
            "AvailabilityZones": [
                "us-east-1d"
            ], 
            "BaseEndpointDnsNames": [
                "vpce-svc-03d5ebb7d9579a2b3.us-east-1.vpce.amazonaws.com"
            ]
        }
    }

Adding and Removing Permissions for Your Endpoint Service

After you've created your endpoint service configuration, you can control which service consumers can discover your service (for example, through the Amazon VPC console or when describing VPC endpoint services). Service consumers are IAM principals—IAM users, IAM roles, and AWS accounts.

To add or remove permissions using the console

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services and select your endpoint service.

  3. Choose Actions, Add principals to whitelist.

  4. Specify the ARN for the principal for which to add permissions. To add more principals, choose Add principal. To remove a principal, choose the cross icon next to the entry.

    Note

    Specify * to add permission for all principals.

  5. Choose Add to Whitelisted principals.

  6. To remove a principal, select it in the list and choose Delete.

To add and remove permissions using the AWS CLI

  1. To add permissions for your endpoint service, use the modify-vpc-endpoint-service-permissions command and use the --add-allowed-principals parameter to add one or more ARNs for the principals.

    Copy
    aws ec2 modify-vpc-endpoint-service-permissions --service-id vpce-svc-03d5ebb7d9579a2b3 --add-allowed-principals '["arn:aws:iam::123456789012:root"]'
  2. To view the permissions you've added for your endpoint service, use the describe-vpc-endpoint-service-permissions command.

    Copy
    aws ec2 describe-vpc-endpoint-service-permissions --service-id vpce-svc-03d5ebb7d9579a2b3
    {
        "AllowedPrincipals": [
            {
                "PrincipalType": "Account", 
                "Principal": "arn:aws:iam::123456789012:root"
            }
        ]
    }
  3. To remove permissions for your endpoint service, use the modify-vpc-endpoint-service-permissions command and use the --remove-allowed-principals parameter to remove one or more ARNs for the principals.

    Copy
    aws ec2 modify-vpc-endpoint-service-permissions --service-id vpce-svc-03d5ebb7d9579a2b3 --remove-allowed-principals '["arn:aws:iam::123456789012:root"]'

Changing the Network Load Balancers and Acceptance Settings

You can modify your endpoint service configuration by changing the Network Load Balancers that are associated with the endpoint service, and by changing whether acceptance is required for requests to connect to your endpoint service.

You cannot disassociate a load balancer if there are interface endpoints attached to your endpoint service.

To change the network load balancers for your endpoint service using the console

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services and select your endpoint service.

  3. Choose Actions, Associate/Disassociate Network Load Balancers.

  4. Select or deselect the load balancers as required, and choose Save.

To modify the acceptance setting using the console

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services and select your endpoint service.

  3. Choose Actions, Modify endpoint acceptance setting.

  4. Select or deselect Require acceptance for endpoint, and choose Modify.

To modify the load balancers and acceptance settings using the AWS CLI

  1. To change the load balancers for your endpoint service, use the modify-vpc-endpoint-service-configuration command and use the --add-network-load-balancer-arn or --remove-network-load-balancer-arn parameter; for example:

    Copy
    aws ec2 modify-vpc-endpoint-service-configuration --service-id vpce-svc-09222513e6e77dc86 --remove-network-load-balancer-arn arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/nlb-vpce/e94221227f1ba532
  2. To change whether acceptance is required, use the modify-vpc-endpoint-service-configuration command and specify --acceptance-required or --no-acceptance-required; for example:

    Copy
    aws ec2 modify-vpc-endpoint-service-configuration --service-id vpce-svc-09222513e6e77dc86 --no-acceptance-required

Accepting and Rejecting Interface Endpoint Connection Requests

After you've created an endpoint service, service consumers can create an interface endpoint to connect to your service. For more information about creating an interface endpoint, see Interface VPC Endpoints (AWS PrivateLink).

If you specified that acceptance is required for connection requests, you must manually accept or reject interface endpoint connection requests to your endpoint service. After an interface endpoint is accepted, it becomes available.

You can reject an interface endpoint connection after it's in the available state.

To accept or reject a connection request using the console

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services and select your endpoint service.

  3. The Endpoint Connections tab lists endpoint connections that are currently pending your approval. Select the endpoint, choose Actions, and choose Accept endpoint connection request to accept the connection or Reject endpoint connection request to reject it.

To accept or reject a connection request using the AWS CLI

  1. The view the endpoint connections that are pending acceptance, use the describe-vpc-endpoint-connections command and filter by the pendingAcceptance state.

    Copy
    aws ec2 describe-vpc-endpoint-connections --filters Name=vpc-endpoint-state,Values=pendingAcceptance
    {
        "VpcEndpointConnections": [
            {
                "VpcEndpointId": "vpce-0c1308d7312217abc", 
                "ServiceId": "vpce-svc-03d5ebb7d9579a2b3", 
                "CreationTimestamp": "2017-11-30T10:00:24.350Z", 
                "VpcEndpointState": "pendingAcceptance", 
                "VpcEndpointOwner": "123456789012"
            }
        ]
    }
  2. To accept an endpoint connection request, use the accept-vpc-endpoint-connections command and specify the endpoint ID and endpoint service ID.

    Copy
    aws ec2 accept-vpc-endpoint-connections --service-id vpce-svc-03d5ebb7d9579a2b3 --vpc-endpoint-ids vpce-0c1308d7312217abc
  3. To reject an endpoint connection request, use the reject-vpc-endpoint-connections command.

    Copy
    aws ec2 reject-vpc-endpoint-connections --service-id vpce-svc-03d5ebb7d9579a2b3 --vpc-endpoint-ids vpce-0c1308d7312217abc

Creating and Managing a Notification for an Endpoint Service

You can create a notification to receive alerts for specific events that occur on the endpoints that are attached to your endpoint service. For example, you can receive an email when an endpoint request is accepted or rejected for your endpoint service. To create a notification, you must associate an Amazon SNS topic with the notification. You can subscribe to the SNS topic to receive an email notification when an endpoint event occurs. For more information, see the Amazon Simple Notification Service Developer Guide.

The Amazon SNS topic that you use for notifications must have a topic policy that allows the Amazon VPC endpoint service to publish notifications on your behalf. Ensure that you include the following statement in your topic policy. For more information, see Managing Access to Your Amazon SNS Topics in the Amazon Simple Notification Service Developer Guide.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "vpce.amazonaws.com" }, "Action": "SNS:Publish", "Resource": "arn:aws:sns:region:account:topic-name" } ] }

To create a notification for an endpoint service

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services and select your endpoint service.

  3. Choose Notifications, Create Notification.

  4. Choose the ARN for the SNS topic to associate with the notification.

  5. For Events, select the endpoint events for which to receive notifications.

  6. Choose Create Notification.

After you create a notification, you can change the SNS topic that's associated with the notification, or you can specify different endpoint events for the notification.

To modify a notification for an endpoint service

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services and select your endpoint service.

  3. Choose Notifications, Actions, Modify Notification.

  4. Specify the ARN for the SNS topic and select or deselect the endpoint events as required.

  5. Choose Modify Notification.

If you no longer need a notification, you can delete it.

To delete a notification

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services and select your endpoint service.

  3. Choose Notifications, Actions, Delete Notification.

  4. Choose Yes, Delete.

To create and manage a notification using the AWS CLI

  1. To create a notification for an endpoint service, use the create-vpc-endpoint-connection-notification command and specify the ARN of the SNS topic, the events for which to be notified, and the ID of the endpoint service; for example:

    Copy
    aws ec2 create-vpc-endpoint-connection-notification --connection-notification-arn arn:aws:sns:us-east-2:123456789012:VpceNotification --connection-events Connect Accept Delete Reject --service-id vpce-svc-1237881c0d25a3abc
    {
        "ConnectionNotification": {
            "ConnectionNotificationState": "Enabled", 
            "ConnectionNotificationType": "Topic", 
            "ServiceId": "vpce-svc-1237881c0d25a3abc", 
            "ConnectionEvents": [
                "Reject",
                "Accept",
                "Delete",
                "Connect"
            ], 
            "ConnectionNotificationId": "vpce-nfn-008776de7e03f5abc", 
            "ConnectionNotificationArn": "arn:aws:sns:us-east-2:123456789012:VpceNotification"
        }
    }
  2. To view your notifications, use the describe-vpc-endpoint-connection-notifications command:

    Copy
    aws ec2 describe-vpc-endpoint-connection-notifications
  3. To change the SNS topic or endpoint events for the notification, use the modify-vpc-endpoint-connection-notification command; for example:

    Copy
    aws ec2 modify-vpc-endpoint-connection-notification --connection-notification-id vpce-nfn-008776de7e03f5abc --connection-events Accept Reject --connection-notification-arn arn:aws:sns:us-east-2:123456789012:mytopic
  4. To delete a notification, use the delete-vpc-endpoint-connection-notifications command:

    Copy
    aws ec2 delete-vpc-endpoint-connection-notifications --connection-notification-ids vpce-nfn-008776de7e03f5abc

Using Proxy Protocol for Connection Information

A Network Load Balancer provides source IP addresses to your application (your service). When service consumers send traffic to your service through an interface endpoint, the source IP addresses provided to your application are the private IP addresses of the Network Load Balancer nodes, and not the IP addresses of the service consumers.

If you need the IP addresses of the service consumers and their corresponding interface endpoint IDs, enable Proxy Protocol on your load balancer and get the client IP addresses from the Proxy Protocol header. For more information, see Proxy Protocol in the User Guide for Network Load Balancers.

Deleting an Endpoint Service Configuration

You can delete an endpoint service configuration. Deleting the configuration does not delete the application hosted in your VPC or the associated load balancers.

Before you delete the endpoint service configuration, you must reject any available or pending-acceptance VPC endpoints that are attached to the service. For more information, see Accepting and Rejecting Interface Endpoint Connection Requests.

To delete an endpoint service configuration using the console

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoint Services and select the service.

  3. Choose Actions, Delete.

  4. Choose Yes, Delete.

To delete an endpoint service configuration using the AWS CLI