How do I troubleshoot VPC connections in Quick Sight to connect to my data sources?

Short description

When you use a VPC to connect to a data source in Quick Sight, you might experience issues for the following reasons:

• You didn't create the VPC connection for the private data source.
• You didn't configure the required subnets for your VPC connection.
• The security groups for your VPC connection or your data source don't allow the required traffic.
• The AWS Identity and Access Management (IAM) role for your VPC connection is missing or doesn't have the required permissions.
• Your data source isn't reachable because of routing issues, a missing internet gateway, or missing connectivity across AWS accounts or from on premises.
• Your VPC connection status is "UNAVAILABLE", or you receive a "CONNECTION_TIMEOUT" or "SSL_CERT_VALIDATION_FAILURE" error.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

You didn't create a VPC connection for your private data source

To use a data source that's in a private subnet, you must create a VPC connection in Quick Sight. Quick Sight uses the VPC connection to launch an elastic network interface to your VPC and reach the private data source.

Note: When you create the data source, the Connection type list shows Quick Sight VPC connections. The list doesn't contain Amazon Virtual Private Cloud (Amazon VPC) names.

You didn't configure the required subnets for your VPC connection

Quick Sight connections require you to configure at least two subnets in different Availability Zones. If you select only one subnet or all subnets are in the same Availability Zone, then the VPC connection fails.

To resolve this issue, use either the Quick Sight console or the AWS CLI to select subnets in different Availability zones.

Quick Sight console

Complete the following steps:

1. Open the Quick Sight console.
2. Choose your profile icon, and then choose Manage Amazon Quick.
3. In the navigation pane, choose Manage VPC connections.
4. For Subnets, select two or more subnets in different Availability Zones with a route to your data source.

AWS CLI

Run the following update-vpc-connection command:

aws quicksight update-vpc-connection \
     --aws-account-id account-id \
     --vpc-connection-id vpc-connection-id \
     --name "vpc-name" \
     --subnet-ids '["subnet-12345678", "subnet-12345678"]' \
     --security-group-ids sg-id \
     --role-arn "role-arn" \
     --region region-id

Note: Replace account-id with your account ID, vpc-connection-id with your VPC connection ID, vpc-name with the VPC connection's display name, and subnet-id-12345678 with your subnet IDs. Also, replace sg-id with your security group ID, role-arn with the Amazon Resource Name (ARN) of your IAM role, and region-id with your AWS Region. Enclose all parameter values, such as the subnet IDs, in double quotation marks.

To find your VPC connection ID and IAM role ARN, run the following list-vpc-connections command:

aws quicksight list-vpc-connections \
     --aws-account-id account-id  \
     --region region-id

Note: Replace account-id with your account ID and region-id with your Region.

Also, make sure that the subnets have a route to your data source so that you don't experience intermittent timeouts.

The security groups for your VPC connection or your data source don't allow the required traffic

Quick Sight uses the security group in the VPC connection in Quick Sight and the security group on your data source for VPC connectivity. To allow the required access, update the VPC connection's security group to explicitly allow all inbound traffic on TCP ports 0-65535 from the data source. Also, add an outbound rule that allows traffic on the data source's port to the data source's security group. Then, update the data source's security group to allow inbound traffic on the data source's port from the VPC connection's security group.

Note: For an Amazon Redshift cluster that uses public connectivity instead of a VPC connection, allow inbound access from the IP address range for your Region.

Also, confirm that the network access control lists (network ACLs) for the data source and VPC connection subnets allow the required traffic in both directions.

The IAM role for your VPC connection is missing or doesn't have the required permissions

When you create a VPC connection in Quick Sight, you specify an IAM role that Quick Sight uses to create and manage network interfaces. If the role doesn't exist or doesn't have the required permissions, then the VPC connection fails.

If the role doesn't exist, then create a new IAM role with the following trust relationship and IAM policy.

Trust relationship:

{
     "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Allow",
             "Principal": {
                 "Service": "quicksight.amazonaws.com"
             },
             "Action": "sts:AssumeRole"
         }
     ]
 }

IAM role policy:

{
     "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Allow",
             "Action": [
                 "ec2:CreateNetworkInterface",
                 "ec2:ModifyNetworkInterfaceAttribute",
                 "ec2:DeleteNetworkInterface",
                 "ec2:DescribeSubnets",
                 "ec2:DescribeSecurityGroups"
             ],
             "Resource": "*"
         }
     ]
 }

