루트 CA 인증서 순환

Version 1.17 (latest)

지원되는 버전:

• v1.15(최신 버전)                        
• v1.14                        
• v1.13                         
• 지원되는 버전 목록

지원되지 않는 버전:

• v1.12                         
• v1.11                         
• v1.10                                      
• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

이 페이지에서는 Apigee Hybrid 구성요소가 서로 통신하는 데 사용하는 내부 인증서에 서명하는 Apigee Hybrid 루트 인증 기관 (CA) 인증서를 설명하고, 만료되기 전에 이를 순환하는 방법을 설명합니다. Apigee Hybrid v1.17부터 이 루트 CA를 직접 순환할 수 있습니다.

요약: Google에서 루트 CA 순환을 실행하는 Apigee와 달리 Apigee Hybrid 순환은 고객 주도입니다. 재정의 파일에서 단계를 설정하고 각 리전에서 단계별로 한 번씩 Apigee 운영자 차트 (apigee-operator)에서 helm upgrade를 실행합니다. 이 루트 CA는 환경 그룹에 제공하는 인그레스 TLS 인증서가 아닙니다. 루트 CA 인증서 정보를 참고하세요.

루트 CA 인증서 정보

모든 Apigee Hybrid 설치에는 cert-manager 네임스페이스에 apigee-ca이라는 이름의 cert-manager Certificate로 저장된 단일 루트 CA가 있습니다. 내부 인증서 하이브리드 발급의 신뢰 루트 역할을 하는 자체 서명 CA(isCA: true, 일반 이름 apigee-hybrid)입니다. 구성요소 간 상호 TLS (mTLS)와 승인 웹훅 및 커스텀 리소스 변환을 보호하는 단방향 (서버 측) TLS가 모두 해당됩니다. 이 CA가 만료되면 하이브리드 구성요소 간의 내부 통신이 중단됩니다.

중요: 이 페이지에 설명된 루트 CA는 내부 하이브리드 트래픽에만 사용됩니다. 환경 그룹의 클라이언트 트래픽을 종료하고 재정의 파일의 virtualhosts를 통해 별도로 구성되는 Apigee 인그레스 게이트웨이에 제공하는 TLS 인증서와는 다릅니다 (인그레스 게이트웨이에서 TLS 및 mTLS 구성 참고). 루트 CA를 순환해도 인그레스 인증서는 변경되지 않으며 인그레스 인증서를 순환해도 이 루트 CA는 순환되지 않습니다.

루트 CA 인증서를 순환하는 이유

하이브리드 차트에서 생성하는 루트 CA의 유효 기간은 10년입니다. 서명하는 내부 인증서가 계속 갱신되고 구성요소 간 통신이 중단되지 않도록 만료 전에 순환해야 합니다. 순환은 다운타임이 없도록 설계되었습니다. 전환 중에 구성요소는 이전 루트 CA와 새 루트 CA를 모두 신뢰하므로 둘 중 하나로 서명된 인증서는 이전 CA가 삭제될 때까지 유효합니다.

참고: 10년 수명은 차트에서 생성하는 CA에 적용됩니다. 자체 CA를 가져오는 경우 수명은 인증서에 따라 달라집니다.

순환 작동 방식

클러스터를 4단계에 걸쳐 순서대로 진행하여 루트 CA를 순환합니다. 모든 구성요소에서 현재 단계가 완료된 후에만 다음 단계로 이동합니다. 각 단계는 Apigee 연산자 차트 (apigee-operator)의 helm upgrade와 함께 적용되는 단일 재정의 필드 certRotation.phase에 의해 주도됩니다.

단계 (certRotation.phase)	변경사항	롤백 가능
1. CREATE_NEW_CA	새 루트 CA (apigee-ca-2)가 생성되어 모든 하이브리드 구성요소의 신뢰 저장소에 추가됩니다. 구성요소에는 여전히 이전 CA에서 서명한 인증서가 있으므로 아직 전환된 것이 없습니다.	예
2. CREATE_NEW_LEAF	새 루트 CA에서 서명한 새 리프 인증서가 발급됩니다. 이전 및 새 루트 CA 모두 신뢰할 수 있으므로 트래픽이 중단되지 않습니다.	예
3. HIDE_OLD_CA	이전 루트 CA가 활성 신뢰 구성에서 삭제됩니다. 새 루트 CA만 계속 사용됩니다. 이 단계에서는 롤백을 계속 사용할 수 있습니다.	예
4. CLEANUP	이전 루트 CA와 발급자가 삭제되고 새 루트 CA가 클러스터의 루트 CA로 승격됩니다. 이 단계는 되돌릴 수 없습니다.	아니요

