External Secrets Operator 연동

External Secrets Operator(ESO)는 클러스터에서 실행되며, Secrets Manager에서 조회한 값으로 쿠버네티스 시크릿을 생성하고 갱신합니다.

이 문서는 Kubernetes Engine에서 사용하는 카카오클라우드용 ESO 배포판의 연동 설정, 지원 범위와 시크릿 활용 방법을 안내합니다.

안내

처음 연동하는 경우 Kubernetes Engine과 Secrets Manager 연동 튜토리얼을 먼저 진행하세요.
설치 후 시크릿 동기화와 갱신을 실습하려면 Kubernetes Engine 클러스터에서 ESO 시크릿 활용 튜토리얼을 참고하세요.

지원 범위 및 제약 사항

카카오클라우드용 ESO 배포판의 지원 기능과 제약 사항은 다음과 같습니다.

지원 기능

시크릿 ID로 값 조회
기본 버전 또는 지정한 버전의 값 조회
JSON 객체의 특정 필드 값을 지정한 키에 저장
JSON 객체의 모든 최상위 키와 값 저장
동기화 정책에 따른 쿠버네티스 시크릿 생성 및 갱신

제약 사항

카카오클라우드용 ESO 배포판에서는 카카오클라우드 프로바이더만 사용할 수 있으며, 다른 프로바이더는 사용할 수 없습니다.
ESO를 통한 Secrets Manager 시크릿의 생성·수정·삭제는 지원하지 않습니다.
이름이나 태그로 여러 Secrets Manager 시크릿을 검색해 동기화하는 기능(dataFrom.find)은 지원하지 않습니다.

사전 준비 사항

클러스터 조건과 네트워크는 설치 튜토리얼의 사전 준비를 확인합니다.
ESO 인증에 사용할 IAM 주체에는 Secrets Manager 시크릿 값 조회 권한과 KMS 사용자(User) 역할 이상이 필요합니다. Secrets Manager·KMS 역할을 확인하세요.
Secrets Manager의 시크릿별 접근 제어를 사용하면 해당 IAM 주체가 허용 대상에 포함되어야 합니다. 접근 제어 설정을 참고하세요.
원본 값과 버전은 Secrets Manager에서 관리합니다. 시크릿 생성과 버전 생성을 참고하세요.

배포판 정보

Kubernetes Engine에서 사용하는 카카오클라우드용 ESO 배포판의 설치 도구, 이미지 및 버전 정보를 안내합니다.

배포 구성

구분	내용
설치 도구	Helm 3, `kubectl`
Helm 차트	`oci://ghcr.io/kakaoenterprise/charts/external-secrets`
Helm 차트 버전	`2.10.0-kc.1`
컨테이너 이미지	`ghcr.io/kakaoenterprise/external-secrets-kakaocloud:v2.10.0-kc.1`
기반 ESO 버전	External Secrets Operator `2.10.0`
Provider	카카오클라우드 Secrets Manager
Provider 동작 방식	읽기 전용

버전 및 표기 규칙

이 문서에서 다루는 배포판은 External Secrets Operator(ESO) 2.10.0을 기반으로 카카오클라우드 Secrets Manager 연동 기능을 추가한 배포판입니다. ESO 프로젝트에서 제공하는 배포판과 구분하기 위해 Helm 차트 버전과 이미지 태그에 kc 식별자를 사용합니다.

아래 표에서 현재 제공 버전은 2.10.0-kc.1이며, 2.10.0-kc.2와 2.11.0-kc.1은 버전 번호 부여 방식을 설명하기 위한 예시입니다. 예시 버전은 실제 제공 또는 배포 일정을 의미하지 않습니다.

구분	Helm 차트 버전	이미지 태그
카카오클라우드용 ESO `2.10.0` 기반 첫 배포	`2.10.0-kc.1`	`v2.10.0-kc.1`
동일한 ESO 버전 기반 수정본 배포 예시	`2.10.0-kc.2`	`v2.10.0-kc.2`
카카오클라우드용 ESO `2.11.0` 기반 배포 예시	`2.11.0-kc.1`	`v2.11.0-kc.1`

