이 문서에서는 Certificate Authority Service (CAS)를 사용하여 인증서를 요청하는 단계를 설명합니다.
Google Distributed Cloud (GDC) 에어 갭 내에서 신뢰를 구축하고 통신을 보호하려면 Certificate Authority Service에서 ACME 사용 설정 또는 사용 중지 인증서를 요청하세요.
이 문서는 프로젝트 내에서 인증서 수명 주기를 관리하는 애플리케이션 개발자 또는 데이터 과학자와 같은 애플리케이션 운영자 그룹 내 사용자를 대상으로 합니다. 자세한 내용은 GDC 에어 갭 문서 대상을 참조하세요.
시작하기 전에
인증서를 요청하려면 먼저 필요한 권한을 요청하고 환경을 준비해야 합니다.
IAM 역할 요청
인증서 요청을 만들고, 보고, 삭제하려면 IAM 조직 관리자에게 연락하여 인증 기관의 프로젝트 네임스페이스에서 CA Service 인증서 요청자(certificate-authority-service-certificate-requester) 역할을 부여해 달라고 요청하세요.
개발 환경 준비
kubeconfig 파일을 생성하여
kubectl액세스를 구성합니다.
ACME 모드가 사용 설정된 CA를 사용하여 인증서 요청
인증 기관이 ACME 모드로 호스팅되는 경우 준비가 완료되면 상태에 ACME 서버 URL이 출력됩니다.
Distributed Cloud 환경에서 CA ACME 서버 URL을 수집합니다.
kubectl get certificateauthorities CA_NAME -n USER_PROJECT_NAMESPACE -ojson | jq -r '.status.acme.uri'
다음을 바꿉니다.
CA_NAME: CA 이름(루트 또는 하위 CA일 수 있음)USER_PROJECT_NAMESPACE: 사용자 프로젝트가 있는 네임스페이스의 이름
ACME 모드가 사용 중지된 CA를 사용하여 인증서 요청
ACME 모드가 사용 중지된 인증서 요청을 만들려면 CertificateRequest 리소스를 만들어 Distributed Cloud 에어 갭 적용 인스턴스에 적용해야 합니다. 이 작업을 실행하는 두 가지 방법은 다음과 같습니다.
CertificateResource를 만들고 리소스에 CSR을 포함합니다.- GDC 자동 생성 비공개 키를 사용하여
CertificateResource를 만들고 인증서 구성을 커스텀 값으로 제공합니다.
CSR을 사용하여 인증서 요청
CertificateRequest리소스를 만들고cert-request.yaml이라는 YAML 파일로 저장합니다. 비공개 키를 사용하여 인증서 서명 요청 (CSR)을 만들고 리소스에 추가합니다.필요한 경우
certificateTemplate필드에 템플릿 이름을 입력하여 사전 구성된 X.509 매개변수 집합으로 인증서를 발급할 수 있습니다.apiVersion: pki.security.gdc.goog/v1 kind: CertificateRequest metadata: name: CERT_REQ_NAME namespace: USER_PROJECT_NAMESPACE spec: certificateAuthorityRef: name: CA_NAME namespace: USER_PROJECT_NAMESPACE csr: CSR certificateTemplate: TEMPLATE_NAME signedCertificateSecret: SECRET_NAME notBefore: VALIDITY_START_TIME notAfter: VALIDITY_END_TIME subjectOverride: SUBJECT_OVERRIDE다음 변수를 바꿉니다.
변수 설명 CERT_REQ_NAME CertificateRequest리소스 이름USER_PROJECT_NAMESPACE 사용자 프로젝트가 있는 네임스페이스의 이름 CA_NAME 루트 또는 하위 CA일 수 있는 CA 이름 CSR CA를 사용하여 서명할 인증서 서명 요청 SECRET_NAME 비공개 키와 서명된 CA 인증서가 포함된 Kubernetes 보안 비밀의 이름 다음 선택적 변수를 바꿉니다.
변수 설명 TEMPLATE_NAME 사용하려는 사전 정의된 인증서 템플릿의 이름입니다. 사용 가능한 템플릿 목록과 충돌에 관한 세부정보는 사전 정의된 인증서 템플릿을 참조하세요. VALIDITY_START_TIME 인증서가 유효하다고 간주되는 시간입니다. 이 값은 YYYY-MM-DDTHH:MM:SSZ형식이어야 합니다 (예:2025-10-19T21:45:30Z). 설정하지 않으면 인증서가 발급 즉시 유효합니다.VALIDITY_END_TIME 인증서가 만료되는 시간입니다. 이 값은 YYYY-MM-DDTHH:MM:SSZ형식이어야 합니다 (예:2026-01-17T18:25:40Z). 설정하지 않으면 인증서가 시작 시간으로부터 90일 후에 만료됩니다.SUBJECT_OVERRIDE 발급된 인증서에 사용할 커스텀 주체로, CSR의 주체 정보를 재정의합니다. 이 값을 원시 ASN.1 DER 인코딩 X.509 주체로 제공합니다. Distributed Cloud 인스턴스에 커스텀 리소스를 적용합니다.
kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIGMANAGEMENT_API_SERVER_KUBECONFIG를 Management API 서버의 kubeconfig 파일 경로로 바꿉니다.인증서 요청의 준비 상태를 확인합니다.
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'다음을 바꿉니다.
MANAGEMENT_API_SERVER_KUBECONFIG: Management API 서버의 kubeconfig 파일 경로USER_PROJECT_NAMESPACE: 사용자 프로젝트가 있는 네임스페이스의 이름CERT_REQ_NAME:CertificateRequest리소스 이름
출력은 다음과 비슷합니다.
{ "lastTransitionTime": "2025-01-27T12:22:59Z", "message": "Certificate is issued", "observedGeneration": 1, "reason": "Issued", "status": "True", "type": "Ready" }인증서 보안 비밀 이름을 가져옵니다.
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'다음을 바꿉니다.
MANAGEMENT_API_SERVER_KUBECONFIG: Management API 서버의 kubeconfig 파일 경로USER_PROJECT_NAMESPACE: 사용자 프로젝트가 있는 네임스페이스의 이름CERT_REQ_NAME:CertificateRequest리소스 이름
출력에는 서명된 인증서가 포함된
SECRET_NAME가 표시됩니다.test-jwk-1
자동 생성 키를 사용하여 인증서 요청
CertificateRequest리소스를 만들고cert-request.yaml이라는 YAML 파일로 저장합니다. 인증서에 선택한 값을 입력합니다.필요한 경우
certificateTemplate필드에 템플릿 이름을 입력하여 사전 구성된 X.509 매개변수 집합으로 인증서를 발급할 수 있습니다.apiVersion: pki.security.gdc.goog/v1 kind: CertificateRequest metadata: name: CERT_REQ_NAME namespace: USER_PROJECT_NAMESPACE spec: certificateAuthorityRef: name: CA_NAME namespace: USER_PROJECT_NAMESPACE certificateConfig: subjectConfig: commonName: COMMON_NAME organization: ORGANIZATION locality: LOCALITY state: STATE country: COUNTRY dnsNames: - DNS_NAMES ipAddresses: - IP_ADDRESSES rfc822Names: - RFC822NAMES uris: - URIS certificateTemplate: TEMPLATE_NAME signedCertificateSecret: SECRET_NAME notBefore: VALIDITY_START_TIME notAfter: VALIDITY_END_TIME subjectOverride: SUBJECT_OVERRIDE다음 변수를 바꿉니다.
변수 설명 CERT_REQ_NAME CertificateRequest리소스 이름USER_PROJECT_NAMESPACE 사용자 프로젝트가 있는 네임스페이스의 이름 CA_NAME 루트 또는 하위 CA일 수 있는 CA 이름 SECRET_NAME 비공개 키와 서명된 CA 인증서가 포함된 Kubernetes 보안 비밀의 이름 다음 선택적 변수를 바꿉니다.
CertificateRequest리소스의spec.certificateConfig.subjectConfig블록에서 필드를 하나 이상 포함해야 합니다.변수 설명 COMMON_NAME 인증서의 일반 이름 ORGANIZATION 인증서에 사용할 조직 LOCALITY 인증서의 지역 STATE 인증서에 사용할 주/도 COUNTRY 인증서의 국가 DNS_NAMES 인증서에 설정할 dNSName subjectAltNames목록IP_ADDRESS 인증서에 설정할 ipAddress subjectAltNames목록RFC822_NAMES 인증서에 설정할 rfc822Name subjectAltNames목록URIS 인증서에 설정할 uniformResourceIdentifier subjectAltNames목록TEMPLATE_NAME 사용하려는 사전 정의된 인증서 템플릿의 이름입니다. 사용 가능한 템플릿 목록과 충돌에 관한 세부정보는 사전 정의된 인증서 템플릿을 참조하세요. VALIDITY_START_TIME 인증서가 유효하다고 간주되는 시간입니다. 이 값은 YYYY-MM-DDTHH:MM:SSZ형식이어야 합니다 (예:2025-10-19T21:45:30Z). 설정하지 않으면 인증서가 발급 즉시 유효합니다.VALIDITY_END_TIME 인증서가 만료되는 시간입니다. 이 값은 YYYY-MM-DDTHH:MM:SSZ형식이어야 합니다 (예:2026-01-17T18:25:40Z). 설정하지 않으면 인증서가 시작 시간으로부터 90일 후에 만료됩니다.SUBJECT_OVERRIDE 발급된 인증서에 사용할 커스텀 주체로, CSR의 주체 정보를 재정의합니다. 이 값을 원시 ASN.1 DER 인코딩 X.509 주체로 제공합니다. Distributed Cloud 인스턴스에 커스텀 리소스를 적용합니다.
kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIGMANAGEMENT_API_SERVER_KUBECONFIG를 Management API 서버의 kubeconfig 파일 경로로 바꿉니다.인증서 요청의 준비 상태를 확인합니다.
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'다음을 바꿉니다.
MANAGEMENT_API_SERVER_KUBECONFIG: Management API 서버의 kubeconfig 파일 경로USER_PROJECT_NAMESPACE: 사용자 프로젝트가 있는 네임스페이스의 이름CERT_REQ_NAME:CertificateRequest리소스 이름
출력은 다음과 비슷합니다.
{ "lastTransitionTime": "2025-01-27T12:22:59Z", "message": "Certificate is issued", "observedGeneration": 1, "reason": "Issued", "status": "True", "type": "Ready" }인증서 보안 비밀 이름을 가져옵니다.
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'다음을 바꿉니다.
MANAGEMENT_API_SERVER_KUBECONFIG: Management API 서버의 kubeconfig 파일 경로USER_PROJECT_NAMESPACE: 사용자 프로젝트가 있는 네임스페이스의 이름CERT_REQ_NAME:CertificateRequest리소스의 이름
출력에는 서명된 인증서가 포함된
SECRET_NAME가 표시됩니다.test-jwk-1
인증서 요청 나열
certificaterequests 매개변수를 사용하여 모든 CertificateRequest 리소스를 나열합니다.
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog
다음을 바꿉니다.
MANAGEMENT_API_SERVER_KUBECONFIG: Management API 서버의 kubeconfig 파일 경로USER_PROJECT_NAMESPACE: 사용자 프로젝트가 있는 네임스페이스의 이름
다음은 agtest-project 네임스페이스를 사용하는 명령어 예시입니다.
kubectl --kubeconfig /root/release/root-admin/root-admin-kubeconfig -n agtest-project get certificaterequest.pki.security.gdc.goog
출력은 다음과 비슷합니다.
NAME READY AGE
test-externalca-subca-cert-req-with-csr True 17h
test-externalca-subca-cert-req-with-csr-override True 17h
인증서 삭제
인증서를 삭제하려면 해당 CertificateRequest 커스텀 리소스를 삭제해야 합니다. 이 작업을 수행하면 CAS 데이터베이스에서 리소스가 삭제됩니다.
삭제하려는
CertificateRequest의 이름을 찾습니다. 인증서 요청을 나열하여 이름을 찾을 수 있습니다.CertificateRequest리소스를 삭제합니다.kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE delete certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME다음을 바꿉니다.
MANAGEMENT_API_SERVER_KUBECONFIG: Management API 서버의 kubeconfig 파일 경로USER_PROJECT_NAMESPACE: 사용자 프로젝트가 있는 네임스페이스의 이름CERT_REQ_NAME:CertificateRequest리소스의 이름
인증서 요청 한도 및 삭제
시스템 안정성을 유지하고 리소스 사용량이 많아지는 것을 방지하기 위해 CAS는 CertificateRequest 커스텀 리소스 수에 제한을 적용하고 선택적인 자동 삭제 기능을 제공합니다.
인증서 요청 할당량
CAS는 조직당 CertificateRequest 커스텀 리소스 수에 할당량을 적용하며 기본 한도는 5,000개입니다. 이 한도를 초과하면 CAS 및 Management API 서버 성능이 저하될 수 있습니다.
CertificateRequest 리소스의 총 개수가 할당량에 가까워지면 (예: 한도의 80% 및 90%) 새 요청을 만들 때 명령어 출력에 경고가 표시됩니다. 할당량에 도달한 후 CertificateRequest를 만들려고 하면 요청이 거부됩니다.
다음과 유사한 오류 메시지가 표시될 수 있습니다.
Error from server (Forbidden): error when creating "cert-request.yaml":
admission webhook "certificaterequests.pki.security.gdc.goog" denied the
request: the number of certificate requests has exceeded the per organization
limit of {LIMIT}. Please refer to the guide PLATAUTH-G2102 for troubleshooting
this issue
이 오류가 발생하면 오래되었거나 불필요한 CertificateRequest 리소스를 삭제해야 할 수 있습니다. 할당량을 조정하려면 조직 내 인프라 운영자 그룹 구성원에게 문의하세요. 런북 PLATAUTH-G2102의 안내에 따라 할당량을 재정의할 수 있습니다.
자동 정리
자동 삭제를 사용 설정하여 만료된 CertificateRequest 리소스를 삭제할 수 있습니다. 이 기능은 구성 가능한 유예 기간이 지난 후 리소스를 삭제하여 리소스를 확보하는 데 도움이 됩니다. 유예 기간은 인증서 만료와 CertificateRequest 리소스가 삭제되는 시점 사이의 시간을 정의합니다.
자동 정리는 기본적으로 사용 중지되어 있습니다. 조직 내 인프라 운영자 그룹의 구성원은 런북 PLATAUTH-G2103의 안내에 따라 이 기능을 사용 설정하고 유예 기간을 구성할 수 있습니다. 유예 기간이 설정되지 않았거나 0으로 설정된 경우 이 기능은 사용 중지된 상태로 유지됩니다.