HCP Consul Dedicated

이 주제는 이전에 HashiCorp Cloud Platform(HCP)을 통해 제공되던 네트워킹 SaaS(Software as a Service) 제품인 HCP Consul Dedicated에 대해 설명해요.

HCP Consul Dedicated는 2025년 11월 12일에 지원이 종료되었어요.

출처: 문서

본문

소개 (Introduction)

HCP Consul dedicated는 일반적인 Consul 작업을 위한 간소화된 워크플로와, HashiCorp가 여러분을 대신해 Consul 서버를 설정하고 관리할 수 있는 옵션을 제공하는 서비스였어요.

2025년 11월 12일에 HashiCorp는 HCP Consul Dedicated 클러스터에 대한 운영과 지원을 종료했어요. 이 날짜부터 Dedicated 클러스터를 배포, 접근, 업데이트 또는 관리할 수 없게 돼요.

HCP Consul Dedicated 배포를 Consul Enterprise를 실행하는 자체 관리형 서버 클러스터로 마이그레이션할 것을 권장해요. 가상 머신에서는 이 마이그레이션에 서버 클러스터에 대한 일부 다운타임이 필요하지만 기존 구성과 운영 간의 연속성을 가능하게 해요. Kubernetes에서는 다운타임이 필요하지 않지만, 마이그레이션이 성공적인지 확인하기 위해 다운타임을 예약할 것을 권장해요.

마이그레이션 워크플로 (Migration workflows)

Dedicated 클러스터를 자체 관리형 환경으로 마이그레이션하는 프로세스는 클러스터가 가상 머신(VM)에서 실행되는지 Kubernetes에서 실행되는지에 따라 달라지는 단계로 구성돼요.

VM

VM에서 마이그레이션하려면 다음 단계를 완료해요:

Kubernetes

Kubernetes에서 마이그레이션하려면 다음 단계를 완료해요:

마이그레이션 권장 사항 및 모범 사례 (Migration recommendations and best practices)

VM에서는 마이그레이션 프로세스에 자체 관리형 클러스터에서 스냅샷을 복원한 시점부터 구성을 업데이트한 후 클라이언트 에이전트를 다시 시작할 때까지 지속되는 임시 중단이 필요해요. Kubernetes에서는 다운타임이 필요하지 않지만, 마이그레이션이 성공적인지 확인하기 위해 다운타임을 예약할 것을 권장해요.

또한 스냅샷이 생성된 후 Dedicated 서버에 기록된 데이터는 복원할 수 없어요.

중단 기간을 제한하려면 프로덕션 워크로드를 완전히 마이그레이션하기 전에 dev 환경을 사용해 마이그레이션을 테스트할 것을 권장해요. 중단 시간은 클라이언트 수, 자체 관리형 환경, 관련 자동화된 프로세스에 따라 달라져요.

VM을 사용하든 Kubernetes를 사용하든, 마이그레이션으로 인한 예기치 않은 데이터 손실이나 데이터 동기화 문제를 해결하기 위해 Consul 유지 관리 모드를 사용해 비활성 기간을 예약할 것도 권장해요.

마이그레이션 사전 요구 사항 (Migration prerequisites)

이 페이지의 마이그레이션 지침은 기존 인프라에 대해 다음과 같은 가정을 해요:

이전 HCP Consul Dedicated 서버 클러스터와 현재 자체 관리형 서버 클러스터의 구성이 일치해야 해요. 이 구성에는 다음 설정이 포함되어야 해요:
- 두 클러스터 모두 3개의 노드가 있어요.
- ACL, TLS, gossip 암호화가 활성화되어 있어요.
자체 관리형 클러스터에 대한 명령줄 접근 권한이 있어요.
마이그레이션의 영향을 받는 클라이언트 노드를 이미 식별했어요.

Kubernetes에서 클러스터를 마이그레이션하는 경우 버전 호환성 매트릭스를 참조해 consul과 consul-k8s의 호환 가능한 버전을 사용하고 있는지 확인해요.

또한 Enterprise 클러스터로 마이그레이션해야 하며, 이를 위해서는 Enterprise 라이선스가 필요해요. Community 에디션 클러스터로의 마이그레이션은 불가능해요. Consul Enterprise 라이선스에 접근할 수 없다면 지원 요청을 제출해 알려주세요. 계정 팀 구성원이 도움을 주기 위해 연락할 거예요.

