Migrating Consul ECS Workloads to a Self-Managed Enterprise Cluster

Migrating Consul ECS Workloads to a Self-Managed Enterprise Cluster

This guide provides a comprehensive step-by-step process for migrating workloads deployed on Amazon ECS from an HCP-managed Consul cluster to a self-managed Consul Enterprise cluster. The migration leverages the Consul ECS AWS Terraform module to facilitate deployment and configuration, ensuring seamless continuity with improved control over infrastructure.

NOTE: HashiCorp highly recommends testing migration in dev environment/instances prior to production migration. Customers should schedule a period of inactivity using Consul Maintenance Mode to address potential concern for data loss/sync. 

Prerequisites

Before proceeding, ensure the following prerequisites are met:

• Self-Managed Consul Enterprise Cluster: The cluster is set up and operational.
• Consul Snapshot: A snapshot of the HCP-managed Consul cluster has been taken and restored to the self-managed cluster.
• AWS Secrets Manager Access: Permissions to create and manage secrets in AWS Secrets Manager.
• Terraform Installed: Terraform is installed and configured for managing AWS resources.

Step-by-Step Migration Process

1. Create a Combined CA Certificate

The ECS workloads require a combined Certificate Authority (CA) file for secure communication with the self-managed Consul cluster.

Download the necessary certificates:

1. ISRG Root X1 (Cross-Signed)
2. ISRG Root X2 (Cross-Signed)
3. E5 Cross
4. E6 Cross
5. R10
6. R11

Next, append the CA certificate from your self-managed Consul server to these files. Then, combine all certificates into a single file: 

cat isrg-root-x1-cross-signed.pem isrg-root-x2-cross-signed.pem e5-cross.pem e6-cross.pem r10.pem r11.pem self-managed-ca.pem  combined-ca.pem

2. Store the Combined CA in AWS Secrets Manager

1. Go to the AWS Secrets Manager console.
2. Choose "Store a new secret" and select "Other type of secret."
3. Paste the contents of the combined-ca.pem file.
4. Name the secret, e.g., consul/ca-cert.
5. Note the ARN of the secret for use in the Terraform configuration.

3. Configure the Consul ECS Terraform Module

Use the Consul ECS AWS Terraform module to deploy Consul clients on ECS.

Terraform Configuration:

module "consul_ecs" {
source = "hashicorp/consul-ecs/aws"
version = "0.1.0" # Replace with the latest version

# General settings
cluster_name = "consul-ecs-cluster"
region = "us-west-2" # Replace with your AWS region

# Consul settings
consul_server_hosts = ["<self-managed-consul-server-ip>"] # Replace with Consul server IPs
consul_ca_cert_arn = "arn:aws:secretsmanager:us-west-2:123456789012:secret:consul/ca-cert" # Replace with your secret ARN
}

Update the consul_server_hosts and consul_ca_cert_arn fields to match your environment.

4. Deploy the ECS Services

Terraform init, plan, and finally apply to complete deployment of the ECS Services

5. Update ECS Task Definitions

Modify the ECS task definitions to include the necessary environment variables and configurations for Consul.

Sample Task Definition Snippet:

{
  "containerDefinitions": [
    {
      "name": "my-app",
      "image": "my-app-image",
      "environment": [
        {
          "name": "CONSUL_HTTP_ADDR",
          "value": "https://<self-managed-consul-server-ip>:8501"
        },
        {
          "name": "CONSUL_CACERT",
          "value": "/etc/consul/combined-ca.pem"
        }
      ],
      "mountPoints": [
        {
          "sourceVolume": "consul-ca-cert",
          "containerPath": "/etc/consul/combined-ca.pem",
          "readOnly": true
        }
      ]
    }
  ],
  "volumes": [
    {
      "name": "consul-ca-cert",
      "host": {
        "sourcePath": "/path/to/combined-ca.pem"
      }
    }
  ]
} 

6. Finalize the Migration

Apply the changes again to ensure all configurations are updated:

terraform apply

Conclusion

Migrating ECS workloads from an HCP-managed Consul cluster to a self-managed Consul Enterprise cluster involves creating a combined CA certificate, securely storing it in AWS Secrets Manager, and deploying the updated configurations using Terraform. This ensures secure and seamless integration of your ECS workloads with the self-managed Consul environment.

Summary of Steps

1. Create Combined CA Certificate: Merge all necessary CA certificates, including your self-managed server's CA.
2. Store in AWS Secrets Manager: Upload the CA to Secrets Manager for secure access.
3. Configure Terraform Module: Update the consul-ecs module with the new Consul server details.
4. Deploy ECS Services: Apply Terraform configurations to redeploy ECS services.
5. Update ECS Task Definitions: Configure tasks to use the new Consul settings.
6. Finalize Migration: Reapply Terraform configurations to ensure everything is updated.

This structured approach ensures a smooth and reliable migration to your self-managed Consul Enterprise cluster.