Google 관리 SSL 인증서 사용

이 페이지에서는 인그레스를 사용하여 Google 관리 SSL 인증서로 외부 부하 분산기를 만드는 방법을 설명합니다. 이 인증서는 Google에서 도메인 이름을 프로비저닝, 갱신, 관리하는 도메인 유효성 검사(DV) 인증서입니다. 이 인증서에는 개인 또는 조직의 ID가 표시되지 않습니다. Google 관리 인증서를 만드는 방법은 Google 관리 인증서를 참조하세요.

API 버전

GKE 클러스터 버전에 따라 다양한 API 버전에서 제공되는 ManagedCertificate 커스텀 리소스를 사용하여 Google 관리형 SSL 인증서를 구성합니다.

  • ManagedCertificate v1beta2 API는 GKE 클러스터 버전 1.15 이상에서 사용할 수 있습니다.
  • ManagedCertificate v1 API는 GKE 클러스터 버전 1.18.9-gke.801 이상에서 사용할 수 있습니다.

GKE 클러스터는 현재 ManagedCertificate v1beta1 API를 지원하지만 이 API 버전은 지원 중단되었으며 향후 GKE 버전에서 삭제될 예정입니다. 최신 API 버전을 사용하는 것이 좋습니다.

API 버전 간 마이그레이션

최신 API 버전을 지원하는 클러스터에서 ManagedCertificate 리소스가 최신 API 버전으로 자동 승격됩니다. 리소스는 주기적으로 업데이트되므로 리소스를 마이그레이션하기 위해 별도의 조치를 취할 필요가 없습니다.

관리형 인증서로 인그레스 만들기

관리형 SSL 인증서를 구성하고 인그레스에 연결하려면 다음을 수행해야 합니다.

  • ManagedCertificate 객체를 만듭니다.
  • 인그레스에 networking.gke.io/managed-certificates 주석을 추가하여 ManagedCertificate 객체를 인그레스에 연결합니다. 이 주석은 ManagedCertificate 리소스의 쉼표로 구분된 목록입니다(예: cert1,cert2,cert3).

제한사항

Google 관리 인증서는 사용자가 직접 가져오고 관리하는 인증서보다 유연성이 낮습니다. 관리형 인증서는 와일드 카드가 아닌 도메인을 최대 100개까지 지원하고 자체 관리형 인증서는 와일드 카드를 지원할 수 있습니다.

자체 관리 인증서가 필요하거나 인그레스에 구성하려는 SSL 인증서가 이미 있으면 인그레스 문서를 참조하세요.

인그레스가 지원하는 인증서의 개수와 유형은 Google Cloud 관리 SSL 인증서의 한도에 따라 정의됩니다.

Google 관리형 인증서의 업데이트는 지원되지 않습니다.

최소한의 다운타임으로 수동 변경하려면 Google 관리형 인증서 수동 업데이트의 단계를 따르세요.

기본 요건

  • 도메인 이름을 소유하고 있어야 합니다. 도메인 이름은 63자(영문 기준) 이하여야 합니다. Google Domains 또는 다른 등록기관을 이용할 수 있습니다.
  • 예약된(고정) 외부 IP 주소를 만듭니다. 고정 IP 주소를 예약하면 인그레스를 삭제해도 이 주소는 내 소유로 유지됩니다. 주소를 예약하지 않으면 주소가 변경되어 도메인의 DNS 레코드를 다시 구성해야 할 수도 있습니다. gcloud 명령줄 도구 또는 Cloud Console을 사용하여 예약된 IP 주소를 만듭니다.

    gcloud

    예약된 IP 주소를 만들려면 다음 명령어를 실행합니다.

    gcloud compute addresses create address-name --global
    

    여기서 address-name은 만들려는 예약된 IP 주소의 이름입니다.

    만든 고정 IP 주소를 찾으려면 다음 명령어를 실행합니다.

    gcloud compute addresses describe address-name --global
    

    출력은 다음과 비슷합니다.

    address: 203.0.113.32
    ...
    

    Console

    1. Cloud Console에서 고정 주소 예약 페이지로 이동합니다.

      고정 주소 예약 페이지로 이동

    2. 이 IP 주소의 이름을 지정합니다(예시: example-ip-address).
    3. 이 주소가 IPv4 또는 IPv6 주소인지 지정합니다. 다음 예시에서는 IPv4 주소를 사용합니다.
    4. 주소 유형으로 전역 옵션을 선택합니다.
    5. 예약을 클릭하여 IP를 예약합니다.
    6. IP 주소가 외부 주소 열에 나열됩니다.

    구성 커넥터

    참고: 이 단계에는 구성 커넥터가 필요합니다. 설치 안내를 따라 클러스터에 구성 커넥터를 설치합니다.

    apiVersion: compute.cnrm.cloud.google.com/v1beta1
    kind: ComputeAddress
    metadata:
      name: example-ip-address
    spec:
      location: global
    이 매니페스트를 배포하려면 compute-address.yaml로 머신에 다운로드하고 다음을 실행합니다.
    kubectl apply -f compute-address.yaml