주의

카카오클라우드 배포 버전은 External Secrets Operator를 기반으로 카카오클라우드 환경에 맞게 구성한 버전입니다. 설치, 장애 분석, 업그레이드 및 롤백 시 전체 이미지 주소와 배포 버전을 함께 확인해 주세요.

변경 이력

카카오클라우드용 ESO의 버전별 주요 변경 사항입니다. 최신 버전부터 표시하며, 배포일은 GHCR 게시일 기준입니다.

버전	배포일	주요 변경 사항
`2.10.0-kc.1`	2026-09-15	ESO `2.10.0` 기반 카카오클라우드 배포

연동 구성

ESO는 ExternalSecret에 지정된 SecretStore를 통해 연결 설정과 인증정보를 확인합니다. 인증에는 쿠버네티스 시크릿에 저장된 IAM 액세스 키를 사용합니다.

리소스	역할
IAM 인증정보용 쿠버네티스 시크릿	사용자가 생성하며, ESO 인증에 사용할 IAM 액세스 키 ID와 보안 액세스 키 저장
`SecretStore`	카카오클라우드 엔드포인트와 IAM 인증정보를 저장한 시크릿 참조 정의
`ExternalSecret`	조회할 Secrets Manager 시크릿 ID와 동기화 대상 정의
Secrets Manager 시크릿	애플리케이션에 전달할 원본 값과 버전 관리
동기화 결과용 쿠버네티스 시크릿	ESO가 조회한 값을 동기화하며, 애플리케이션에서 환경 변수나 파일 등으로 사용

기본 연동 설정

설치된 ESO를 사용해 Secrets Manager의 값을 쿠버네티스 시크릿으로 동기화하는 방법을 안내합니다. 기본 연동의 전체 절차와 명령어는 Kubernetes Engine과 Secrets Manager 연동 튜토리얼의 기본 연동 단계에서 자세히 확인할 수 있습니다.

리소스를 생성할 네임스페이스를 준비합니다.
IAM 인증정보 시크릿을 생성합니다.
SecretStore에 엔드포인트와 인증정보 참조를 설정하고 적용합니다.
ExternalSecret에 Secrets Manager 시크릿 ID와 대상 쿠버네티스 시크릿을 지정하고 적용합니다.
동기화 결과를 확인합니다.

이후 예제는 위 절차에서 생성한 eso-demo 네임스페이스와 kakaocloud-secret-store를 사용합니다. YAML 작성 및 적용 방법은 각 예제의 안내를 따르세요.

주요 설정 항목은 다음과 같습니다.

리소스	설정	의미
SecretStore	`spec.provider.kakaocloud.secretsManagerEndpoint`	Secrets Manager의 HTTPS 기본 URL
SecretStore	`spec.provider.kakaocloud.auth.iamEndpoint`	IAM의 HTTPS 기본 URL
SecretStore	`spec.provider.kakaocloud.auth.secretRef`	IAM 액세스 키를 저장한 쿠버네티스 시크릿 참조
ExternalSecret	`spec.secretStoreRef`	사용할 SecretStore의 이름과 종류
ExternalSecret	`spec.target.name`	동기화할 쿠버네티스 시크릿의 이름
ExternalSecret	`spec.data[].remoteRef.key`	Secrets Manager 시크릿의 ID. 시크릿 이름을 사용하지 않음
ExternalSecret	`spec.data[].remoteRef.version`	조회할 버전 번호 문자열. 생략하면 기본 버전 조회
ExternalSecret	`spec.data[].secretKey`	조회한 값을 저장할 쿠버네티스 시크릿의 키
ExternalSecret	`spec.data[].remoteRef.property`	값을 조회할 JSON 필드. 생략하면 시크릿 전체 값 조회
ExternalSecret	`spec.dataFrom[].extract.key`	JSON 객체의 모든 최상위 필드를 추출할 Secrets Manager 시크릿의 ID
ExternalSecret	`spec.dataFrom[].extract.version`	조회할 버전 번호 문자열. 생략하면 기본 버전 조회

