Kubernetes Engine과 Secrets Manager 연동
카카오클라우드 Kubernetes Engine 클러스터에 External Secrets Operator(ESO)를 설치하고 Secrets Manager와의 기본 연동 상태를 검증합니다.
- 예상 소요 시간: 약 30분
- 사전 준비 사항
- 카카오클라우드 Secrets Manager Provider는 조회 전용(Read-only)이며, Secrets Manager의 시크릿 생성·수정·삭제는 지원하지 않습니다. 자세한 내용은 서비스 가이드의 지원 범위 및 제약 사항을 참고하세요.
- 액세스 키를 발급한 프로젝트의 Secrets Manager에서 대상 시크릿의 값을 조회할 수 있는 권한이 있어야 합니다. 필요한 권한은 Secrets Manager·KMS 역할을 확인하세요.
시나리오 소개
이 튜토리얼에서는 Kubernetes Engine 클러스터에 External Secrets Operator(ESO)를 설치하고, 카카오클라우드 Secrets Manager의 시크릿을 쿠버네티스 시크릿으로 동기화합니다.
ESO는 Secrets Manager에서 시크릿 값을 조회해 쿠버네티스 시크릿으로 생성하고, 설정한 주기에 따라 변경 사항을 반영합니다.
주요 내용은 다음과 같습니다.
- ESO 설치
- Secrets Manager 인증정보 구성
SecretStore및ExternalSecret생성- 쿠버네티스 시크릿 동기화 확인
ESO의 연동 구조와 각 리소스의 역할은 서비스 가이드의 연동 구성을 참고하세요.
배포 구성
이 실습에서는 Helm 3와 kubectl을 사용해 oci://ghcr.io/kakaoenterprise/charts/external-secrets 차트의 2.10.0-kc.1 버전을 설치합니다. 컨테이너 이미지와 기반 ESO 버전은 서비스 가이드의 배포 구성, 버전 표기 방식은 버전 및 표기 규칙을 참고하세요.
시작하기 전에
이 시나리오의 실습을 원활하게 진행하려면 쿠버네티스 클러스터와 Secrets Manager 시크릿을 준비하고, 네트워크 통신 요구사항을 확인해야 합니다.
클러스터 및 설치 환경 준비
설치에 앞서 아래 조건을 모두 충족하는 쿠버네티스 클러스터가 필요합니다.
- 1대 이상의
amd64(x86_64) 워커 노드 가동 (Ready상태) - 로컬 환경에서
kubectl로 클러스터 접속 가능 - Helm 3 설치 완료
kubectl과helm이 설치 대상 클러스터에 연결되도록 kubeconfig 설정- 워커 노드 또는 ESO 파드에서 외부 HTTPS 통신 허용
클러스터가 없다면 클러스터 생성 및 관리를 참고해 생성하세요. 접속 환경은 kubectl 제어 설정에 따라 준비합니다.
카카오클라우드 고객용 Helm 차트는 1.33 이상의 쿠버네티스 환경을 요구하므로, 하위 버전의 클러스터에서는 설치가 제한됩니다.
Secrets Manager 시크릿 생성
시크릿 생성 가이드에 따라 실습용 시크릿을 준비하고 ID를 확인합니다. 시크릿 생성과 값 조회에 필요한 권한은 Secrets Manager·KMS 역할에서 확인하세요.
시크릿별 접근 제어를 사용하는 경우 ESO에 사용할 IAM 주체가 허용 대상에 포함되어야 합니다.
ExternalSecret에서는 시크릿 이름이 아닌 ID를 사용하기 때문에 콘솔에서 대상 시크릿 ID를 확인해 주세요.
네트워크 통신 확인
ESO 설치와 시크릿 동기화 과정에서 필요한 외부 및 클러스터 내부 통신 경로는 다음과 같습니다.
| 출발지 | 목적지 | 포트 | 용도 |
|---|---|---|---|
| 설치 환경 또는 워커 노드 | ghcr.io, pkg-containers.githubusercontent.com | TCP 443 | Helm 차트 및 컨테이너 이미지 다운로드 |
| ESO 컨트롤러 파드 | iam.kakaocloud.com | TCP 443 | IAM 인증 토큰 발급 |
| ESO 컨트롤러 파드 | secrets-manager-service.kr-central-2.kakaocloud.com | TCP 443 | 시크릿 값 조회 |
| Kubernetes API 서버 | ESO 웹훅 | 웹훅 설정에 따라 다름 | SecretStore, ClusterSecretStore 및 ExternalSecret Admission 검증- 클러스터 버전별 웹훅 설정 참고 |
위 표의 IAM과 Secrets Manager 주소는 퍼블릭 엔드포인트입니다. 프라이빗 엔드포인트를 사용하는 경우 해당 서비스의 목적지를 실제 엔드포인트 주소로 변경하세요. 설정 방법은 서비스 가이드의 프라이빗 엔드포인트 사용을 참고하세요.
프라이빗 서브넷에서 GHCR이나 퍼블릭 엔드포인트에 접근하려면 NAT 등 외부 통신 경로가 필요할 수 있습니다. 방화벽, 보안 그룹 또는 NetworkPolicy를 사용하는 환경에서는 사용하는 통신 경로를 허용해 주세요.
시작하기
이제 아래 순서에 따라 ESO를 설치하고 Secrets Manager와 연동해 보겠습니다.
Step 1. 클러스터 접속 및 도구 확인
현재 kubectl 컨텍스트가 설치 대상 클러스터를 가리키는지 확인합니다.
kubectl config current-context
kubectl get nodes
helm version
다음 상태라면 준비가 완료된 것입니다.
- 대상 클러스터 컨텍스트가 출력됨
- 워커 노드가
Ready상태임 - Helm 3 버전이 출력됨
Step 2. Helm 차트 조회
GHCR에 게시된 Helm 차트를 조회합니다.
helm show chart \
oci://ghcr.io/kakaoenterprise/charts/external-secrets \
--version 2.10.0-kc.1
차트 정보가 정상적으로 출력되면 설치를 진행합니다.
Step 3. Helm으로 ESO 설치
쿠버네티스 1.34 이상 클러스터에서는 다음 명령을 사용합니다. 쿠버네티스 1.33 클러스터에서는 아래 참고에 안내된 옵션을 추가한 뒤 실행하세요.
helm upgrade --install external-secrets \
oci://ghcr.io/kakaoenterprise/charts/external-secrets \
--version 2.10.0-kc.1 \
--namespace external-secrets \
--create-namespace \
--set installCRDs=true \
--wait \
--timeout=5m
- 쿠버네티스 1.33 클러스터에서는 API 서버와 Admission 웹훅 간 통신을 위해 위 설치 명령에
--set webhook.hostNetwork=true와--set webhook.port=9443옵션을 추가합니다. 호스트 네트워크에서는 ESO의 기본 웹훅 포트인10250이 워커 노드의 Kubelet 포트와 충돌할 수 있으므로9443을 사용합니다. - 쿠버네티스 1.34 이상 클러스터에서는 Konnectivity를 통해 웹훅과 통신하므로 위 옵션을 추가할 필요가 없습니다.
게시된 ESO 이미지는 amd64 아키텍처를 지원합니다. 다른 아키텍처의 노드가 섞인 클러스터에서는 다음 내용을 eso-node-selector.yaml로 저장하고, 위 설치 명령에 -f eso-node-selector.yaml을 추가하세요. 컨트롤러, 웹훅, 인증서 컨트롤러가 모두 amd64 노드에 배치됩니다.
global:
nodeSelector:
kubernetes.io/arch: amd64
Step 4. 설치 상태 확인
Helm 릴리즈 상태를 확인합니다.
helm list --namespace external-secrets
파드와 Deployment 상태를 확인합니다.
kubectl get pods -n external-secrets
kubectl get deployment -n external-secrets
컨트롤러, 웹훅, 인증서 컨트롤러(cert-controller) 관련 파드가 모두 Running 및 Ready 상태여야 합니다. CRD가 생성되었는지도 확인합니다.
kubectl get crd \
externalsecrets.external-secrets.io \
secretstores.external-secrets.io \
clustersecretstores.external-secrets.io
Step 5. 애플리케이션 네임스페이스 생성
SecretStore, ExternalSecret 및 동기화된 쿠버네티스 시크릿을 생성할 네임스페이스를 준비합니다.
kubectl create namespace eso-demo
eso-demo 네임스페이스가 이미 존재하면 이 단계는 생략합니다. 다른 네임스페이스를 사용하려면 이후 명령과 YAML의 eso-demo를 해당 이름으로 변경하세요.
Step 6. IAM 인증정보 시크릿 생성
IAM 액세스 키 ID와 보안 액세스 키를 쿠버네티스 시크릿으로 생성합니다. 코드 아래 입력란에 두 값을 모두 입력한 뒤 명령을 복사해 실행하세요. 입력란을 비워 두면 인증정보 대신 ${...} 문자열이 그대로 저장됩니다.
kubectl -n eso-demo create secret generic kakaocloud-credentials \
--from-literal=accessKeyID='${IAM_ACCESS_KEY_ID}' \
--from-literal=secretAccessKey='${SECRET_ACCESS_KEY}'
| 변수 | 설명 |
|---|---|
| IAM_ACCESS_KEY_ID🖌︎ | IAM 액세스 키 ID |
| SECRET_ACCESS_KEY🖌︎ | 보안 액세스 키 |
생성 결과를 확인합니다.
kubectl get secret kakaocloud-credentials -n eso-demo
입력한 IAM 액세스 키가 셸의 명령어 기록에 남을 수 있으므로 주의하세요.
Step 7. SecretStore 생성
SecretStore는 카카오클라우드 IAM 및 Secrets Manager 엔드포인트와 인증정보 시크릿의 위치를 정의합니다. 다음 내용을 secret-store.yaml 파일로 작성합니다.
apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
name: kakaocloud-secret-store
namespace: eso-demo
spec:
provider:
kakaocloud:
secretsManagerEndpoint: https://secrets-manager-service.kr-central-2.kakaocloud.com
auth:
iamEndpoint: https://iam.kakaocloud.com
secretRef:
accessKeyID:
name: kakaocloud-credentials
key: accessKeyID
secretAccessKey:
name: kakaocloud-credentials
key: secretAccessKey
secretsManagerEndpoint와 auth.iamEndpoint에는 HTTPS 기본 URL만 입력하고, API 경로, 쿼리 문자열, 사용자 정보는 추가하지 않습니다.
SecretStore를 적용하고, Ready 상태가 될 때까지 기다립니다.
kubectl apply -f secret-store.yaml
kubectl wait \
--for=condition=Ready \
secretstore/kakaocloud-secret-store \
-n eso-demo \
--timeout=60s
상태를 확인합니다.
kubectl get secretstore kakaocloud-secret-store -n eso-demo
정상 상태에서는 READY=True가 표시됩니다. READY=False이면 상세 상태를 확인합니다.
kubectl describe secretstore kakaocloud-secret-store -n eso-demo
Step 8. ExternalSecret 생성
ExternalSecret은 조회할 Secrets Manager 시크릿 ID와 생성할 쿠버네티스 시크릿을 정의합니다.
다음 내용을 external-secret.yaml 파일로 작성합니다.
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: kakaocloud-external-secret
namespace: eso-demo
spec:
refreshPolicy: Periodic
refreshInterval: 1h0m0s
secretStoreRef:
name: kakaocloud-secret-store
kind: SecretStore
target:
name: kakaocloud-synced-secret
creationPolicy: Owner
data:
- secretKey: password
remoteRef:
key: ${KAKAOCLOUD_SECRET_ID}
# property: password
| 변수 | 설명 |
|---|---|
| KAKAOCLOUD_SECRET_ID🖌︎ | Secrets Manager 시크릿 ID |
위 예시는 Secrets Manager 시크릿 전체 값을 쿠버네티스 시크릿의 password 키에 저장합니다. 원본 값이 JSON 객체이고 그중 password 필드의 값만 저장하려면 property: password의 주석을 해제하세요.
코드 아래 입력란에 실제 Secrets Manager 시크릿 ID를 입력한 뒤 생성된 YAML을 저장합니다. 이후 매니페스트를 적용하고 Ready 상태가 될 때까지 기다립니다.
kubectl apply -f external-secret.yaml
kubectl wait \
--for=condition=Ready \
externalsecret/kakaocloud-external-secret \
-n eso-demo \
--timeout=60s
Step 9. 동기화 결과 확인
ExternalSecret 상태를 확인합니다.
kubectl get externalsecret kakaocloud-external-secret -n eso-demo
정상적으로 동기화되면 STATUS가 SecretSynced, READY가 True로 표시됩니다.
NAME STORE REFRESH INTERVAL STATUS READY
kakaocloud-external-secret kakaocloud-secret-store 1h0m0s SecretSynced True
상세 상태와 이벤트는 다음 명령으로 확인할 수 있습니다.
kubectl describe externalsecret kakaocloud-external-secret -n eso-demo
대상 쿠버네티스 시크릿 생성 결과를 확인합니다.
kubectl get secret kakaocloud-synced-secret -n eso-demo
쿠버네티스 시크릿의 값을 노출하지 않고 생성된 데이터 키만 확인하려면 다음 명령을 사용합니다.
kubectl get secret kakaocloud-synced-secret \
-n eso-demo \
-o go-template='{{range $key, $value := .data}}{{$key}}{{"\n"}}{{end}}'
ExternalSecret의 READY=True, STATUS=SecretSynced 상태와 대상 시크릿의 password 키가 확인되면 기본 동기화가 완료된 것입니다.
설치나 동기화에 실패하면 ESO 연동 문제 해결에서 증상별 확인 항목을 확인하세요.
다음 단계
기본 동기화를 완료했다면 시크릿 동기화 및 갱신 실습을 진행하세요. 다음 실습은 현재 네임스페이스, 인증정보와 SecretStore를 재사용하고 별도의 동기화 리소스로 기본 버전 변경에 따른 값의 갱신을 확인합니다. 후속 실습을 진행하려면 아래 실습 리소스 삭제 절차를 실행하지 말고 바로 다음 튜토리얼로 이동하세요.
실습 리소스 정리
실습 리소스 삭제
후속 실습이나 서비스 가이드의 예제도 진행했다면 시크릿 활용 문서의 실습 리소스 정리를 먼저 완료하세요. 아래 명령은 설치 실습에서 생성한 기본 동기화 리소스, SecretStore와 IAM 인증정보 시크릿을 삭제합니다.
kubectl delete externalsecret kakaocloud-external-secret -n eso-demo
kubectl delete secretstore kakaocloud-secret-store -n eso-demo
kubectl delete secret kakaocloud-credentials -n eso-demo
실습 네임스페이스 전체를 더 이상 사용하지 않으면 삭제할 수 있습니다.
kubectl delete namespace eso-demo
ESO 삭제
이 튜토리얼의 차트와 설치 설정에서는 아래 명령 실행 시 ESO의 CRD와 해당 커스텀 리소스가 함께 삭제됩니다. creationPolicy: Owner로 생성된 쿠버네티스 시크릿도 함께 삭제되어 이를 참조하는 워크로드에 영향을 줄 수 있습니다. 다른 네임스페이스에서 ESO를 사용 중이라면 실행하지 마세요.
helm uninstall external-secrets -n external-secrets