Setting up a custom domain name - Amazon Redshift
Register a domain name and select a certificateCreate the custom domainConnect to your cluster or workgroup with a custom domain name, using a SQL client
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Setting up a custom domain name

Setting up the custom domain name consists of a several tasks: These include registering the domain name with your DNS provider and creating a certificate. After you perform these pieces of work, you configure the custom domain name in the Amazon Redshift console, or in the Amazon Redshift Serverless console, or configure it with Amazon CLI commands. The following sections detail the steps.

Register a domain name and select a certificate

You must have a registered internet domain name to configure a custom domain name in Amazon Redshift. You can register an internet domain using Route 53, or using a third-party domain registration provider. You complete these tasks outside of the Amazon Redshift console. A registered domain is a prerequisite for completing the remaining procedures to create a custom domain.

Note

If you're using a provisioned cluster, prior to performing the steps to configure the custom domain name, it must be relocation enabled. For more information, see Relocating your cluster. This step isn't required for Amazon Redshift Serverless.

The custom domain name typically includes the root domain and a subdomain, like mycluster.example.com. To configure it, perform the following steps:

Create a DNS CNAME entry for your custom domain name

  1. Register a root domain, for example example.com. Optionally, you can use an existing domain. Your custom name can be limited by restrictions on particular characters, or other naming validation. For more information about registering a domain with Route 53, see Registering a new domain.

  2. Add a DNS CNAME record that points your custom domain name to the Redshift endpoint for your cluster or workgroup. You can find the endpoint in the properties for the cluster or workgroup, in the Redshift console or in the Amazon Redshift Serverless console. Copy the JDBC URL that's available in the cluster or workgroup properties, under General information. The URLs appear like the following:

    • For an Amazon Redshift cluster: redshift-cluster-sample.abc123456.us-east-1.redshift.amazonaws.com

    • For an Amazon Redshift Serverless workgroup: endpoint-name.012345678901.us-east-1-dev.redshift-serverless-dev.amazonaws.com

    If the URL has a JDBC prefix, remove it.

    Note

    DNS records are subject to availability, because each name must be unique and available for use within your organization.

Limitations

There are a couple restraints regarding creating CNAME records for a custom domain:

  • Creating multiple custom domain names for the same provisioned cluster or Amazon Redshift Serverless workgroup isn't supported. You can associate only one CNAME record.

  • Associating a CNAME record with more than one cluster or workgroup isn't supported. The CNAME for each Redshift resource must be unique.

After you register your domain and create the CNAME record, you select a new or existing certificate. You perform this step using Amazon Certificate Manager:

Request a certificate from ACM for a domain name

  1. Sign in to the Amazon Web Services Management Console and open the ACM console at https://console.amazonaws.cn/acm/.

  2. Choose Request a certificate.

  3. Enter your custom domain name in the Domain name field.

    Note

    You can specify many prefixes, in addition to the certificate domain, in order to use a single certificate for multiple custom-domain records. To illustrate, you can use additional records like one.example.com, two.example.com, or a wildcard DNS record like *.example.com with the same certificate.

  4. Choose Review and request.

  5. Choose Confirm and request.

  6. For a valid request, a registered owner of the internet domain must consent to the request before ACM issues the certificate. Make sure the status appears as Issued in the ACM console, when you're finished with the steps.

We recommend that you create a DNS validated certificate that meets eligibility for managed renewal, which is available with Amazon Certificate Manager. Managed renewal means that ACM either renews your certificates automatically or it sends you email notices when expiration is approaching. For more information, see Managed renewal for ACM certificates.

Create the custom domain

You can use the Amazon Redshift or Amazon Redshift Serverless console to create your custom domain URL. If you haven't configured it, the Custom domain name property appears as a dash (–) under General information. After you create your CNAME record and the certificate, you associate the custom domain name for the cluster or workgroup.

In order to create a custom domain association, the following IAM permissions are required:

  • redshift:CreateCustomDomainAssociation – You can restrict permission to a specific cluster by adding its ARN.

  • redshiftServerless:CreateCustomDomainAssociation – You can restrict permission to a specific workgroup by adding its ARN.

  • acm:DescribeCertificate

As a best practice, we recommend attaching permissions policies to an IAM role and then assigning it to users and groups as needed. For more information, see Identity and access management in Amazon Redshift.