설정 시 주의 사항

엔드포인트에는 HTTPS 기본 URL만 입력합니다. API 경로, 쿼리 문자열 또는 인증 정보를 포함하지 않습니다.
remoteRef.property 또는 dataFrom.extract를 사용하려면 Secrets Manager 시크릿 값이 유효한 JSON 객체여야 합니다.
일반 문자열에 필드 추출을 적용하거나 존재하지 않는 필드를 지정하면 동기화에 실패합니다.

프라이빗 엔드포인트 사용

프라이빗 엔드포인트를 사용하려면 SecretStore의 spec.provider.kakaocloud.secretsManagerEndpoint와 spec.provider.kakaocloud.auth.iamEndpoint에 각 서비스에서 제공하는 HTTPS 기본 URL을 설정합니다. *.kakaocloud-in.com 등의 실제 엔드포인트 주소를 사용하고, IAM URL에는 /identity/v3/auth/tokens 경로를 붙이지 않습니다.

ESO 컨트롤러 파드에서 해당 주소가 프라이빗 IP로 해석되고, HTTPS 연결 및 TLS 인증서 검증이 가능한지 확인하세요. 프라이빗 엔드포인트를 사용하지 않는 서비스와 GHCR에는 별도의 외부 통신 경로가 필요할 수 있습니다.

특정 버전 고정

배포 환경 재현이나 단계적 시크릿 교체를 위해 특정 버전을 계속 사용해야 한다면 사용 중인 ExternalSecret 매니페스트의 spec.data에 remoteRef.version을 지정하고 다시 적용합니다. 코드 아래 입력란에 실제 조회할 시크릿 ID와 버전 번호를 입력하세요. 버전을 고정하면 기본 버전을 변경해도 대상 쿠버네티스 시크릿은 해당 기본 버전을 따라가지 않습니다.

버전 고정 예시
  data:
    - secretKey: password
      remoteRef:
        key: ${SECRET_ID}
        version: "${SECRET_VERSION}"

변수	설명
SECRET_ID🖌︎	Secrets Manager 시크릿 ID
SECRET_VERSION🖌︎	조회할 버전 번호

JSON 객체의 모든 최상위 키와 값을 동기화하면서 특정 버전을 고정하려면 spec.dataFrom의 extract.version을 지정합니다. extract.version을 생략하면 기본 버전을 조회합니다. 다음은 spec 아래에 넣을 설정입니다.

JSON 객체의 버전 고정 예시
  dataFrom:
    - extract:
        key: ${SECRET_ID}
        version: "${SECRET_VERSION}"

변수	설명
SECRET_ID🖌︎	Secrets Manager 시크릿 ID
SECRET_VERSION🖌︎	조회할 버전 번호

주의

remoteRef.version과 extract.version은 Secrets Manager 시크릿의 버전을 의미합니다. 두 필드는 문자열(String)이므로 버전 번호를 반드시 따옴표로 감싸야 합니다.

JSON 시크릿 동기화

아래 JSON 객체를 값으로 저장한 Secrets Manager 시크릿을 준비합니다. 각 YAML 예제의 입력란에 해당 시크릿의 ID를 입력합니다.

아래 두 예제는 refreshInterval: 1h0m0s를 사용합니다. 최초 쿠버네티스 시크릿 생성은 매니페스트 적용 후 진행되며, 이후 원격 값의 변경은 설정한 1시간 주기로 반영됩니다.

시크릿 값 예시
{
  "username": "app-user",
  "password": "app-password",
  "endpoint": "db.example.internal"
}

필요한 속성만 선택

