Prerequisites

Things to do and things you need before you get started

Before you can delete an environment and all of its clusters and data, there are several things you’ll need to do and get. We’ll cover those here.

Custom Domain Configuration

CRITICAL PREREQUISITE: Before beginning the disconnection process, you MUST have a custom domain configured for your ClickHouse cluster.

  • Custom Domain Configured: Your cluster uses your own domain (e.g., clickhouse.yourdomain.com)
  • DNS Control: You control the hosted zone for this domain
  • ACME Secret Configured: You’ve gathered ACME credentials (for Let’s Encrypt certificate automation)
  • Current DNS Chain: Your domain currently points to Altinity DNS typically via CNAME (e.g., subdomain.yourdomain.com → env.altinity.cloud → Altinity load balancers)

Why this is required:

If you do not have a custom DNS setup, you will lose access to your cluster after disconnection because Altinity’s DNS records and edge-proxy components are removed. Your domain must already be in a zone you control so you can publish replacement records that point directly to your infrastructure.

Current DNS Flow:

subdomain.yourdomain.com (your hosted zone)
  → environment-name.env.altinity.cloud (Altinity DNS)
    → edge-proxy-xyz.elb.amazonaws.com (Altinity LB)

After Disconnection:

subdomain.yourdomain.com (your Route53)
  → contour-xyz.elb.amazonaws.com (YOUR Contour LB)

ACME/Certificate Management:

When you set up custom domain with Altinity, you provided ACME credentials (typically for Let’s Encrypt). These are stored as a Kubernetes Secret and used by crtd (Altinity’s proprietary certificate manager) to automatically request and renew TLS certificates.

IMPORTANT: crtd is Altinity-specific and will be replaced with open-source cert-manager during disconnection.

What happens during disconnection:

  1. **Install open-source components alongside altinity components
  2. **Migrate secrets to formats compatible with open-source components
  3. **Request new certificates using cert-manager for Contour
  4. **Run Altinity and open-source setup together during transition/testing phase
  5. **Remove Altinity components after the new setup is proven to work

After disconnection, your environment will:

  • ✅ Use your ACME credentials to request certificates from Let’s Encrypt
  • ✅ Automatically renew certificates ~30 days before expiration
  • ✅ Support the DNS-01 or HTTP-01 challenges
  • ✅ Work with ClusterIssuer configuration patterns

Do NOT delete before disconnection:

  • Existing TLS certificate secrets
  • Existing Altinity Components and their relevant configurations
  • ClusterIssuer/Issuer configurations (will be recreated for cert-manager)

How to verify you have a custom domain:

dig subdomain.yourdomain.com +short
# If you see *.altinity.cloud → you have custom domain configured ✓
# If you see *.elb.amazonaws.com only → contact Altinity Support first ✗

You may need to work with Altinity support to set up a custom domain

If you haven’t configured a custom domain yet:

  1. STOP - Do not proceed with disconnection
  2. Contact Altinity Support to set up custom domain with ACME
  3. Update your applications to use the custom domain
  4. Verify DNS chain includes .altinity.cloud
  5. Verify TLS certificates are working
  6. Then return to this guide

AWS Access

  • AWS Account Access: Administrative access to your AWS account (not Altinity’s)
  • AWS CLI Installed: Version 2.0+ or 1.16.156+
  • AWS Credentials Configured: Valid IAM user or role credentials
  • IAM Permissions: At minimum, you need:
    • eks:DescribeCluster
    • eks:ListClusters
    • eks:UpdateClusterConfig (if you need to enable public API access)
    • eks:CreateAccessEntry (for setting up access)
    • eks:AssociateAccessPolicy
    • ec2:* (for managing load balancers, security groups)
    • route53:* (for DNS management)
    • iam:* (for managing roles and policies)

Kubernetes Access

  • kubectl Installed: Version matching your EKS cluster version (±1 minor version)
  • Cluster Admin Access: You need system:masters equivalent permissions
  • Network Access: One of the following:
    • VPN connection to your VPC
    • Bastion/jump host in the VPC
    • AWS Cloud9 environment in the VPC
    • Public API endpoint access enabled on EKS cluster

ClickHouse Access

  • clickhouse-client Installed: For testing native protocol connections
  • ClickHouse Credentials: Admin username and password
  • Understanding of Your Schema: Knowledge of your databases, tables, and replication setup

Required Tools

# Verify AWS CLI
aws --version
# Required: >= 2.0.0 or >= 1.16.156

# Verify kubectl
kubectl version --client
# Should match your cluster version ±1 minor version

# Verify clickhouse-client (optional but recommended)
clickhouse-client --version

# Verify jq (for JSON parsing)
jq --version

# Verify envsubst (for template substitution)
envsubst --version

Pre-Disconnection Verification

Verify Current State

# Set your environment variables (save to a file for reuse)
cat > ~/.clickhouse-disconnect-env <<'EOF'
export CLUSTER_NAME="your-eks-cluster-name"
export AWS_REGION="us-east-1"
export CH_NAMESPACE="altinity-cloud-managed-clickhouse"
export SYS_NAMESPACE="altinity-cloud-system"
EOF

# Load the variables into your shell
source ~/.clickhouse-disconnect-env

# Verify cluster exists
aws eks describe-cluster --name $CLUSTER_NAME --region $AWS_REGION

# Check cluster version (for compatibility)
aws eks describe-cluster --name $CLUSTER_NAME --region $AWS_REGION \\
    --query 'cluster.version' --output text

# List ClickHouse installations (if you have access)
kubectl get chi -n $CH_NAMESPACE 2>/dev/null || echo "No kubectl access yet"

# Check current backups (example - adjust to your setup)
aws s3 ls s3://your-backup-bucket/clickhouse-backups/ --region $AWS_REGION 2>/dev/null || echo "Need to verify backup location"

Verify kubectl access (custom domain checks)

Run these checks after confirming kubectl connectivity.

# Check if ACME secret exists
kubectl get secrets -n $SYS_NAMESPACE | grep -i acme

# Common secret names:
# - acme-credentials
# - letsencrypt-secret
# - cloudflare-api-token (if using Cloudflare DNS-01 challenge)
# - route53-credentials (if using Route53 DNS-01 challenge)

# View secret details (without revealing credentials)
kubectl describe secret <acme-secret-name> -n $SYS_NAMESPACE

# Check crtd is running (Altinity's certificate manager)
kubectl get pods -n $SYS_NAMESPACE | grep crtd

# Check ClusterIssuers/Issuers (crtd configuration)
kubectl get clusterissuer
kubectl get issuer -A

# Check existing certificates
kubectl get certificate -A

Risk Assessment

High Risk Items

  • Data Loss: If backups are not configured properly
    • Mitigation: Test backup and restore BEFORE disconnecting
  • Service Outage: If application migrations fail
    • Mitigation: Maintain both endpoints during transition period
  • Security Exposure: If enabling public API access
    • Mitigation: Use security groups to restrict access by IP

Medium Risk Items

  • Performance Degradation: If Contour is not configured optimally
    • Mitigation: Load test Contour before migration
  • Certificate Expiration: Edge-proxy certificates expire in 3 months
    • Mitigation: Complete disconnection within 6-8 weeks

Low Risk Items

  • Learning Curve: Team needs to learn new operational procedures
    • Mitigation: Create comprehensive runbooks

Support Resources

Before Starting

  • Altinity Support: support@altinity.com
  • Questions about process: Discuss with Altinity support team
  • Custom requirements: Request modifications to standard process

Reference Documentation

👉 Next: Checking AWS and Network Access