시작하기 전에

• kubectl 및 helm 명령줄 도구를 설치하고 kubectl 컨텍스트가 순환 중인 클러스터를 가리키는지 확인합니다.
• 클러스터가 정상인지 확인합니다. 각 helm upgrade는 모든 ApigeeDeployment가 running 상태에 있고 요청한 단계가 현재 단계, 다음 단계 또는 롤백 단계인지 확인합니다. 클러스터가 비정상이거나 단계를 건너뛰려고 하면 업그레이드가 거부됩니다.
• 멀티 리전 배포를 실행하는 경우 시작하기 전에 해당 섹션을 읽어보세요. 모든 리전이 동일한 새 루트 CA로 수렴해야 합니다.

루트 CA 순환

로테이션 작동 방식에 나열된 각 단계에 대해 다음 단계를 순서대로 실행합니다. 단계를 적용한 다음 다음 단계로 이동하기 전에 완료되었는지 확인합니다. 멀티 리전 배포에서는 각 리전에서 이러한 단계를 실행합니다.

1단계: 단계를 설정하고 적용하기

재정의 파일에 certRotation 스탠자를 추가하거나 업데이트하여 phase을 적용할 단계로 설정합니다. 예를 들어 순환을 시작하려면 다음을 실행합니다.

certRotation:
  phase: CREATE_NEW_CA

먼저 드라이 런으로 변경사항을 테스트합니다.

helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f OVERRIDES_FILE.yaml \
  --dry-run=server

그런 다음 변경사항을 적용합니다.

helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f OVERRIDES_FILE.yaml

2단계: 단계가 완료되었는지 확인

클러스터는 하이브리드 네임스페이스의 cert-info ConfigMap에 순환 진행 상황을 기록합니다. currentPhase 값을 읽습니다.

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.currentPhase}'

currentPhase이 방금 적용한 단계와 동일한 경우에만 단계가 완료됩니다. currentPhase는 모든 구성요소가 요청된 단계로 조정된 후에만 진행되므로 일치할 때까지 진행하지 마세요.

참고: 몇 분 후에도 currentPhase가 진행되지 않으면 하이브리드 네임스페이스에서 apigee-controller-manager 포드의 로그를 확인하여 조정 오류를 확인하세요.

경고: apigee-controller-manager 배포에서 apigee.cloud.google.com/cr-phase 주석을 완료 신호로 사용하지 마세요. 이 주석은 원하는 단계를 기록하고 구성요소가 조정되기 전에 helm upgrade를 실행하는 순간을 변경합니다. 이 값을 사용하여 언제 다음 단계로 진행할지 결정하면 너무 일찍 진행하라는 메시지가 표시됩니다. 대신 항상 cert-info ConfigMap에서 currentPhase을 읽으세요.

currentPhase가 일치하면 동일한 ConfigMap에서 적용할 다음 단계를 읽습니다.

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.readyForNextPhase}'

certRotation.phase을 해당 값으로 설정하고 1단계와 2단계를 반복합니다. CLEANUP 단계를 완료할 때까지 계속합니다.

경고: CLEANUP 단계는 되돌릴 수 없습니다. CLEANUP가 완료되면 이전 루트 CA와 발급자가 사라지며 순환을 실행취소할 수 없습니다. CLEANUP를 적용하기 전에 모든 리전에서 HIDE_OLD_CA를 완료했고 API가 정상적으로 제공되는지 확인하세요. 이전 단계에서는 롤백할 수 있지만 CLEANUP에서는 롤백할 수 없습니다.

참고: 모든 리전에서 CLEANUP이 완료되면 순환이 완료됩니다. 향후 업그레이드를 위해 구성을 깔끔하게 유지하려면 재정의 파일에서 certRotation 스탠자를 삭제하세요. 회전이 아직 진행 중인 동안에는 certRotation 스탠자를 삭제하거나 변경하지 마세요. 로테이션이 완료된 후 스탠자를 그대로 두면 나중에 관련 없는 helm upgrade 중에 phase: CLEANUP를 다시 적용해도 아무런 효과가 없으며 정리 작업이 반복되지 않습니다. 각 helm upgrade는 현재, 다음 또는 롤백 단계만 허용하기 때문입니다.

