인증서 요청

이 문서에서는 Certificate Authority Service (CAS)를 사용하여 인증서를 요청하는 단계를 설명합니다.

Google Distributed Cloud (GDC) 에어 갭 내에서 신뢰를 구축하고 통신을 보호하려면 Certificate Authority Service에서 ACME 사용 또는 중지된 인증서를 요청하세요.

이 문서는 프로젝트 내에서 인증서 수명 주기를 관리하는 애플리케이션 개발자 또는 데이터 과학자와 같은 애플리케이션 운영자 그룹 내의 사용자를 대상으로 합니다. 자세한 내용은 GDC 에어 갭 문서의 대상을 참고하세요.

시작하기 전에

인증서를 요청하려면 먼저 필요한 권한을 요청하고 환경을 준비해야 합니다.

IAM 역할 요청

인증서 요청을 만들고, 보고, 삭제하려면 조직 IAM 관리자에게 문의하여 인증 기관의 프로젝트 네임스페이스에서 CA 서비스 인증서 요청자(certificate-authority-service-certificate-requester) 역할을 부여해 달라고 요청하세요.

개발 환경 준비

• gdcloud CLI를 아직 다운로드하여 설치하지 않았다면 다운로드하여 설치합니다.

• kubectl CLI를 설치합니다.

• 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 모드가 사용 중지된 인증서 요청을 만들려면 Distributed Cloud 에어 갭 인스턴스에 CertificateRequest 리소스를 만들고 적용해야 합니다. 이 작업을 실행하는 두 가지 방법은 다음과 같습니다.

• CertificateResource를 만들고 리소스에 CSR을 포함합니다.
• GDC 자동 생성 비공개 키를 사용하여 CertificateResource를 만들고 인증서 구성을 커스텀 값으로 제공합니다.

CSR을 사용하여 인증서 요청

1. 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 주체로 제공합니다.

2. Distributed Cloud 인스턴스에 커스텀 리소스를 적용합니다.

   kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG
   

   MANAGEMENT_API_SERVER_KUBECONFIG를 Management API 서버의 kubeconfig 파일 경로로 바꿉니다.

3. 인증서 요청의 준비 상태를 확인합니다.

   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"
   }
   

4. 인증서 보안 비밀 이름을 가져옵니다.

   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
   

자동 생성된 키를 사용하여 인증서 요청

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 주체로 제공합니다.

2. Distributed Cloud 인스턴스에 커스텀 리소스를 적용합니다.

   kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG
   

   MANAGEMENT_API_SERVER_KUBECONFIG를 Management API 서버의 kubeconfig 파일 경로로 바꿉니다.

3. 인증서 요청의 준비 상태를 확인합니다.

   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"
   }
   

4. 인증서 보안 비밀 이름을 가져옵니다.

   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 데이터베이스에서 리소스가 삭제됩니다.

1. 삭제하려는 CertificateRequest의 이름을 찾습니다. 인증서 요청을 나열하여 이름을 찾을 수 있습니다.

2. 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 할당량을 조정하려면 조직 내의 인프라 운영자 그룹의 구성원에게 문의하세요. 이들은 런북 runbook PLATAUTH-G2102의 안내에 따라 할당량을 재정의할 수 있습니다.

자동 정리

자동 정리를 사용 설정하여 만료된 CertificateRequest 리소스를 삭제할 수 있습니다. 이 기능은 구성 가능한 유예 기간이 지난 후 리소스를 삭제하여 리소스를 확보하는 데 도움이 됩니다. 유예 기간은 인증서 만료와 CertificateRequest 리소스가 삭제되는 시점 사이의 기간을 정의합니다.

자동 정리는 기본적으로 사용 중지되어 있습니다. 조직 내의 인프라 운영자 그룹의 구성원은 런북 PLATAUTH-G2103의 안내에 따라 이 기능을 사용 설정하고 유예 기간을 구성할 수 있습니다. 유예 기간이 설정되지 않았거나 0으로 설정된 경우 이 기능은 사용 중지된 상태로 유지됩니다.