Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

How-To: Migrate Your Quilt Stack to a New DNS Name

This guide outlines the recommended steps for migrating the Quilt application to a different DNS zone in AWS Route 53—for example, from example.company.com to internal.example.company.com. The migration involves DNS, certificate, and SSO changes, and should be executed in a phased, testable manner to avoid downtime.

Prerequisites

  • Access to modify Route 53 DNS hosted zones

  • IAM permissions to deploy and modify Quilt CloudFormation stacks

  • Knowledge of current DNS and SSO configuration

  • TLS certificate management capabilities (via ACM)

Step-by-Step Instructions

1. Obtain an update CloudFormation template from Quilt

  • Verify whether your new domain has the same depth (number of "." segments) as your current deployment.

  • Request a new template via the Install form, with the new DNS name  depth.

2. Prepare the Private Hosted Zone

  • Create a private hosted zone in Route 53 (e.g., internal.example.company.com).

  • Ensure your VPCs are associated with the private zone.

3. Handle SSO Configuration

  • If your SSO provider supports multiple domains:

    • Add the new domain to the existing SSO application.

  • If not:

    • Create a new SSO app mapped to the new domain.

4. Update DNS Records

  • Create CNAME records in the new zone pointing service hosts to your ELB.

  • Do not remove old zone records until migration is complete.

5. TLS Certificate Updates

If the current CertificateArnELB does not match the new domain:

  • Issue a new certificate for the private domain.
  • Use that certificate's ARN for the CertificateArnELB

6. Modify and Redeploy Quilt Stack

Redeploy the template by updating the following CloudFormation Parameters:

  • QuiltWebHost set to the new private domain.

  • Updated CertificateArnELB if applicable.

  • Modified SSO parameters (depending on step 3).

7. Smoke Test the Migration

  • Deploy a test stack using the new private domain.

  • Run end-to-end smoke tests on:

    • Authentication

    • Data catalog access

    • Any other user-facing workflows

Notes & Caveats

  • Failure to update the TLS cert will result in a browser warning.

  • Incorrect SSO configuration can result in broken auth flows.

  • Contact support@quilt.bio if email notifications do not include the new hostname.