You assign the custom domain name by performing the following steps.

  1. Choose the cluster in the Redshift console, or the workgroup in the Amazon Redshift Serverless console, and choose Create custom domain name under the Action menu. A dialogue appears.

  2. Enter the custom domain name.

  3. Select the ARN from Amazon Certificate Manager for the ACM Certificate. Confirm your changes. Per the guidance in the steps you took to create the certificate, we recommend that you choose a DNS validated certificate that's eligible for managed renewal through Amazon Certificate Manager.

  4. Verify in the cluster properties that the Custom domain name and Custom domain certificate ARN are populated with your entries. The Custom domain certificate expiry date is also listed.

After the custom domain is configured, using sslmode=verify-full works only for the new, custom domain. It doesn't work for the default endpoint. But you can can still connect to the default endpoint by using other ssl modes, such as sslmode=verify-ca.

Renaming a cluster that has a custom domain assigned, using the console

Note

This series of steps doesn't apply to an Amazon Redshift Serverless workgroup. You can't change the workgroup name.

In order to rename a cluster that has a custom domain name, the acm:DescribeCertificate IAM permission is required.

  1. Go to the Amazon Redshift console and choose the cluster whose name you want to change. Choose Edit to edit the cluster properties.

  2. Edit the Cluster identifier. You can also change other properties for the cluster. Then choose Save changes.

  3. After the cluster is renamed, you have to update the DNS record to change the CNAME entry for the custom domain to point to the updated Amazon Redshift endpoint.

Updating the CNAME record in a disaster recovery use case

Using a CNAME record to create a custom domain can be useful in a disaster recovery case. If you're unable to access your data warehouse, the procedure that follows details actions you can take when you can't access your primary database cluster or workgroup.

We assume you follow high-availability practices and have secondary resources in place. In this case, for example, you could have a warm-standby cluster or workgroup available that regularly receives restored data from the primary cluster. This backup data warehouse could be in another Amazon availability zone or in a separate region. You can redirect clients to it by completing the following steps:

  1. This step assumes your cluster or workgroup is available in the console. If it isn't, you can skip it: Choose the primary cluster in the Amazon Redshift console or the primary workgroup in the Amazon Redshift Serverless console. The custom domain name appears in the properties. Choose Delete custom domain name from the Actions menu. In the window that appears, type delete to confirm and choose Delete.

  2. Choose the new cluster or workgroup. Follow the steps in this topic to create a custom domain name. Use the same domain name and select the same CNAME record you used for the primary cluster or workgroup. If your secondary resource is in a new region, you must create and use a new certificate.

  3. Go to your domain-registration provider. This can be Route 53 or a third-party provider. Select the CNAME record you created originally. When you created the record, you set it to route traffic to the endpoint URL of your primary cluster or workgroup. Change the value to the endpoint URL of your standby cluster or workgroup. After you save the change, it routes traffic to the new resource. Note that you might have to wait for DNS propagation.

  4. This is an optional step: Change inbound and outbound security group network-traffic rules to route traffic to your standby cluster or workgroup. Additionally, when you activate the standby resource, it's assumed you already ran or plan to run restore operations to bring the standby data in line with production data.

One advantage of changing the value of the endpoint URL to re-route traffic is that there aren't any configuration changes required for clients that use your custom domain name. Their connection properties don't have to change.

Note that any disaster-recovery steps you take should fit with your existing availability plan. Other resiliency strategies, such as deploying resources in multiple regions or sophisticated backup techniques are beyond the scope of this document.

Note

As a point of reminder, cluster relocation isn't a prerequisite for configuring additional Redshift networking features, like those used for disaster recovery or other purposes. You don't have to turn it on to enable the following:

  • Connecting from a cross-account or cross-region VPC to Redshift – You can connect from one Amazon virtual private cloud (VPC) to another that contains a Redshift database. This makes it easier to manage, for example, client access from disparate accounts or VPCs, without having to provide local VPC access to identities connecting to the database. For more information, see Connecting to Amazon Redshift Serverless from a Redshift VPC endpoint in another account or region.

  • Setting up a custom domain name – You can create a custom domain name, as described in this topic, to make the endpoint name more relevant and simple.

Describe custom domain associations, using CLI commands

Use the commands in this section to get a list of custom domain names associated with a specific provisioned cluster or with an Amazon Redshift Serverless workgroup.

You need the following permissions:

  • For a provisioned cluster: redshift:DescribeCustomDomainAssociations

  • For an Amazon Redshift Serverless workgroup: redshiftServerless:ListCnameAssociations

As a best practice, we recommend attaching permissions policies to an IAM role and then assigning it to users and groups as needed. For more information, see Identity and access management in Amazon Redshift.

The following shows a sample command to list the custom domain names for a given Amazon Redshift cluster:

aws redshift describe-custom-domain-associations ––custom-domain-name customdomainname