관리형 인증서 설정

  1. ManagedCertificate 리소스를 만듭니다. 이 리소스는 SSL 인증서를 만들 대상 도메인을 지정합니다. 와일드 카드 도메인은 지원되지 않습니다.

    다음은 샘플 ManagedCertificate 매니페스트입니다.

    apiVersion: networking.gke.io/v1
    kind: ManagedCertificate
    metadata:
      name: certificate-name
    spec:
      domains:
        - domain-name1
        - domain-name2
    

    각 항목의 의미는 다음과 같습니다.

    • certificate-nameManagedCertificate 리소스의 이름입니다.
    • domain-name1domain-name2는 도메인 이름입니다(예: example.com, mail.example.com, www.example.com).

    매니페스트를 certificate-name.yaml이라는 파일로 저장하고 다음 명령어로 리소스를 만듭니다.

    kubectl apply -f certificate-name.yaml
    
  2. NodePort 서비스를 만들어 애플리케이션을 인터넷에 노출합니다.

    다음은 서비스 매니페스트 파일 예시입니다.

    apiVersion: v1
    kind: Service
    metadata:
      name: service-name
    spec:
      selector:
        key: value
      type: NodePort
      ports:
        - protocol: TCP
          port: 80
          targetPort: 8080
    

    이 예시 사양은 selector를 사용하여 서비스에 포함할 Pod를 선택합니다. 서비스를 구성하는 방법에 대한 자세한 내용은 NodePort 문서를 참조하세요.

    매니페스트를 service-name.yaml이라는 파일로 저장하고 다음 명령어로 서비스를 만듭니다.

    kubectl apply -f service-name.yaml
    
  3. 인그레스를 만들고 앞에서 만든 ManagedCertificate에 연결합니다.

    다음은 샘플 인그레스 매니페스트입니다.

    apiVersion: networking.k8s.io/v1beta1
    kind: Ingress
    metadata:
      name: ingress-name
      annotations:
        kubernetes.io/ingress.global-static-ip-name: address-name
        networking.gke.io/managed-certificates: certificate-name
    spec:
      backend:
        serviceName: service-name
        servicePort: service-port
    

    각 항목의 의미는 다음과 같습니다.

    • ingress-name은 인그레스 객체의 이름입니다.
    • address-name은 예약된 IP 주소의 이름입니다.
    • certificate-name은 인증서의 이름입니다.
    • service-name은 이전 단계에서 만든 서비스의 이름입니다.
    • service-port는 서비스 매니페스트에서 지정한 포트입니다. targetPort가 아닌 port 필드의 값이어야 합니다.

    매니페스트를 ingress-name.yaml이라는 파일로 저장하고 다음 명령어로 인그레스를 만듭니다.

    kubectl apply -f ingress-name.yaml
    
  4. 이전 단계에서 만든 부하 분산기의 IP 주소를 조회합니다. 다음 명령어를 사용하여 부하 분산기의 IP 주소를 가져옵니다.

    kubectl get ingress
    

    출력은 다음과 비슷합니다.

    NAME              HOSTS     ADDRESS         PORTS     AGE
    example-ingress   *         203.0.113.32     80        54s
    

    부하 분산기의 IP 주소가 ADDRESS 열에 나열됩니다. 예약된 고정 IP 주소를 사용할 경우 이 주소는 부하 분산기의 주소입니다.

    주소가 나열되지 않으면 인그레스 설정이 완료되기를 기다립니다.

  5. 부하 분산기의 IP 주소를 가리키도록 도메인의 DNS 레코드를 구성합니다. Cloud DNS를 사용할 경우 자세한 내용은 레코드 관리 가이드를 참조하세요.

  6. 관리형 인증서가 프로비저닝될 때까지 기다립니다. 최대 15분이 걸릴 수 있습니다. 다음 명령어로 인증서의 상태를 확인할 수 있습니다.

    kubectl describe managedcertificate certificate-name
    

    인증서가 성공적으로 프로비저닝되면 Status.CertificateStatus 필드 값이 Active가 됩니다. 다음 예시에서는 인증서가 성공적으로 프로비저닝된 후의 kubectl describe 출력을 보여줍니다.

    Name:         certificate-name
    Namespace:    default
    Labels:       <none>
    Annotations:  <none>
    API Version:  networking.gke.io/v1
    Kind:         ManagedCertificate
    (...)
    Spec:
      Domains:
        domain-name1
        domain-name2
    Status:
      CertificateStatus: Active
    (...)
    
  7. https:// 프리픽스로 도메인에 방문하여 SSL이 작동하는지 확인합니다. 브라우저에 연결이 안전하다고 표시되며 인증서 세부정보를 확인할 수 있습니다.