remoteRef.property로 JSON 객체의 특정 필드를 선택하고, secretKey로 해당 값을 저장할 쿠버네티스 시크릿의 키를 지정합니다. 아래 예제는 username과 password 필드의 값을 각각 같은 이름의 키에 저장합니다.

app-credentials.yaml
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: app-credentials
  namespace: eso-demo
spec:
  refreshPolicy: Periodic
  refreshInterval: 1h0m0s
  secretStoreRef:
    name: kakaocloud-secret-store
    kind: SecretStore
  target:
    name: app-credentials
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: ${SECRET_ID}
        property: username
    - secretKey: password
      remoteRef:
        key: ${SECRET_ID}
        property: password

변수	설명
SECRET_ID🖌︎	Secrets Manager 시크릿 ID

app-credentials 적용 및 검증
kubectl apply -f app-credentials.yaml
kubectl wait --for=condition=Ready \
  externalsecret/app-credentials -n eso-demo --timeout=60s
kubectl get secret app-credentials -n eso-demo \
  -o go-template='{{range $key, $_ := .data}}{{$key}}{{"\n"}}{{end}}'

ExternalSecret이 Ready=True이고 출력된 키가 username과 password이면 이 예제의 생성 결과가 정상입니다.

JSON 최상위 항목 전체 추출

dataFrom.extract를 사용하면 JSON 객체의 모든 최상위 키와 값을 쿠버네티스 시크릿에 저장합니다. 아래 예제는 username, password, endpoint 키를 생성하고 각 키에 해당 필드의 값을 저장합니다.

database-credentials.yaml
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
  namespace: eso-demo
spec:
  refreshPolicy: Periodic
  refreshInterval: 1h0m0s
  secretStoreRef:
    name: kakaocloud-secret-store
    kind: SecretStore
  target:
    name: database-credentials
    creationPolicy: Owner
  dataFrom:
    - extract:
        key: ${SECRET_ID}

변수	설명
SECRET_ID🖌︎	Secrets Manager 시크릿 ID

database-credentials 적용 및 검증
kubectl apply -f database-credentials.yaml
kubectl wait --for=condition=Ready \
  externalsecret/database-credentials -n eso-demo --timeout=60s
kubectl get secret database-credentials -n eso-demo \
  -o go-template='{{range $key, $_ := .data}}{{$key}}{{"\n"}}{{end}}'

ExternalSecret이 Ready=True이고 출력된 키가 username, password, endpoint이면 이 예제의 생성 결과가 정상입니다.

애플리케이션에 필요한 필드의 값만 전달하려면 앞의 remoteRef.property 방식으로 필드를 선택하세요.

애플리케이션 설정 전달

앞의 JSON 시크릿 동기화 예제에서 생성한 app-credentials를 애플리케이션의 환경 변수 또는 파일로 전달합니다. 애플리케이션에서 사용하는 방식에 따라 다음 두 방법 중 하나를 선택합니다.

환경 변수로 주입

앞의 JSON 시크릿 동기화 예제의 app-credentials 생성이 완료된 뒤 사용합니다. 아래 설정은 eso-demo 네임스페이스의 Deployment에서 spec.template.spec.containers[] 아래 사용할 컨테이너에 추가하는 일부 설정입니다.

환경 변수 매핑 예시
env:
  - name: APP_USERNAME
    valueFrom:
      secretKeyRef:
        name: app-credentials
        key: username
  - name: APP_PASSWORD
    valueFrom:
      secretKeyRef:
        name: app-credentials
        key: password

참고

ESO가 쿠버네티스 시크릿을 갱신하더라도 실행 중인 컨테이너의 환경 변수는 자동으로 변경되지 않습니다. 새 값을 적용하려면 파드를 다시 생성하거나 별도의 워크로드 재시작 정책을 구성해야 합니다.

시크릿 볼륨 마운트