You can run this command when you have a custom domain name enabled to determine the custom domain names associated with the cluster. For more information about the CLI command for for describing custom domain associations, see describe-custom-domain-associations.

Similarly, the following shows a sample command to list the custom domain names for a given Amazon Redshift Serverless workgroup. There are a few different ways to to this. You can provide only the custom domain name:

aws redshift-serverless list-custom-domain-associations ––custom-domain-name customdomainname

You can also get the associations by providing only the certificate ARN:

aws redshift-serverless list-custom-domain-associations ––custom-domain-certificate-arn certificatearn

You can run these commands when you have a custom domain name enabled to determine the custom domain names associated with the workgroup. You can also run a command to get the properties of a custom domain association. To do this, you must provide the custom domain name and workgroup name as parameters. It returns the certificate ARN, the workgroup name, and the custom domain's certificate expiration time:

aws redshift-serverless get-custom-domain-association ––workgroup-name workgroupname ––custom-domain-name customdomainname

For more information about CLI reference commands available for Amazon Redshift Serverless, see redshift-serverless.

Associating the custom domain with a different certificate

In order to change the certificate association for a custom domain name, the following IAM permissions are required:

  • redshift:ModifyCustomDomainAssociation

  • acm:DescribeCertificate

As a best practice, we recommend attaching permissions policies to an IAM role and then assigning it to users and groups as needed. For more information, see Identity and access management in Amazon Redshift.

Use the following command to associate the custom domain with a different certificate. The ––custom-domain-name and custom-domain-certificate-arn arguments are mandatory. The ARN for the new certificate must be different than the existing ARN.

aws redshift modify-custom-domain-association ––cluster-id redshiftcluster ––custom-domain-name customdomainname ––custom-domain-certificate-arn certificatearn

The following sample shows how to associate the custom domain with a different certificate for an Amazon Redshift Serverless workgroup.

aws redshift-serverless modify-custom-domain-association ––workgroup-name redshiftworkgroup ––custom-domain-name customdomainname ––custom-domain-certificate-arn certificatearn

There is a maximum delay of 30 seconds before you can connect to the cluster. Part of the delay occurs as the Amazon Redshift cluster updates its properties, and there is some additional delay as DNS is updated. For more information about the API and each property setting, see ModifyCustomDomainAssociation.

Deleting the custom domain

To delete the custom domain name, the user must have permissions for the following actions:

  • For a provisioned cluster: redshift:DeleteCustomDomainAssociation

  • For an Amazon Redshift Serverless workgroup: redshiftServerless:DeleteCustomDomainAssociation

On the console

You can delete the custom domain name by selecting the Actions button and choosing Delete custom domain name. After you do this, you can still connect to the server by updating your tools to use the endpoints listed in the console.

Using a CLI command

The following sample shows how to delete the custom domain name. The delete operation requires that you provide the existing custom domain name for the cluster.

aws redshift delete-custom-domain-association ––cluster-id redshiftcluster ––custom-domain-name customdomainname

The following sample shows how to delete the custom domain name for an Amazon Redshift Serverless workgroup. The custom domain name is a required parameter.

aws redshift-serverless delete-custom-domain-association ––workgroup-name workgroupname ––custom-domain-name customdomainname

For more information, see DeleteCustomDomainAssociation.

Connect to your cluster or workgroup with a custom domain name, using a SQL client

In order to connect with a custom domain name, the following IAM permissions are required for a provisioned cluster: redshift:DescribeCustomDomainAssociations. For Amazon Redshift Serverless, you don't have to add permissions.

As a best practice, we recommend attaching permissions policies to an IAM role and then assigning it to users and groups as needed. For more information, see Identity and access management in Amazon Redshift.

After you complete the steps to create your CNAME and assign it to your cluster or workgroup in the console, you can provide the custom URL in the connection properties of your SQL client. Note that there can be a delay from DNS propagation immediately following the creation of a CNAME record.

  1. Open a SQL client. For example, you can use SQL/Workbench J. Open the properties for a connection, and add the custom domain name for the connection string. For example, jdbc:redshift://mycluster.example.com:5439/dev?sslmode=verify-full. In this example, dev specifies the default database.

  2. Add the Username and Password for your database user.

  3. Test the connection. Your ability to query database resources such as specific tables can vary, based on the permissions granted to the database user or granted to the Amazon Redshift database roles assigned.

    Note that you might have to set your cluster or workgroup to be publicly accessible to connect to it if it's in a VPC. You can change this setting in the network properties.

Note

Connections to a custom domain name are supported with JDBC and Python drivers. ODBC connections aren't supported.