Kubernetes 1.22에서 지원 중단된 API

이 페이지에서는 GKE 버전 1.22로 업그레이드하기 위한 클러스터를 준비하는 방법을 설명합니다. 1.22에서 삭제된 지원 중단된 API를 호출하는 API 클라이언트를 찾고 GA API를 사용하도록 해당 클라이언트를 업데이트할 수 있습니다. 자세한 내용은 Kubernetes 지원 중단된 API 마이그레이션 가이드를 참조하세요.

1.22에서 삭제된 API

Kubernetes 버전 1.22에서 대부분의 지원 중단된 API는 Beta(v1beta1)에서 GA(v1)로 전환된 이전의 베타 API들입니다. GA API는 보다 장기적인 호환성 보증을 제공하며, 지원 중단된 베타 API 대신 사용됩니다.

모든 기존 객체는 GA API를 사용하여 상호 작용할 수 있습니다.

웹훅 리소스

MutatingWebhookConfiguration 및 ValidatingWebhookConfiguration의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다.

  • admissionregistration.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

  • GA API 버전의 중요한 변경사항을 보여주는 다음 표를 참조하세요.

    필드 변경
    webhooks[*].failurePolicy 기본값이 Ignore에서 Fail로 변경되었습니다.
    webhooks[*].matchPolicy 기본값이 Exact에서 Equivalent로 변경되었습니다.
    webhooks[*].timeoutSeconds 기본값이 30s에서 10s로 변경되었습니다.
    webhooks[*].sideEffects 기본값이 삭제되었고 이제 이 필드가 필수 항목입니다. None 및 NoneOnDryRun만 허용됩니다.
    webhooks[*].admissionReviewVersions 기본값이 삭제되었고 이제 이 필드가 필수 항목입니다. AdmissionReview에 지원되는 버전은 v1 및 v1beta1입니다.
    webhooks[*].name admissionregistration.k8s.io/v1을 통해 생성된 객체 목록에서 고유해야 합니다.

CustomResourceDefinition

CustomResourceDefinition의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다.

  • apiextensions.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

  • GA API 버전의 중요한 변경사항을 보여주는 다음 표를 참조하세요.

    필드 변경
    spec.scope 더 이상 Namespaced가 기본값이 아닙니다. 값을 명시적으로 지정해야 합니다.
    spec.version 삭제되었습니다. 대신 spec.versions를 사용하세요.
    spec.validation 삭제되었습니다. 대신 spec.versions[*].schema를 사용하세요.
    spec.subresources 삭제되었습니다. 대신 spec.versions[*].subresources를 사용하세요.
    spec.additionalPrinterColumns 삭제되었습니다. 대신 spec.versions[*].additionalPrinterColumns를 사용하세요.
    spec.conversion.webhookClientConfig spec.conversion.webhook.clientConfig로 이동되었습니다.
    spec.conversion.conversionReviewVersions spec.conversion.webhook.conversionReviewVersions로 이동되었습니다.
    spec.versions[*].schema.openAPIV3Schema 이제 v1 CustomResourceDefinition 객체를 만들 때 필수이고 구조적 스키마여야 합니다.
    spec.preserveUnknownFields v1 CustomResourceDefinition 객체를 만들 때 true 값이 허용되지 않습니다. 이 값은 스키마 정의 내에서 x-kubernetes-preserve-unknown-fields: true로 지정되어야 합니다.
    additionalPrinterColumns additionalPrinterColumns 항목에서 JSONPath 필드 이름이 jsonPath로 바뀌었습니다.

APIService

APIService의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다. apiregistration.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

TokenReview

TokenReview의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다. authentication.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

SubjectAccessReview 리소스

LocalSubjectAccessReview, SelfSubjectAccessReview, SubjectAccessReview의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다.

  • authorization.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

  • GA API 버전의 중요한 변경사항을 보여주는 다음 표를 참조하세요.

    필드 변경
    spec.group 이름이 spec.groups로 변경되었습니다.

CertificateSigningRequest

CertificateSigningRequest의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다.

  • certificates.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

  • GA API 버전의 중요한 변경사항을 보여주는 다음 표를 참조하세요.

    필드 변경
    spec.signerName 인증서를 요청하는 API 클라이언트의 경우 이 필드가 필수 항목입니다(알려진 Kubernetes 서명자 참조). kubernetes.io/legacy-unknown에 대한 요청은 certificates.k8s.io/v1 API를 통한 생성이 허용되지 않습니다.
    spec.usages 인증서를 요청하는 API 클라이언트의 경우 이 필드는 필수 항목입니다. 이 필드는 중복된 값을 포함할 수 없으며, 알려진 사용량만 포함해야 합니다.
    status.conditions 인증서를 승인하거나 서명하는 API 클라이언트의 경우 필드는 중복 유형을 포함할 수 없습니다.
    status.conditions[*].status 인증서를 승인하거나 서명하는 API 클라이언트의 경우 이 필드가 이제 필수 항목입니다.
    status.certificate 인증서를 승인하거나 서명하는 API 클라이언트의 경우 이 필드는 PEM으로 인코딩되어야 하며, CERTIFICATE 블록만 포함해야 합니다.