앞의 JSON 시크릿 동기화 예제에서 생성한 app-credentials의 각 키를 파일로 마운트합니다. 코드 아래 입력란에 해당 파일을 읽도록 구성한 애플리케이션 이미지 주소를 입력하여 다음 파일을 작성합니다.

app-credentials-volume.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-credentials-volume
  namespace: eso-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app-credentials-volume
  template:
    metadata:
      labels:
        app: app-credentials-volume
    spec:
      containers:
        - name: app
          image: ${APPLICATION_IMAGE}
          volumeMounts:
            - name: app-credentials
              mountPath: /etc/app-credentials
              readOnly: true
      volumes:
        - name: app-credentials
          secret:
            secretName: app-credentials
            items:
              - key: username
                path: username
              - key: password
                path: password

변수	설명
APPLICATION_IMAGE🖌︎	애플리케이션 이미지 주소

볼륨 마운트 워크로드 적용
kubectl apply -f app-credentials-volume.yaml
kubectl rollout status deployment/app-credentials-volume -n eso-demo --timeout=120s

컨테이너에는 /etc/app-credentials/username과 /etc/app-credentials/password 파일이 각각 생성되며, 각 파일에는 해당 시크릿 키의 값이 저장됩니다. 앞의 예제에서는 각각 app-user와 app-password가 들어갑니다. Deployment 준비 상태와 별도로 애플리케이션이 이 경로에서 값을 읽는지 확인하세요.

위 예제에서는 ESO가 쿠버네티스 시크릿을 갱신하면 마운트된 파일 내용도 일정 시간 후 자동으로 변경됩니다. 파일에 반영되기까지 걸리는 시간은 클러스터 설정과 상태에 따라 다릅니다. 다만 애플리케이션이 설정 파일을 시작할 때 한 번만 읽는다면, 새 값을 사용하려면 설정을 다시 읽게 하거나 파드를 재시작해야 합니다.

Ingress에 TLS 인증서 전달

TLS 인증서와 개인 키를 쿠버네티스 시크릿으로 동기화한 뒤 기존 Ingress에서 참조합니다.

이 구성을 적용하려면 다음 리소스가 준비되어 있어야 합니다.

eso-demo 네임스페이스의 Ingress와 백엔드 서비스
해당 Ingress를 처리하는 인그레스 컨트롤러
서비스에 연결할 도메인

카카오클라우드 Secrets Manager에는 다음 두 필드를 포함한 별도의 JSON 시크릿을 생성합니다.

필드	입력값
`certificate`	필요한 중간 인증서 체인을 포함한 PEM 형식의 인증서
`privateKey`	`certificate`와 쌍을 이루는 PEM 형식의 개인 키

인증서와 개인 키를 PEM 문자열 그대로 입력하며, 별도로 Base64 인코딩하지 않습니다.

PEM 입력 시 줄바꿈 유지

인증서와 개인 키는 PEM 형식의 줄바꿈을 유지하여 입력하세요. JSON으로 작성하는 경우 문자열 내부의 줄바꿈은 \n으로 표현합니다. 줄바꿈이 공백으로 바뀌지 않도록 주의하세요.

다음은 JSON으로 작성할 때의 입력 형식 예시입니다. 인증서 내용과 개인 키 내용을 포함한 각 문자열 전체를 실제 PEM 인증서와 개인 키로 바꾸세요. 개인 키의 BEGIN 및 END 표시는 원본 PEM 형식을 그대로 유지합니다.

Secrets Manager에 저장할 TLS 인증서와 개인 키 예시
{
  "certificate": "-----BEGIN CERTIFICATE-----\n인증서 내용\n-----END CERTIFICATE-----\n",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n개인 키 내용\n-----END PRIVATE KEY-----\n"
}

아래 예제는 refreshInterval: 1h0m0s를 사용합니다. 최초 TLS 시크릿 생성은 매니페스트 적용 후 진행되며, 이후 원격 값의 변경은 설정한 1시간 주기로 반영됩니다.