멀티 리전 배포

멀티 리전 배포에서 모든 클러스터에는 자체 cert-info ConfigMap, 자체 운영자, 자체 신뢰 저장소가 있으며 모든 리전은 동일한 새 루트 CA를 신뢰해야 합니다. 이 차트는 apigee-ca-2 보안 비밀이 아직 없는 경우에만 새 루트 CA를 생성하므로 기본 리전에서 새 CA를 한 번 만들고 이를 순환하기 전에 다른 리전에 복사합니다.

다음 순서로 순환을 실행합니다. 리전을 다음 단계로 이동하기 전에 리전에서 currentPhase를 확인합니다 (2단계: 단계가 완료되었는지 확인 참고).

1. 기본 리전에서 CREATE_NEW_CA을 실행합니다. 이 차트는 새 루트 CA를 생성하고 apigee-ca-2 보안 비밀에 저장합니다.
2. 기본 리전의 cert-manager 네임스페이스에서 다른 모든 리전의 cert-manager 네임스페이스로 apigee-ca-2 보안 비밀을 복사합니다. 이후에 해당 리전에서 CREATE_NEW_CA을 실행합니다. 이는 새 리전으로 확장할 때 사용하는 동일한 비밀 복사 패턴입니다. 멀티 리전 배포를 참고하세요.
3. 다른 각 리전에서 한 번에 하나의 리전씩 CREATE_NEW_CA을 실행합니다. apigee-ca-2 보안 비밀이 이미 있으므로 차트에서 새 CA 생성을 건너뛰고 리전을 공유된 CA에 바인딩합니다.
4. 각 리전에서 CREATE_NEW_LEAF을 실행합니다.
5. 각 리전에서 HIDE_OLD_CA을 실행합니다.
6. 각 리전에서 CLEANUP을 실행합니다.
7. 각 지역의 재정의 파일에서 certRotation 스탠자를 삭제하여 구성을 정리합니다.

CREATE_NEW_CA, CREATE_NEW_LEAF, HIDE_OLD_CA를 통해 모든 리전은 이전 루트 CA와 새 루트 CA를 모두 신뢰하므로 이 기간 동안 리전 간 트래픽을 중단하지 않고도 리전이 서로 다른 단계에 있을 수 있습니다.

경고: CLEANUP는 이전 루트 CA를 삭제하므로 예외입니다. 모든 지역에서 HIDE_OLD_CA이 완료될 때까지 어떤 지역에서도 CLEANUP을 실행하지 마세요. 한 리전에서 CLEANUP를 실행하는 반면 다른 리전에서는 이전 CA로 서명된 리프 인증서를 계속 제공하는 경우 정리된 리전에서는 더 이상 해당 트래픽을 신뢰하지 않으므로 리전 간에 즉각적인 통신 실패와 TLS 핸드셰이크 오류가 발생합니다.

자체 CA 사용

차트에서 생성된 루트 CA 대신 자체 루트 CA를 사용하려면 순환을 시작하기 전에 새 CA 보안 비밀을 미리 만드세요. 차트는 대상 보안 비밀이 없는 경우에만 CA를 생성하므로 기존 보안 비밀은 그대로 사용됩니다.

루트 CA 이름은 자유 형식이 아닙니다. Hybrid는 각 CA 세대를 고정된 이름(apigee-ca, apigee-ca-2, apigee-ca-3 등)으로 예상하며 차트는 정확히 해당 이름으로 다음 CA를 찾습니다. 자체 CA를 가져오는 경우 정확히 다음 이름(첫 번째 순환의 경우 apigee-ca-2)으로 보안 비밀을 만들어야 합니다. 차트에서는 다른 이름으로 생성된 CA를 감지하지 않습니다. 현재 보안 비밀 이름과 사용할 다음 이름을 찾으려면 CA 인증서와 이를 지원하는 보안 비밀을 나열합니다.

kubectl get certificate -n cert-manager \
  -o custom-columns=CERTIFICATE:.metadata.name,SECRET:.spec.secretName

클러스터가 어떤 세대에 속하는지 검사하는 다른 방법은 루트 CA 만료 추적을 참고하세요.