After you update the role, check your VPC connection. If the status is UNAVAILABLE, then run the create-vpc-connection command so that Quick Sight creates the network interfaces with the required role.

If the role exists, then make sure that it has the required permissions to allow Quick Sight to assume the role.

Important: If the VPC connection is active, then don't delete the IAM role. Quick Sight also uses the IAM role to delete network interfaces when you delete the VPC connection. If you delete the role, then you can't delete the VPC connection.

Your data source isn't reachable from the VPC connection's subnets

If the security groups and IAM role are correct but the data source is still unreachable, then the issue is typically network routing. The subnets for your VPC connection must have a network path to your data source.

For data sources in the same VPC, update the subnet route table to include a local route to the CIDR block for the VPC. To confirm that the data source is reachable, use an Amazon Elastic Compute Cloud (Amazon EC2) instance in the same subnet to access the source's private IP address.

If the data source is in a different VPC, then configure VPC peering between the Quick Sight and the data source. Or, create a Connect attachment in AWS Transit Gateway. In the subnet route tables, add a route to the destination CIDR block for the VPC that points to the peering connection or transit gateway. Also, make sure that the security groups for Quick Sight and the data source allow the required traffic. For more information, see How do I connect Quick Suite to a private Amazon Relational Database Service (Amazon RDS) data source in a different AWS Region or AWS account?

If the data source is on premises, then make sure that the VPC has a working connection through AWS Direct Connect or AWS Site-to-Site VPN. In the subnet route tables, add a route to the Direct Connect gateway or virtual private gateway.

If the data source is public, then don't use a VPC connection to access the data source. Instead, set the data source as publicly accessible.

For example, for a public Amazon Redshift cluster, complete the following steps:

1. Open the Amazon Redshift console.
2. In the navigation pane, choose Cluster, and then select your cluster.
3. Choose Actions, and then choose Modify publicly accessible setting.
4. For Connection type, select a public connection in Quick Sight for the data source.
5. In the data source's security group, allow inbound access from the Quick Sight IP address ranges for your Region.

Your VPC connection status is "UNAVAILABLE", or you receive a connection timeout error

You might receive the following errors when you try to use the VPC connection:

"sourceErrorCode: CONNECTION_TIMEOUT
sourceErrorMessage: Connection attempt timed out."

"sourceErrorCode: SSL_CERT_VALIDATION_FAILURE
sourceErrorMessage: PKIX path building failed: unable to find valid certification path to requested target."

To troubleshoot this issue, check the VPC connection status. If the status is UNAVAILABLE, then network interface creation failed. To resolve this issue, see The IAM role for your VPC connection is missing or doesn't have the required permissions.

To get information about the issue, such as error messages on a specific network interface, run the following describe-vpc-connection command:

aws quicksight describe-vpc-connection \
     --aws-account-id account-ID-example \
     --vpc-connection-id vpc-ID-example

Note: Replace account-ID-example with your account ID and vpc-ID-example with your VPC connection ID. To identify the VPC connection ID, run the following list-vpc-connections command:

aws quicksight list-vpc-connections \
     --aws-account-id account-id \
     --region region-id

Note: Replace account-id with your account ID and region-id with your Region.

To troubleshoot "CONNECTION_TIMEOUT" errors, make sure that you correctly configured your security groups, subnets, and subnet routing. Also, confirm that the data source listens on the port that you configured. To check the port, use an Amazon EC2 instance in the same VPC to run a TCP test.

To troubleshoot "SSL_CERT_VALIDATION_FAILURE" errors, confirm that your data source uses a server certificate that's signed by a public certificate authority (CA). Quick Sight doesn't accept self-signed certificates or certificates that are issued from a non-public CA.

To provide a trusted certificate, it's a best practice to use a certificate from AWS Certificate Manager (ACM). You can also use a certificate from a CA on the Mozilla included CA certificate list on the Mozilla website.

For Amazon RDS, use the AWS managed Amazon RDS CA bundle.

For the full list of network and database configuration requirements, see Network configuration requirements.

Related information

Configuring Amazon Quick Sight access to AWS data sources

AWS::QuickSight::VPCConnection