Lease

Lease의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다. coordination.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

인그레스(1.21 이하에서 생성된 클러스터의 경우 1.23까지 사용 가능)

클러스터가 버전 1.22 이상에서 생성된 경우 버전 1.22 이상을 실행하는 GKE 클러스터에 Ingress의 베타 API 버전(extensions/v1beta1 및 networking.k8s.io/v1beta1)이 더 이상 제공되지 않습니다.

그러나 GKE 버전 1.21 이하에서 생성되고 패치 버전 1.22.7-gke.300 이상에서 1.22로 업그레이드된 클러스터의 경우 클러스터가 버전 1.23으로 업그레이드될 때까지 베타 API 버전을 계속 사용할 수 있습니다. 이는 이전 클러스터 버전 1.22의 오픈소스 Kubernetes에서 삭제된 이러한 API 버전의 사용자에게 클러스터를 마이그레이션할 시간을 더 제공하기 위해 이전 클러스터에 적용되는 일회성 예외입니다.

GKE 버전 1.23 이상을 실행하는 모든 클러스터는 지원 중단된 Ingress 베타 API를 더 이상 제공하지 않습니다. 이러한 API 버전을 사용하는 매니페스트는 더 이상 적용할 수 없습니다. 이전의 영구 객체는 1.23으로 업그레이드되기 전후로 계속 작동하며 새 API 버전을 사용하여 보고 업데이트할 수 있습니다.

  • networking.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

  • GA API 버전의 중요한 변경사항을 보여주는 다음 표를 참조하세요.

    필드 변경
    spec.backend 이름이 spec.defaultBackend로 변경되었습니다.
    backend serviceName 이름이 service.name으로 변경되었습니다.
    servicePort 숫자 백엔드 servicePort 필드의 이름이 service.port.number로 변경되었습니다. 문자열 백엔드 servicePort 필드의 이름이 service.port.name으로 변경되었습니다.
    pathType 이제 지정된 각 경로에 대해 필수 항목입니다. 값은 Prefix, Exact, ImplementationSpecific일 수 있습니다. 정의되지 않은 v1beta1 동작과 일치하는 항목을 찾으려면 ImplementationSpecific를 사용합니다.

다음 매니페스트는 v1 및 v1beta1의 동일한 인그레스에 대해 설명합니다.

v1beta1 매니페스트

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: example
spec:
  backend:
    serviceName: default-backend
    servicePort: 80
  rules:
  - http:
      paths:
      - path: /testpath
        backend:
          serviceName: test
          servicePort: 80

v1 매니페스트

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
spec:
  defaultBackend:
    service:
      name: default-backend
      port:
        number: 80
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: ImplementationSpecific
        backend:
          service:
            name: test
            port:
              number: 80

인그레스 v1beta1 API에 액세스하는 클라이언트를 식별하도록 Google Cloud Observability가 사용 설정된 클러스터에 대해 다음 쿼리를 사용할 수 있습니다.

resource.type="k8s_cluster"
resource.labels.cluster_name="$CLUSTER_NAME"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.request.apiVersion=("extensions/v1beta1" OR "networking.k8s.io/v1beta1")
protoPayload.request.kind="Ingress"
NOT ("kube-system")

IngressClass

IngressClass의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다. networking.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

RBAC 리소스

ClusterRole, ClusterRoleBinding, Role, RoleBinding의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다. rbac.authorization.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

PriorityClass

PriorityClass의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다. scheduling.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

스토리지 리소스

CSIDriver, CSINode, StorageClass, VolumeAttachment의 베타 API 버전은 버전 1.22를 기준으로 더 이상 제공되지 않습니다. storage.k8s.io/v1 API 버전을 사용하도록 매니페스트 및 API 클라이언트를 마이그레이션하세요.

지원 중단된 API를 사용하여 클러스터 찾기

지원 중단 통계에서 지원 중단된 API를 사용 중인 클러스터를 찾을 수 있습니다. 지원 중단 통계는 또한 클러스터에서 지원 중단된 API를 호출하는 API 클라이언트와 같은 정보를 제공합니다.

또한 감사 로그를 사용해서 지원 중단된 API를 호출하는 클라이언트를 찾을 수 있습니다.

지원 중단된 API에 쓰기 호출을 수행하는 API 클라이언트 찾기

Google Cloud Observability가 사용 설정된 클러스터의 경우 다음 관리자 활동 감사 로그 쿼리를 사용하여 Google이 관리하지 않는 사용자 에이전트가 사용한 지원 중단된 API를 표시할 수 있습니다.