1. CREATE_NEW_CA를 실행하기 전에 cert-manager 네임스페이스에서 다음 CA 이름 (첫 번째 순환의 경우 apigee-ca-2)으로 CA 인증서와 비공개 키를 보유하는 보안 비밀을 만듭니다. 보안 비밀은 kubernetes.io/tls 유형이어야 하며 tls.crt, tls.key, ca.crt의 세 키가 포함되어야 합니다. kubectl create secret tls는 ca.crt 키를 설정할 수 없으므로 일반 형식을 사용하세요.

   kubectl create secret generic apigee-ca-2 \
     --namespace cert-manager \
     --type=kubernetes.io/tls \
     --from-file=tls.crt=CERT_FILE \
     --from-file=tls.key=KEY_FILE \
     --from-file=ca.crt=CA_FILE
   

2. 루트 CA 순환에 설명된 대로 순환을 실행합니다. CREATE_NEW_CA 중에 차트에서 apigee-ca-2 보안 비밀번호를 감지하고 CA 생성을 건너뛰고 새 발급자(apigee-ca-issuer-2)를 CA에 바인딩합니다. 다른 모든 단계는 변경되지 않습니다.

자체 CA를 가져오는 경우 수명은 인증서에 포함된 수명이며 차트의 10년 기본값이 아닙니다.

순환 롤백

CLEANUP 이전의 모든 단계는 롤백할 수 있습니다. 롤백하려면 certRotation.phase을 클러스터에서 롤백 타겟으로 보고하는 값으로 설정하고 helm upgrade로 적용합니다. 포워드 단계를 적용하는 것과 정확히 동일합니다.

cert-info ConfigMap에서 롤백 타겟을 읽습니다.

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.readyForRollbackPhase}'

각 단계의 전달 및 롤백 타겟은 다음과 같습니다.

현재 단계	다음 단계	롤백 단계
PHASE_UNSPECIFIED (시작되지 않음)	CREATE_NEW_CA	PHASE_UNSPECIFIED
CREATE_NEW_CA	CREATE_NEW_LEAF	PHASE_UNSPECIFIED
CREATE_NEW_LEAF	HIDE_OLD_CA	CREATE_NEW_CA
HIDE_OLD_CA	CLEANUP	CREATE_NEW_LEAF
CLEANUP	— (회전 완료)	— (없음, 되돌릴 수 없음)

참고: PHASE_UNSPECIFIED은 순환을 시작한 적이 없는 클러스터의 상태입니다. 새로 설치는 여기에서 시작됩니다. 또한 첫 번째 단계의 롤백 타겟이기도 합니다.

경고: CLEANUP에는 롤백 타겟이 없습니다. 완료되면 이전 루트 CA가 영구적으로 삭제됩니다. CLEANUP를 적용하기 전에 모든 지역에서 로테이션이 정상인지 확인합니다.

루트 CA 만료 추적

Apigee Hybrid 순환은 고객이 주도하므로 고객은 루트 CA가 만료되기 전에 순환해야 합니다. apigee-ca 인증서 만료일을 추적하고 모든 리전에서 네 단계를 완료할 시간이 있도록 만료일 전에 순환을 계획하세요.

루트 CA가 만료되는 시점을 확인하려면 cert-manager 네임스페이스에서 CA 인증서를 나열한 다음 현재 사용 중인 생성의 만료일을 읽습니다.

kubectl get certificate -n cert-manager

kubectl get certificate apigee-ca -n cert-manager \
  -o jsonpath='{.status.notAfter}'

첫 번째 명령어는 각 세대의 루트 CA(apigee-ca, apigee-ca-2 등)를 나열합니다. 두 번째는 지정된 인증서의 만료일을 출력합니다. 현재 사용 중인 생성에 대해 실행하세요.

Apigee Hybrid 자동 문제 표시는 ApigeeIssue 리소스로 감지된 클러스터 문제를 보고하며, kubectl get apigeeissues를 사용하여 나열할 수 있습니다. 정기 모니터링의 일환으로 표시된 문제를 확인합니다.

다음 단계

• 인증서와 비밀이 리전 간에 공유되는 방법은 멀티 리전 배포를 참고하세요.
• 인그레스 게이트웨이에서 TLS 및 mTLS 구성을 검토하여 별도의 고객 제공 인그레스 인증서를 이해합니다.
• 자동 문제 표시를 검토하여 감지된 문제가 있는지 클러스터를 모니터링합니다.