Migrating and onboarding to STACKIT CDN

This guide explains how to route your traffic to STACKIT CDN. Whether you are onboarding a new application, migrating from a different CDN, or moving active production workloads, follow these phases to ensure a smooth transition.

Phase 1: Preparation

Before changing any DNS records, prepare your origin server and STACKIT environment.

• Create a distribution: Create a STACKIT CDN distribution. Set the origin to the DNS record or IP address pointing to your origin server.
• Update your allowlist: If your origin is protected by a firewall or IP allowlist, add the STACKIT CDN PoP endpoint CIDRs to your allowlist. This ensures the CDN edge nodes can fetch content from your origin successfully.

The STACKIT CDN PoP network is dynamic, and the IP ranges will change as the network expands. We strongly recommend setting up an automated process (such as a daily cronjob) to fetch the latest IP ranges and synchronize them with your firewall rules.

Phase 2: Configuration and testing

Configure your CDN and Web Application Firewall (WAF) settings according to your requirements. Before routing live traffic, test the STACKIT-managed domain to verify the behavior.

Use the STACKIT CDN Logs, your origin logs and your browser developer tools to verify the following:

• Access: Ensure users can access the origin through the CDN-managed domain.
• Cache behavior: Check for expected cache hits and misses.
• Redirects: Verify that all HTTP/HTTPS redirects function correctly.
• Headers: Verify that required HTTP headers are passed to the origin and that sensitive or restricted headers are stripped or modified as expected.
• Cookies: Ensure that necessary cookies are forwarded correctly and do not unintentionally bypass the cache.
• TLS versions: Confirm that the accepted TLS versions and cipher suites align with your security requirements.
• WAF rules: Monitor blocked, logged, and allowed requests to ensure the WAF paranoia level is appropriate and not blocking legitimate traffic.

Phase 3: DNS preparation

Verify that your frontend domain’s DNS entry correctly resolves to an IP address. You can check the current routing using command-line tools.

Linux/macOS

Use the dig command to check the A record:

dig @9.9.9.9 <your-managed-domain-id>.aa.cdn.onstackit.cloud. A

Windows

Use PowerShell to resolve the name:

Resolve-DnsName -Name <your-managed-domain-id>.aa.cdn.onstackit.cloud. -Type A -Server 9.9.9.9

Understanding the DNS output

When querying the domain, the output reveals the DNS resolution path:

• @9.9.9.9: The DNS resolver you are using (in this case, Quad9).
• <your-managed-domain-id>.aa.cdn.onstackit.cloud.: The domain you are querying.
• A: The record type requested.

Example resolution path:

example.com. 30 IN CNAME <your-managed-domain-id>.aa.cdn.onstackit.cloud.
<your-managed-domain-id>.aa.cdn.onstackit.cloud. 3570 IN CNAME sit-cdn-<uuid>.b-cdn.net.
sit-cdn-<uuid>.b-cdn.net. 5 IN A 123.145.167.189

Depending on your setup, you will see one or two CNAME hops that eventually resolve to a b-cdn.net domain pointing to an IP address. The returned A record IP belongs to the nearest Point of Presence (PoP) based on your geographic location and activated CDN regions.

Before executing the final migration, lower the time to live (TTL) on your existing DNS records and wait for the old TTL to expire. For example, if your current TTL is 86400 (24 hours), wait at least 24 hours before proceeding to phase 4. A TTL of 5 minutes or lower is highly recommended, as it provides greater flexibility during the transition and allows you to revert changes quickly if needed.

Phase 4: Execute the cutover

Choose the migration scenario that matches your current environment and uptime requirements.

Migrate productive workloads (zero downtime)

Use this approach when migrating from another CDN or moving highly critical production loads where downtime is unacceptable. This requires you to provide a custom certificate.

1. Obtain a custom SSL/TLS certificate (for example, via Let’s Encrypt) for your frontend domain.

2. Create a payload.json file containing your base64-encoded certificate and key. Set the skipDnsCheck flag to bypass DNS validation:

   {
     "certificate": {
       "type": "custom",
       "certificate": "<base64-encoded-PEM-certificate>",
       "key": "<base64-encoded-PEM-key>",
       "skipDnsCheck": true
     },
     "intentId": "<your-generated-uuid>"
   }

3. Use the STACKIT CLI to add your targeted frontend domain as a custom domain by posting the payload to the API:

   stackit curl https://cdn.api.stackit.cloud/v1/projects/{projectId}/distributions/{distributionId}/customDomains/{domain} -X POST --data @./payload.json

4. Once the domain and custom certificate are active in STACKIT, switch your DNS CNAME record to point to the STACKIT-managed domain.

Migrate from a different CDN (accepted downtime)

Use this approach if a brief interruption is acceptable and you want STACKIT to manage the SSL/TLS certificates automatically.

1. Switch your custom domain’s CNAME record to point to your STACKIT CDN-managed domain.

2. Wait for the CNAME propagation to reach the root DNS servers. This typically takes 10 to 15 minutes, but can take up to 48 hours depending on your previous TTL.

3. Use dig or Resolve-DnsName to verify the propagation is successful.

4. Once propagated, create your STACKIT custom domain in the portal. STACKIT will automatically provision the managed certificate.

Onboard a new application

Use this approach for new applications that are not yet receiving live user traffic.

1. Point your domain’s CNAME record to the STACKIT-managed domain.

2. Wait for DNS propagation.

3. Add the custom domain in the STACKIT portal to trigger the creation of the managed SSL/TLS certificate.

Phase 5: Post-migration and cleanup

Once your DNS changes have propagated and STACKIT CDN is serving your live traffic, complete the following final steps:

1. Monitor the cutover: Closely watch your STACKIT CDN Logs and your origin server metrics. Look for unexpected 5xx errors, unusual spikes in traffic hitting the origin (indicating low cache hit rates), or WAF false positives.

2. Verify certificates: If you used the accepted downtime or onboarding scenarios, verify that STACKIT has successfully issued and applied the managed Let’s Encrypt certificate.

3. Decommission old infrastructure: Once you are confident the migration is stable and your old DNS TTL has fully expired globally, you can safely scale down or delete your previous CDN distribution.

If you encounter critical issues during the cutover, you can instantly revert traffic by changing your DNS CNAME or A records back to your previous CDN provider. Because you lowered your TTL in phase 3, this rollback will propagate quickly.