코드 아래 입력란에 해당 TLS용 Secrets Manager 시크릿 ID를 입력합니다. 인증서와 개인 키를 각각 tls.crt, tls.key로 매핑하고 대상 쿠버네티스 시크릿 타입을 kubernetes.io/tls로 지정합니다.

ingress-tls-secret.yaml
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: ingress-tls
  namespace: eso-demo
spec:
  refreshPolicy: Periodic
  refreshInterval: 1h0m0s
  secretStoreRef:
    name: kakaocloud-secret-store
    kind: SecretStore
  target:
    name: ingress-tls
    creationPolicy: Owner
    template:
      type: kubernetes.io/tls
  data:
    - secretKey: tls.crt
      remoteRef:
        key: ${SECRET_ID}
        property: certificate
    - secretKey: tls.key
      remoteRef:
        key: ${SECRET_ID}
        property: privateKey

변수	설명
SECRET_ID🖌︎	TLS용 Secrets Manager 시크릿 ID

매니페스트를 적용하고 쿠버네티스 시크릿의 타입과 데이터 키를 확인합니다.

TLS 시크릿 적용 및 검증
kubectl apply -f ingress-tls-secret.yaml
kubectl wait --for=condition=Ready \
  externalsecret/ingress-tls -n eso-demo --timeout=60s
kubectl get secret ingress-tls -n eso-demo \
  -o go-template='{{.type}}{{"\n"}}{{range $key, $_ := .data}}{{$key}}{{"\n"}}{{end}}'

출력에 kubernetes.io/tls 타입과 tls.crt, tls.key 키가 있는지 확인합니다. 이 확인만으로 인증서의 유효성이나 인증서와 개인 키의 일치가 검증되지는 않습니다.

다음은 eso-demo 네임스페이스의 기존 Ingress에 추가할 일부 설정입니다. 코드 아래 입력란에 실제 서비스 도메인을 입력하고, 기존 Ingress의 호스트 및 백엔드 설정과 함께 사용하세요.

기존 ingress.yaml의 TLS 설정 부분
spec:
  tls:
    - hosts:
        - ${DOMAIN}
      secretName: ingress-tls

변수	설명
DOMAIN🖌︎	서비스 도메인

Ingress에 연결한 뒤 실제 도메인으로 HTTPS 접속이 되는지 확인하세요. 연결에 실패하면 인그레스 컨트롤러, DNS, Load Balancer 설정을 점검하고, 인증서가 접속 도메인과 일치하는지와 중간 인증서가 누락되지 않았는지 확인하세요.

예제 리소스 정리

서비스 가이드의 예제를 모두 실행한 후 리소스를 정리하려면 서비스 가이드 예제 리소스 정리를 참고하세요.

운영 및 검증

동기화 정책, 구성 상태 확인 방법, 보안 및 다중 네임스페이스 사용 시 고려 사항을 설명합니다.

보안 및 운영 유의 사항

카카오클라우드 IAM 주체에는 필요한 프로젝트와 Secrets Manager 시크릿 조회 권한만 최소한으로 부여하세요.
매니페스트(YAML)의 remoteRef.key에는 Secrets Manager 시크릿 이름이 아닌 ID를 입력하세요. YAML 파일에 시크릿 원문이나 IAM 액세스 키를 기록하지 마세요.
운영 점검 시 시크릿 원문을 출력하지 마세요. Ready=True, SecretSynced 상태와 최근 동기화 시점을 확인하고, 실제 데이터 변경 여부는 별도로 검증하세요.
IAM 액세스 키를 저장한 쿠버네티스 시크릿과 동기화 결과용 쿠버네티스 시크릿은 필요한 사용자와 워크로드만 조회할 수 있도록 접근 권한을 설정하세요.

동기화 정책

동기화 정책(refreshPolicy)은 쿠버네티스 시크릿의 갱신 시점을 정합니다. 생략하면 Periodic으로 동작합니다.