VM에서 자체 관리형으로 마이그레이션 (Migrate to self-managed on VMs)

다음 단계를 완료해 VM에서 자체 관리형 Consul Enterprise 클러스터로 마이그레이션해요.

클러스터의 스냅샷 가져오기 (Retrieve a snapshot of your cluster)

스냅샷은 HCP Consul 클러스터 상태의 백업이에요. Consul은 이 스냅샷을 사용해 새 자체 관리형 환경에서 이전 상태를 복원해요.

2025년 11월 12일부터 HCP Dedicated 클러스터의 스냅샷을 찍을 수 없어요. 클러스터 스냅샷은 30일 동안 보관할 거예요. 가장 최근 스냅샷에 접근하는 데 도움이 필요하면 HCP 지원팀에 문의하세요.

스냅샷을 자체 관리형 클러스터로 전송 (Transfer the snapshot to a self-managed cluster)

보안 복사(SCP) 명령을 사용해 스냅샷 파일을 자체 관리형 Consul 클러스터로 이동해요.

$ scp /home/backup/hcp-cluster.snapshot <user>@<self-managed-node>:/home/backup

스냅샷을 사용해 자체 관리형 환경에서 클러스터 복원 (Use the snapshot to restore the cluster in your self-managed environment)

스냅샷 파일을 자체 관리형 노드로 전송한 후, 자체 관리형 환경에서 스냅샷으로 클러스터 상태를 복원할 수 있어요.

CONSUL_HTTP_TOKEN 환경 변수가 자체 관리형 환경의 ACL 토큰 값으로 설정되어 있는지 확인해요. 그런 다음 다음 명령을 실행해요.

$ consul snapshot restore /home/backup/hcp-cluster.snapshot
Restored snapshot

환경 변수를 사용할 수 없다면 명령에 -token= 플래그를 추가해요:

$ consul snapshot restore /home/backup/hcp-cluster.snapshot -token="<token-value>"
Restored snapshot

이 명령에 대한 자세한 내용은 Consul CLI 문서를 참고해요.

새 서버를 가리키도록 클라이언트 구성 파일 업데이트 (Update the client configuration file to point to the new server)

Consul 클라이언트의 에이전트 구성을 수정해요. 다음 구성 값을 업데이트해야 해요:

retry_join IP 주소
TLS 암호화
ACL 토큰

기존 인증 기관을 사용하거나 자체 관리형 클러스터에서 새 인증 기관을 만들 수 있어요. 자세한 내용은 Consul 문서의 Service mesh certificate authority overview를 참고해요.

다음 예는 수정된 클라이언트 구성을 보여줘요.

retry_join = ["<new.server.IP.address>"]

tls {
    defaults {
        auto_encrypt {
            allow_tls =true
            tls = true
        }
        verify_incoming = true
        verify_outgoing = true
    }
}

acl {
    enabled = true
    default_policy = "deny"
    enable_token_persistence = true
    tokens {
        agent = "<Token-Value>"
    }
}

이 필드 구성에 대한 자세한 내용은 Consul 문서의 에이전트 구성 참조를 참고해요.

클라이언트 에이전트를 다시 시작하고 마이그레이션이 성공했는지 확인 (Restart the client agent and verify that the migration was successful)

클라이언트를 다시 시작해 업데이트된 구성을 적용하고 새 클러스터에 다시 연결해요.

$ sudo systemctl restart consul

모든 클라이언트 에이전트를 업데이트하고 다시 시작한 후 카탈로그를 확인해 클라이언트가 성공적으로 마이그레이션되었는지 확인해요. Consul UI를 확인하거나 다음 CLI 명령을 실행할 수 있어요.

$ consul members

지원 리소스 연결 해제 및 HCP Consul Dedicated 클러스터 해체 (Disconnect supporting resources and decommission the HCP Consul Dedicated cluster)

클라이언트 에이전트가 자체 관리형 클러스터에 성공적으로 연결되었음을 확인한 후 VPC 피어링 연결과 기타 사용하지 않는 리소스를 삭제해요. 다른 HCP 서비스를 사용하는 경우 이러한 리소스가 현재 사용 중이지 않은지 확인해요. 피어링 연결이나 HVN을 삭제하면 어떤 HCP 제품에서도 사용할 수 없어요.

Kubernetes에서 자체 관리형으로 마이그레이션 (Migrate to self-managed on Kubernetes)

다음 단계를 완료해 Kubernetes에서 자체 관리형 Consul Enterprise 클러스터로 마이그레이션해요.