resource.type="k8s_cluster"
labels."k8s.io/removed-release"="DEPRECATED_API_MINOR_VERSION"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.authenticationInfo.principalEmail!~("system:serviceaccount:kube-system:")

DEPRECATED_API_MINOR_VERSION을 지원 중단된 API가 삭제된 부 버전(예: 1.22)으로 바꿉니다.

관리자 활동 감사 로그는 GKE 클러스터에 대해 자동으로 사용 설정됩니다. 이 쿼리를 사용하면 지원 중단된 API에 쓰기 호출을 수행하는 사용자 에이전트가 표시됩니다.

지원 중단된 API에 읽기 호출을 수행하는 API 클라이언트 찾기

기본적으로 감사 로그는 지원 중단된 API에 대해 쓰기 호출만 표시합니다. 지원 중단된 API에 대해 읽기 호출도 표시하려면 데이터 액세스 감사 로그를 구성합니다.

안내에 따라 Google Cloud 콘솔을 사용하여 데이터 액세스 감사 로그 구성을 수행합니다. Google Cloud 콘솔에서 Kubernetes Engine API를 선택합니다. 정보 패널의 로그 유형 탭에서 Admin Read 및 Data Read를 선택합니다.

이러한 로그가 사용 설정되면 이제 원본 쿼리를 사용해서 지원 중단된 API에 대해 읽기 호출 및 쓰기 호출을 모두 볼 수 있습니다.

타사 구성요소 업그레이드

지원 중단 통계에서는 클러스터에서 지원 중단된 API를 호출하는 서드 파티 에이전트에 대한 결과를 표시할 수 있습니다.

이 통계의 문제를 해결하려면 다음 단계를 따르세요.

  1. 서드 파티 소프트웨어 제공업체에 업데이트된 버전이 있는지 확인합니다.
  2. 서드 파티 소프트웨어를 최신 버전으로 업그레이드합니다. 소프트웨어를 업그레이드할 수 없는 경우 지원 중단되어 삭제된 API를 사용하는 버전으로 GKE를 업그레이드하면 서비스가 손상되는지 테스트해야 합니다.

프로덕션 클러스터를 업그레이드하기 전에 스테이징 클러스터에서 이러한 업그레이드와 GKE 버전 업그레이드를 수행하여 서비스 중단을 모니터링하는 것이 좋습니다.

버전 1.22로 업그레이드 준비

API 객체를 삭제하고 다시 만들 필요가 없습니다. 새 API 버전을 사용하여 기존의 모든 영구 API 객체를 이미 읽고 업데이트할 수 있습니다. 그러나 Kubernetes 1.22로 업그레이드하기 전에 클라이언트와 매니페스트를 마이그레이션하는 것이 좋습니다. Kubernetes 사용 중단된 API 마이그레이션 가이드의 '필요한 조치' 섹션에서 자세히 알아보세요.

지원 중단 통계 및 권장사항을 확인하면 클러스터가 지원 중단된 Kubernetes 기능 또는 API를 사용 중인지 확인할 수 있습니다. 지원 중단 통계는 Kubernetes 객체의 구성이 아닌 지원 중단된 API에 대한 사용자 에이전트의 관찰된 API 호출을 기반으로 합니다.

지원 중단의 영향을 받은 클러스터 업데이트

지원 중단의 영향을 받은 클러스터를 업그레이드하려면 다음 단계를 수행하세요.

  1. 지원 중단 통계 또는 로그에서 지원 중단된 API가 사용자 에이전트에 사용되는지 확인합니다.
  2. 지원 중단된 API를 사용하는 사용자 에이전트를 지원되는 API 버전을 사용하도록 업데이트합니다.
  3. 지원 중단된 API를 호출하는 서드 파티 소프트웨어를 최신 버전으로 업데이트합니다.
  4. 프로덕션 클러스터를 업그레이드하기 전에 테스트 클러스터를 업그레이드하고 테스트 환경에서 애플리케이션을 테스트하여 지원 중단된 API를 더 이상 사용할 수 없게 되면 발생할 수 있는 서비스 중단을 줄입니다.
  5. 모든 사용자 에이전트를 업데이트한 후 GKE는 지원 중단된 API의 사용이 30일 동안 관찰되지 않을 때까지 기다리고 자동 업데이트를 차단 해제합니다. 자동 업그레이드는 출시 일정에 따라 진행됩니다.
  6. 영향을 받은 사용자 에이전트를 업데이트할 수 없는 경우 별도의 테스트 클러스터를 업그레이드하여 업그레이드로 인해 서비스 중단이 발생하는지 확인합니다. 업그레이드로 인해 서비스 중단이 발생하지 않으면 클러스터를 수동으로 업그레이드하면 됩니다.

리소스

자세한 내용은 OSS Kubernetes 설명서에서 확인할 수 있습니다.