정책	동작	사용 예시
`Periodic`	`refreshInterval` 주기로 원격 값을 다시 조회하며, `0s`이면 최초 동기화 후 정기 조회하지 않음	시크릿 교체를 자동 반영하는 일반 환경
`OnChange`	`ExternalSecret` 메타데이터 또는 명세가 바뀔 때 동기화하며, `refreshInterval`은 적용되지 않음	승인 후 수동으로 반영하는 환경
`CreatedOnce`	최초 동기화 후 주기 갱신하지 않으며, `refreshInterval`은 적용되지 않음	원격 값의 주기적 변경 반영이 필요 없는 환경

Periodic에서 refreshInterval: 0s로 설정하면 최초 동기화 후 대상 쿠버네티스 시크릿이 정상 상태인 동안에는 force-sync 어노테이션을 변경해도 갱신되지 않습니다.

이 예제의 creationPolicy: Owner에서는 CreatedOnce를 사용해도 대상 쿠버네티스 시크릿이 삭제되거나 데이터가 수정되면 다시 동기화합니다.

검증 결과 판정 기준

검증 항목	성공 기준	실패 시 우선 확인 항목
SecretStore 구성 및 인증	`SecretStore` `Ready=True`	IAM 인증정보, 엔드포인트 및 네트워크
Secrets Manager 시크릿 조회 및 최초 동기화	`ExternalSecret` `Ready=True`, 대상 쿠버네티스 시크릿 및 예상 데이터 키 생성	시크릿 ID, 조회 권한, Secrets Manager 연결, `SecretStore` 참조명, 컨트롤러 이벤트
동기화 결과용 쿠버네티스 시크릿 갱신	출력된 값이 조회 대상 Secrets Manager 시크릿 버전의 값과 일치	새 버전 생성 여부, `refreshPolicy`, 버전 고정 여부
환경 변수 주입	재생성된 파드에서 새 값 사용	파드 재시작 여부, `secretKeyRef` 오타
시크릿 파일 마운트	마운트 파일 변경 및 애플리케이션 재적용	`subPath`로 파일을 마운트했는지, 애플리케이션이 변경된 파일을 다시 읽는지 확인
Ingress TLS 연결	TLS 시크릿 타입 확인 후 HTTPS 연결 성공	인그레스 컨트롤러, DNS, 접속 도메인과 인증서의 일치 여부, 중간 인증서 누락 여부

SecretStore의 Ready=True만으로 Secrets Manager 시크릿의 조회 권한이나 실제 조회 성공이 확인되지는 않습니다. 실제 조회는 ExternalSecret의 상태와 생성된 대상 데이터로 확인합니다.

여러 네임스페이스에서 사용하는 경우

여러 네임스페이스에서 연결 및 인증 설정을 공유하려면 ClusterSecretStore를, 동일한 ExternalSecret 설정을 일괄 생성하고 관리하려면 ClusterExternalSecret을 사용할 수 있습니다.

자세한 설정 방법은 ESO 공식 문서의 ClusterSecretStore와 ClusterExternalSecret를 참고해 주세요.

문제 해결

설치 오류, 웹훅 타임아웃 또는 동기화 실패는 ESO 연동 문제 해결에서 증상별로 확인하세요.

지원 범위 및 제약 사항​

지원 기능​

제약 사항​

사전 준비 사항​

배포판 정보​

배포 구성​

버전 및 표기 규칙​

변경 이력​

연동 구성​

기본 연동 설정​

프라이빗 엔드포인트 사용​

특정 버전 고정​

JSON 시크릿 동기화​

필요한 속성만 선택​

JSON 최상위 항목 전체 추출​

애플리케이션 설정 전달​

환경 변수로 주입​

시크릿 볼륨 마운트​

Ingress에 TLS 인증서 전달​

운영 및 검증​

동기화 정책​

검증 결과 판정 기준​

여러 네임스페이스에서 사용하는 경우​

문제 해결​