HCP Consul Dedicated 클러스터의 스냅샷 가져오기 (Retrieve a snapshot of the HCP Consul Dedicated cluster)

스냅샷은 HCP Consul 클러스터 상태의 백업이에요. Consul은 이 스냅샷을 사용해 새 자체 관리형 환경에서 이전 상태를 복원해요.

스냅샷을 자체 관리형 클러스터로 전송 (Transfer the snapshot to a self-managed cluster)

보안 복사(SCP) 명령을 사용해 스냅샷 파일을 자체 관리형 Consul 클러스터로 이동해요.

$ scp /home/backup/hcp-cluster.snapshot <user>@<self-managed-node>:/home/backup

스냅샷을 사용해 자체 관리형 환경에서 클러스터 복원 (Use the snapshot to restore the cluster in your self-managed environment)

스냅샷 파일을 자체 관리형 노드로 전송한 후 kubectl exec 명령을 사용해 자체 관리형 Kubernetes 환경에서 클러스터 상태를 복원해요.

$ kubectl exec -c consul-server-0 -- consul snapshot restore /home/backup/hcp-cluster.snapshot
Restored snapshot

snapshot 명령에 대한 자세한 내용은 Consul CLI 문서를 참고해요.

CoreDNS 구성 업데이트 (Update the CoreDNS configuration)

Kubernetes 클러스터의 CoreDNS 구성을 업데이트해 Dedicated 클러스터의 IP 주소를 가리키도록 해요. 구성된 호스트네임이 배포된 pod 내부에서 클러스터의 IP로 올바르게 해석되는지 확인해요.

Corefile: |-
    .:53 {
        errors
        health {
            lameduck 5s }
        ready
        kubernetes cluster.local in-addr.arpa ip6.arpa {
            pods insecure
            fallthrough in-addr.arpa ip6.arpa
            ttl 30
    }
    hosts {
        35.91.49.134 server.hcp-managed.consul
        fallthrough
    }
        prometheus 0.0.0.0:9153
        forward . 8.8.8.8 8.8.4.4 /etc/resolv.conf
        cache 30
        loop
        reload
        loadbalance
    }

호스트네임을 해석하려고 할 때 문제가 있으면 nameserver가 pod 내부의 CLUSTER-IP로 해석되는지 확인해요. 다음 명령을 실행해 CLUSTER-IP를 반환해요.

 # k -n kube-system get svc
   NAME      TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)         AGE
   coredns   ClusterIP   10.100.224.88   <none>        53/UDP,53/TCP   4h24m

`values.yaml` 파일 업데이트 (Update the `values.yaml` file)

자체 관리형 클러스터의 Helm 구성 또는 values.yaml 파일을 업데이트해요. 다음 작업을 수행해야 해요:

externalServers.host 값을 업데이트해요. CoreDNS 구성을 업데이트할 때 추가한 호스트 이름을 사용해요.
consul 네임스페이스에 다음 모든 CA 파일의 내용을 추가해 만든 새 CA 파일이 있는 Kubernetes 시크릿을 생성해요. 새 자체 관리형 서버의 CA 파일 내용을 마지막에 추가해요.
externalServers.tlsServerName 필드를 적절한 값으로 업데이트해요. 일반적으로 관리형 클러스터의 호스트네임이에요. 값을 모르는 경우 이 구성을 적용할 때 TLS 확인이 실패하고 오류 로그에 가능한 값이 나열돼요.
새 CA 인증서를 사용하도록 externalServers.useSystemRoots를 false로 설정해요.

이 필드 구성에 대한 자세한 내용은 Consul on Kubernetes Helm chart 참조를 참고해요.

클러스터 업그레이드 (Upgrade the cluster)

values.yaml 파일을 업데이트한 후 consul-k8s upgrade 명령을 실행해 자체 관리형 Kubernetes 클러스터를 업데이트해요.

$ consul-k8s upgrade -config-file=values.yaml

이 명령은 업데이트된 구성으로 Consul pod를 재배포해요. CoreDNS 설치가 여전히 Dedicated 클러스터를 가리키지만 pod는 새 CA 파일에 접근할 수 있어요.

워크로드 애플리케이션 재배포 (Redeploy workload applications)

init 컨테이너가 다시 실행되고 새 CA 파일을 가져오도록 모든 워크로드 애플리케이션을 재배포해요. 애플리케이션을 재배포한 후 워크로드 pod에서 kubectl describe pod 명령을 실행하고 출력이 다음 예와 유사한지 확인해요.