자가 관리형 인증서에서 Google 관리형 인증서로 이전

자가 관리형 SSL 인증서에서 Google 관리형 SSL 인증서로 인그레스를 이전하는 경우, Google 관리형 SSL 인증서가 활성화되기 전에 자가 관리형 SSL 인증서를 삭제하지 마세요. Google 관리형 SSL 인증서는 성공적으로 프로비저닝된 후 자동으로 활성화됩니다. Google 관리형 SSL 인증서가 활성화되면 자가 관리형 SSL 인증서를 삭제할 수 있습니다.

자체 관리 인증서에서 Google 관리 SSL 인증서로 마이그레이션하려면 다음 안내를 따르세요.

  1. 관리형 인증서 설정 섹션의 설명에 따라 인그레스에 새 관리형 인증서를 추가합니다.
  2. Google 관리 인증서 리소스가 활성 상태가 될 때까지 기다립니다. 다음 명령어로 인증서 상태를 확인합니다.

    kubectl describe managedcertificate certificate-name
    
  3. 활성 상태가 되면 인그레스를 업데이트하여 자체 관리형 인증서에 대한 참조를 삭제합니다.

관리형 인증서 삭제

클러스터에서 관리형 인증서를 삭제하려면 ManagedCertificate 리소스를 삭제하고 해당 리소스를 참조하는 인그레스 주석을 삭제해야 합니다.

  1. kubectl로 ManagedCertificate 리소스를 삭제합니다.

    kubectl delete -f certificate-name.yaml
    

    다음과 같은 출력이 표시됩니다.

    managedcertificate.networking.gke.io "certificate-name" deleted
    
  2. 인그레스에서 주석을 삭제합니다.

    kubectl annotate ingress ingress-name networking.gke.io/managed-certificates-
    

    명령어 끝에 마이너스 기호(-)가 있습니다.

  3. 부하 분산기용으로 예약한 고정 IP 주소를 해제합니다.

    gcloud

    gcloud 명령줄 도구를 사용합니다.

    gcloud compute addresses delete address-name --global
    

    여기서 address-name은 IP 주소의 이름입니다.

    Console

    1. Cloud Console에서 외부 IP 주소 페이지로 이동합니다.

      외부 IP 주소 페이지로 이동

    2. 해제할 IP 주소 옆에 있는 상자를 선택합니다.
    3. IP 주소 해제를 클릭합니다.

    구성 커넥터

    참고: 이 단계에는 구성 커넥터가 필요합니다. 설치 안내를 따라 클러스터에 구성 커넥터를 설치합니다.

    apiVersion: compute.cnrm.cloud.google.com/v1beta1
    kind: ComputeAddress
    metadata:
      name: example-ip-address
    spec:
      location: global

    이 매니페스트를 배포하려면 머신에 compute-address.yaml로 다운로드하고 다음을 실행합니다.

    kubectl delete -f compute-address.yaml

문제 해결

이 섹션에서는 관리형 인증서로 문제를 해결하는 방법에 대한 정보를 제공합니다.

ManagedCertificate 및 인그레스 리소스의 이벤트 확인

