Skip to content

Update Domain Name (DNS) of Platform

This guide covers the procedure for changing the domain name (DNS) of your Traceable Platform.

Overview

You may need to update the platform DNS when:

  • Migrating to a new domain
  • Changing from temporary to production domain
  • Organizational domain changes

Important: This is a multi-step process that affects multiple components. Follow all steps carefully.

Prerequisites

  • Access to the Traceable Operator (TI) UI
  • Access to Keycloak admin console
  • New TLS certificates for the new domain (or ability to generate self-signed)
  • DNS records configured for the new domain

Step 1: Update DNS in TI

  1. Login to the Traceable Operator
  2. Navigate to Global Variables
  3. Update the DNS field with the new domain name
  4. Save the changes

Step 2: Update Certificate

Choose one of the following options:

Option 1: Generate Self-Signed Certificate

  1. Navigate to Tasks → GenerateTlsCerts → generate_self_signed_certs
  2. Run the task to generate new self-signed certificates for the new DNS

Option 2: Upload CA-Signed Certificate

  1. Navigate to Tasks → GenerateTlsCerts → upload_install_tls_certs
  2. Upload your CA-signed certificate files:
    • Private key
    • Server certificate (with intermediate and root certs)
    • Root CA certificate

Reference: See Update Certificates for detailed certificate requirements.

Step 3: Update Keycloak

Update Frontend URL

  1. Login to Keycloak: https://<new-dns>/auth
    • Username: keycloak
    • Password: (from TI Global Variables)
  2. Select Traceable realm
  3. Go to Realm Settings
  4. Update the Frontend URL to the new DNS
  5. Click Save

Update Client Redirect URIs

  1. In Keycloak, go to Clients
  2. Select iam-client
  3. Update the DNS in Valid Redirect URIs
  4. Click Save

Step 4: Update TI (Upgrade Operator)

  1. Navigate to Installer → Upgrade → Upgrade Operator
  2. Set the version to your current installer version (e.g., 0.1.164)
  3. Add Additional Args:
--set cluster.tfi.dns=<new-dns> --set ingress.altDns[0]=<old-dns>

Note: --set ingress.altDns[0]=<old-dns> is optional but recommended for transition period.

  1. Execute the upgrade

Handling 405 Error

If you see the following error after the upgrade:

<html> <head><title>405 Not Allowed</title></head> <body> 
<center><h1>405 Not Allowed</h1></center> 
<hr><center>nginx/1.26.0</center> </body> </html>

Solution: Open a new browser tab and login to the TI using the new DNS.

Step 5: Trigger Reinstall Workflow

  1. Navigate to Installer → Install Workflow
  2. Review the Install/Skip status of items
  3. Click Next → Next → Start Installer
  4. Wait for the workflow to complete

Post-Installation Tasks

Clean Old Secrets

  1. Navigate to Installer → Namespaces → Traceable → Browser → All Namespaces → Secrets
  2. Delete secrets that contain the old DNS name

Validate Ingress Configuration

  1. Navigate to Installer → Namespaces → Traceable → Browser → All Namespaces → Ingress
  2. Verify all ingresses are updated with the correct DNS

If you added altDns: Remove the additional ingress entry for traceable-installer ingress.

Regenerate Agent Token

  1. Login to the Platform UI using the new DNS
  2. Navigate to Settings → Access Tokens
  3. Generate a new Agent Token
  4. Update TPA configuration with:
    • New Agent Token
    • New DNS endpoint

Update Platform Agent Certificate

If using self-signed or private CA certificates, update the TPA to trust the new certificate chain.

Update SSO Integration

If using SAML or other SSO:

  1. Update the redirect URIs in your Identity Provider
  2. Update any SAML metadata with the new DNS

Update External Integrations

Update the DNS and tokens in any external integrations:

  • Webhooks
  • API integrations
  • Monitoring systems
  • CI/CD pipelines

Verification

After completing all steps:

  1. Access Platform:
https://<new-dns>
  1. Verify TI Access:
https://<new-dns>/ti

  1. Test Login: Verify authentication works correctly

  2. Check TPA Connection: Verify agents can connect with new DNS

  3. Test API Calls: Verify API tokens work with new endpoint

Troubleshooting

Cannot Access Platform After DNS Change

Symptoms: Connection refused or timeout on new DNS.

Solutions:

  1. Verify DNS records are properly configured
  2. Check ingress status:
kubectl get ingress -n traceable
  1. Verify TLS certificates are valid for new DNS
  2. Check firewall rules allow traffic to new DNS

Keycloak Redirect Issues

Symptoms: Login redirects to old DNS or fails.

Solutions:

  1. Verify Frontend URL is updated in Keycloak
  2. Verify Valid Redirect URIs include new DNS
  3. Clear browser cache and cookies
  4. Check Keycloak logs for errors

TPA Cannot Connect

Symptoms: Agents show disconnected after DNS change.

Solutions:

  1. Regenerate Agent Token from new DNS
  2. Update TPA configuration with new DNS and token
  3. If using self-signed certs, update TRACEABLE_ROOT_CA_FILE
  4. Restart TPA service

SSO Login Fails

Symptoms: SAML authentication fails after DNS change.

Solutions:

  1. Update redirect URIs in Identity Provider
  2. Update SAML metadata if required
  3. Verify Keycloak SAML configuration
  4. Check IAM logs for errors

Rollback Procedure

If you need to rollback to the old DNS:

  1. Revert DNS in TI Global Variables
  2. Restore old certificates (if changed)
  3. Revert Keycloak Frontend URL and Redirect URIs
  4. Run Upgrade Operator with old DNS:
--set cluster.tfi.dns=<old-dns>
  1. Trigger reinstall workflow
  2. Regenerate tokens and update agents

Support

For DNS update assistance, contact: support@harness.io

Provide the following information:

  • Old and new DNS names
  • Error messages encountered
  • Ingress configuration
  • Keycloak configuration screenshots