$ kubectl describe pod -l name="product-api-8cf8c8ccc-kvkk8"
Environment:
    POD_NAME:                   product-api-8cf8c8ccc-kvkk8 (v1:metadata.name)
    POD_NAMESPACE:              default (v1:metadata.namespace)
    NODE_NAME:                  (v1:spec.nodeName)
    CONSUL_ADDRESSES:           server.consul.one
    CONSUL_GRPC_PORT:           8502
    CONSUL_HTTP_PORT:           443
    CONSUL_API_TIMEOUT:         5m0s
    CONSUL_NODE_NAME:           $(NODE_NAME)-virtual
    CONSUL_USE_TLS:             true
    CONSUL_CACERT_PEM:           -----BEGIN CERTIFICATE-----\r
MIIFYDCCBEigAwIBAgIQQAF3ITfU6UK47naqPGQKtzANBgkqhkiG9w0BAQsFADA/ \r
MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT \r
DkRTVCBSb290IENBIFgzMB4XDTIxMDEyMDE5MTQwM1oXDTI0MDkzMDE4MTQwM1ow \r
TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh \r
cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwggIiMA0GCSqGSIb3DQEB

CoreDNS 항목 전환 (Switch the CoreDNS entry)

CoreDNS 구성을 업데이트해 자체 관리형 서버의 IP 주소를 사용하도록 해요.

자체 관리형 클러스터의 tlsServerName이 Dedicated 클러스터의 tlsServerName과 다른 경우 필드를 업데이트하고 consul-k8s upgrade 명령을 다시 실행해야 해요. 자체 관리형 클러스터의 경우 tlsServerName은 일반적으로 server.<datacenter-name>.consul 형식을 취해요.

마이그레이션이 성공했는지 확인 (Verify that the migration was successful)

CoreDNS 항목을 업데이트한 후 Consul 카탈로그를 확인해 마이그레이션이 성공했는지 확인해요. Consul UI를 확인하거나 kubectl exec 명령을 실행할 수 있어요.

$ kubectl exec -c consul-server-0 -- consul members

HCP Consul Dedicated 클러스터와 지원 리소스 연결 해제 및 해체 (Disconnect and decommission the HCP Consul Dedicated cluster and its supporting resources)

서비스가 자체 관리형 클러스터에 성공적으로 연결되었음을 확인한 후 VPC 피어링 연결과 기타 사용하지 않는 리소스를 삭제해요. 다른 HCP 서비스를 사용하는 경우 이러한 리소스가 현재 사용 중이지 않은지 확인해요. 피어링 연결이나 HVN을 삭제하면 어떤 HCP 제품에서도 사용할 수 없어요.

문제 해결 (Troubleshooting)

HCP Consul Dedicated 클러스터에서 자체 관리형 Consul Enterprise 클러스터로 마이그레이션할 때 오류가 발생할 수 있어요.

VM에서 문제 해결 (Troubleshoot on VMs)

새 ACL 부트스트랩 토큰을 생성하려고 할 때 403 Permission Denied 오류가 발생하거나 부트스트랩 토큰을 잃어버린 경우 Raft 인덱스를 업데이트해 ACL 시스템을 재설정할 수 있어요. 오류 출력에 포함된 Raft 인덱스 번호를 사용해 부트스트랩 재설정 파일에 재설정 인덱스를 작성해요. 이 명령은 리더(Leader) 노드에서 실행해야 해요.

다음 예는 13을 Raft 인덱스로 사용해요:

$ echo 13 >> consul.d/acl-bootstrap-reset

Kubernetes에서 문제 해결 (Troubleshoot on Kubernetes)

호스트네임을 해석할 때 문제가 발생하면 nameserver가 CLUSTER-IP와 일치하지 않는지 확인해요. 한 가지 가능한 문제는 ClusterDNS 필드가 Kubernetes 워커 노드와 다른 kubelet 구성의 IP를 가리키는 것이에요. kubelet 구성을 CLUSTER-IP를 사용하도록 변경한 다음 모든 노드에서 kubelet 프로세스를 다시 시작해야 해요.

지원 (Support)

자체 관리형 Consul Enterprise 클러스터로 마이그레이션할 때 질문이 있거나 추가 도움이 필요하면 지원 팀에 요청을 제출하세요.

HCP Consul Dedicated