허용된 인증서 수를 초과하면 TooManyCertificates 이유가 포함된 이벤트가 ManagedCertificate v1에 추가됩니다. 다음 명령어를 사용하여 ManagedCertificate 객체에서 이벤트를 확인할 수 있습니다.

kubectl describe managedcertificate certificate-name

각 항목의 의미는 다음과 같습니다.

  • certificate-name은 ManagedCertificate 객체의 이름입니다.

존재하지 않는 ManagedCertificate v1을 인그레스에 연결하면 MissingCertificate 이유가 포함된 이벤트가 인그레스에 추가됩니다. 다음 명령어를 사용하여 인그레스 리소스의 이벤트를 확인할 수 있습니다.

kubectl describe ingress ingress-name

각 항목의 의미는 다음과 같습니다.

  • ingress-name은 인그레스 객체의 이름입니다.

도메인이 여러 부하 분산기의 IP 주소로 확인될 경우 관리형 인증서가 프로비저닝되지 않음

도메인이 여러 부하 분산기(여러 인그레스)의 IP 주소로 확인되면 ManagedCertificate 리소스 한 개를 만들고 모든 인그레스에 연결해야 합니다. 대신 여러 ManagedCertificate 리소스를 만들고 개별 인그레스에 각각 연결하면 인증 기관이 도메인의 소유권을 확인하지 못하고 일부 인증서가 프로비저닝되지 않을 수 있습니다. 확인을 성공하려면 도메인이 확인되는 모든 IP 주소 아래에 인증서가 표시되어야 합니다.

특히 도메인이 다른 인그레스 리소스로 구성된 IPv4 및 IPv6 주소로 확인되면 ManagedCertificate 리소스 한 개를 만들고 두 인그레스 모두에 연결해야 합니다.

관리형 인증서와 인그레스 간의 통신 중단

관리형 인증서는 kubernetes.io/pre-shared-cert 주석을 사용하여 인그레스와 통신합니다. 다음 경우에는 이 통신을 중단시킬 수 있습니다.

  • kubernetes.io/pre-shared-cert 주석을 계속 지우는 자동화 프로세스를 실행합니다.
  • 인그레스의 스냅샷을 저장 및 삭제한 후 스냅샷에서 인그레스를 복원합니다. 한편으로는 인그레스의 pre-shared-cert 주석에 나열된 SslCertificate 리소스가 삭제되었을 수 있습니다. 인그레스는 양자택일 시맨틱스를 포함하며 연결된 인증서가 누락되면 작동하지 않습니다.

관리형 인증서를 만들 때 검증 오류

ManagedCertificate 리소스가 생성되기 전에 ManagedCertificate 정의가 검증됩니다. 검증이 실패하면 ManagedCertificate 리소스가 생성되지 않고 오류 메시지가 출력됩니다. 아래에서는 여러 오류 메시지와 원인을 설명합니다.

spec.domains in body should have at most 100 items

ManagedCertificate 매니페스트가 spec.domains 필드에 도메인을 100개 넘게 나열합니다. 관리형 인증서는 도메인을 최대 100개까지만 지원합니다.

spec.domains in body should match '^(([a-zA-Z0-9]+|[a-zA-Z0-9][-a-zA-Z0-9]*[a-zA-Z0-9])\.)+[a-zA-Z][-a-zA-Z0-9]*[a-zA-Z0-9]\.?$'

spec.domains 필드에 지정한 도메인 이름 또는 와일드 카드 도메인 이름이 잘못되었습니다. ManagedCertificate 리소스는 와일드 카드 도메인(예: *.example.com)을 지원하지 않습니다.

spec.domains in body should be at most 63 chars long

지정한 도메인 이름이 너무 깁니다. 관리형 인증서가 지원하는 도메인 이름은 최대 63자입니다.

Google 관리형 인증서 수동 업데이트

새 도메인의 인증서가 프로비저닝될 때까지 이전 도메인의 인증서가 계속 작동하도록 인증서를 수동으로 업데이트하려면 다음 단계를 따르세요.

  1. 새 도메인의 새 관리형 인증서를 만듭니다.
  2. 이전 인증서를 삭제하지 않고 인그레스에 연결합니다.
  3. Active 상태가 될 때까지 기다립니다.
  4. 인그레스에서 이전 인증서를 분리하고 삭제합니다.

다음 단계