VPC Connectivity

VPC connectivity issues are among the most common problems when setting up OpenSearch UI with VPC-based domains. This guide walks through diagnosing and resolving each type of connectivity failure.

Start here to identify your issue:

The most common VPC issue is forgetting to authorize the OpenSearch UI service to access the VPC endpoint.

Check if the authorization exists:

If the response doesn't include application.opensearchservice.amazonaws.com, the endpoint is not authorized.

Authorize the endpoint:

Wait 5-10 minutes for the authorization to propagate, then check the data source health in your application.

Serverless collections use network policies instead. Verify the policy:

Check that the policy includes:

If missing, create or update the network policy:

Even with endpoint authorization, the domain's security group must allow inbound traffic on port 443.

1. Find the security group attached to your domain:

   Copy

   aws opensearch describe-domain \
       --domain-name my-vpc-domain \
       --region us-east-1 \
       --query 'DomainStatus.VPCOptions.SecurityGroupIds'

2. Check the inbound rules:

   Copy

   aws ec2 describe-security-groups \
       --group-ids sg-abc123 \
       --region us-east-1 \
       --query 'SecurityGroups[0].IpPermissions'

3. Look for a rule allowing TCP 443 inbound.

Add an inbound rule for TCP 443:

Replace 10.0.0.0/16 with your VPC CIDR block. For tighter security, use the security group of the VPC endpoint as the source:

VPC endpoints rely on DNS to route traffic. If DNS resolution is misconfigured, the application can't find the domain.

Check if the VPC has DNS resolution enabled:

Both should return true.

Enable DNS support and hostnames:

If you're using Route 53 private hosted zones, ensure they don't override the VPC endpoint DNS entries. Custom DNS configurations can interfere with the automatic DNS resolution that VPC endpoints rely on.

If your OpenSearch domain is in a private subnet and needs to communicate with AWS services (like the OpenSearch UI service), a NAT gateway may be required.

• The domain is in a private subnet (no internet gateway route)
• The VPC endpoint for OpenSearch is not configured
• The domain needs to reach AWS APIs for management operations

Check the route table for the domain's subnet:

Look for a route to 0.0.0.0/0 pointing to a NAT gateway (nat-xxx).

If no NAT gateway exists and one is needed:

1. Create a NAT gateway in a public subnet:

   Copy

   aws ec2 create-nat-gateway \
       --subnet-id subnet-public-123 \
       --allocation-id eipalloc-abc123 \
       --region us-east-1

2. Add a route in the private subnet's route table:

   Copy

   aws ec2 create-route \
       --route-table-id rtb-private-456 \
       --destination-cidr-block 0.0.0.0/0 \
       --nat-gateway-id nat-xyz789 \
       --region us-east-1

If you have Lambda functions in a VPC that need to interact with the OpenSearch UI API or the underlying domains, they need proper network configuration.

A Lambda function in a VPC tries to call the OpenSearch UI application URL or the domain endpoint and gets a timeout.

1. Check if the Lambda function is in a VPC:

   Copy

   aws lambda get-function-configuration \
       --function-name my-function \
       --query 'VpcConfig'

2. Verify the Lambda's subnet has a route to the internet (via NAT) or to the VPC endpoint.

3. Check the Lambda's security group allows outbound traffic on port 443.

Create a VPC endpoint for the OpenSearch service:

If the Lambda needs to reach the public OpenSearch UI URL:

1. Place the Lambda in a private subnet
2. Ensure the private subnet routes to a NAT gateway in a public subnet
3. The Lambda's security group must allow outbound TCP 443

If the connection works sometimes but not always, the issue is usually related to transient network conditions.

1. Domain is processing a configuration change — During blue/green deployments, connectivity may be briefly interrupted
2. Security group was modified — Someone may have temporarily changed the rules
3. VPC endpoint is being recreated — After certain domain changes, the endpoint may be reprovisioned
4. Resource constraints on the domain — High CPU or memory pressure can cause timeouts

Check domain events:

If Processing is true, the domain is undergoing a change. Wait for it to complete.

Check CloudWatch metrics:

Run through each item when debugging VPC connectivity:

• VPC endpoint authorization is in place (list-vpc-endpoint-access)
• Security group allows inbound TCP 443
• Security group allows outbound traffic
• VPC has DNS support enabled
• VPC has DNS hostnames enabled
• Domain is in Active state (not Processing)
• Domain access policy allows the OpenSearch UI service
• (Serverless) Network policy includes SourceServices
• (Serverless) Data access policy grants read permissions
• (Lambda) Lambda subnet has route to NAT or VPC endpoint
• (Lambda) Lambda security group allows outbound 443
• No conflicting Route 53 private hosted zones

If you've exhausted this checklist and still have connectivity issues:

1. Collect the domain name, VPC ID, subnet IDs, and security group IDs
2. Run describe-domain and save the full output
3. Check CloudTrail for any recent AuthorizeVpcEndpointAccess or UpdateDomainConfig events
4. Open a support case with AWS Support including all collected information