이제 VMware용 Anthos 클러스터는 VMware용 Google Distributed Cloud(소프트웨어 전용)입니다. 자세한 내용은 제품 개요를 참조하세요.

VMware 관련 알려진 문제용 Google Distributed Cloud(소프트웨어 전용)

이 페이지에는 VMware용 Google Distributed Cloud의 알려진 모든 문제가 정리되어 있습니다. 이 페이지는 기본 기술 인프라의 수명 주기를 관리하고 서비스 수준 목표(SLO)가 충족되지 않거나 애플리케이션이 실패할 때 알림 및 페이지에 응답하는 IT 관리자 및 운영자를 위해 작성되었습니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할과 예시 태스크에 대한 자세한 내용은 일반 GKE Enterprise 사용자 역할 및 태스크를 참조하세요.

제품 버전이나 카테고리별로 알려진 문제를 필터링하려면 다음 드롭다운 메뉴에서 원하는 필터를 선택하세요.

Google Distributed Cloud 버전을 선택합니다.

문제 카테고리를 선택하세요.

또는 해당 문제를 검색하세요.

카테고리 식별된 버전 문제 및 해결 방법

업데이트

1.28+

번들 인그레스를 사용 중지할 때 프리플라이트 검사가 실패함

클러스터 구성 파일에서 loadBalancer.vips.ingressVIP 필드를 삭제하여 번들 인그레스를 사용 중지하면 MetalLB 프리플라이트 검사의 버그로 인해 클러스터 업데이트가 'invalid user ingress vip: invalid IP' 오류 메시지와 함께 실패합니다.

해결 방법:

이 오류 메시지를 무시하세요.
다음 방법 중 하나를 사용하여 사전 비행 검사를 건너뜁니다.

gkectl update cluster 명령어에 --skip-validation-load-balancer 플래그를 추가합니다.
onpremusercluster 객체에 onprem.cluster.gke.io/server-side-preflight-skip: skip-validation-load-balancer 주석을 추가합니다.

VMware, 업그레이드

1.16

vCenter에 안티어피니티 그룹 규칙이 누락되어 클러스터 업그레이드 실패

클러스터 업그레이드 중에 vCenter에 안티어피니티 그룹(AAG) 규칙이 없으면 머신 객체가 '만들기' 단계에서 중단되고 노드 객체에 연결되지 않을 수 있습니다.

문제가 있는 머신 객체를 설명하면 'DRS 규칙 태스크 'task-xxxx' 재구성 완료'와 같은 메시지가 반복해서 표시될 수 있습니다.

    kubectl --kubeconfig KUBECONFIG describe machine MACHINE_OBJECT_NAME

해결 방법:

관리자 클러스터 구성과 사용자 클러스터 구성에서 모두 안티어피니티 그룹 설정을 사용 중지하고 강제 업데이트 명령어를 트리거하여 클러스터 업그레이드를 차단 해제합니다.

    gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig ADMIN_CLUSTER_KUBECONFIG --force

    gkectl update cluster --config USER_CLUSTER_CONFIG_FILE --kubeconfig USER_CLUSTER_KUBECONFIG --force

마이그레이션

1.29, 1.30

보안 비밀 암호화가 사용 설정된 적이 있는 경우 사용자 클러스터를 Controlplane V2로 마이그레이션할 수 없음

사용자 클러스터를 Controlplane V2로 마이그레이션할 때 상시 가동 보안 비밀 암호화가 사용 설정된 적이 있으면 마이그레이션 프로세스에서 보안 비밀 암호화 키를 제대로 처리하지 못합니다. 이 문제로 인해 새 Controlplane V2 클러스터는 보안 비밀을 복호화할 수 없습니다. 다음 명령어의 출력이 비어 있지 않으면 상시 보안 비밀 암호화가 특정 시점에 사용 설정되었으며 클러스터가 이 문제의 영향을 받는 것입니다.

    kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
      get onpremusercluster USER_CLUSTER_NAME \
      -n USER_CLUSTER_NAME-gke-onprem-mgmt \
      -o jsonpath={.spec.secretsEncryption}

이미 마이그레이션을 시작했지만 마이그레이션이 실패한 경우 Google에 문의하여 지원을 받으세요. 그렇지 않으면 마이그레이션 하기 전에 상시 보안 비밀 암호화를 사용 중지하고 보안 비밀을 복호화합니다.

마이그레이션

1.29.0-1.29.600, 1.30.0-1.30.100

보안 비밀 암호화가 사용 설정된 경우 비HA에서 HA로 관리자 클러스터 마이그레이션이 실패함

관리자 클러스터가 1.14 이하에서 상시 보안 비밀 암호화를 사용 설정하고 이전 버전에서 영향을 받는 1.29 및 1.30 버전으로 업그레이드한 경우 관리자 클러스터를 비HA에서 HA로 마이그레이션할 때 이전 프로세스가 보안 비밀 암호화 키를 제대로 처리하지 못하며 이 문제로 인해 새 HA 관리 클러스터에서 보안 비밀을 복호화할 수 없습니다.

클러스터에서 이전 형식의 키를 사용할 수 있는지 확인하려면 다음 단계를 따르세요.

    kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secret -n kube-system admin-master-component-options -o jsonpath='{.data.data}' | base64 -d | grep -oP '"GeneratedKeys":\[.*?\]'

출력에 다음과 같이 빈 키가 표시되면 클러스터가 이 문제의 영향을 받는다는 뜻입니다.

    "GeneratedKeys":[{"KeyVersion":"1","Key":""}]

이미 마이그레이션을 시작했지만 마이그레이션이 실패한 경우 Google에 문의하여 지원을 받으세요.

그렇지 않으면 마이그레이션을 시작하기 전에 암호화 키를 순환하세요.

업그레이드

1.16, 1.28, 1.29, 1.30

관리 워크스테이션 업그레이드 중에 `credential.yaml`이 잘못 재생성됨

gkeadm upgrade admin-workstation 명령어를 사용하여 관리자 워크스테이션을 업그레이드하면 credential.yaml 파일이 잘못 재생성됩니다. 사용자 이름 및 비밀번호 입력란이 비어 있습니다. 또한 privateRegistry 키에 오타가 있습니다.

privateRegistry 키의 동일한 오타 문제가 admin-cluster.yaml 파일에도 있습니다.
credential.yaml 파일은 관리자 클러스터 업그레이드 프로세스 중에 다시 생성되므로 이전에 수정한 경우에도 오타가 존재합니다.

해결 방법:

admin-cluster.yaml의 privateRegistry.credentials.fileRef.entry와 일치하도록 credential.yaml의 비공개 레지스트리 키 이름을 업데이트합니다.
credential.yaml에서 비공개 레지스트리 사용자 이름과 비밀번호를 업데이트합니다.

업그레이드

1.16, 1.28

업그레이드 전 조정 제한 시간으로 인해 사용자 클러스터 업그레이드 실패

사용자 클러스터를 업그레이드할 때 업그레이드 전 조정 작업이 정의된 제한 시간보다 오래 걸릴 수 있으며, 이로 인해 업그레이드가 실패할 수 있습니다. 오류 메시지는 다음과 같이 표시됩니다.

Failed to reconcile the user cluster before upgrade: the pre-upgrade reconcile failed, error message:
failed to wait for reconcile to complete: error: timed out waiting for the condition,
message: Cluster reconcile hasn't finished yet, please fix that before
rerun the upgrade.

업그레이드 전 조정 작업의 제한 시간은 사용자 클러스터의 노드 풀당 5분에 1분을 더한 값입니다.

해결 방법:

gkectl diagnose cluster 명령어가 오류 없이 전달되는지 확인합니다.
gkectl upgrade cluster 명령어에 --skip-reconcile-before-preflight 플래그를 추가하여 업그레이드 전 조정 작업을 건너뜁니다. 예를 들면 다음과 같습니다.

gkectl upgrade cluster --skip-reconcile-before-preflight --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
--config USER_CLUSTER_CONFIG_FILE

업데이트

1.16, 1.28.0-1.28.800, 1.29.0-1.29.400, 1.30.0

DataplaneV2 ForwardMode를 업데이트해도 anetd DaemonSet 재시작이 자동으로 트리거되지 않음

gkectl update cluster를 사용하여 사용자 클러스터 dataplaneV2.forwardMode 필드를 업데이트하면 변경사항은 ConfigMap에서만 업데이트되고 anetd DaemonSet은 다시 시작될 때까지 구성 변경사항을 선택하지 않으며 변경사항이 적용되지 않습니다.

해결 방법:

gkectl update cluster 명령어가 완료되면 Done updating the user cluster 출력이 표시됩니다. 이 메시지가 표시되면 다음 명령어를 실행하여 anetd DaemonSet를 다시 시작하여 구성 변경사항을 가져옵니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG rollout restart daemonset anetd

다시 시작 후 DaemonSet 준비 상태를 확인합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get daemonset anetd

위 명령어의 출력에서 DESIRED 열의 숫자가 READY 열의 숫자와 일치하는지 확인합니다.

업그레이드

1.16

관리자 클러스터 백업 단계에서 클러스터 업그레이드 중에 etcdctl 명령어를 찾을 수 없음

1.16에서 1.28로 사용자 클러스터를 업그레이드하는 동안 관리자 클러스터가 백업됩니다. 관리자 클러스터 백업 프로세스에 'etcdctl: command not found' 오류 메시지가 표시됩니다. 사용자 클러스터 업그레이드가 성공하고 관리자 클러스터는 정상 상태로 유지됩니다. 유일한 문제는 관리자 클러스터의 메타데이터 파일이 백업되지 않는다는 점입니다.

이 문제의 원인은 etcdctl 바이너리가 1.28에서 추가되었으며 1.16 노드에서는 사용할 수 없기 때문입니다.

관리자 클러스터 백업에는 etcd 스냅샷을 만든 후 관리자 클러스터에 대한 메타데이터 파일을 작성하는 등 여러 단계가 포함됩니다. etcd 포드로 실행한 후에도 etcdctl이 계속 트리거될 수 있으므로 etcd 백업이 계속 성공합니다. 하지만 여전히 노드에 설치된 etcdctl 바이너리를 사용하므로 메타데이터 파일을 작성할 수 없습니다. 그러나 메타데이터 파일 백업은 백업을 차단하지 않으므로 사용자 클러스터 업그레이드와 마찬가지로 백업 프로세스가 계속 성공적으로 실행됩니다.

해결 방법:

메타데이터 파일의 백업을 수행하려면 gkectl로 관리자 클러스터 백업 및 복원에 따라 관리자 클러스터 버전과 일치하는 gkectl 버전을 사용하여 별도의 관리자 클러스터 백업을 트리거합니다.

설치

1.16-1.29

수동 부하 분산으로 사용자 클러스터 생성 실패

수동 부하 분산으로 구성된 사용자 클러스터를 만들 때 번들 인그레스가 사용 중지된 경우에도 ingressHTTPNodePort 값이 30,000 이상이어야 함을 나타내는 gkectl check-config 오류가 발생합니다.

이 문제는 ingressHTTPNodePort 및 ingressHTTPSNodePort 필드가 설정되었는지 여부와 관계없이 발생합니다.

해결 방법:

이 문제를 해결하려면 gkectl check-config에서 반환된 결과를 무시합니다. 번들 인그레스를 사용 중지하려면 번들 인그레스 사용 중지를 참고하세요.

업데이트

1.29.0

사용자 클러스터를 Controlplane V2로 마이그레이션한 후 관리자 클러스터 metrics-server PDB가 잘못 구성될 수 있음

PodDisruptionBudget(PDB) 문제는 고가용성(HA) 관리자 클러스터를 사용하고 마이그레이션 후 역할이 없는 관리자 클러스터 노드가 0개 또는 1개 있는 경우에 발생합니다. 역할이 없는 노드 객체가 있는지 확인하려면 다음 명령어를 실행합니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get nodes -o wide

마이그레이션 후 역할이 없는 노드 객체가 2개 이상 있는 경우 PDB가 잘못 구성되지 않은 것입니다.

증상

admin cluster diagnose의 출력에는 다음 정보가 포함됩니다.

Checking all poddisruptionbudgets...FAILURE
  Reason: 1 pod disruption budget error(s).
  Unhealthy Resources:
  PodDisruptionBudget metrics-server: gke-managed-metrics-server/metrics-server might be configured incorrectly: the total replicas(1) should be larger than spec.MinAvailable(1).

해결 방법:

다음 명령어를 실행하여 PDB를 삭제합니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG delete pdb metrics-server -n gke-managed-metrics-server

설치, 업그레이드 및 업데이트

1.28.0-1.28.600,1.29.0-1.29.100

Binary Authorization 웹훅에서 CNI 플러그인이 시작되어 노드 풀 중 하나가 표시되지 않음

드물게 경합 상태에서 Binary Authorization 웹훅 및 gke-connect 포드의 잘못된 설치 시퀀스로 인해 노드가 준비 상태에 도달하지 못해 사용자 클러스터 생성이 중단될 수 있습니다. 영향을 받는 시나리오에서는 노드가 준비 상태에 도달하지 못해 사용자 클러스터 생성이 중단될 수 있습니다. 이 경우 다음 메시지가 표시됩니다.

     Node pool is not ready: ready condition is not true: CreateOrUpdateNodePool: 2/3 replicas are ready

해결 방법:

구성 파일에서 Binary Authorization 구성을 삭제합니다. 설정 안내는 VMware 기반 GKE용 Binary Authorization 2일 차 설치 가이드를 참조하세요.

현재 클러스터 생성 프로세스 중에 비정상 노드를 차단 해제하려면 다음 명령어를 사용하여 사용자 클러스터에서 Binary Authorization 웹훅 구성을 일시적으로 삭제합니다.

        kubectl --kubeconfig USER_KUBECONFIG delete ValidatingWebhookConfiguration binauthz-validating-webhook-configuration

부트스트랩 프로세스가 완료되면 다음 웹훅 구성을 다시 추가할 수 있습니다.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: binauthz-validating-webhook-configuration
webhooks:
- name: "binaryauthorization.googleapis.com"
  namespaceSelector:
    matchExpressions:
    - key: control-plane
      operator: DoesNotExist
  objectSelector:
    matchExpressions:
    - key: "image-policy.k8s.io/break-glass"
      operator: NotIn
      values: ["true"]
  rules:
  - apiGroups:
    - ""
    apiVersions:
    - v1
    operations:
    - CREATE
    - UPDATE
    resources:
    - pods
    - pods/ephemeralcontainers
  admissionReviewVersions:
  - "v1beta1"
  clientConfig:
    service:
      name: binauthz
      namespace: binauthz-system
      path: /binauthz
    # CA Bundle will be updated by the cert rotator.
    caBundle: Cg==
  timeoutSeconds: 10
  # Fail Open
  failurePolicy: "Ignore"
  sideEffects: None

업그레이드

1.16, 1.28, 1.29

`deletionTimestamp`가 있는 미러링된 머신으로 인해 CPV2 사용자 클러스터 업그레이드가 중단됨

사용자 클러스터를 업그레이드하는 동안 사용자 클러스터의 미러링된 머신 객체에 deletionTimestamp가 포함된 경우 업그레이드 작업이 중단될 수 있습니다. 업그레이드가 중단된 경우 다음과 같은 오류 메시지가 표시됩니다.

    machine is still in the process of being drained and subsequently removed

이 문제는 이전에 사용자 클러스터에서 미러링된 머신에 대해 gkectl delete machine을 실행하여 사용자 컨트롤 플레인 노드를 복구하려고 시도한 경우 발생할 수 있습니다.

해결 방법:

미러링된 머신 객체를 가져와 백업용으로 로컬 파일에 저장합니다.

다음 명령어를 실행하여 미러링된 머신에서 파이널라이저를 삭제하고 사용자 클러스터에서 삭제될 때까지 기다립니다.

    kubectl --kubeconfig ADMIN_KUBECONFIG patch machine/MACHINE_OBJECT_NAME -n USER_CLUSTER_NAME-gke-onprem-mgmt -p '{"metadata":{"finalizers":[]}}' --type=merge

Controlplane V2 사용자 클러스터 컨트롤 플레인 노드의 단계에 따라 컨트롤 플레인 노드에서 노드 복구를 트리거하여 올바른 소스 머신 사양이 사용자 클러스터에 다시 동기화되도록 하세요.
gkectl upgrade cluster를 다시 실행하여 업그레이드를 재개하세요.

구성, 설치

1.15, 1.16, 1.28, 1.29

다른 서브넷의 컨트롤 플레인 VIP로 인해 클러스터 생성 실패

HA 관리자 클러스터 또는 ControlPlane V2 사용자 클러스터의 경우 컨트롤 플레인 VIP가 다른 클러스터 노드와 동일한 서브넷에 있어야 합니다. 그렇지 않으면 kubelet이 컨트롤 플레인 VIP를 사용하여 API 서버와 통신할 수 없기 때문에 클러스터 생성에 실패합니다.

해결 방법:

클러스터를 만들기 전에 컨트롤 플레인 VIP가 다른 클러스터 노드와 동일한 서브넷에 구성되어 있는지 확인합니다.

설치, 업그레이드, 업데이트

1.29.0 - 1.29.100

FQDN이 아닌 vCenter 사용자 이름으로 인한 클러스터 생성/업그레이드 실패

vsphere CSI 포드에서 vCenter 사용자 이름이 잘못되었음을 나타내는 오류와 함께 클러스터 만들기/업그레이드가 실패합니다. 사용된 사용자 이름이 정규화된 도메인 이름이 아니기 때문입니다. vsphere-csi-controller 포드에 다음과 같은 오류 메시지가 표시됩니다.

    GetCnsconfig failed with err: username is invalid, make sure it is a fully qualified domain username

이 문제는 버전 1.29 이상에서만 발생합니다. 정규화된 도메인 사용자 이름을 사용하도록 하는 유효성 검사가 vSphere CSI 드라이버에 추가되었기 때문입니다.

해결 방법:

사용자 인증 정보 구성 파일에서 vCenter 사용자 이름에 정규화된 도메인 이름을 사용합니다. 예를 들어 '사용자이름1' 대신 '사용자이름1@example.com'을 사용합니다.

업그레이드, 업데이트

1.28.0 - 1.28.500

버전 1.10 이하에서 만든 클러스터의 경우 관리자 클러스터 업그레이드가 실패합니다.

관리자 클러스터를 1.16에서 1.28로 업그레이드할 때 새 관리자 마스터 머신의 부트스트랩에서 컨트롤 플레인 인증서를 생성하지 못할 수 있습니다. 이 문제는 버전 1.28 이상에서 Kubernetes API 서버에 대한 인증서가 생성되는 방식이 변경되어 발생합니다. 이 문제는 버전 1.10 이하에서 만든 클러스터가 1.16으로 모두 업그레이드되었고 업그레이드 전에 리프 인증서를 로테이션하지 않은 경우에 재현됩니다.

이 문제로 인해 관리자 클러스터 업그레이드 실패가 발생했는지 확인하려면 다음 단계를 수행합니다.

SSH를 사용하여 장애가 발생한 관리자 마스터 머신에 연결합니다.
/var/log/startup.log를 열고, 다음과 같은 오류를 검색합니다.

Error adding extensions from section apiserver_ext
801B3213B57F0000:error:1100007B:X509 V3 routines:v2i_AUTHORITY_KEYID:unable to get issuer keyid:../crypto/x509/v3_akid.c:177:
801B3213B57F0000:error:11000080:X509 V3 routines:X509V3_EXT_nconf_int:error in extension:../crypto/x509/v3_conf.c:48:section=apiserver_ext, name=authorityKeyIdentifier, value=keyid>

해결 방법:

SSH를 사용하여 관리자 마스터 머신에 연결합니다. 자세한 내용은 SSH를 사용하여 관리자 클러스터 노드에 연결하기를 참조하세요.
/etc/startup/pki-yaml.sh 사본을 만들고 이름을 /etc/startup/pki-yaml-copy.sh로 지정합니다.
/etc/startup/pki-yaml-copy.sh을 수정합니다. authorityKeyIdentifier=keyidset를 찾아 apiserver_ext, client_ext, etcd_server_ext, kubelet_server_ext 확장자 섹션에서 authorityKeyIdentifier=keyid,issuer로 변경합니다. 예를 들어 다음과 같습니다.
```
      [ apiserver_ext ]
      keyUsage = critical, digitalSignature, keyEncipherment
      extendedKeyUsage=serverAuth
      basicConstraints = critical,CA:false
      authorityKeyIdentifier = keyid,issuer
      subjectAltName = @apiserver_alt_names
```
/etc/startup/pki-yaml-copy.sh에 변경사항을 저장합니다.
텍스트 편집기를 사용하여 /opt/bin/master.sh를 열고 /etc/startup/pki-yaml.sh의 모든 항목을 찾아 /etc/startup/pki-yaml-copy.sh로 바꾼 후 변경사항을 저장합니다.
/opt/bin/master.sh를 실행하여 인증서를 생성하고 머신 시작을 완료합니다.
gkectl upgrade admin을 다시 실행하여 관리자 클러스터를 업그레이드합니다.
업그레이드가 완료되면 로테이션 시작에 설명된 대로 관리자 및 사용자 클러스터 모두에 대해 리프 인증서를 로테이션합니다.
인증서 로테이션이 완료되면 이전에 했던 것과 동일하게 /etc/startup/pki-yaml-copy.sh를 편집하고 /opt/bin/master.sh를 실행합니다.

구성

1.29.0

Dataplane V2가 사용 설정된 클러스터에 대한 잘못된 경고 메시지

gkectl을 실행하여 Dataplane V2가 이미 사용 설정된 클러스터를 생성, 업데이트 또는 업그레이드하면 다음 잘못된 경고 메시지가 출력됩니다.

WARNING: Your user cluster is currently running our original architecture with 
[DataPlaneV1(calico)]. To enable new and advanced features we strongly recommend
to update it to the newer architecture with [DataPlaneV2] once our migration 
tool is available.

gkectl에 있는 버그로 인해 클러스터 구성 파일에 이미 enableDataplaneV2: true를 설정했더라도 dataplaneV2.forwardMode가 사용되지 않는 한 항상 이 경고가 표시됩니다.

해결 방법:

이 경고는 무시해도 됩니다.

구성

1.28.0-1.28.400, 1.29.0

HA 관리자 클러스터 설치 프리플라이트 검사에서 잘못된 고정 IP 수를 보고함

HA 관리자 클러스터를 만들 때 프리플라이트 검사에 다음과 같은 잘못된 오류 메시지가 표시됩니다.

- Validation Category: Network Configuration
    - [FAILURE] CIDR, VIP and static IP (availability and overlapping): needed
    at least X+1 IP addresses for admin cluster with X nodes

1.28 이상의 HA 관리자 클러스터에는 더 이상 부가기능 노드가 없으므로 요구사항이 잘못되었습니다. 또한, 3개의 관리자 클러스터 컨트롤 플레인 노드 IP는 관리자 클러스터 구성 파일의 network.controlPlaneIPBlock 섹션에 지정되어 있으므로, IP 블록 파일의 IP는 kubeception 사용자 클러스터 컨트롤 플레인 노드에만 필요합니다.

해결 방법:

수정되지 않은 릴리스에서 잘못된 비행 전 검사를 건너뛰려면 gkectl 명령어에 --skip-validation-net-config를 추가하세요.

작업

1.29.0-1.29.100

HA가 아닌 관리자 클러스터로 마이그레이션한 후 Connect Agent에서 Google Cloud와의 연결이 끊어짐

HA가 아닌 관리자 클러스터에서 HA 관리자 클러스터로 마이그레이션한 경우, 관리자 클러스터의 연결 에이전트는 "JWT 서명 확인 실패" 오류와 함께 gkeconnect.googleapis.com에 대한 연결이 끊어집니다. 마이그레이션하는 동안 KSA 서명 키가 변경되므로 OIDC JWK를 새로 고치려면 다시 등록해야 하기 때문입니다.

해결 방법:

관리자 클러스터를 Google Cloud에 다시 연결하려면 다음 단계에 따라 재등록을 트리거하세요.

먼저 gke-connect 배포 이름을 가져옵니다.

kubectl --kubeconfig KUBECONFIG get deployment -n gke-connect

gke-connect 배포를 삭제합니다.

kubectl --kubeconfig KUBECONFIG delete deployment GKE_CONNECT_DEPLOYMENT -n gke-connect

onpremadmincluster CR에 "강제 재조정" 주석을 추가하여 onprem-admin-cluster-controller에 대한 강제 재조정을 트리거합니다.

kubectl --kubeconfig KUBECONFIG patch onpremadmincluster ADMIN_CLUSTER_NAME -n kube-system --type merge -p '
metadata:
  annotations:
    onprem.cluster.gke.io/force-reconcile: "true"
'

이는 사용 가능한 기존 gke-connect 배포가 없는 경우 onprem-admin-cluster-controller는 항상 gke-connect 배포를 다시 배포하고 클러스터를 다시 등록한다는 개념입니다.

해결 방법(컨트롤러가 조정을 완료하는 데 몇 분 정도 걸릴 수 있음)을 수행한 후 gke-connect-agent 로그에서 "JWT 서명 확인 실패" 400 오류가 사라진 것을 확인할 수 있습니다.

kubectl --kubeconfig KUBECONFIG logs GKE_CONNECT_POD_NAME -n gke-connect

설치, 운영체제

1.28.0-1.28.500, 1.29.0

Docker 브리지 IP가 COS 클러스터 컨트롤 플레인 노드에 172.17.0.1/16을 사용

Google Distributed Cloud는 기본 172.17.0.1/16 서브넷을 예약하지 않도록 Docker 구성에서 Docker 브리지 IP에 전용 서브넷인 --bip=169.254.123.1/24를 지정합니다. 하지만 버전 1.28.0~1.28.500 및 1.29.0에서 COS OS 이미지의 회귀로 인해 Google Distributed Cloud가 Docker 구성을 맞춤설정한 후 Docker 서비스가 다시 시작되지 않았습니다. 따라서 Docker는 기본 172.17.0.1/16을 브리지 IP 주소 서브넷으로 선택합니다. 이 IP 주소 범위 내에서 이미 실행 중인 워크로드가 있는 경우 IP 주소 충돌이 발생할 수 있습니다.

해결 방법:

이 문제를 해결하려면 Docker 서비스를 다시 시작해야 합니다.

sudo systemctl restart docker

Docker가 올바른 브리지 IP 주소를 선택하는지 확인합니다.

ip a | grep docker0

이 솔루션은 VM 재생성 시 유지되지 않습니다. VM을 다시 만들 때마다 이 해결 방법을 다시 적용해야 합니다.

update

1.28.0-1.28.400, 1.29.0-1.29.100

표준 CNI에서 다중 네트워크 인터페이스를 사용할 수 없음

표준 CNI 바이너리 bridge, ipvlan, vlan, macvlan, dhcp, tuning, host-local, ptp, portmap는 영향을 받는 버전의 OS 이미지에 포함되어 있지 않습니다. 이러한 CNI 바이너리는 데이터 영역 v2에서 사용되지 않지만 다중 네트워크 인터페이스 기능의 추가 네트워크 인터페이스에 사용될 수 있습니다.

이러한 CNI 플러그인을 사용하는 다중 네트워크 인터페이스는 작동하지 않습니다.

해결 방법:

이 기능을 사용하는 경우 수정사항이 있는 버전으로 업그레이드합니다.

update

1.15, 1.16, 1.28

Netapp trident 종속 항목이 vSphere CSI 드라이버를 방해함

클러스터 노드에 multipathd를 설치하면 vSphere CSI 드라이버를 방해하여 사용자 워크로드를 시작할 수 없게 됩니다.

해결 방법:

multipathd 사용 중지

업데이트

1.15, 1.16

필수 구성을 추가할 때 관리자 클러스터 웹훅에서 업데이트를 차단할 수 있음

검증을 건너뛰어 관리자 클러스터에서 일부 필수 구성이 비어 있는 경우 관리자 클러스터 웹훅에서 필수 구성을 추가하지 못하도록 할 수도 있습니다. 예를 들어 기존 관리자 클러스터에 gkeConnect 필드가 설정되지 않은 경우 gkectl update admin 명령어로 추가하면 다음 오류 메시지가 표시될 수 있습니다.

admission webhook "vonpremadmincluster.onprem.cluster.gke.io" denied the request: connect: Required value: GKE connect is required for user clusters

해결 방법:

1.15 관리자 클러스터의 경우 --disable-admin-cluster-webhook 플래그와 함께 gkectl update admin 명령어를 실행합니다. 예를 들면 다음과 같습니다.
```
        gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig ADMIN_CLUSTER_KUBECONFIG --disable-admin-cluster-webhook
        
```
1.16 관리자 클러스터의 경우 --force 플래그와 함께 gkectl update admin 명령어를 실행합니다. 예를 들면 다음과 같습니다.
```
        gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig ADMIN_CLUSTER_KUBECONFIG --force
        
```

구성

1.15.0-1.15.10, 1.16.0-1.16.6, 1.28.0-1.28.200

`manualLB` 사양이 비어 있는 경우 `controlPlaneNodePort` 필드의 기본값은 30968임

수동 부하 분산기(loadBalancer.kind가 "ManualLB"로 설정됨)를 사용할 경우 버전 1.16 이상에서 고가용성(HA) 관리자 클러스터에 대해 구성 파일에서 loadBalancer.manualLB 섹션을 구성하지 않아도 됩니다. 그러나 이 섹션이 비어 있으면 Google Distributed Cloud는 manualLB.controlPlaneNodePort를 포함한 모든 노드 포트에 기본값을 할당하므로 다음 오류 메시지와 함께 클러스터 생성에 실패합니다.

- Validation Category: Manual LB
  - [FAILURE] NodePort configuration: manualLB.controlPlaneNodePort must
   not be set when using HA admin cluster, got: 30968

해결 방법:

HA 관리자 클러스터의 관리자 클러스터 구성에서 manualLB.controlPlaneNodePort: 0을 지정합니다.

loadBalancer:
  ...
  kind: ManualLB
  manualLB:
    controlPlaneNodePort: 0
  ...

스토리지

1.28.0-1.28.100

Ubuntu OS 이미지에서 nfs-common이 누락됨

Ubuntu OS 이미지에 nfs-common이 누락되어 NetApp과 같은 NFS 종속 드라이버를 사용하는 고객에게 문제가 발생할 수 있습니다.

1.28로 업그레이드한 후 로그에 다음과 같은 항목이 포함되었으면 이 문제의 영향을 받는 것입니다.

Warning FailedMount 63s (x8 over 2m28s) kubelet MountVolume.SetUp failed for volume "pvc-xxx-yyy-zzz" : rpc error: code = Internal desc = error mounting NFS volume 10.0.0.2:/trident_pvc_xxx-yyy-zzz on mountpoint /var/lib/kubelet/pods/aaa-bbb-ccc/volumes/kubernetes.io~csi/pvc-xxx-yyy-zzz/mount: exit status 32".

해결 방법:

노드가 Canonical에서 패키지를 다운로드할 수 있는지 확인합니다.

다음으로 클러스터에 다음 DaemonSet을 적용하여 nfs-common을 설치합니다.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: install-nfs-common
  labels:
    name: install-nfs-common
  namespace: kube-system
spec:
  selector:
    matchLabels:
      name: install-nfs-common
  minReadySeconds: 0
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 100%
  template:
    metadata:
      labels:
        name: install-nfs-common
    spec:
      hostPID: true
      hostIPC: true
      hostNetwork: true
      initContainers:
      - name: install-nfs-common
        image: ubuntu
        imagePullPolicy: IfNotPresent
        securityContext:
          privileged: true
        command:
        - chroot
        - /host
        - bash
        - -c
        args:
        - |
          apt install -y nfs-common
        volumeMounts:
        - name: host
          mountPath: /host
      containers:
      - name: pause
        image: gcr.io/gke-on-prem-release/pause-amd64:3.1-gke.5
        imagePullPolicy: IfNotPresent
      volumes:
      - name: host
        hostPath:
          path: /

스토리지

1.28.0-1.28.100

관리자 클러스터 구성 템플릿에서 스토리지 정책 필드가 누락됨

관리자 클러스터의 SPBM은 1.28.0 이상 버전에서 지원됩니다. 하지만 구성 파일 템플릿에 vCenter.storagePolicyName 필드가 누락되었습니다.

해결 방법:

관리자 클러스터의 스토리지 정책을 구성하려면 관리자 클러스터 구성 파일에 `vCenter.storagePolicyName` 필드를 추가합니다. 안내를 참조하세요.

로깅 및 모니터링

1.28.0-1.28.100

Kubernetes Metadata API가 VPC-SC를 지원하지 않음

최근에 추가된 API kubernetesmetadata.googleapis.com은 VPC-SC를 지원하지 않습니다. 이로 인해 메타데이터 수집 에이전트가 VPC-SC의 이 API에 도달하지 못합니다. 이후에는 측정항목 메타데이터 라벨이 누락됩니다.

해결 방법:

`kube-system` 네임스페이스에서 CR `stackdriver`에 다음 명령어를 실행하여 `featureGates.disableExperimentalMetadataAgent` 필드를 `true`로 설정합니다.

`kubectl -n kube-system patch stackdriver stackdriver -p '{"spec":{"featureGates":{"disableExperimentalMetadataAgent":true}}}'`

그런 후 다음 명령어를 실행합니다.

`kubectl -n kube-system patch deployment stackdriver-operator -p '{"spec":{"template":{"spec":{"containers":[{"name":"stackdriver-operator","env":[{"name":"ENABLE_LEGACY_METADATA_AGENT","value":"true"}]}]}}}}'`

업그레이드, 업데이트

1.15.0-1.15.7, 1.16.0-1.16.4, 1.28.0

관리자 클러스터 및 ControlPlane V2가 사용 설정된 사용자 클러스터가 다른 vSphere 사용자 인증 정보를 사용하면 clusterapi-controller가 비정상 종료될 수 있음

관리자 클러스터 및 ControlPlane V2가 사용 설정된 사용자 클러스터가 다른 vSphere 사용자 인증 정보를 사용하면(예: 관리자 클러스터의 vSphere 사용자 인증 정보를 업데이트한 후) 다시 시작한 후에 clusterapi-controller가 vCenter에 연결하지 못할 수 있습니다. 관리자 클러스터의 `kube-system` 네임스페이스에서 실행 중인 clusterapi-controller의 로그를 확인합니다.

kubectl logs -f -l component=clusterapi-controllers -c vsphere-controller-manager \
    -n kube-system --kubeconfig KUBECONFIG

로그에 다음과 같은 항목이 포함되었으면 이 문제의 영향을 받는 것입니다.

E1214 00:02:54.095668       1 machine_controller.go:165] Error checking existence of machine instance for machine object gke-admin-node-77f48c4f7f-s8wj2: Failed to check if machine gke-admin-node-77f48c4f7f-s8wj2 exists: failed to find datacenter "VSPHERE_DATACENTER": datacenter 'VSPHERE_DATACENTER' not found

해결 방법:

관리자 클러스터 및 Controlplane V2가 사용 설정된 모든 사용자 클러스터가 동일한 vSphere 사용자 인증 정보를 사용하도록 vSphere 사용자 인증 정보를 업데이트합니다.

로깅 및 모니터링

1.14

etcd의 Prometheus Alert Manager에 실패한 GRPC 요청이 많음

Prometheus는 다음 예시와 비슷한 알림을 보고할 수 있습니다.

Alert Name: cluster:gke-admin-test1: Etcd cluster kube-system/kube-etcd: 100% of requests for Watch failed on etcd instance etcd-test-xx-n001.

이 알림이 무시할 수 있는 거짓양성인지 확인하려면 다음 단계를 완료합니다.

알림 메시지에 나와 있는 grpc_method를 기준으로 원시 grpc_server_handled_total 측정항목을 확인합니다. 이 예시에서는 Watch의 grpc_code 라벨을 확인합니다.

다음 MQL 쿼리를 통해 Cloud Monitoring을 사용하여 이 측정항목을 확인할 수 있습니다.
```
fetch
    k8s_container | metric 'kubernetes.io/anthos/grpc_server_handled_total' | align rate(1m) | every 1m
```
코드가 다음 중 하나가 아니면 OK 이외의 모든 코드에 대한 알림을 무시해도 안전합니다.
```
Unknown|FailedPrecondition|ResourceExhausted|Internal|Unavailable|DataLoss|DeadlineExceeded
```

해결 방법:

이러한 거짓양성 알림을 무시하도록 Prometheus를 구성하려면 다음 옵션을 검토합니다.

Alert Manager UI에서 알림을 무음으로 설정합니다.
알림을 무음으로 설정하는 옵션이 없는 경우 다음 단계를 검토하여 거짓양성을 숨깁니다.
1. 수정사항이 유지될 수 있도록 모니터링 연산자를 0 복제본으로 축소합니다.
2. prometheus-config configmap을 수정하고 다음 예시에 표시된 대로 grpc_method!="Watch"를 etcdHighNumberOfFailedGRPCRequests 알림 구성에 추가합니다.
  - 원본:
```
rate(grpc_server_handled_total{cluster="CLUSTER_NAME",grpc_code!="OK",job=~".*etcd.*"}[5m])
```
  - 수정됨:
```
rate(grpc_server_handled_total{cluster="CLUSTER_NAME",grpc_code=~"Unknown|FailedPrecondition|ResourceExhausted|Internal|Unavailable|DataLoss|DeadlineExceeded",grpc_method!="Watch",job=~".*etcd.*"}[5m])
```
    다음 CLUSTER_NAME을 클러스터 이름으로 바꿉니다.
3. Prometheus 및 Alertmanager Statefulset를 다시 시작하여 새 구성을 선택합니다.
코드가 문제 사례 중 하나에 해당하는 경우 중 하나에 해당하면 etcd 로그 및 kube-apiserver 로그를 확인하여 추가로 디버그합니다.

네트워킹

1.16.0-1.16.2, 1.28.0

이그레스 NAT 장기 지속 연결이 끊김

연결이 설정되고 5~10분 후에 트래픽이 없으면 이그레스 NAT 연결이 끊길 수 있습니다.

conntrack은 인바운드 방향(클러스터에 대한 외부 연결)에서만 중요하므로 이 문제는 연결이 잠시 동안 정보를 전송하지 않은 후에 대상 측에서 무언가를 전송하는 경우에만 발생합니다. 이그레스 NAT 포드가 항상 메시지를 인스턴스화하는 경우 이 문제가 표시되지 않습니다.

이 문제는 데몬에서 사용되지 않는 것으로 인식하는 conntrack 항목을 anetd 가비지 컬렉션이 의도치 않게 삭제하기 때문에 발생합니다. 이 동작을 시정하기 위해 최근 업스트림 수정사항이 anetd에 통합되었습니다.

해결 방법:

간편한 해결 방법은 없으며 버전 1.16에서는 이러한 동작으로 인한 문제가 발견되지 않았습니다. 이 문제로 인해 장기 지속 연결이 끊긴 경우 해결 방법은 이그레스 IP 주소와 동일한 노드에서 워크로드를 사용하거나 TCP 연결에서 일관되게 메시지를 전송하는 것입니다.

작업

1.14, 1.15, 1.16

CSR 서명자가 인증서 서명 시 `spec.expirationSeconds`를 무시함

expirationSeconds가 설정된 CertificateSigningRequest(CSR)를 만들면 expirationSeconds가 무시됩니다.

해결 방법:

이 문제의 영향을 받는 경우 사용자 클러스터 구성 파일에 disableNodeIDVerificationCSRSigning: true를 추가하여 사용자 클러스터를 업데이트하고 gkectl update cluster 명령어를 실행하여 이 구성으로 클러스터를 업데이트할 수 있습니다.

네트워킹, 업그레이드, 업데이트

1.16.0-1.16.3

`disable_bundled_ingress`에 대한 사용자 클러스터 부하 분산기 검증 실패

기존 클러스터의 번들 인그레스를 중지하려고 하면 gkectl update cluster 명령어가 다음 예시와 비슷한 오류와 함께 실패합니다.

[FAILURE] Config: ingress IP is required in user cluster spec

이 오류는 프리플라이트 검사 중 gkectl이 부하 분산기 인그레스 IP 주소를 확인하기 때문에 발생합니다. 번들 인그레스를 중지할 때는 이 검사가 필요하지 않지만 disableBundledIngress가 true로 설정된 경우에는 gkectl 프리플라이트 검사가 실패합니다.

해결 방법:

다음 예시와 같이 클러스터를 업데이트할 때 --skip-validation-load-balancer 파라미터를 사용합니다.

gkectl update cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG  \
  --skip-validation-load-balancer

자세한 내용은 기존 클러스터의 번들 인그레스를 중지하는 방법을 참조하세요.

업그레이드, 업데이트

1.13, 1.14, 1.15.0-1.15.6

CA 순환 후 관리자 클러스터 업데이트 실패

관리자 클러스터 인증 기관(CA) 인증서를 순환하는 경우 후속 gkectl update admin 명령어 실행 시도가 실패합니다. 반환되는 오류는 다음과 비슷합니다.

failed to get last CARotationStage: configmaps "ca-rotation-stage" not found

해결 방법:

이 문제의 영향을 받는 경우 gkectl update admin 명령어에 --disable-update-from-checkpoint 플래그를 사용하여 관리자 클러스터를 업데이트할 수 있습니다.

gkectl update admin --config ADMIN_CONFIG_file \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --disable-update-from-checkpoint

--disable-update-from-checkpoint 플래그를 사용하면 업데이트 명령어가 클러스터 업데이트 중에 체크포인트 파일을 정보 소스로 사용하지 않습니다. 체크포인트 파일은 나중에 사용할 수 있도록 계속 업데이트됩니다.

스토리지

1.15.0-1.15.6, 1.16.0-1.16.2

포드 시작 실패로 인해 CSI 워크로드 프리플라이트 검사 실패

프리플라이트 검사 중에 CSI 워크로드 검증 검사는 default 네임스페이스에 포드를 설치합니다. CSI 워크로드 포드는 vSphere CSI 드라이버가 설치되었는지 확인하고 동적 볼륨 프로비저닝을 수행할 수 있습니다. 이 포드가 시작되지 않으면 CSI 워크로드 검증 검사가 실패합니다.

이 포드가 시작되지 못하게 할 수 있는 몇 가지 알려진 문제가 있습니다.

허용 웹훅이 설치된 일부 클러스터의 경우와 같이 포드에 리소스 한도가 지정되지 않은 경우 포드가 시작되지 않습니다.
default 네임스페이스에 자동 Istio 사이드카 삽입이 사용 설정된 클러스터에 Cloud Service Mesh가 설치된 경우 CSI 워크로드 포드가 시작되지 않습니다.

CSI 워크로드 포드가 시작되지 않은 경우 프리플라이트 검증 중에 다음과 같은 시간 초과 오류가 표시됩니다.

- [FAILURE] CSI Workload: failure in CSIWorkload validation: failed to create writer Job to verify the write functionality using CSI: Job default/anthos-csi-workload-writer-<run-id> replicas are not in Succeeded phase: timed out waiting for the condition

설정된 포드 리소스 부족으로 인해 실패가 발생했는지 확인하려면 다음 명령어를 실행하여 anthos-csi-workload-writer-<run-id> 작업 상태를 확인합니다.

kubectl describe job anthos-csi-workload-writer-<run-id>

CSI 워크로드 포드에 리소스 한도가 올바르게 설정되지 않으면 작업 상태에 다음과 같은 오류 메시지가 포함됩니다.

CPU and memory resource limits is invalid, as it are not defined for container: volume-tester

Istio 사이드카 삽입으로 인해 CSI 워크로드 포드가 시작되지 않은 경우 default 네임스페이스에서 자동 Istio 사이드카 삽입을 일시적으로 중지할 수 있습니다. 네임스페이스의 라벨을 확인하고 다음 명령어를 사용하여 istio.io/rev로 시작하는 라벨을 삭제합니다.

kubectl label namespace default istio.io/rev-

포드가 잘못 구성된 경우 vSphere CSI 드라이버를 사용한 동적 볼륨 프로비저닝이 작동하는지 수동으로 확인합니다.

standard-rwo StorageClass를 사용하는 PVC를 만듭니다.
PVC를 사용하는 포드를 만듭니다.
포드가 데이터를 읽고 볼륨에 쓸 수 있는지 확인합니다.
적절하게 작동하는 것을 확인한 후 포드와 PVC를 삭제합니다.

vSphere CSI 드라이버를 사용한 동적 볼륨 프로비저닝이 작동하면 gkectl diagnose 또는 gkectl upgrade를 --skip-validation-csi-workload 플래그와 함께 실행하여 CSI 워크로드 검사를 건너뜁니다.

작업

1.16.0-1.16.2

사용자 관리형 관리자 워크스테이션에 로그온하면 gkectl update cluster 명령어 시간이 초과되어 사용자 클러스터를 업데이트하지 못할 수 있습니다. 이는 관리자 클러스터 버전이 1.15이고 gkectl update cluster를 실행하기 전에 gkectl update admin을 실행하는 경우에 발생합니다. 이 오류가 발생하면 클러스터를 업데이트하려고 시도할 때 다음 오류가 표시됩니다.

      Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition
Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition

1.15 관리자 클러스터를 업데이트하는 동안 프리플라이트 검사를 트리거하는 validation-controller가 클러스터에서 삭제됩니다. 그런 다음 사용자 클러스터를 업데이트하려고 하면 제한 시간에 도달할 때까지 프리플라이트 검사가 중단됩니다.

해결 방법:

다음 명령어를 실행하여 validation-controller를 재배포합니다.

      gkectl prepare --kubeconfig ADMIN_KUBECONFIG --bundle-path BUNDLE_PATH --upgrade-platform

준비가 완료되면 gkectl update cluster를 다시 실행하여 사용자 클러스터를 업데이트합니다.

작업

1.16.0-1.16.2

사용자 관리형 관리자 워크스테이션에 로그온하면 gkectl create cluster 명령어 시간이 초과되어 사용자 클러스터를 만들지 못할 수 있습니다. 이 문제는 관리자 클러스터 버전이 1.15인 경우에 발생합니다. 이 오류가 발생하면 클러스터를 생성하려고 시도할 때 다음 오류가 표시됩니다.

      Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition
Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition

validation-controller는 1.16에서 추가되었으므로 1.15 관리자 클러스터를 사용할 때는 프리플라이트 검사 트리거를 담당하는 validation-controller가 없습니다. 따라서 사용자 클러스터를 만들려고 하면 제한 시간에 도달할 때까지 프리플라이트 검사가 중단됩니다.

해결 방법:

다음 명령어를 실행하여 validation-controller를 배포합니다.

      gkectl prepare --kubeconfig ADMIN_KUBECONFIG --bundle-path BUNDLE_PATH --upgrade-platform

준비가 완료되면 gkectl create cluster를 다시 실행하여 사용자 클러스터를 만듭니다.

업그레이드, 업데이트

1.16.0-1.16.2

부가기능 서비스의 프로젝트 또는 위치가 서로 일치하지 않을 경우 관리자 클러스터 업데이트 또는 업그레이드가 실패함

관리자 클러스터를 버전 1.15.x에서 1.16.x로 업그레이드하거나 다음과 같이 connect, stackdriver, cloudAuditLogging 또는 gkeOnPremAPI 구성을 추가하는 경우 관리자 클러스터를 업데이트하면 관리자 클러스터 웹훅에서 작업이 거부될 수 있습니다. 다음 오류 메시지 중 하나가 표시될 수 있습니다.

"projects for connect, stackdriver and cloudAuditLogging must be the same when specified during cluster creation."
"locations for connect, gkeOnPremAPI, stackdriver and cloudAuditLogging must be in the same region when specified during cluster creation."
"locations for stackdriver and cloudAuditLogging must be the same when specified during cluster creation."

관리자 클러스터를 업데이트하거나 업그레이드하려면 onprem-admin-cluster-controller가 종류 클러스터에서 관리자 클러스터를 조정해야 합니다. 종류 클러스터에 관리자 클러스터 상태가 복원되면 관리자 클러스터 웹훅은 OnPremAdminCluster 객체가 관리자 클러스터 생성용인지, 업데이트 또는 업그레이드 작업 재개용인지 구분할 수 없습니다. 업데이트 및 업그레이드 시 일부 만들기 전용 유효성 검증이 예기치 않게 호출됩니다.

해결 방법:

OnPremAdminCluster 객체에 onprem.cluster.gke.io/skip-project-location-sameness-validation: true 주석을 추가합니다.

onpremadminclusters 클러스터 리소스를 수정합니다.
```
kubectl edit onpremadminclusters ADMIN_CLUSTER_NAME -n kube-system –kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
다음을 바꿉니다.
- ADMIN_CLUSTER_NAME: 관리자 클러스터 이름
- ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로
onprem.cluster.gke.io/skip-project-location-sameness-validation: true 주석을 추가하고 커스텀 리소스를 저장합니다.
관리자 클러스터 유형에 따라 다음 단계 중 하나를 완료합니다.
- HA 이외 관리자 클러스터에 체크포인트 파일이 있는 경우: 업데이트 명령어에 disable-update-from-checkpoint 파라미터를 추가하거나 업그레이드 명령어에 `disable-upgrade-from-checkpoint` 파라미터를 추가합니다. 이러한 파라미터는 다음에 update 또는 upgrade 명령어를 실행할 때만 필요합니다.
  - ```
  gkectl update admin --config ADMIN_CONFIG_file --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --disable-update-from-checkpoint
```
- ```
gkectl upgrade admin --config ADMIN_CONFIG_file --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --disable-upgrade-from-checkpoint
```
- HA 관리자 클러스터 또는 체크포인트 파일이 중지된 경우. 관리자 클러스터를 정상적으로 업데이트하거나 업그레이드합니다. 업데이트 또는 업그레이드 명령어에 추가 파라미터가 필요하지 않습니다.

작업

1.16.0-1.16.2

사용자 관리형 관리자 워크스테이션을 사용할 때 사용자 클러스터 삭제가 실패함

사용자 관리형 관리자 워크스테이션에 로그온하면 gkectl delete cluster 명령어 시간이 초과되어 사용자 클러스터를 삭제하지 못할 수 있습니다. 이 문제는 사용자 관리형 워크스테이션에서 먼저 gkectl을 실행하여 사용자 클러스터를 만들거나 업데이트하거나 업그레이드한 경우에 발생합니다. 이 오류가 발생하면 클러스터를 삭제하려고 시도할 때 다음 오류가 표시됩니다.

      failed to wait for user cluster management namespace "USER_CLUSTER_NAME-gke-onprem-mgmt"
      to be deleted: timed out waiting for the condition

삭제 시 클러스터는 먼저 모든 객체를 삭제합니다. 만들기, 업데이트 또는 업그레이드 중에 생성된 검증 객체 삭제는 삭제 단계에서 중단됩니다. 이는 파이널라이저가 객체 삭제를 차단하여 클러스터 삭제가 실패하기 때문입니다.

해결 방법:

모든 검증 객체의 이름을 가져옵니다.

         kubectl  --kubeconfig ADMIN_KUBECONFIG get validations \
           -n USER_CLUSTER_NAME-gke-onprem-mgmt

각 검증 객체에 대해 다음 명령어를 실행하여 검증 객체에서 파이널라이저를 삭제합니다.
```
      kubectl --kubeconfig ADMIN_KUBECONFIG patch validation/VALIDATION_OBJECT_NAME \
        -n USER_CLUSTER_NAME-gke-onprem-mgmt -p '{"metadata":{"finalizers":[]}}' --type=merge
      
```
모든 검증 객체에서 파이널라이저를 삭제하면 객체가 삭제되고 사용자 클러스터 삭제 작업이 자동으로 완료됩니다. 별도로 취해야 할 조치는 없습니다.

네트워킹

1.15, 1.16

외부 서버에 대한 이그레스 NAT 게이트웨이 트래픽이 실패함

소스 포드 및 이그레스 NAT 게이트웨이 포드가 두 개의 서로 다른 워커 노드에 있는 경우 소스 포드의 트래픽이 외부 서비스에 도달할 수 없습니다. 포드가 동일한 호스트에 있으면 외부 서비스 또는 애플리케이션에 대한 연결이 성공합니다.

이 문제는 터널 집계가 사용 설정되었을 때 vSphere가 VXLAN 패킷을 삭제하는 경우에 발생합니다. NSX 및 VMware에는 알려진 VXLAN 포트(4789)에서만 집계된 트래픽을 전송하는 알려진 문제가 있습니다.

해결 방법:

Cilium에서 사용하는 VXLAN 포트를 4789로 변경합니다.

cilium-config ConfigMap을 수정합니다.

kubectl edit cm -n kube-system cilium-config --kubeconfig USER_CLUSTER_KUBECONFIG

cilium-config ConfigMap에 다음을 추가합니다.
```
tunnel-port: 4789
```

anetd DaemonSet를 다시 시작합니다.

kubectl rollout restart ds anetd -n kube-system --kubeconfig USER_CLUSTER_KUBECONFIG

이 해결 방법은 클러스터가 업그레이드될 때마다 취소됩니다. 업그레이드할 때마다 다시 구성해야 합니다. 영구적인 해결을 위해서는 VMware가 vSphere에서 해당 문제를 해결해야 합니다.

업그레이드

1.15.0-1.15.4

상시 보안 비밀 암호화가 사용 설정된 상태에서 관리자 클러스터 업그레이드가 실패함

상시 보안 비밀 암호화가 사용 설정된 상태에서 관리자 클러스터를 1.14.x에서 1.15.x로 업그레이드하려고 하면 컨트롤러에서 생성되는 암호화 키와 관리자 마스터 데이터 디스크에 저장되는 키의 불일치로 인해 실패합니다. gkectl upgrade admin 출력에 다음 오류 메시지가 포함됩니다.

      E0926 14:42:21.796444   40110 console.go:93] Exit with error:
      E0926 14:42:21.796491   40110 console.go:93] Failed to upgrade the admin cluster: failed to create admin cluster: failed to wait for OnPremAdminCluster "admin-cluster-name" to become ready: failed to wait for OnPremAdminCluster "admin-cluster-name" to be ready: error: timed out waiting for the condition, message: failed to wait for OnPremAdminCluster "admin-cluster-name" to stay in ready status for duration "2m0s": OnPremAdminCluster "non-prod-admin" is not ready: ready condition is not true: CreateOrUpdateControlPlane: Creating or updating credentials for cluster control plane

kubectl get secrets -A --kubeconfig KUBECONFIG`를 실행하면 다음 오류와 함께 실패합니다.

      Internal error occurred: unable to transform key "/registry/secrets/anthos-identity-service/ais-secret": rpc error: code = Internal desc = failed to decrypt: unknown jwk

해결 방법

관리자 클러스터 백업이 있는 경우 다음 단계를 수행하여 업그레이드 실패를 해결합니다.

관리자 클러스터 구성 파일에서 secretsEncryption을 중지하고 다음 명령어를 사용하여 클러스터를 업데이트합니다.
```
gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG
```
새 관리자 마스터 VM이 생성되면 관리자 마스터 VM에 SSH로 연결하고 데이터 디스크의 새 키를 백업의 이전 키로 바꿉니다. 이 키는 관리자 마스터의 /opt/data/gke-k8s-kms-plugin/generatedkeys에 있습니다.
/etc/kubernetes/manifests의 kms-plugin.yaml 정적 포드 매니페스트를 업데이트하여 --kek-id를 원래 암호화 키의 kid 필드와 일치하도록 업데이트합니다.
/etc/kubernetes/manifests/kms-plugin.yaml을 다른 디렉터리로 이동한 후 다시 이동하여 kms-plugin 정적 포드를 다시 시작합니다.
gkectl upgrade admin을 다시 실행하여 관리자 업그레이드를 계속합니다.

업그레이드 실패 방지

아직 업그레이드하지 않은 경우 1.15.0-1.15.4로 업그레이드하지 않는 것이 좋습니다. 영향을 받는 버전으로 업그레이드해야 하는 경우 관리자 클러스터를 업그레이드하기 전에 다음 단계를 수행합니다.

관리자 클러스터를 백업합니다.
관리자 클러스터 구성 파일에서 secretsEncryption을 중지하고 다음 명령어를 사용하여 클러스터를 업데이트합니다.
```
gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG
```
관리자 클러스터를 업그레이드합니다.
상시 보안 비밀 암호화를 사용 설정합니다.

스토리지

1.11-1.16

변경 블록 추적(CBT) 사용 시 디스크 오류 및 연결 실패

Google Distributed Cloud는 디스크에서 변경 블록 추적(CBT)을 지원하지 않습니다. 일부 백업 소프트웨어는 CBT 기능을 사용하여 디스크 상태를 추적하고 백업을 수행하므로 디스크가 Google Distributed Cloud를 실행하는 VM에 연결할 수 없게 됩니다. 자세한 내용은 VMware KB 문서를 참조하세요.

해결 방법:

타사 백업 소프트웨어로 인해 디스크에 CBT가 사용 설정될 수 있으므로 Google Distributed Cloud VM을 백업하지 마세요. 이러한 VM은 백업할 필요가 없습니다.

이 변경사항은 업데이트나 업그레이드 후 유지되지 않으므로 노드에서 CBT를 사용 설정하지 마세요.

이미 CBT가 사용 설정된 디스크가 있는 경우 VMware KB 문서의 해결 단계에 따라 First Class Disk에서 CBT를 중지하세요.

스토리지

1.14, 1.15, 1.16

여러 호스트에서 공유 파일에 대한 병렬 추가 수행 시 NFSv3의 데이터 손상

Nutanix 스토리지 배열을 사용하여 호스트에 NFSv3 공유를 제공하는 경우 데이터가 손상되거나 포드가 성공적으로 실행되지 않을 수 있습니다. 이 문제는 특정 버전의 VMware 및 Nutanix 버전 간에 알려진 호환성 문제로 인해 발생합니다. 자세한 내용은 관련 VMware KB 문서를 참조하세요.

해결 방법:

VMware KB 문서는 최신 상태가 아니므로 최신 해결책이 없다는 점에 유의하세요. 이 문제를 해결하려면 호스트의 ESXi를 최신 버전으로 업데이트하고 스토리지 어레이의 Nutanix를 최신 버전으로 업데이트하세요.

운영체제

1.13.10, 1.14.6, 1.15.3

kubelet과 Kubernetes 컨트롤 플레인 간의 버전 불일치

특정 Google Distributed Cloud 출시 버전의 경우 노드에서 실행되는 kubelet이 Kubernetes 컨트롤 플레인과 다른 버전을 사용합니다. OS 이미지에 미리 로드된 kubelet 바이너리는 다른 버전을 사용하기 때문에 불일치가 있습니다.

다음 표에는 식별된 버전 불일치가 나와 있습니다.

Google Distributed Cloud 버전	kubelet 버전	Kubernetes 버전
1.13.10	v1.24.11-gke.1200	v1.24.14-gke.2100
1.14.6	v1.25.8-gke.1500	v1.25.10-gke.1200
1.15.3	v1.26.2-gke.1001	v1.26.5-gke.2100

해결 방법:

이와 관련해 별도의 조치를 취할 필요는 없습니다. Kubernetes 패치 버전 간에만 불일치가 있으며 이 버전 차이로 인해 문제가 발생하지는 않습니다.

업그레이드, 업데이트

1.15.0-1.15.4

CA 버전이 1개를 초과하는 경우 관리자 클러스터 업그레이드 또는 업데이트가 실패함

관리자 클러스터의 인증 기관(CA) 버전이 1보다 크면 웹훅의 CA 버전 검증으로 인해 업데이트 또는 업그레이드가 실패합니다. gkectl 업그레이드/업데이트 출력에는 다음 오류 메시지가 포함됩니다.

    CAVersion must start from 1

해결 방법:

노드 자동 크기 조절을 중지하려면 관리자 클러스터에서 auto-resize-controller 배포를 축소하세요. 이는 1.15의 관리자 클러스터 커스텀 리소스에 도입된 새 필드가 auto-resize-controller에서 nil 포인터 오류를 발생시킬 수 있기 때문에 필요합니다.
```
 kubectl scale deployment auto-resize-controller -n kube-system --replicas=0 --kubeconfig KUBECONFIG
      
```

gkectl 명령어를 --disable-admin-cluster-webhook플래그와 함께 실행합니다. 예를 들면 다음과 같습니다.

        gkectl upgrade admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG --disable-admin-cluster-webhook

작업

1.13, 1.14.0-1.14.8, 1.15.0-1.15.4, 1.16.0-1.16.1

HA 이외 Controlplane V2 클러스터 삭제가 제한 시간까지 중단됨

HA 이외 Controlplane V2 클러스터가 삭제되면 시간이 초과될 때까지 노드 삭제가 중단됩니다.

해결 방법:

클러스터에 중요 데이터가 있는 StatefulSet가 포함된 경우 Cloud Customer Care에 문의하여 이 문제를 해결하세요.

그렇지 않은 경우 다음 단계를 따르세요.

vSphere에서 모든 클러스터 VM을 삭제합니다. vSphere UI를 통해 VM을 삭제하거나 다음 명령어를 실행할 수 있습니다.
```
      govc vm.destroy
```
.

클러스터를 다시 강제 삭제합니다.

     gkectl delete cluster --cluster USER_CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG --force

스토리지

1.15.0+, 1.16.0+

버전 1.15 이상으로 업그레이드한 후 트리 내 PVC/PV에 대해 1분마다 지속적인 CNS attachvolume 태스크가 표시됨

클러스터에 트리 내 vSphere 영구 볼륨(예: standard StorageClass로 생성된 PVC)이 포함된 경우 vCenter에서 com.vmware.cns.tasks.attachvolume 태스크가 1분마다 트리거됩니다.

해결 방법:

vSphere CSI 기능 configMap을 수정하고 list-volumes를 false로 설정합니다.

     kubectl edit configmap internal-feature-states.csi.vsphere.vmware.com -n kube-system --kubeconfig KUBECONFIG

vSphere CSI 컨트롤러 포드를 다시 시작합니다.

     kubectl rollout restart deployment vsphere-csi-controller -n kube-system --kubeconfig KUBECONFIG

스토리지

1.16.0

PVC에 대한 거짓 경고

클러스터에 트리 내 vSphere 영구 볼륨이 포함된 경우 gkectl diagnose 및 gkectl upgrade 명령어로 클러스터 스토리지 설정을 검증할 때 영구 볼륨 클레임(PVC)에 대한 거짓 경고가 발생할 수 있습니다. 경고 메시지는 다음과 같이 표시됩니다.

    CSIPrerequisites pvc/pvc-name: PersistentVolumeClaim pvc-name bounds to an in-tree vSphere volume created before CSI migration enabled, but it doesn't have the annotation pv.kubernetes.io/migrated-to set to csi.vsphere.vmware.com after CSI migration is enabled

해결 방법:

다음 명령어를 실행하여 위 경고에 표시된 PVC의 주석을 확인합니다.

    kubectl get pvc PVC_NAME -n PVC_NAMESPACE -oyaml --kubeconfig KUBECONFIG

출력의 annotations 필드에 다음이 포함되어 있으면 경고를 무시해도 됩니다.

      pv.kubernetes.io/bind-completed: "yes"
      pv.kubernetes.io/bound-by-controller: "yes"
      volume.beta.kubernetes.io/storage-provisioner: csi.vsphere.vmware.com

업그레이드, 업데이트

1.15.0+, 1.16.0+

여러 키가 만료되었을 때 서비스 계정 키 순환이 실패함

클러스터가 비공개 레지스트리를 사용하지 않는 경우 구성요소 액세스 서비스 계정 키 및 로깅-모니터링(또는 연결-등록) 서비스 계정 키가 만료되면 서비스 계정 키를 순환할 때 gkectl update credentials가 다음과 유사한 오류와 함께 실패합니다.

Error: reconciliation failed: failed to update platform: ...

해결 방법:

먼저 구성요소 액세스 서비스 계정 키를 순환합니다. 동일한 오류 메시지가 표시되지만 구성요소 액세스 서비스 계정 키 순환 후 다른 키를 순환할 수 있을 것입니다.

그래도 업데이트가 실패할 경우 Cloud Customer Care에 문의하여 이 문제를 해결하세요.

업그레이드

1.16.0-1.16.5

사용자 클러스터 컨트롤러가 1.16으로 업그레이드되면 1.15 사용자 마스터 머신에 예기치 않은 재생성 발생

사용자 클러스터를 업그레이드하는 동안 사용자 클러스터 컨트롤러가 1.16으로 업그레이드된 후 동일한 관리자 클러스터에서 관리하는 다른 1.15 사용자 클러스터가 있으면 사용자 마스터 머신이 예기치 않게 다시 생성될 수 있습니다.

1.16 사용자 클러스터 컨트롤러에는 1.15 사용자 마스터 머신 재생성을 트리거할 수 있는 버그가 있습니다.

해결 방법은 이 문제가 발생하는 방식에 따라 달라집니다.

Google Cloud 콘솔을 사용하여 사용자 클러스터를 업그레이드할 때의 해결 방법:

옵션 1: 수정사항이 포함된 VMware용 GKE 1.16.6 이상 버전을 사용하세요.

옵션 2: 다음 단계를 수행합니다.

다음 명령어를 사용하여 재실행 주석을 수동으로 추가합니다.

kubectl edit onpremuserclusters USER_CLUSTER_NAME -n USER_CLUSTER_NAME-gke-onprem-mgmt --kubeconfig ADMIN_KUBECONFIG

재실행 주석은 다음과 같습니다.

onprem.cluster.gke.io/server-side-preflight-rerun: true

OnPremUserCluster의 status 필드를 확인하여 업그레이드 진행 상황을 모니터링합니다.

자체 관리자 워크스테이션을 사용하여 사용자 클러스터를 업그레이드할 때의 해결 방법

옵션 1: 수정사항이 포함된 VMware용 GKE 1.16.6 이상 버전을 사용하세요.

옵션 2: 다음 단계를 수행합니다.

다음 콘텐츠가 포함된 빌드 정보 파일 /etc/cloud/build.info를 추가합니다. 이렇게 하면 프리플라이트 검사가 서버가 아닌 관리자 워크스테이션에서 로컬로 실행됩니다.
```
gke_on_prem_version: GKE_ON_PREM_VERSION
```
예를 들면 다음과 같습니다.
```
gke_on_prem_version: 1.16.0-gke.669
```
업그레이드 명령어를 다시 실행합니다.
업그레이드가 완료되면 build.info 파일을 삭제합니다.

Create

1.16.0-1.16.5, 1.28.0-1.28.100

호스트 이름이 IP 블록 파일에 없으면 프리플라이트 검사가 실패함

클러스터 생성 중에 IP 블록 파일의 모든 IP 주소에 호스트 이름을 지정하지 않으면 프리플라이트 검사가 실패하고 다음 오류 메시지가 표시됩니다.

multiple VMs found by DNS name  in xxx datacenter. Anthos Onprem doesn't support duplicate hostname in the same vCenter and you may want to rename/delete the existing VM.`

프리플라이트 검사에 빈 호스트 이름이 중복되었다고 가정하는 버그가 있습니다.

해결 방법:

옵션 1: 수정사항이 포함된 버전을 사용합니다.

옵션 2: --skip-validation-net-config 플래그를 추가하여 이 프리플라이트 검사를 우회합니다.

옵션 3: IP 블록 파일의 각 IP 주소에 고유한 호스트 이름을 지정합니다.

업그레이드, 업데이트

1.16

HA가 아닌 관리자 클러스터 및 컨트롤 플레인 v1 사용자 클러스터를 사용하는 경우 관리자 클러스터를 업그레이드/업데이트할 때 볼륨 마운트 실패

HA가 아닌 관리자 클러스터 및 컨트롤 플레인 v1 사용자 클러스터의 경우 관리자 클러스터를 업그레이드하거나 업데이트할 때 사용자 클러스터 마스터 머신 재부팅과 동시에 관리자 클러스터 마스터 머신이 재생성되어 경합 상태가 발생할 수 있습니다. 그 결과 사용자 클러스터 컨트롤 플레인 포드가 관리자 클러스터 컨트롤 플레인과 통신할 수 없게 되어 사용자 클러스터 컨트롤 플레인의 kube-etcd 및 kube-apiserver에 볼륨 연결 문제가 발생합니다.

문제를 확인하려면 영향을 받은 포드에 대해 다음 명령어를 실행합니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace USER_CLUSTER_NAME describe pod IMPACTED_POD_NAME

그러면 다음과 같은 이벤트를 보게 됩니다.

Events:
  Type     Reason       Age                  From               Message
  ----     ------       ----                 ----               -------
  Warning  FailedMount  101s                 kubelet            Unable to attach or mount volumes: unmounted volumes=[kube-audit], unattached volumes=[], failed to process volumes=[]: timed out waiting for the condition
  Warning  FailedMount  86s (x2 over 3m28s)  kubelet            MountVolume.SetUp failed for volume "pvc-77cd0635-57c2-4392-b191-463a45c503cb" : rpc error: code = FailedPrecondition desc = volume ID: "bd313c62-d29b-4ecd-aeda-216648b0f7dc" does not appear staged to "/var/lib/kubelet/plugins/kubernetes.io/csi/csi.vsphere.vmware.com/92435c96eca83817e70ceb8ab994707257059734826fedf0c0228db6a1929024/globalmount"

해결 방법:

사용자 컨트롤 플레인 노드에 SSH로 연결합니다. 컨트롤 플레인 v1 사용자 클러스터이므로 사용자 컨트롤 플레인 노드는 관리자 클러스터에 있습니다.
다음 명령어를 사용하여 kubelet을 다시 시작합니다.
```
    sudo systemctl restart kubelet
    
```
다시 시작하면 kubelet에서 스테이지 전역 마운트를 올바르게 재구성할 수 있습니다.

업그레이드, 업데이트

1.16.0

컨트롤 플레인 노드 생성 실패

관리자 클러스터를 업그레이드 또는 업데이트하는 동안 경합 상태로 인해 vSphere Cloud Controller 관리자가 예기치 않게 새 컨트롤 플레인 노드를 삭제할 수 있습니다. 이로 인해 노드가 생성될 때까지 clusterapi-controller가 중단되고 결국 업그레이드/업데이트 시간이 초과됩니다. 이 경우 gkectl 업그레이드/업데이트 명령어 출력은 다음과 비슷합니다.

    controlplane 'default/gke-admin-hfzdg' is not ready: condition "Ready": condition is not ready with reason "MachineInitializing", message "Wait for the control plane machine "gke-admin-hfzdg-6598459f9zb647c8-0\" to be rebooted"...

증상을 확인하려면 아래 명령어를 실행하여 관리자 클러스터에서 vSphere 클라우드 컨트롤러 관리자에 로그인합니다.

    kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
    kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n kube-system

다음은 위 명령어의 샘플 오류 메시지입니다.

    node name: 81ff17e25ec6-qual-335-1500f723 has a different uuid. Skip deleting this node from cache.

해결 방법:

실패한 머신을 재부팅하여 삭제된 노드 객체를 다시 만듭니다.

각 컨트롤 플레인 노드에 SSH로 연결하고 vSphere 클라우드 컨트롤러 관리자 정적 포드를 다시 시작합니다.

      sudo crictl ps | grep vsphere-cloud-controller-manager | awk '{print $1}'
      sudo crictl stop PREVIOUS_COMMAND_OUTPUT

업그레이드/업데이트 명령어를 재실행합니다.

작업

1.16

동일한 데이터 센터의 중복된 호스트 이름으로 인해 클러스터 업그레이드 또는 생성이 실패함

동일한 데이터 센터에 중복된 호스트 이름이 있으면 1.15 클러스터를 업그레이드하거나 고정 IP로 1.16 클러스터를 만들 수 없습니다. 이 실패는 vSphere 클라우드 컨트롤러 관리자가 노드 객체에 외부 IP 및 제공업체 ID를 추가할 수 없기 때문에 발생합니다. 이로 인해 클러스터 업그레이드/생성 시간이 초과됩니다.

문제를 식별하려면 클러스터의 vSphere cloud-controller-manager 포드 로그를 가져옵니다. 사용하는 명령어는 다음과 같이 클러스터 유형에 따라 달라집니다.

관리자 클러스터:

      kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n kube-system

사용자 클러스터(kubeception):

      kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAME | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAME

사용자 클러스터: (Controlplane V2):

      kubectl get pods --kubeconfig USER_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig USER_KUBECONFIG -n kube-system

다음은 샘플 오류 메시지입니다.

    I1003 17:17:46.769676       1 search.go:152] Finding node admin-vm-2 in vc=vcsa-53598.e5c235a1.asia-northeast1.gve.goog and datacenter=Datacenter
    E1003 17:17:46.771717       1 datacenter.go:111] Multiple vms found VM by DNS Name. DNS Name: admin-vm-2

데이터 센터에서 호스트 이름이 중복되었는지 확인합니다.

다음 방법을 사용하여 호스트 이름이 중복되었는지 확인하고 필요한 경우 해결 방법을 수행할 수 있습니다.

          export GOVC_DATACENTER=GOVC_DATACENTER
          export GOVC_URL=GOVC_URL
          export GOVC_USERNAME=GOVC_USERNAME
          export GOVC_PASSWORD=GOVC_PASSWORD
          export GOVC_INSECURE=true
          govc find . -type m -guest.hostName HOSTNAME

명령어 및 출력 예시:

          export GOVC_DATACENTER=mtv-lifecycle-vc01
          export GOVC_URL=https://mtv-lifecycle-vc01.anthos/sdk
          export GOVC_USERNAME=xxx
          export GOVC_PASSWORD=yyy
          export GOVC_INSECURE=true
          govc find . -type m -guest.hostName f8c3cd333432-lifecycle-337-xxxxxxxz
          ./vm/gke-admin-node-6b7788cd76-wkt8g
          ./vm/gke-admin-node-6b7788cd76-99sg2
          ./vm/gke-admin-master-5m2jb

수행할 해결 방법은 실패한 작업에 따라 달라집니다.

업그레이드 해결 방법:

적용 가능한 클러스터 유형에 대한 해결 방법을 수행합니다.

사용자 클러스터:
1. user-ip-block.yaml에서 영향을 받는 머신의 호스트 이름을 고유한 이름으로 업데이트하고 강제 업데이트를 트리거합니다.
```
          gkectl update cluster --kubeconfig ADMIN_KUBECONFIG --config NEW_USER_CLUSTER_CONFIG --force
          
```
2. gkectl upgrade cluster 재실행

관리자 클러스터:

admin-ip-block.yaml에서 영향을 받는 머신의 호스트 이름을 고유한 이름으로 업데이트하고 강제 업데이트를 트리거합니다.

          gkectl update admin --kubeconfig ADMIN_KUBECONFIG --config NEW_ADMIN_CLUSTER_CONFIG --force --skip-cluster-ready-check

HA 이외 관리자 클러스터이고 관리자 마스터 VM이 중복된 호스트 이름을 사용하는 경우에는 다음 작업도 수행해야 합니다.
관리자 마스터 머신 이름 가져오기

          kubectl get machine --kubeconfig ADMIN_KUBECONFIG -owide -A

관리자 마스터 머신 객체 업데이트
참고: NEW_ADMIN_MASTER_HOSTNAME은 1단계의 admin-ip-block.yaml에서 설정한 값과 동일해야 합니다.

          kubectl patch machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG --type='json' -p '[{"op": "replace", "path": "/spec/providerSpec/value/networkSpec/address/hostname", "value":"NEW_ADMIN_MASTER_HOSTNAME"}]'

관리 마스터 머신 객체에서 호스트 이름이 업데이트되었는지 확인하세요.

          kubectl get machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG -oyaml
          kubectl get machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG -o jsonpath='{.spec.providerSpec.value.networkSpec.address.hostname}'

체크포인트를 중지한 후 관리자 클러스터 업그레이드를 재실행합니다.

          gkectl upgrade admin --kubeconfig ADMIN_KUBECONFIG --config ADMIN_CLUSTER_CONFIG --disable-upgrade-from-checkpoint

설치 해결 방법:

적용 가능한 클러스터 유형에 대한 해결 방법을 수행합니다.

관리자 클러스터:
1. 관리 노드 머신을 삭제합니다.
2. 데이터 디스크를 삭제합니다.
3. 관리자 클러스터 체크포인트 파일을 삭제합니다.
4. admin-ip-block.yaml에서 영향을 받는 머신의 호스트 이름을 고유한 이름으로 업데이트합니다.
5. gkectl create admin을 재실행합니다.
사용자 클러스터:
1. 리소스를 삭제합니다.
2. user-ip-block.yaml에서 영향을 받는 머신의 호스트 이름을 고유한 이름으로 업데이트합니다.
3. gkectl create cluster를 재실행합니다.

작업

1.16.0, 1.16.1, 1.16.2, 1.16.3

vSphere 사용자 이름 또는 비밀번호에서 `$` 및 `가 지원되지 않음

vSphere 사용자 이름 또는 비밀번호에 $ 또는 `가 포함되어 있으면 다음 작업이 실패합니다.

Controlplane V2가 사용 설정된 1.15 사용자 클러스터를 1.16으로 업그레이드
1.15 고가용성(HA) 관리자 클러스터를 1.16으로 업그레이드
Controlplane V2가 사용 설정된 1.16 사용자 클러스터 만들기
1.16 HA 관리자 클러스터 만들기

수정사항이 포함된 Google Distributed Cloud 1.16.4 이상 버전을 사용하거나 다음 해결 방법을 수행합니다. 수행할 해결 방법은 실패한 작업에 따라 달라집니다.

업그레이드 해결 방법:

vCenter 측에서 vCenter 사용자 이름 또는 비밀번호를 변경하여 $ 및 `를 삭제합니다.
사용자 인증 정보 구성 파일에서 vCenter 사용자 이름 또는 비밀번호를 업데이트합니다.
클러스터 강제 업데이트를 트리거합니다.

사용자 클러스터:

        gkectl update cluster --kubeconfig ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG --force

관리자 클러스터:

        gkectl update admin --kubeconfig ADMIN_KUBECONFIG --config ADMIN_CLUSTER_CONFIG --force --skip-cluster-ready-check

설치 해결 방법:

vCenter 측에서 vCenter 사용자 이름 또는 비밀번호를 변경하여 $ 및 `를 삭제합니다.
사용자 인증 정보 구성 파일에서 vCenter 사용자 이름 또는 비밀번호를 업데이트합니다.
적용 가능한 클러스터 유형에 대한 해결 방법을 수행합니다.

관리자 클러스터:
1. 관리 노드 머신을 삭제합니다.
2. 데이터 디스크를 삭제합니다.
3. 관리자 클러스터 체크포인트 파일을 삭제합니다.
4. gkectl create admin을 재실행합니다.
사용자 클러스터:
1. 리소스를 삭제합니다.
2. gkectl create cluster를 재실행합니다.

스토리지

1.11+, 1.12+, 1.13+, 1.14+, 1.15+, 1.16

노드가 동일한 이름으로 다시 생성된 후 PVC 만들기 실패

노드를 삭제한 후 동일한 노드 이름으로 노드를 다시 만들면 다음과 같은 오류와 함께 후속 PersistentVolumeClaim(PVC) 생성이 실패할 가능성이 약간 있습니다.

    The object 'vim.VirtualMachine:vm-988369' has already been deleted or has not been completely created

이 오류는 vSphere CSI 컨트롤러가 제거된 머신을 캐시에서 삭제하지 않는 경합 상태로 인해 발생합니다.

해결 방법:

vSphere CSI 컨트롤러 포드를 다시 시작합니다.

    kubectl rollout restart deployment vsphere-csi-controller -n kube-system --kubeconfig KUBECONFIG

작업

1.16.0

gkectl repair admin-master가 kubeconfig unmarshall 오류를 반환함

HA 관리자 클러스터에서 gkectl repair admin-master 명령어를 실행하면 gkectl이 다음 오류 메시지를 반환합니다.

  Exit with error: Failed to repair: failed to select the template: failed to get cluster name from kubeconfig, please contact Google support. failed to decode kubeconfig data: yaml: unmarshal errors:
    line 3: cannot unmarshal !!seq into map[string]*api.Cluster
    line 8: cannot unmarshal !!seq into map[string]*api.Context

해결 방법:

명령어에 --admin-master-vm-template= 플래그를 추가하고 복구할 머신의 VM 템플릿을 제공합니다.

  gkectl repair admin-master --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
      --config ADMIN_CLUSTER_CONFIG_FILE \
      --admin-master-vm-template=/DATA_CENTER/vm/VM_TEMPLATE_NAME

머신의 VM 템플릿을 찾으려면 다음 안내를 따르세요.

vSphere 클라이언트에서 호스트 및 클러스터 페이지로 이동합니다.
VM 템플릿을 클릭하고 관리자 클러스터 이름으로 필터링합니다.
관리자 클러스터용 VM 템플릿 3개가 표시됩니다.
복구할 머신의 이름과 일치하는 VM 템플릿 이름을 복사하고 복구 명령어에 이 템플릿 이름을 사용합니다.

  gkectl repair admin-master \
      --config=/home/ubuntu/admin-cluster.yaml \
      --kubeconfig=/home/ubuntu/kubeconfig \
      --admin-master-vm-template=/atl-qual-vc07/vm/gke-admin-98g94-zx...7vx-0-tmpl

네트워킹

1.10.0+, 1.11.0+, 1.12.0+, 1.13.0+, 1.14.0-1.14.7, 1.15.0-1.15.3, 1.16.0

디스크 공간 부족으로 인해 Seesaw VM이 손상됨

Seesaw를 클러스터의 부하 분산기 유형으로 사용하는 경우 Seesaw VM이 다운되거나 부팅에 계속 실패하면 vSphere 콘솔에 다음 오류 메시지가 표시될 수 있습니다.

    GRUB_FORCE_PARTUUID set, initrdless boot failed. Attempting with initrd

이 오류는 Seesaw VM에서 실행되는 fluent-bit가 올바른 로그 순환으로 구성되지 않았기 때문에 VM의 디스크 공간이 부족함을 나타냅니다.

해결 방법:

du -sh -- /var/lib/docker/containers/* | sort -rh를 사용하여 디스크 공간의 대부분을 차지하는 로그 파일을 찾습니다. 가장 큰 로그 파일을 삭제하고 VM을 재부팅합니다.

참고: VM에 완전히 액세스할 수 없으면 디스크를 작동 중인 VM(예: 관리자 워크스테이션)에 연결하고 연결된 디스크에서 파일을 삭제한 후 원래 Seesaw VM에 디스크를 다시 연결하세요.

문제가 다시 발생하지 않도록 VM에 연결하고 /etc/systemd/system/docker.fluent-bit.service 파일을 수정합니다. Docker 명령어에 --log-opt max-size=10m --log-opt max-file=5를 추가한 후 systemctl restart docker.fluent-bit.service를 실행합니다.

작업

1.13, 1.14.0-1.14.6, 1.15

관리자 클러스터 업그레이드 또는 업데이트 후 관리자 SSH 공개 키 오류

고가용성이 없지만 체크포인트가 사용 설정된 관리자 클러스터를 업그레이드(gkectl upgrade admin) 또는 업데이트(gkectl update admin)하려고 시도하면 업그레이드 또는 업데이트가 실패하고 다음과 같은 오류가 발생할 수 있습니다.

Checking admin cluster certificates...FAILURE
    Reason: 20 admin cluster certificates error(s).
Unhealthy Resources:
    AdminMaster clusterCA bundle: failed to get clusterCA bundle on admin master, command [ssh -o IdentitiesOnly=yes -i admin-ssh-key -o StrictHostKeyChecking=no -o ConnectTimeout=30 ubuntu@AdminMasterIP -- sudo cat /etc/kubernetes/pki/ca-bundle.crt] failed with error: exit status 255, stderr: Authorized uses only. All activity may be monitored and reported.
    ubuntu@AdminMasterIP: Permission denied (publickey).

failed to ssh AdminMasterIP, failed with error: exit status 255, stderr: Authorized uses only. All activity may be monitored and reported.
    ubuntu@AdminMasterIP: Permission denied (publickey)

error dialing ubuntu@AdminMasterIP: failed to establish an authenticated SSH connection: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey]...

해결 방법:

수정 사항이 포함된 Google Distributed Cloud의 패치 버전으로 업그레이드할 수 없는 경우 Google 지원에 문의하여 도움을 받으세요.

업그레이드

1.13.0-1.13.9, 1.14.0-1.14.6, 1.15.1-1.15.2

GKE On-Prem API에 등록된 관리자 클러스터 업그레이드가 실패할 수 있음

관리자 클러스터가 GKE On-Prem API에 등록되었을 때는 Fleet 멤버십을 업데이트할 수 없기 때문에 관리자 클러스터를 해당 버전으로 업그레이드하지 못할 수 있습니다. 이 오류가 발생하면 클러스터를 업그레이드하려고 시도할 때 다음 오류가 표시됩니다.

    failed to register cluster: failed to apply Hub Membership: Membership API request failed: rpc error: code = InvalidArgument desc = InvalidFieldError for field endpoint.on_prem_cluster.resource_link: field cannot be updated

관리자 클러스터는 사용자가 클러스터를 명시적으로 등록할 때 또는 GKE On-Prem API 클라이언트를 사용해서 사용자 클러스터를 업그레이드할 때 API에 등록됩니다.

해결 방법:

관리자 클러스터를 등록 해제합니다.

    gcloud alpha container vmware admin-clusters unenroll ADMIN_CLUSTER_NAME --project CLUSTER_PROJECT --location=CLUSTER_LOCATION --allow-missing

관리자 클러스터 업그레이드를 재개합니다. 오래된 '클러스터 등록 실패' 오류가 일시적으로 표시될 수 있습니다. 잠시 후 자동으로 업데이트됩니다.

업그레이드, 업데이트

1.13.0-1.13.9, 1.14.0-1.14.4, 1.15.0

등록된 관리자 클러스터의 리소스 링크 주석이 보존되지 않음

관리자 클러스터가 GKE On-Prem API에 등록된 경우 해당 리소스 링크 주석이 OnPremAdminCluster 커스텀 리소스에 적용됩니다. 이 주석은 사용된 주석 키가 잘못되어 이후 관리자 클러스터를 업데이트하는 동안 보존되지 않습니다. 이로 인해 실수로 관리자 클러스터가 GKE On-Prem API에 다시 등록될 수 있습니다.

해결 방법:

관리자 클러스터를 등록 해제합니다.

    gcloud alpha container vmware admin-clusters unenroll ADMIN_CLUSTER_NAME --project CLUSTER_PROJECT --location=CLUSTER_LOCATION --allow-missing

관리자 클러스터를 다시 재등록합니다.

네트워킹

1.15.0-1.15.2

CoreDNS `orderPolicy`가 인식되지 않음

OrderPolicy는 매개변수로 인식되지 않고 사용되지 않습니다. 대신 Google Distributed Cloud는 항상 Random을 사용합니다.

이 문제는 CoreDNS 템플릿이 업데이트되지 않아서 orderPolicy가 무시되기 때문에 발생합니다.

해결 방법:

CoreDNS 템플릿을 업데이트하고 수정사항을 적용합니다. 이 수정사항은 업그레이드가 수행될 때까지 지속됩니다.

기존 템플릿을 수정합니다.

kubectl edit cm -n kube-system coredns-template

템플릿의 콘텐츠를 다음으로 바꿉니다.

coredns-template: |-
  .:53 {
    errors
    health {
      lameduck 5s
    }
    ready
    kubernetes cluster.local in-addr.arpa ip6.arpa {
      pods insecure
      fallthrough in-addr.arpa ip6.arpa
    }
{{- if .PrivateGoogleAccess }}
    import zones/private.Corefile
{{- end }}
{{- if .RestrictedGoogleAccess }}
    import zones/restricted.Corefile
{{- end }}
    prometheus :9153
    forward . {{ .UpstreamNameservers }} {
      max_concurrent 1000
      {{- if ne .OrderPolicy "" }}
      policy {{ .OrderPolicy }}
      {{- end }}
    }
    cache 30
{{- if .DefaultDomainQueryLogging }}
    log
{{- end }}
    loop
    reload
    loadbalance
}{{ range $i, $stubdomain := .StubDomains }}
{{ $stubdomain.Domain }}:53 {
  errors
{{- if $stubdomain.QueryLogging }}
  log
{{- end }}
  cache 30
  forward . {{ $stubdomain.Nameservers }} {
    max_concurrent 1000
    {{- if ne $.OrderPolicy "" }}
    policy {{ $.OrderPolicy }}
    {{- end }}
  }
}
{{- end }}

업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13.0-1.13.7, 1.14.0-1.14.3

체크포인트와 실제 CR 사이의 OnPremAdminCluster 상태 불일치

특정 경합 상태로 인해 체크포인트와 실제 CR 사이에 OnPremAdminCluster 상태가 불일치할 수 있습니다. 이 문제가 발생하면 관리자 클러스터를 업그레이드한 후 업데이트할 때 다음 오류가 발생할 수 있습니다.

Exit with error:
E0321 10:20:53.515562  961695 console.go:93] Failed to update the admin cluster: OnPremAdminCluster "gke-admin-rj8jr" is in the middle of a create/upgrade ("" -> "1.15.0-gke.123"), which must be completed before it can be updated
Failed to update the admin cluster: OnPremAdminCluster "gke-admin-rj8jr" is in the middle of a create/upgrade ("" -> "1.15.0-gke.123"), which must be completed before it can be updated

이 문제를 해결하려면 체크포인트를 수정하거나 업그레이드/업데이트에 대해 체크포인트를 사용 중지해야 합니다. 문제 해결을 계속하려면 지원팀에 연락하세요.

작업

1.13.0-1.13.9, 1.14.0-1.14.5, 1.15.0-1.15.1

조정 프로세스 중 관리자 클러스터에서 관리자 인증서 변경

Google Distributed Cloud는 클러스터 업그레이드와 같은 모든 조정 프로세스 중에 관리자 클러스터 컨트롤 플레인에서 관리자 인증서를 변경합니다. 이 동작은 특히 버전 1.15 클러스터와 같은 관리자 클러스터에 대해 잘못된 인증서를 가져올 가능성이 높습니다.

이러한 상황에서는 다음과 같은 문제가 발생할 수 있습니다.

잘못된 인증서로 인해 다음 명령어가 시간 초과되고 오류가 반환될 수 있습니다.
- gkectl create admin
- gkectl upgrade amdin
- gkectl update admin
이러한 명령어는 다음과 같은 승인 오류를 반환할 수 있습니다.
```
Failed to reconcile admin cluster: unable to populate admin clients: failed to get admin controller runtime client: Unauthorized
```

관리자 클러스터의 kube-apiserver 로그에 다음과 같은 오류가 포함될 수 있습니다.

Unable to authenticate the request" err="[x509: certificate has expired or is not yet valid...

해결 방법:

수정사항이 포함된 Google Distributed Cloud 버전(1.13.10 이상, 1.14.6 이상, 1.15.2 이상)으로 업그레이드합니다. 업그레이드할 수 없는 경우 Cloud Customer Care에 문의하여 이 문제를 해결하세요.

네트워킹, 운영

1.10, 1.11, 1.12, 1.13, 1.14

우선순위 클래스 누락으로 인해 제거되거나 대기 중인 Anthos Network Gateway 구성요소

kube-system의 네트워크 게이트웨이 포드에서 다음에 요약된 출력 예시와 같이 Pending 또는 Evicted 상태를 표시할 수 있습니다.

$ kubectl -n kube-system get pods | grep ang-node
ang-node-bjkkc     2/2     Running     0     5d2h
ang-node-mw8cq     0/2     Evicted     0     6m5s
ang-node-zsmq7     0/2     Pending     0     7h

이러한 오류는 제거 이벤트 또는 노드 리소스로 인해 포드를 예약할 수 없음을 나타냅니다. Anthos Network Gateway 포드에는 PriorityClass가 없으므로 다른 워크로드와 같은 기본 우선순위가 있습니다. 노드에 리소스 제약이 있으면 네트워크 게이트웨이 포드가 삭제될 수 있습니다. 이 동작은 특히 ang-node DaemonSet에 좋지 않습니다. 이러한 포드는 특정 노드에 예약되어야 하며 마이그레이션할 수 없기 때문입니다.

해결 방법:

1.15 이상으로 업그레이드합니다.

단기적으로 문제를 해결하려면 PriorityClass를 수동으로 Anthos Network Gateway 구성요소에 할당합니다. Google Distributed Cloud 컨트롤러는 클러스터 업그레이드와 같은 조정 프로세스 중에 이러한 수동 변경 사항을 덮어씁니다.

system-cluster-critical PriorityClass를 ang-controller-manager 및 autoscaler 클러스터 컨트롤러 배포에 할당합니다.
system-node-critical PriorityClass를 ang-daemon 노드 DaemonSet에 할당합니다.

업그레이드, 업데이트

1.12, 1.13, 1.14, 1.15.0-1.15.2

gcloud로 클러스터를 등록한 후 관리자 클러스터 업그레이드 실패

gcloud를 사용하여 비어 있지 않은 gkeConnect 섹션으로 관리자 클러스터를 등록한 후 클러스터를 업그레이드하려고 할 때 다음 오류가 표시될 수 있습니다.

failed to register cluster: failed to apply Hub Mem\
bership: Membership API request failed: rpc error: code = InvalidArgument desc = InvalidFieldError for field endpoint.o\
n_prem_cluster.admin_cluster: field cannot be updated

gke-connect 네임스페이스를 삭제합니다.

kubectl delete ns gke-connect --kubeconfig=ADMIN_KUBECONFIG

관리자 클러스터 이름을 가져옵니다.

kubectl get onpremadmincluster -n kube-system --kubeconfig=ADMIN_KUBECONFIG

Fleet 멤버십을 삭제합니다.

gcloud container fleet memberships delete ADMIN_CLUSTER_NAME

관리자 클러스터 업그레이드를 재개합니다.

작업

1.13.0-1.13.8, 1.14.0-1.14.5, 1.15.0-1.15.1

`gkectl diagnose snapshot --log-since`가 클러스터 노드에서 실행되는 `journalctl` 명령어의 기간을 제한하지 못함

스냅샷에는 클러스터 노드에서 journalctl를 실행하여 기본적으로 수집되는 모든 로그가 포함되어 있으므로 클러스터의 스냅샷 생성 기능에는 영향을 주지 않습니다. 따라서 디버깅 정보가 누락되지 않습니다.

설치, 업그레이드, 업데이트

1.9+, 1.10+, 1.11+, 1.12+

`gkectl prepare windows` 실패

MicrosoftDockerProvider가 지원 중단되었기 때문에 gkectl prepare windows는 1.13 이전 버전의 Google Distributed Cloud에 Docker를 설치할 수 없습니다.

해결 방법:

이 문제를 해결하는 일반적인 방법은 Google Distributed Cloud 1.13으로 업그레이드하고 1.13 gkectl을 사용하여 Windows VM 템플릿을 만든 다음 Windows 노드 풀을 만드는 것입니다. 아래와 같이 현재 버전에서 Google Distributed Cloud 1.13으로 업그레이드하는 두 가지 옵션이 있습니다.

참고: 1.13으로 업그레이드할 필요 없이 현재 버전에서 이 문제를 해결할 수 있는 방법이 있지만, 더 많은 수동 단계가 필요합니다. 이 옵션을 고려하려면 지원팀에 문의하세요.

옵션 1: 블루/그린 업그레이드

Windows 노드 풀이 있는 Google Distributed Cloud 1.13 이상 버전을 사용하여 새 클러스터를 만들고 새 클러스터로 워크로드를 마이그레이션한 후 현재 클러스터를 해체할 수 있습니다. 최신 Google Distributed Cloud 마이너 버전을 사용하는 것이 좋습니다.

참고: 이렇게 하려면 새 클러스터를 프로비저닝하기 위해 추가 리소스가 필요하지만 기존 워크로드에 대한 다운타임 및 중단이 감소합니다.

옵션 2: Windows 노드 풀을 삭제했다가 Google Distributed Cloud 1.13으로 업그레이드할 때 다시 추가하기

참고: 이 옵션의 경우 클러스터를 1.13으로 업그레이드하고 Windows 노드 풀을 다시 추가할 때까지는 Windows 워크로드를 실행할 수 없습니다.

user-cluster.yaml 파일에서 Windows 노드 풀 구성을 삭제하여 기존 Windows 노드 풀을 삭제한 후 다음 명령어를 실행합니다.
```
gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE
```
해당 대상 부 버전의 업그레이드 사용자 가이드에 따라 Linux 전용 관리자+사용자 클러스터를 1.12로 업그레이드합니다.
(1.13으로 업그레이드하기 전에 이 단계를 수행해야 함) enableWindowsDataplaneV2: true가 OnPremUserCluster CR에 구성되어 있는지 확인합니다. 그렇지 않으면 클러스터가 Docker가 설치되지 않은 새로 생성된 1.13 Windows VM 템플릿과 호환되지 않는 Windows 노드 풀에 Docker를 계속 사용합니다. 구성되지 않았거나 false로 설정된 경우, 클러스터를 업데이트하여 user-cluster.yaml에서 true로 설정하고 다음을 실행합니다.
```
gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE
```
업그레이드 사용자 가이드에 따라 Linux 전용 관리자+사용자 클러스터를 1.13으로 업그레이드합니다.

1.13 gkectl을 사용해서 Windows VM 템플릿을 준비합니다.

gkectl prepare windows --base-vm-template BASE_WINDOWS_VM_TEMPLATE_NAME --bundle-path 1.13_BUNDLE_PATH --kubeconfig=ADMIN_KUBECONFIG

user-cluster.yaml에서 OSImage 필드를 새로 만든 Windows VM 템플릿으로 설정하여 Windows 노드 풀 구성을 다시 추가합니다.

클러스터를 업데이트하여 Windows 노드 풀을 추가합니다.

gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE

설치, 업그레이드, 업데이트

1.13.0-1.13.9, 1.14.0-1.14.5, 1.15.0-1.15.1

`RootDistanceMaxSec` 구성이 `ubuntu` 노드에 적용되지 않음

예상 구성인 20초 대신 RootDistanceMaxSec의 5초 기본값이 노드에 사용됩니다. `/var/log/startup.log`에 있는 VM에 SSH를 통해 연결하여 노드 시작 로그를 확인하면 다음 오류를 찾을 수 있습니다.

+ has_systemd_unit systemd-timesyncd
/opt/bin/master.sh: line 635: has_systemd_unit: command not found

5초 RootDistanceMaxSec를 사용하면 클럭 드리프트가 5초보다 큰 경우 시스템 클럭이 NTP 서버와 동기화되지 않을 수 있습니다.

해결 방법:

클러스터에 다음 DaemonSet를 적용하여 RootDistanceMaxSec를 구성합니다.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: change-root-distance
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: change-root-distance
  template:
    metadata:
      labels:
        app: change-root-distance
    spec:
      hostIPC: true
      hostPID: true
      tolerations:
      # Make sure pods gets scheduled on all nodes.
      - effect: NoSchedule
        operator: Exists
      - effect: NoExecute
        operator: Exists
      containers:
      - name: change-root-distance
        image: ubuntu
        command: ["chroot", "/host", "bash", "-c"]
        args:
        - |
          while true; do
            conf_file="/etc/systemd/timesyncd.conf.d/90-gke.conf"
            if [ -f $conf_file ] && $(grep -q "RootDistanceMaxSec=20" $conf_file); then
              echo "timesyncd has the expected RootDistanceMaxSec, skip update"
            else
              echo "updating timesyncd config to RootDistanceMaxSec=20"
              mkdir -p /etc/systemd/timesyncd.conf.d
              cat > $conf_file << EOF
          [Time]
          RootDistanceMaxSec=20
          EOF
              systemctl restart systemd-timesyncd
            fi
            sleep 600
          done
        volumeMounts:
        - name: host
          mountPath: /host
        securityContext:
          privileged: true
      volumes:
      - name: host
        hostPath:
          path: /

업그레이드, 업데이트

1.12.0-1.12.6, 1.13.0-1.13.6, 1.14.0-1.14.2

`osImageType` 필드가 비어 있어 `gkectl update admin`이 실패함

버전 1.13 gkectl을 사용하여 버전 1.12 관리자 클러스터를 업데이트하면 다음 오류가 표시될 수 있습니다.

Failed to update the admin cluster: updating OS image type in admin cluster
is not supported in "1.12.x-gke.x"

버전 1.13 또는 1.14 클러스터에 gkectl update admin을 사용하면 응답에 다음 메시지가 표시될 수 있습니다.

Exit with error:
Failed to update the cluster: the update contains multiple changes. Please
update only one feature at a time

gkectl 로그를 확인하면 osImageType을 빈 문자열에서 ubuntu_containerd로 설정하는 등 여러 변경 사항이 있습니다.

이러한 업데이트 오류는 버전 1.9에서 도입된 이후 관리자 클러스터 구성의 osImageType 필드의 잘못된 백필이 원인입니다.

해결 방법:

수정사항이 적용된 Google Distributed Cloud 버전으로 업그레이드합니다. 업그레이드할 수 없는 경우 Cloud Customer Care에 문의하여 이 문제를 해결하세요.

설치, 보안

1.13, 1.14, 1.15, 1.16

SNI가 Controlplane V2를 사용하는 사용자 클러스터에서 작동하지 않음

Controlplane V2가 사용 설정(enableControlplaneV2: true)된 경우 authentication.sni로 사용자 클러스터의 Kubernetes API 서버에 추가 제공 인증서를 제공하는 기능이 작동하지 않습니다.

해결 방법:

Google Distributed Cloud 패치를 수정사항과 사용할 수 있을 때까지 SNI를 사용해야 하는 경우 Controlplane V2(enableControlplaneV2: false)를 사용 중지합니다.

설치

1.0-1.11, 1.12, 1.13.0-1.13.9, 1.14.0-1.14.5, 1.15.0-1.15.1

비공개 레지스트리 사용자 이름의 `$`로 인해 관리자 컨트롤 플레인 머신 시작 실패

비공개 레지스트리 사용자 이름에 $가 포함된 경우 관리자 컨트롤 플레인 머신이 시작되지 않습니다. 관리자 컨트롤 플레인 머신에서 /var/log/startup.log를 확인하면 다음 오류가 표시됩니다.

++ REGISTRY_CA_CERT=xxx
++ REGISTRY_SERVER=xxx
/etc/startup/startup.conf: line 7: anthos: unbound variable

해결 방법:

$가 없는 비공개 레지스트리 사용자 이름을 사용하거나 수정 사항이 적용된 Google Distributed Cloud 버전을 사용하세요.

업그레이드, 업데이트

1.12.0-1.12.4

관리자 클러스터 업데이트 중 지원되지 않는 변경사항에 대한 거짓양성 경고

관리자 클러스터를 업데이트할 때 로그에 다음과 같은 거짓양성 경고가 표시되지만 무시하면 됩니다.

    console.go:47] detected unsupported changes: &v1alpha1.OnPremAdminCluster{
      ...
      -         CARotation:        &v1alpha1.CARotationConfig{Generated: &v1alpha1.CARotationGenerated{CAVersion: 1}},
      +         CARotation:        nil,
      ...
    }

업그레이드, 업데이트

1.13.0-1.13.9, 1.14.0-1.14.5, 1.15.0-1.15.1

KSA 서명 키 순환 후 사용자 클러스터 업데이트 실패

KSA 서명 키를 순환한 후 바로 사용자 클러스터를 업데이트하면 gkectl update가 실패하고 다음 오류 메시지가 표시될 수 있습니다.

Failed to apply OnPremUserCluster 'USER_CLUSTER_NAME-gke-onprem-mgmt/USER_CLUSTER_NAME':
admission webhook "vonpremusercluster.onprem.cluster.gke.io" denied the request:
requests must not decrement *v1alpha1.KSASigningKeyRotationConfig Version, old version: 2, new version: 1"

해결 방법:

KSA 서명 키 버전을 다시 1로 변경하되 최신 키 데이터는 유지합니다.

관리자 클러스터의 USER_CLUSTER_NAME 네임스페이스에서 보안 비밀을 확인하고 ksa-signing-key 보안 비밀 이름을 가져옵니다.
```
kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME get secrets | grep ksa-signing-key
```

ksa-signing-key 보안 비밀을 복사하고 복사한 보안 비밀의 이름을 service-account-cert로 지정합니다.

kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME get secret KSA-KEY-SECRET-NAME -oyaml | \
sed 's/ name: .*/ name: service-account-cert/' | \
kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME apply -f -

이전의 ksa-signing-key 보안 비밀을 삭제합니다.

kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME delete secret KSA-KEY-SECRET-NAME

ksa-signing-key-rotation-stage configma의 data.data 필드를 '{"tokenVersion":1,"privateKeyVersion":1,"publicKeyVersions":[1]}'로 업데이트합니다.
```
kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME \
edit configmap ksa-signing-key-rotation-stage
```

검증 웹훅을 사용 중지하여 OnPremUserCluster 커스텀 리소스에서 버전 정보를 수정합니다.

kubectl --kubeconfig=ADMIN_KUBECONFIG patch validatingwebhookconfiguration onprem-user-cluster-controller -p '
webhooks:
- name: vonpremnodepool.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    resources:
    - onpremnodepools
- name: vonpremusercluster.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    resources:
    - onpremuserclusters
'

OnPremUserCluster 커스텀 리소스에서 spec.ksaSigningKeyRotation.generated.ksaSigningKeyRotation 필드를 1로 업데이트합니다.
```
kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME-gke-onprem-mgmt \
edit onpremusercluster USER_CLUSTER_NAME
```
대상 사용자 클러스터가 준비될 때까지 다음과 같이 상태를 확인할 수 있습니다.
```
kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME-gke-onprem-mgmt \
get onpremusercluster
```

사용자 클러스터의 검증 웹훅을 복원합니다.

kubectl --kubeconfig=ADMIN_KUBECONFIG patch validatingwebhookconfiguration onprem-user-cluster-controller -p '
webhooks:
- name: vonpremnodepool.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    - UPDATE
    resources:
    - onpremnodepools
- name: vonpremusercluster.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    - UPDATE
    resources:
    - onpremuserclusters
'

클러스터가 수정사항이 적용된 버전으로 업그레이드될 때까지 다른 KSA 서명 키 순환을 사용하지 마세요.

작업

1.13.1+, 1.14, 1., 1.16

Terraform이 사용자 클러스터를 삭제할 때 F5 BIG-IP 가상 서버가 삭제되지 않음

Terraform을 사용하여 F5 BIG-IP 부하 분산기가 있는 사용자 클러스터를 삭제할 때는 클러스터 삭제 후 F5 BIG-IP 가상 서버가 삭제되지 않습니다.

해결 방법:

F5 리소스를 삭제하려면 사용자 클러스터 F5 파티션을 삭제하는 단계를 따릅니다.

설치, 업그레이드, 업데이트

1.13.8, 1.14.4

종류 클러스터가 `docker.io`에서 컨테이너 이미지를 가져옴

버전 1.13.8 또는 버전 1.14.4 관리자 클러스터를 만들거나 관리자 클러스터를 버전 1.13.8 또는 1.14.4로 업그레이드하면 종류 클러스터가 docker.io에서 다음 컨테이너 이미지를 가져옵니다.

docker.io/kindest/kindnetd

docker.io/kindest/local-path-provisioner

docker.io/kindest/local-path-helper

관리자 워크스테이션에서 docker.io에 액세스할 수 없으면 관리자 클러스터 만들기 또는 업데이트 중 kind 클러스터를 가져올 수 없습니다. 관리자 워크스테이션에서 다음 명령어를 실행하면 해당 컨테이너가 ErrImagePull로 보류 중인 것으로 표시됩니다.

docker exec gkectl-control-plane kubectl get pods -A

응답에는 다음과 같은 항목이 포함됩니다.

...
kube-system         kindnet-xlhmr                             0/1
    ErrImagePull  0    3m12s
...
local-path-storage  local-path-provisioner-86666ffff6-zzqtp   0/1
    Pending       0    3m12s
...

이러한 컨테이너 이미지는 kind 클러스터 컨테이너 이미지에 미리 로드됩니다. 하지만 v0.18.0 종류에는 미리 로드된 컨테이너 이미지 관련 문제가 있으며 실수로 인터넷에서 이미지를 가져옵니다.

해결 방법:

관리자 클러스터가 생성 또는 업그레이드에 대해 대기하는 동안 관리자 워크스테이션에서 다음 명령어를 실행합니다.

docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/kindnetd:v20230330-48f316cd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af docker.io/kindest/kindnetd:v20230330-48f316cd
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/kindnetd:v20230330-48f316cd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af docker.io/kindest/kindnetd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af

docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-helper:v20230330-48f316cd@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270 docker.io/kindest/local-path-helper:v20230330-48f316cd
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-helper:v20230330-48f316cd@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270 docker.io/kindest/local-path-helper@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270

docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-provisioner:v0.0.23-kind.0@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501 docker.io/kindest/local-path-provisioner:v0.0.23-kind.0
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-provisioner:v0.0.23-kind.0@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501 docker.io/kindest/local-path-provisioner@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501

작업

1.13.0-1.13.7, 1.14.0-1.14.4, 1.15.0

네트워크에서 중복 GARP 요청을 필터링할 때 HA Controlplane V2 사용자 클러스터 및 관리자 클러스터에서 장애 조치 실패

클러스터 VM이 중복 GARP(Gratuitous ARP) 요청을 필터링하는 스위치와 연결된 경우 연결 유지된 리더 선택에서 경합 상태가 발생할 수 있으며 이로 인해 일부 노드에서 잘못된 ARP 표 항목이 발생할 수 있습니다.

영향을 받는 노드는 컨트롤 플레인 VIP를 ping할 수 있지만 컨트롤 플레인 VIP에 대한 TCP 연결은 제한 시간에 도달합니다.

해결 방법:

영향을 받는 클러스터의 각 컨트롤 플레인 노드에서 다음 명령어를 실행합니다.

    iptables -I FORWARD -i ens192 --destination CONTROL_PLANE_VIP -j DROP

업그레이드, 업데이트

1.13.0-1.13.7, 1.14.0-1.14.4, 1.15.0

vCenter 인증서 순환 후 `vsphere-csi-controller`를 다시 시작해야 함

vsphere-csi-controller는 vCenter 인증서 순환 후 해당 vCenter 보안 비밀을 새로고침합니다. 하지만 현재 시스템이 vsphere-csi-controller의 포드를 올바르게 다시 시작하지 않아 순환 후 vsphere-csi-controller가 비정상 종료됩니다.

해결 방법:

1.13 이상 버전에서 만들어진 클러스터의 경우 아래 안내에 따라 vsphere-csi-controller를 다시 시작합니다.

kubectl --kubeconfig=ADMIN_KUBECONFIG rollout restart deployment vsphere-csi-controller -n kube-system

설치

1.10.3-1.10.7, 1.11, 1.12, 1.13.0-1.13.1

클러스터 등록 오류 시 관리자 클러스터 생성이 실패하지 않음

관리자 클러스터를 만드는 동안 클러스터 등록이 실패하더라도 해당 오류로 gkectl create admin 명령어가 실패하지 않고 성공할 수 있습니다. 즉, 관리자 클러스터 만들기가 Fleet에 등록하지 않고도 '성공'할 수 있습니다.

증상을 식별하기 위해 `gkectl create admin` 로그에서 다음 오류 메시지를 찾을 수 있습니다.

Failed to register admin cluster

또한 Cloud 콘솔에서 등록된 클러스터 간에 클러스터를 찾을 수 있는지 확인할 수 있습니다.

해결 방법:

1.12 이상 버전에서 만들어진 클러스터의 경우 클러스터를 만든 후 안내에 따라 관리자 클러스터 등록을 재시도합니다. 이전 버전에서 만들어진 클러스터의 경우 다음을 수행합니다.

연결-등록 SA 키 파일에 'foo. bar' 같은 가짜 키-값 쌍을 추가합니다.
gkectl update admin을 실행하여 관리자 클러스터를 다시 등록합니다.

업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13.0-1.13.1

관리자 클러스터 업그레이드 중에 관리자 클러스터 재등록을 건너뛸 수 있음

관리자 클러스터 업그레이드 중에 사용자 컨트롤 플레인 노드 업그레이드가 제한 시간에 도달하면 관리자 클러스터는 업데이트된 연결 에이전트 버전에 다시 등록되지 않습니다.

해결 방법:

클러스터가 등록된 클러스터에 표시되는지 확인합니다. 선택 사항으로 인증을 설정한 후 클러스터에 로그인합니다. 클러스터가 여전히 등록된 경우 등록 재시도를 위한 안내를 건너뛸 수 있습니다. 1.12 이상 버전으로 업그레이드된 클러스터의 경우 클러스터를 만든 후 안내에 따라 관리자 클러스터 등록을 재시도합니다. 이전 버전으로 업그레이드된 클러스터의 경우 다음을 수행합니다.

연결-등록 SA 키 파일에 'foo. bar' 같은 가짜 키-값 쌍을 추가합니다.
gkectl update admin을 실행하여 관리자 클러스터를 다시 등록합니다.

구성

1.15.0

`vCenter.dataDisk`에 대한 거짓 오류 메시지

고가용성 관리자 클러스터의 경우 gkectl prepare에 이 거짓 오류 메시지가 표시됩니다.

vCenter.dataDisk must be present in the AdminCluster spec

해결 방법:

이 오류 메시지는 무시해도 됩니다.

VMware

1.15.0

중복 VM-호스트 어피니티 규칙으로 인해 노드 풀 만들기 실패

VM-호스트 어피니티를 사용하는 노드 풀을 만드는 동안 경합 상태로 인해 같은 이름으로 생성된 여러 VM-호스트 어피니티 규칙이 발생할 수 있습니다 이로 인해 노드 풀 생성이 실패할 수 있습니다.

해결 방법:

노드 풀 만들기를 진행할 수 있도록 이전 중복 규칙을 삭제합니다. 이러한 규칙은 이름이 [USER_CLUSTER_NAME]-[HASH]입니다.

작업

1.15.0

`failed to delete the admin master node object and reboot the admin master VM`으로 인해 `gkectl repair admin-master`가 실패할 수 있음

경합 상태로 인해 다음 오류와 함께 gkectl repair admin-master 명령어가 실패할 수 있습니다.

Failed to repair: failed to delete the admin master node object and reboot the admin master VM

해결 방법:

이 명령어는 멱등성을 갖습니다. 명령어가 성공할 때까지 안전하게 재실행할 수 있습니다.

업그레이드, 업데이트

1.15.0

컨트롤 플레인 노드의 재생성 또는 업데이트 후 포드가 Failed 상태로 유지됨

컨트롤 플레인 노드를 다시 만들거나 업데이트한 후에는 NodeAffinity 조건자 실패로 인해 특정 포드가 Failed 상태로 남아 있을 수 있습니다. 실패한 포드는 일반적인 클러스터 작업 또는 상태에 영향을 주지 않습니다.

해결 방법:

실패한 포드를 무시하거나 수동으로 삭제할 수 있습니다.

보안, 구성

1.15.0-1.15.1

비공개 레지스트리 사용자 인증 정보로 인해 OnPremUserCluster가 준비되지 않음

준비된 사용자 인증 정보 및 비공개 레지스트리를 사용하지만 비공개 레지스트리에 준비된 사용자 인증 정보가 구성되어 있지 않으면 OnPremUserCluster가 준비되지 않을 수 있으며 다음 오류 메시지가 표시될 수 있습니다.

failed to check secret reference for private registry …

해결 방법:

준비된 사용자 인증 정보 구성의 안내에 따라 사용자 클러스터에 대해 비공개 레지스트리 사용자 인증 정보를 준비합니다.

업그레이드, 업데이트

1.15.0

`gkectl upgrade admin`가 `StorageClass standard sets the parameter diskformat which is invalid for CSI Migration` 와 함께 실패

gkectl upgrade admin 중에 CSI 마이그레이션의 스토리지 프리플라이트 검사는 StorageClasses에 CSI 마이그레이션 후에 무시되는 파라미터가 없는지 확인합니다. 예를 들어 diskformat 파라미터가 있는 StorageClass가 있으면 gkectl upgrade admin은 StorageClass를 표시하고 프리플라이트 검증에 실패를 보고합니다. Google Distributed Cloud 1.10 이전 버전에서 생성된 관리자 클러스터에는 이 유효성 검사에 실패하는 diskformat: thin이 있는 StorageClass가 있지만 이 StorageClass는 CSI 마이그레이션 후에도 여전히 정상적으로 작동합니다. 이러한 오류는 대신 경고로 해석해야 합니다.

자세한 내용은 트리 내 vSphere 볼륨을 vSphere 컨테이너 스토리지 플러그인으로 마이그레이션의 StorageClass 파라미터 섹션을 참조하세요.

해결 방법:

클러스터에 CSI 마이그레이션 실행 후 파라미터가 무시된 StorageClass가 있는지 확인한 후 gkectl upgrade admin을 --skip-validation-cluster-health 플래그와 함께 실행합니다.

스토리지

1.15, 1.16

Windows 파일 시스템을 사용하여 마이그레이션된 트리 내 vSphere 볼륨은 vSphere CSI 드라이버와 함께 사용할 수 없음

특정 조건에서는 디스크를 Windows 노드에 읽기 전용으로 연결할 수 있습니다. 이렇게 연결하면 해당 볼륨이 포드 내에서 읽기 전용이 됩니다. 이 문제는 새로운 노드 집합이 이전 노드 집합을 대체하는 경우에 발생할 가능성이 높습니다(예: 클러스터 업그레이드 또는 노드 풀 업데이트). 이전에 올바르게 작동한 스테이트풀(Stateful) 워크로드가 새로운 노드 집합에서 볼륨에 쓰기를 수행하지 못할 수 있습니다.

해결 방법:

볼륨에 쓰기를 수행할 수 없는 포드의 UID를 가져옵니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get pod \
    POD_NAME --namespace POD_NAMESPACE \
    -o=jsonpath='{.metadata.uid}{"\n"}'

PersistentVolumeClaim을 사용하여 PersistentVolume 이름을 가져옵니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get pvc \
    PVC_NAME --namespace POD_NAMESPACE \
    -o jsonpath='{.spec.volumeName}{"\n"}'

포드가 실행 중인 노드 이름을 확인합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIGget pods \
    --namespace POD_NAMESPACE \
    -o jsonpath='{.spec.nodeName}{"\n"}'

SSH 또는 vSphere 웹 인터페이스를 통해 노드에 대한 Powershell 액세스 권한을 얻습니다.

환경 변수를 설정합니다.

PS C:\Users\administrator> pvname=PV_NAME
PS C:\Users\administrator> podid=POD_UID

PersistentVolume과 연결된 디스크의 디스크 번호를 식별합니다.

PS C:\Users\administrator> disknum=(Get-Partition -Volume (Get-Volume -UniqueId ("\\?\"+(Get-Item (Get-Item
"C:\var\lib\kubelet\pods\$podid\volumes\kubernetes.io~csi\$pvname\mount").Target).Target))).DiskNumber

디스크가 readonly인지 확인합니다.
```
PS C:\Users\administrator> (Get-Disk -Number $disknum).IsReadonly
```
결과는 True여야 합니다.

readonly을 false로 설정합니다.

PS C:\Users\administrator> Set-Disk -Number $disknum -IsReadonly $false
PS C:\Users\administrator> (Get-Disk -Number $disknum).IsReadonly

포드가 다시 시작되도록 삭제합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete pod POD_NAME \
    --namespace POD_NAMESPACE

포드는 동일한 노드에 예약되어야 합니다. 그러나 포드가 새 노드에 예약되는 경우 새 노드에서 이전 단계를 반복해야 할 수 있습니다.

업그레이드, 업데이트

1.12, 1.13.0-1.13.7, 1.14.0-1.14.4

`vsphere-csi-secret`가 `gkectl update credentials vsphere --admin-cluster` 이후에 업데이트되지 않음

클러스터 사용자 인증 정보 업데이트 후 관리자 클러스터의 vSphere 사용자 인증 정보를 업데이트하는 경우 관리자 클러스터의 kube-system 네임스페이스 아래에 vsphere-csi-secret이 여전히 이전 사용자 인증 정보를 사용하는 경우가 있습니다.

해결 방법:

vsphere-csi-secret 보안 비밀을 가져옵니다.

kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system get secrets | grep vsphere-csi-secret

이전 단계에서 가져온 vsphere-csi-secret 보안 비밀의 데이터를 업데이트합니다.

kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system patch secret CSI_SECRET_NAME -p \
  "{\"data\":{\"config\":\"$( \
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system get secrets CSI_SECRET_NAME -ojsonpath='{.data.config}' \
      | base64 -d \
      | sed -e '/user/c user = \"VSPHERE_USERNAME_TO_BE_UPDATED\"' \
      | sed -e '/password/c password = \"VSPHERE_PASSWORD_TO_BE_UPDATED\"' \
      | base64 -w 0 \
    )\"}}"

vsphere-csi-controller를 다시 시작합니다.

kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system rollout restart deployment vsphere-csi-controller

다음 명령어를 사용하여 출시 상태를 추적할 수 있습니다.
```
kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system rollout status deployment vsphere-csi-controller
```
배포가 성공적으로 출시되면 컨트롤러에서 업데이트된 vsphere-csi-secret을 사용해야 합니다.

업그레이드, 업데이트

1.10, 1.11, 1.12.0-1.12.6, 1.13.0-1.13.6, 1.14.0-1.14.2

`gkectl update cluster`로 Cloud 감사 로그를 사용 설정할 때 `audit-proxy` 비정상 종료 루프 발생

--cluster-name이 비어 있기 때문에 audit-proxy 비정상 종료 루프가 발생할 수 있습니다. 이 동작은 클러스터 이름이 감사 프록시 포드/컨테이너 매니페스트에 전파되지 않는 업데이트 로직의 버그로 인해 발생합니다.

해결 방법:

enableControlplaneV2: true가 있는 컨트롤 플레인 v2 사용자 클러스터의 경우 SSH를 사용하여 사용자 컨트롤 플레인 머신에 연결하고 /etc/kubernetes/manifests/audit-proxy.yaml을 --cluster_name=USER_CLUSTER_NAME으로 업데이트합니다.

컨트롤 플레인 v1 사용자 클러스터의 경우 kube-apiserver Statefulset에서 audit-proxy 컨테이너를 수정하여 --cluster_name=USER_CLUSTER_NAME을 추가합니다.

kubectl edit statefulset kube-apiserver -n USER_CLUSTER_NAME --kubeconfig=ADMIN_CLUSTER_KUBECONFIG

업그레이드, 업데이트

1.11, 1.12, 1.13.0-1.13.5, 1.14.0-1.14.1

`gkectl upgrade cluster` 직후의 추가 컨트롤 플레인 재배포

gkectl upgrade cluster 실행 직후 컨트롤 플레인 포드가 다시 배포될 수 있습니다. gkectl list clusters의 클러스터 상태가 RUNNING에서 RECONCILING으로 변경됩니다. 사용자 클러스터에 대한 요청이 제한 시간에 도달할 수 있습니다.

이 동작은 gkectl upgrade cluster 이후 컨트롤 플레인 인증서 순환이 자동으로 수행되기 때문입니다.

이 문제는 컨트롤 플레인 v2를 사용하지 않는 사용자 클러스터에만 발생합니다.

해결 방법:

클러스터 상태가 gkectl list clusters에서 다시 RUNNING으로 변경될 때까지 기다리거나 1.13.6 이상, 1.14.2 이상 또는 1.15 이상의 수정사항이 있는 버전으로 업그레이드합니다.

업그레이드, 업데이트

1.12.7

잘못된 출시 버전 1.12.7-gke.19가 삭제됨

Google Distributed Cloud 1.12.7-gke.19는 잘못된 출시 버전이며 사용해서는 안 됩니다. 아티팩트가 Cloud Storage 버킷에서 삭제되었습니다.

해결 방법:

대신 1.12.7-gke.20 출시 버전을 사용하세요.

업그레이드, 업데이트

1.12.0+, 1.13.0-1.13.7, 1.14.0-1.14.3

`gke-connect-agent`가 레지스트리 사용자 인증 정보가 업데이트된 후에도 이전 이미지를 계속 사용함

다음 방법 중 하나를 사용하여 레지스트리 사용자 인증 정보를 업데이트하는 경우

비공개 레지스트리를 사용하지 않는 경우 gkectl update credentials componentaccess
비공개 레지스트리를 사용하는 경우 gkectl update credentials privateregistry

gke-connect-agent가 이전 이미지를 계속 사용하거나 ImagePullBackOff로 인해 gke-connect-agent 포드를 가져올 수 없는 것을 발견할 수 있습니다.

이 문제는 Google Distributed Cloud 릴리스 1.13.8, 1.14.4 및 이후 릴리스에서 수정될 예정입니다.

해결 방법:

옵션 1: gke-connect-agent를 수동으로 재배포

gke-connect 네임스페이스를 삭제합니다.

kubectl --kubeconfig=KUBECONFIG delete namespace gke-connect

원래의 등록 서비스 계정 키로 gke-connect-agent를 다시 배포합니다(키를 업데이트할 필요 없음).

관리자 클러스터의 경우:

gkectl update credentials register --kubeconfig=ADMIN_CLUSTER_KUBECONFIG --config ADMIN_CLUSTER_CONFIG_FILE --admin-cluster

사용자 클러스터의 경우:

gkectl update credentials register --kubeconfig=ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE

옵션 2. gke-connect-agent 배포에 사용되는 이미지 가져오기 보안 비밀 regcred의 데이터를 수동으로 변경할 수 있습니다.

kubectl --kubeconfig=KUBECONFIG -n=gke-connect patch secrets regcred -p "{\"data\":{\".dockerconfigjson\":\"$(kubectl --kubeconfig=KUBECONFIG -n=kube-system get secrets private-registry-creds -ojsonpath='{.data.\.dockerconfigjson}')\"}}"

옵션 3. 다음과 같이 gke-connect-agent 배포에 클러스터에 대한 기본 이미지 가져오기 보안 비밀을 추가할 수 있습니다.

기본 보안 비밀을 gke-connect 네임스페이스에 복사합니다.

kubectl --kubeconfig=KUBECONFIG -n=kube-system get secret private-registry-creds -oyaml | sed 's/ namespace: .*/ namespace: gke-connect/' | kubectl --kubeconfig=KUBECONFIG -n=gke-connect apply -f -

gke-connect-agent 배포 이름을 가져옵니다.

kubectl --kubeconfig=KUBECONFIG -n=gke-connect get deployment | grep gke-connect-agent

gke-connect-agent 배포에 기본 보안 비밀을 추가합니다.

kubectl --kubeconfig=KUBECONFIG -n=gke-connect patch deployment DEPLOYMENT_NAME -p '{"spec":{"template":{"spec":{"imagePullSecrets": [{"name": "private-registry-creds"}, {"name": "regcred"}]}}}}'

설치

1.13, 1.14

수동 LB 구성 검사 실패

gkectl check-config를 실행하여 수동 부하 분산기로 클러스터를 만들기 전에 구성을 검증하면 다음 오류 메시지와 함께 명령어가 실패합니다.

 - Validation Category: Manual LB    Running validation check for "Network 
configuration"...panic: runtime error: invalid memory address or nil pointer 
dereference

해결 방법:

옵션 1: 수정사항이 포함된 패치 버전 1.13.7 및 1.14.4를 사용할 수 있습니다.

옵션 2: 동일한 명령어를 실행하여 구성을 검증하되 부하 분산기 유효성 검사는 건너뛸 수 있습니다.

gkectl check-config --skip-validation-load-balancer

작업

1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14

etcd 감시 부족

etcd 버전 3.4.13 이하를 실행하는 클러스터는 감시 부족 및 비작업 리소스 감시를 경험할 수 있으며, 이로 인해 다음 문제가 발생할 수 있습니다.

포드 예약이 중단됨
노드를 등록할 수 없음
kubelet이 포드 변경사항을 관찰하지 못함

이러한 문제로 인해 클러스터가 작동하지 않을 수 있습니다.

이 문제는 Google Distributed Cloud 출시 버전 1.12.7, 1.13.6, 1.14.3과 후속 출시 버전에서 해결되었습니다. 이러한 최신 출시 버전에는 etcd 버전 3.4.21이 사용됩니다. Google Distributed Cloud의 모든 이전 버전은 이 문제의 영향을 받습니다.

해결 방법

즉시 업그레이드할 수 없으면 클러스터의 노드 수를 줄여서 클러스터 실패 위험을 완화할 수 있습니다. etcd_network_client_grpc_sent_bytes_total 측정항목이 300MBps 미만이 될 때까지 노드를 삭제하세요.

측정항목 탐색기에서 이 측정항목을 보려면 다음 안내를 따르세요.

Google Cloud 콘솔의 측정항목 탐색기로 이동합니다.
측정항목 탐색기로 이동
구성 탭을 선택합니다.
측정항목 선택을 확장하고 필터 표시줄에 Kubernetes Container를 입력한 후 하위 메뉴를 사용해서 측정항목을 선택합니다.
1. 활성 리소스 메뉴에서 Kubernetes 컨테이너를 선택합니다.
2. 활성 측정항목 카테고리 메뉴에서 Anthos를 선택합니다.
3. 활성 측정항목 메뉴에서 etcd_network_client_grpc_sent_bytes_total을 선택합니다.
4. 적용을 클릭합니다.

업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13, 1.14

GKE Identity Service로 인해 컨트롤 플레인 지연 시간이 발생할 수 있음

클러스터가 다시 시작되거나 업그레이드될 때 만료된 JWT 토큰으로 구성된 트래픽으로 인해 GKE Identity Service가 과부하될 수 있습니다. 이 토큰은 인증 웹훅을 통해 kube-apiserver에서 GKE Identity Service로 전달됩니다. GKE Identity Service에서 비정상 종료 루프가 발생하지는 않지만 응답 및 추가 요청 처리가 중지됩니다. 이 문제는 결국 높은 컨트롤 플레인 지연 시간으로 이어집니다.

이 문제는 다음 Google Distributed Cloud 출시 버전에서 해결되었습니다.

1.12.6+
1.13.6+
1.14.2+

이 문제의 영향을 받는지 확인하려면 다음 단계를 수행합니다.

외부에서 GKE Identity Service 엔드포인트에 연결할 수 있는지 확인합니다.
```
curl -s -o /dev/null -w "%{http_code}" \
    -X POST https://CLUSTER_ENDPOINT/api/v1/namespaces/anthos-identity-service/services/https:ais:https/proxy/authenticate -d '{}'
```
CLUSTER_ENDPOINT를 클러스터의 컨트롤 플레인 VIP 및 컨트롤 플레인 부하 분산기 포트로 바꿉니다(예: 172.16.20.50:443).

이 문제의 영향을 받는 경우 명령어가 400 상태 코드를 반환합니다. 요청 시간이 초과되면 ais 포드를 다시 시작하고 curl 명령어를 다시 실행하여 문제가 해결되는지 확인하세요. 000 상태 코드가 표시되면 문제가 해결된 것입니다. 계속 400 상태 코드가 표시되면 GKE Identity Service HTTP 서버가 시작하지 않습니다. 이 경우 계속하세요.

GKE Identity Service 및 kube-apiserver 로그를 확인합니다.

GKE Identity Service 로그를 확인합니다.

kubectl logs -f -l k8s-app=ais -n anthos-identity-service \
    --kubeconfig KUBECONFIG

로그에 다음과 같은 항목이 포함되었으면 이 문제의 영향을 받습니다.

I0811 22:32:03.583448      32 authentication_plugin.cc:295] Stopping OIDC authentication for ???. Unable to verify the OIDC ID token: JWT verification failed: The JWT does not appear to be from this identity provider. To match this provider, the 'aud' claim must contain one of the following audiences:

클러스터의 kube-apiserver 로그를 확인하세요.

다음 명령어에서 KUBE_APISERVER_POD는 지정된 클러스터에서 kube-apiserver 포드의 이름입니다.

관리자 클러스터:

kubectl --kubeconfig ADMIN_KUBECONFIG logs \
    -n kube-system KUBE_APISERVER_POD kube-apiserver

사용자 클러스터:

kubectl --kubeconfig ADMIN_KUBECONFIG logs \
    -n USER_CLUSTER_NAME KUBE_APISERVER_POD kube-apiserver

kube-apiserver 로그에 다음과 같은 항목이 포함된 경우 이 문제의 영향을 받는 것입니다.

E0811 22:30:22.656085       1 webhook.go:127] Failed to make webhook authenticator request: error trying to reach service: net/http: TLS handshake timeout
E0811 22:30:22.656266       1 authentication.go:63] "Unable to authenticate the request" err="[invalid bearer token, error trying to reach service: net/http: TLS handshake timeout]"

해결 방법

클러스터를 즉시 업그레이드하여 수정할 수 없는 경우 문제가 되는 포드를 식별하고 다시 시작하여 문제를 해결할 수 있습니다.

GKE ID 서비스 세부정보 수준을 9로 높입니다.

kubectl patch deployment ais -n anthos-identity-service --type=json \
    -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", \
    "value":"--vmodule=cloud/identity/hybrid/charon/*=9"}]' \
    --kubeconfig KUBECONFIG

GKE ID 서비스 로그에서 잘못된 토큰 컨텍스트가 있는지 확인합니다.

kubectl logs -f -l k8s-app=ais -n anthos-identity-service \
    --kubeconfig KUBECONFIG

잘못된 토큰 컨텍스트와 연결된 토큰 페이로드를 가져오려면 다음 명령어를 사용해서 각각의 관련된 서비스 계정 보안 비밀을 파싱합니다.
```
kubectl -n kube-system get secret SA_SECRET \
    --kubeconfig KUBECONFIG \
    -o jsonpath='{.data.token}' | base64 --decode
```
토큰을 디코딩하고 소스 포드 이름과 네임스페이스를 보려면 jwt.io의 디버거에 토큰을 복사합니다.
토큰에서 식별된 포드를 다시 시작합니다.

작업

1.9, 1.10, 1.11, 1.12, 1.13

사용자 클러스터 컨트롤 플레인 포드의 상태 점검 누락

클러스터 상태 컨트롤러와 gkectl diagnose cluster 명령어는 모두 네임스페이스에서 포드 상태 점검을 포함한 일련의 상태 점검을 수행합니다. 하지만 실수로 사용자 컨트롤 플레인 포드를 건너뛰기 시작합니다. 컨트롤 플레인 v2 모드를 사용하는 경우 클러스터에 영향을 주지 않습니다.

해결 방법:

워크로드나 클러스터 관리에는 영향을 주지 않습니다. 컨트롤 플레인 포드 상태를 확인하려면 다음 명령어를 실행하면 됩니다.

kubectl get pods -owide -n USER_CLUSTER_NAME --kubeconfig ADMIN_CLUSTER_KUBECONFIG

네트워킹

1.10, 1.11, 1.12.0-1.12.6, 1.13.0-1.13.6, 1.14.0-1.14.2

부하 분산기 생성 시 Seesaw 검증 실패

다음 오류 메시지와 함께 gkectl create loadbalancer가 실패합니다.

- Validation Category: Seesaw LB - [FAILURE] Seesaw validation: xxx cluster lb health check failed: LB"xxx.xxx.xxx.xxx" is not healthy: Get "http://xxx.xxx.xxx.xxx:xxx/healthz": dial tcpxxx.xxx.xxx.xxx:xxx: connect: no route to host

이는 Seesaw 그룹 파일이 이미 존재하기 때문입니다. 프리플라이트 검사는 존재하지 않는 Seesaw 부하 분산기를 검사합니다.

해결 방법:

이 클러스터의 기존 Seesaw 그룹 파일을 삭제합니다. 파일 이름은 관리자 클러스터의 경우 seesaw-for-gke-admin.yaml, 사용자 클러스터의 경우 seesaw-for-{CLUSTER_NAME}.yaml입니다.

네트워킹

1.14

conntrack 테이블 삽입 실패로 인한 애플리케이션 시간 초과

Google Distributed Cloud 버전 1.14는 Ubuntu 또는 COS 운영체제 이미지를 사용할 때 netfilter 연결 추적 (conntrack) 테이블 삽입 실패에 취약합니다. 삽입 실패로 인해 무작위 애플리케이션 시간 초과가 발생하고, conntrack 테이블에 새 항목을 위한 공간이 있는 경우에도 발생할 수 있습니다. 이러한 실패는 체인 길이를 기준으로 테이블 삽입을 제한하는 커널 5.15 이상의 변경사항으로 인해 발생합니다.

이 문제의 영향을 받는지 확인하려면 다음 명령어를 사용하여 각 노드의 커널 내 연결 추적 시스템 통계를 확인하세요.

sudo conntrack -S

응답은 다음과 같습니다.

cpu=0       found=0 invalid=4 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=1       found=0 invalid=0 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=2       found=0 invalid=16 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=3       found=0 invalid=13 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=4       found=0 invalid=9 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=5       found=0 invalid=1 insert=0 insert_failed=0 drop=0 early_drop=0 error=519 search_restart=0 clash_resolve=126 chaintoolong=0 
...

응답의 chaintoolong 값이 0이 아닌 값이면 이 문제의 영향을 받습니다.

해결 방법

단기적인 완화 방법은 netfiler 해시 테이블(nf_conntrack_buckets)과 netfilter 연결 추적 테이블(nf_conntrack_max)의 크기를 늘리는 것입니다. 각 클러스터 노드에서 다음 명령어를 사용하여 테이블 크기를 늘립니다.

sysctl -w net.netfilter.nf_conntrack_buckets=TABLE_SIZE
sysctl -w net.netfilter.nf_conntrack_max=TABLE_SIZE

TABLE_SIZE를 새 크기(바이트 단위)로 바꿉니다. 기본 테이블 크기 값은 262144입니다. 노드에 있는 코어 수의 65,536배와 동일한 값을 설정하는 것이 좋습니다. 예를 들어 노드에 8개의 코어가 있으면 테이블 크기를 524288로 설정합니다.

네트워킹

1.13.0-1.13.2

Controlplane v2가 있는 Windows 노드에서 calico-typha 또는 anetd-operator 비정상 종료 루프

Controlplane v2 또는 새 설치 모델을 사용하면 calico-typha 또는 anetd-operator가 Windows 노드에 예약되고 비정상 종료 루프에 노출될 수 있습니다.

두 배포가 Windows 노드 taint를 포함한 모든 taint를 허용하도록 하기 때문입니다.

해결 방법:

1.13.3 이상으로 업그레이드하거나 다음 명령어를 실행하여 `calico-typha` 또는 `anetd-operator` 배포를 수정합니다.

    # If dataplane v2 is not used.
    kubectl edit deployment -n kube-system calico-typha --kubeconfig USER_CLUSTER_KUBECONFIG
    # If dataplane v2 is used.
    kubectl edit deployment -n kube-system anetd-operator --kubeconfig USER_CLUSTER_KUBECONFIG

다음 spec.template.spec.tolerations를 삭제합니다.

    - effect: NoSchedule
      operator: Exists
    - effect: NoExecute
      operator: Exists

그리고 다음 톨러레이션(toleration)을 추가합니다.

    - key: node-role.kubernetes.io/master
      operator: Exists

구성

1.14.0-1.14.2

사용자 클러스터 비공개 레지스트리 사용자 인증 정보 파일을 로드할 수 없음

fileRef 사용자 인증 정보를 사용하여 privateRegistry 섹션을 지정하면 사용자 클러스터를 만들지 못할 수 있습니다. 다음 메시지와 함께 프리플라이트가 실패할 수 있습니다.

[FAILURE] Docker registry access: Failed to login.

해결 방법:

필드를 지정할 의도가 없었거나 관리자 클러스터와 동일한 비공개 레지스트리 사용자 인증 정보를 사용하려면 사용자 클러스터 구성 파일에서 privateRegistry 섹션을 삭제하거나 주석 처리하면 됩니다.
사용자 클러스터에 특정 비공개 레지스트리 사용자 인증 정보를 사용하려면 다음과 같이 privateRegistry 섹션을 임시로 지정할 수 있습니다.
```
privateRegistry:
  address: PRIVATE_REGISTRY_ADDRESS
  credentials:
    username: PRIVATE_REGISTRY_USERNAME
    password: PRIVATE_REGISTRY_PASSWORD
  caCertPath: PRIVATE_REGISTRY_CACERT_PATH
```
(참고: 이는 일시적인 수정에 불과하며 이러한 필드는 이미 지원 중단되었습니다. 1.14.3 이상으로 업그레이드할 때 사용자 인증 정보 파일을 사용하는 것이 좋습니다.)

스토리지

1.12+, 1.13.3

`kube-controller-manager`가 6분 후에 영구 볼륨을 강제로 분리할 수 있음

kube-controller-manager가 6분 후 PV/PVC를 분리할 때 시간 초과되면 PV/PVC를 강제로 분리할 수 있습니다. kube-controller-manager의 자세한 로그에서 다음과 유사한 이벤트를 보여줍니다.

$ cat kubectl_logs_kube-controller-manager-xxxx | grep "DetachVolume started" | grep expired

kubectl_logs_kube-controller-manager-gke-admin-master-4mgvr_--container_kube-controller-manager_--kubeconfig_kubeconfig_--request-timeout_30s_--namespace_kube-system_--timestamps:2023-01-05T16:29:25.883577880Z W0105 16:29:25.883446       1 reconciler.go:224] attacherDetacher.DetachVolume started for volume "pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16" (UniqueName: "kubernetes.io/csi/csi.vsphere.vmware.com^126f913b-4029-4055-91f7-beee75d5d34a") on node "sandbox-corp-ant-antho-0223092-03-u-tm04-ml5m8-7d66645cf-t5q8f"
This volume is not safe to detach, but maxWaitForUnmountDuration 6m0s expired, force detaching

문제를 확인하려면 노드에 로그인하고 다음 명령어를 실행합니다.

# See all the mounting points with disks
lsblk -f

# See some ext4 errors
sudo dmesg -T

kubelet 로그에는 다음과 같은 오류가 표시됩니다.

Error: GetDeviceMountRefs check failed for volume "pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16" (UniqueName: "kubernetes.io/csi/csi.vsphere.vmware.com^126f913b-4029-4055-91f7-beee75d5d34a") on node "sandbox-corp-ant-antho-0223092-03-u-tm04-ml5m8-7d66645cf-t5q8f" :
the device mount path "/var/lib/kubelet/plugins/kubernetes.io/csi/pv/pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16/globalmount" is still mounted by other references [/var/lib/kubelet/plugins/kubernetes.io/csi/pv/pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16/globalmount

해결 방법:

SSH를 사용하여 영향을 받는 노드에 연결하고 노드를 재부팅합니다.

업그레이드, 업데이트

1.12+, 1.13+, 1.14+

서드 파티 CSI 드라이버가 사용된 경우 클러스터 업그레이드가 중단됨

서드 파티 CSI 드라이버를 사용하는 경우 클러스터를 업그레이드하지 못할 수 있습니다. gkectl cluster diagnose 명령어가 다음 오류를 반환할 수 있습니다.

"virtual disk "kubernetes.io/csi/csi.netapp.io^pvc-27a1625f-29e3-4e4f-9cd1-a45237cc472c" IS NOT attached to machine "cluster-pool-855f694cc-cjk5c" but IS listed in the Node.Status"

해결 방법:

--skip-validation-all 옵션을 사용하여 업그레이드를 수행합니다.

작업

1.10+, 1.11+, 1.12+, 1.13+, 1.14+

`gkectl repair admin-master`가 VM 하드웨어 버전을 업그레이드하지 않고 관리자 마스터 VM을 생성함

gkectl repair admin-master를 통해 생성된 관리자 마스터 노드는 예상보다 낮은 VM 하드웨어 버전을 사용할 수 있습니다. 문제가 발생하면 gkectl diagnose cluster 보고서에서 오류를 확인할 수 있습니다.

CSIPrerequisites [VM Hardware]: The current VM hardware versions are lower than vmx-15 which is unexpected. Please contact Anthos support to resolve this issue.

해결 방법:

관리자 마스터 노드를 종료하고 https://kb.vmware.com/s/article/1003746을 따라 오류 메시지에 설명된 예상 버전으로 노드를 업그레이드한 다음 노드를 시작합니다.

운영체제

1.10+, 1.11+, 1.12+, 1.13+, 1.14+, 1.15+, 1.16+

예상치 못한 종료 또는 재부팅 시 VM이 DHCP 임대를 해제하여 IP가 변경될 수 있음

systemd v244의 systemd-networkd에는 KeepConfiguration 구성에 대한 기본 동작 변경이 있습니다. 변경 전에는 VM이 종료 또는 재부팅 시 DHCP 서버에 DHCP 임대 해제 메시지를 전송하지 않았습니다. 변경 후에는 VM에서 이러한 메시지를 전송하고 IP를 DHCP 서버로 반환합니다. 따라서 해제된 IP가 다른 VM에 재할당되거나 다른 IP가 VM에 할당되어 (vSphere 수준이 아닌 Kubernetes 수준에서) IP 충돌이 발생하거나 VM에서 IP가 변경되어 다양한 방식으로 클러스터가 손상될 수 있습니다.

예를 들어 다음과 같은 증상이 나타날 수 있습니다.

vCenter UI에는 동일한 IP를 사용하는 VM이 없다고 표시되지만

kubectl get
        nodes -o wide

에서 중복 IP가 있는 노드를 반환합니다.

NAME   STATUS    AGE  VERSION          INTERNAL-IP    EXTERNAL-IP    OS-IMAGE            KERNEL-VERSION    CONTAINER-RUNTIME
node1  Ready     28h  v1.22.8-gke.204  10.180.85.130  10.180.85.130  Ubuntu 20.04.4 LTS  5.4.0-1049-gkeop  containerd://1.5.13
node2  NotReady  71d  v1.22.8-gke.204  10.180.85.130  10.180.85.130  Ubuntu 20.04.4 LTS  5.4.0-1049-gkeop  containerd://1.5.13

calico-node 오류로 인해 새 노드를 시작할 수 없습니다.

2023-01-19T22:07:08.817410035Z 2023-01-19 22:07:08.817 [WARNING][9] startup/startup.go 1135: Calico node 'node1' is already using the IPv4 address 10.180.85.130.
2023-01-19T22:07:08.817514332Z 2023-01-19 22:07:08.817 [INFO][9] startup/startup.go 354: Clearing out-of-date IPv4 address from this node IP="10.180.85.130/24"
2023-01-19T22:07:08.825614667Z 2023-01-19 22:07:08.825 [WARNING][9] startup/startup.go 1347: Terminating
2023-01-19T22:07:08.828218856Z Calico node failed to start

해결 방법:

클러스터에 다음 DaemonSet를 배포하여 systemd-networkd 기본 동작 변경을 되돌립니다. 이 DaemonSet를 실행하는 VM은 종료 또는 재부팅 시 IP를 DHCP 서버에 해제하지 않습니다. IP는 임대가 만료되면 DHCP 서버에 의해 자동으로 해제됩니다.

      apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: set-dhcp-on-stop
      spec:
        selector:
          matchLabels:
            name: set-dhcp-on-stop
        template:
          metadata:
            labels:
              name: set-dhcp-on-stop
          spec:
            hostIPC: true
            hostPID: true
            hostNetwork: true
            containers:
            - name: set-dhcp-on-stop
              image: ubuntu
              tty: true
              command:
              - /bin/bash
              - -c
              - |
                set -x
                date
                while true; do
                  export CONFIG=/host/run/systemd/network/10-netplan-ens192.network;
                  grep KeepConfiguration=dhcp-on-stop "${CONFIG}" > /dev/null
                  if (( $? != 0 )) ; then
                    echo "Setting KeepConfiguration=dhcp-on-stop"
                    sed -i '/\[Network\]/a KeepConfiguration=dhcp-on-stop' "${CONFIG}"
                    cat "${CONFIG}"
                    chroot /host systemctl restart systemd-networkd
                  else
                    echo "KeepConfiguration=dhcp-on-stop has already been set"
                  fi;
                  sleep 3600
                done
              volumeMounts:
              - name: host
                mountPath: /host
              resources:
                requests:
                  memory: "10Mi"
                  cpu: "5m"
              securityContext:
                privileged: true
            volumes:
            - name: host
              hostPath:
                path: /
            tolerations:
            - operator: Exists
              effect: NoExecute
            - operator: Exists
              effect: NoSchedule

작업, 업그레이드, 업데이트

1.12.0-1.12.5, 1.13.0-1.13.5, 1.14.0-1.14.1

관리자 클러스터가 1.11.x에서 업그레이드된 후 구성요소 액세스 서비스 계정 키가 삭제됨

이 문제는 1.11.x에서 업그레이드된 관리자 클러스터에만 영향을 주며 1.12 이후 새로 생성된 관리자 클러스터에는 영향을 주지 않습니다.

1.11.x 클러스터를 1.12.x로 업그레이드하면 admin-cluster-creds 보안 비밀의 component-access-sa-key 필드가 삭제되어 비어 있게 됩니다. 다음 명령어를 실행하여 확인할 수 있습니다.

kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get secret admin-cluster-creds -o yaml | grep 'component-access-sa-key'

출력이 비어 있으면 키가 완전 삭제되었다는 의미입니다.

구성요소 액세스 서비스 계정 키가 삭제되면 새 사용자 클러스터를 설치하거나 기존 사용자 클러스터를 업그레이드할 수 없습니다. 다음은 표시될 수 있는 오류 메시지입니다.

느린 검증 프리플라이트 실패, 오류 메시지: "Failed to create the test VMs: failed to get service account key: service account is not configured."
gkectl prepare 준비 실패, 오류 메시지: "Failed to prepare OS images: dialing: unexpected end of JSON input"
Google Cloud 콘솔 또는 gcloud CLI를 사용하여 1.13 사용자 클러스터를 업그레이드하는 경우 gkectl update admin --enable-preview-user-cluster-central-upgrade를 실행하여 플랫폼 컨트롤러를 배포하면 명령어가 "failed to download bundle to disk: dialing: unexpected end of JSON input" 메시지와 함께 실패합니다. kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get onprembundle -oyaml 출력의 status 필드에서 이 메시지를 확인할 수 있습니다.

해결 방법:

다음 명령어를 실행하여 구성요소 액세스 서비스 계정 키를 보안 비밀에 다시 수동으로 추가합니다.

kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get secret admin-cluster-creds -ojson | jq --arg casa "$(cat COMPONENT_ACESS_SERVICE_ACOOUNT_KEY_PATH | base64 -w 0)" '.data["component-access-sa-key"]=$casa' | kubectl --kubeconfig ADMIN_KUBECONFIG apply -f -

작업

1.13.0+, 1.14.0+

Controlplane V2가 사용 설정된 경우 클러스터 자동 확장 처리가 작동하지 않음

Controlplane V2 또는 새 설치 모델로 만든 사용자 클러스터에서 자동 확장이 사용 설정된 노드 풀이 항상 user-cluster.yaml에 autoscaling.minReplicas를 사용합니다. 클러스터 자동 확장 처리 포드의 로그에도 비정상으로 표시됩니다.

  > kubectl --kubeconfig $USER_CLUSTER_KUBECONFIG -n kube-system \
  logs $CLUSTER_AUTOSCALER_POD --container_cluster-autoscaler
 TIMESTAMP  1 gkeonprem_provider.go:73] error getting onpremusercluster ready status: Expected to get a onpremusercluster with id foo-user-cluster-gke-onprem-mgmt/foo-user-cluster
 TIMESTAMP 1 static_autoscaler.go:298] Failed to get node infos for groups: Expected to get a onpremusercluster with id foo-user-cluster-gke-onprem-mgmt/foo-user-cluster

다음 명령어를 실행하면 클러스터 자동 확장 처리 포드를 찾을 수 있습니다.

  > kubectl --kubeconfig $USER_CLUSTER_KUBECONFIG -n kube-system \
   get pods | grep cluster-autoscaler
cluster-autoscaler-5857c74586-txx2c                          4648017n    48076Ki    30s

해결 방법:

수정사항이 포함된 버전으로 업그레이드할 때까지 `gkectl 업데이트 클러스터`가 있는 모든 노드 풀에서 자동 확장을 중지합니다.

설치

1.12.0-1.12.4, 1.13.0-1.13.3, 1.14.0

CIDR이 IP 블록 파일에서 허용되지 않음

사용자가 IP 블록 파일에서 CIDR을 사용하는 경우 구성 검증이 실패하며 다음 오류가 반환됩니다.

- Validation Category: Config Check
    - [FAILURE] Config: AddressBlock for admin cluster spec is invalid: invalid IP:
172.16.20.12/30

해결 방법:

수정사항이 포함된 버전(1.12.5, 1.13.4, 1.14.1 이상)으로 업그레이드할 때까지 IP 블록 파일에 개별 IP를 포함합니다.

업그레이드, 업데이트

1.14.0-1.14.1

admin-cluster.yaml의 OS 이미지 유형 업데이트가 사용자 컨트롤 플레인 머신이 다시 생성될 때까지 대기하지 않음

admin-cluster.yaml에서 컨트롤 플레인 OS 이미지 유형을 업데이트할 때 해당 사용자 클러스터가 Controlplane V2를 통해 생성된 경우 gkectl 명령어가 완료될 때 사용자 컨트롤 플레인 머신의 재생성이 완료되지 않을 수 있습니다.

해결 방법:

업데이트가 완료되면 kubectl --kubeconfig USER_KUBECONFIG get nodes -owide를 사용하여 노드 OS 이미지 유형을 모니터링하여 사용자 컨트롤 플레인 머신의 재생성이 완료될 때까지 기다립니다. 예: Ubuntu에서 COS로 업데이트하는 경우 업데이트 명령어가 완료된 후에도 모든 컨트롤 플레인 머신이 Ubuntu에서 COS로 완전히 변경될 때까지 기다려야 합니다.

작업

1.10, 1.11, 1.12, 1.13, 1.14.0

Calico CNI 서비스 계정 인증 토큰 문제로 인한 포드 생성 또는 삭제 오류

Google Distributed Cloud 1.14.0의 Calico 문제로 인해 파드 생성 및 삭제가 실패하고 kubectl describe pods 출력에 다음과 같은 오류 메시지가 표시됩니다.

  error getting ClusterInformation: connection is unauthorized: Unauthorized

이 문제는 Calico를 사용하여 클러스터를 만들거나 1.14로 업그레이드한 후 24시간이 지나야만 관측됩니다.

관리자 클러스터는 항상 Calico를 사용하는 반면 사용자 클러스터의 경우 user-cluster.yaml에 구성 필드 `enableDataPlaneV2`가 있습니다. 해당 필드가 `false`로 설정되었거나 지정되지 않은 경우 사용자 클러스터에 Calico가 사용됩니다.

노드의 install-cni 컨테이너는 24시간 동안 유효한 토큰으로 kubeconfig를 만듭니다. 이 토큰은 calico-node 포드에 의해 주기적으로 갱신되어야 합니다. calico-node 포드는 노드의 kubeconfig 파일이 포함된 디렉터리에 액세스할 수 없으므로 토큰을 갱신할 수 없습니다.

해결 방법:

이 문제는 Google Distributed Cloud 버전 1.14.1에서 해결되었습니다. 이 버전 이상으로 업그레이드하세요.

즉시 업그레이드할 수 없는 경우 관리자 및 사용자 클러스터의 calico-node DaemonSet에 다음 패치를 적용합니다.

  kubectl -n kube-system get daemonset calico-node \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG -o json \
    | jq '.spec.template.spec.containers[0].volumeMounts += [{"name":"cni-net-dir","mountPath":"/host/etc/cni/net.d"}]' \
    | kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f -

  kubectl -n kube-system get daemonset calico-node \
    --kubeconfig USER_CLUSTER_KUBECONFIG -o json \
    | jq '.spec.template.spec.containers[0].volumeMounts += [{"name":"cni-net-dir","mountPath":"/host/etc/cni/net.d"}]' \
    | kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f -

다음을 바꿉니다.

ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로
USER_CLUSTER_CONFIG_FILE: 사용자 클러스터 구성 파일의 경로

설치

1.12.0-1.12.4, 1.13.0-1.13.3, 1.14.0

CIDR을 사용할 때 IP 블록 검증 실패

사용자가 적절한 구성을 사용하더라도 클러스터 생성이 실패합니다. 클러스터에 IP가 충분하지 않아 사용자에게 생성 실패가 표시됩니다.

해결 방법:

CIDR을 작은 CIDR 블록 여러 개로 분할(예: 10.0.0.0/30을 10.0.0.0/31, 10.0.0.2/31로)합니다. CIDR이 N+1개(N은 클러스터의 노드 수)면 충분합니다.

업그레이드, 업데이트

1.11, 1.12

버전 1.12로 업그레이드한 후 자체 배포된 GMP 구성요소가 보존되지 않음

Google Distributed Cloud 버전 1.12 미만을 사용 중이며 클러스터의 gmp-system 네임스페이스에 Google 관리형 Prometheus(GMP) 구성요소를 수동으로 설정한 경우 버전 1.12.x로 업그레이드하면 구성요소가 보존되지 않습니다.

버전 1.12부터 gmp-system 네임스페이스 및 CRD의 GMP 구성요소를 stackdriver 객체에서 관리하며 enableGMPForApplications 플래그가 기본적으로 false로 설정됩니다. 1.12로 업그레이드하기 전에 네임스페이스에 GMP 구성요소를 수동으로 배포하면 stackdriver가 리소스를 삭제합니다.

해결 방법:

모든 기존 PodMonitoring 커스텀 리소스(CR)를 백업합니다.
모든 클러스터를 버전 1.12로 업그레이드하고 Managed Service for Prometheus를 사용 설정합니다.
PodMonitoring CR을 다시 배포합니다.

작업

1.11, 1.12, 1.13.0 - 1.13.1

클러스터 스냅샷 `system` 시나리오에서 ClusterAPI 객체가 누락됨

system 시나리오에서 클러스터 스냅샷의 default 네임스페이스 아래에 리소스가 포함되지 않습니다.

하지만 이 네임스페이스 아래에 있는 Cluster API 객체 등 일부 Kubernetes 리소스에 유용한 디버깅 정보가 포함되어 있습니다. 디버깅 정보가 클러스터 스냅샷에 포함되어야 합니다.

해결 방법:

다음 명령어를 수동으로 실행하여 디버깅 정보를 수집할 수 있습니다.

export KUBECONFIG=USER_CLUSTER_KUBECONFIG
kubectl get clusters.cluster.k8s.io -o yaml
kubectl get controlplanes.cluster.k8s.io -o yaml
kubectl get machineclasses.cluster.k8s.io -o yaml
kubectl get machinedeployments.cluster.k8s.io -o yaml
kubectl get machines.cluster.k8s.io -o yaml
kubectl get machinesets.cluster.k8s.io -o yaml
kubectl get services -o yaml
kubectl describe clusters.cluster.k8s.io
kubectl describe controlplanes.cluster.k8s.io
kubectl describe machineclasses.cluster.k8s.io
kubectl describe machinedeployments.cluster.k8s.io
kubectl describe machines.cluster.k8s.io
kubectl describe machinesets.cluster.k8s.io
kubectl describe services

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

USER_CLUSTER_KUBECONFIG는 사용자 클러스터의 kubeconfig 파일입니다.

업그레이드, 업데이트

1.11.0~1.11.4, 1.12.0~1.12.3, 1.13.0~1.13.1

vSAN 설정을 위한 노드 드레이닝 중에 사용자 클러스터 삭제가 중단됨

다음 시나리오에서 사용자 클러스터를 삭제, 업데이트 또는 업그레이드할 때 노드 드레이닝이 중단될 수 있습니다.

버전 1.12.x부터 관리자 클러스터가 vSAN에서 vSphere CSI 드라이버를 사용해 왔습니다.
관리자 클러스터와 사용자 클러스터에 트리 내 vSphere 플러그인이 만든 PVC/PV 객체가 없습니다.

증상을 확인하려면 아래 명령어를 실행합니다.

kubectl logs clusterapi-controllers-POD_NAME_SUFFIX  --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAMESPACE

다음은 위 명령어의 샘플 오류 메시지입니다.

E0920 20:27:43.086567 1 machine_controller.go:250] Error deleting machine object [MACHINE]; Failed to delete machine [MACHINE]: failed to detach disks from VM "[MACHINE]": failed to convert disk path "kubevols" to UUID path: failed to convert full path "ds:///vmfs/volumes/vsan:[UUID]/kubevols": ServerFaultCode: A general system error occurred: Invalid fault

kubevols는 vSphere 트리 내 드라이버의 기본 디렉터리입니다. 생성된 PVC/PV 객체가 없으면 현재 구현에서 kubevols가 항상 존재한다고 가정하기 때문에 kubevols를 찾는 중에 노드 드레이닝이 중단되는 버그가 발생할 수 있습니다.

해결 방법:

노드가 생성된 Datastore에 kubevols 디렉터리를 만듭니다. 이는 user-cluster.yaml 또는 admin-cluster.yaml 파일의 vCenter.datastore 필드에서 정의됩니다.

구성

1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14

사용자 클러스터를 삭제한 후 `Cluster Autoscaler` clusterrolebinding 및 clusterrole이 삭제됩니다.

사용자 클러스터를 삭제하면 클러스터 자동 확장 처리의 해당 clusterrole 및 clusterrolebinding도 삭제됩니다. 이는 클러스터 자동 확장 처리가 사용 설정된 동일 관리자 클러스터의 다른 모든 사용자 클러스터에 영향을 줍니다. 이렇게 영향을 주는 이유는 동일한 관리자 클러스터 내의 모든 클러스터 자동 확장 처리 포드에 동일한 clusterrole 및 clusterrolebinding이 사용되기 때문입니다.

증상은 다음과 같습니다.

cluster-autoscaler 로그

kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
cluster-autoscaler

ADMIN_CLUSTER_KUBECONFIG

2023-03-26T10:45:44.866600973Z W0326 10:45:44.866463       1 reflector.go:424] k8s.io/client-go/dynamic/dynamicinformer/informer.go:91: failed to list *unstructured.Unstructured: onpremuserclusters.onprem.cluster.gke.io is forbidden: User "..." cannot list resource "onpremuserclusters" in API group "onprem.cluster.gke.io" at the cluster scope
2023-03-26T10:45:44.866646815Z E0326 10:45:44.866494       1 reflector.go:140] k8s.io/client-go/dynamic/dynamicinformer/informer.go:91: Failed to watch *unstructured.Unstructured: failed to list *unstructured.Unstructured: onpremuserclusters.onprem.cluster.gke.io is forbidden: User "..." cannot list resource "onpremuserclusters" in API group "onprem.cluster.gke.io" at the cluster scope

해결 방법:

해결 방법 단계 보기

관리자 클러스터에서 clusterrole 및 clusterrolebinding이 누락되었는지 확인합니다.

kubectl get clusterrolebindings --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system | grep cluster-autoscaler

kubectl get clusterrole --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system | grep cluster-autoscaler

누락된 경우 다음 클러스터 역할 및 clusterrolebinding을 관리자 클러스터에 적용합니다. 각 사용자 클러스터의 clusterrolebinding에 서비스 계정 제목을 추가하세요.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cluster-autoscaler
rules:
- apiGroups: ["cluster.k8s.io"]
  resources: ["clusters"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["cluster.k8s.io"]
  resources: ["machinesets","machinedeployments", "machinedeployments/scale","machines"]
  verbs: ["get", "list", "watch", "update", "patch"]
- apiGroups: ["onprem.cluster.gke.io"]
  resources: ["onpremuserclusters"]
  verbs: ["get", "list", "watch"]
- apiGroups:
  - coordination.k8s.io
  resources:
  - leases
  resourceNames: ["cluster-autoscaler"]
  verbs:
  - get
  - list
  - watch
  - create
  - update
  - patch
- apiGroups:
  - ""
  resources:
  - nodes
  verbs: ["get", "list", "watch", "update", "patch"]
- apiGroups:
  - ""
  resources:
  - pods
  verbs: ["get", "list", "watch"]
- apiGroups:
  - ""
  resources:
  - pods/eviction
  verbs: ["create"]
# read-only access to cluster state
- apiGroups: [""]
  resources: ["services", "replicationcontrollers", "persistentvolumes", "persistentvolumeclaims"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["daemonsets", "replicasets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["statefulsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
  resources: ["jobs"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["policy"]
  resources: ["poddisruptionbudgets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["storage.k8s.io"]
  resources: ["storageclasses", "csinodes"]
  verbs: ["get", "list", "watch"]
# misc access
- apiGroups: [""]
  resources: ["events"]
  verbs: ["create", "update", "patch"]
- apiGroups: [""]
  resources: ["configmaps"]
  verbs: ["create"]
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["cluster-autoscaler-status"]
  verbs: ["get", "update", "patch", "delete"]

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  labels:
    k8s-app: cluster-autoscaler
  name: cluster-autoscaler
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-autoscaler
subjects:
  - kind: ServiceAccount
  name: cluster-autoscaler
  namespace:  NAMESPACE_OF_USER_CLUSTER_1 
  - kind: ServiceAccount
  name: cluster-autoscaler
  namespace:  NAMESPACE_OF_USER_CLUSTER_2 
  ...

구성

1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13

사용자 클러스터 삭제 후 관리자 클러스터 `cluster-health-controller` 및 `vsphere-metrics-exporter`가 작동하지 않음

사용자 클러스터를 삭제하면 해당 clusterrole도 삭제되어 자동 복구 및 vsphere 측정항목 내보내기가 작동하지 않습니다.

증상은 다음과 같습니다.

cluster-health-controller 로그

kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
cluster-health-controller

ADMIN_CLUSTER_KUBECONFIG

error retrieving resource lock default/onprem-cluster-health-leader-election: configmaps "onprem-cluster-health-leader-election" is forbidden: User "system:serviceaccount:kube-system:cluster-health-controller" cannot get resource "configmaps" in API group "" in the namespace "default": RBAC: clusterrole.rbac.authorization.k8s.io "cluster-health-controller-role" not found

vsphere-metrics-exporter 로그

kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
vsphere-metrics-exporter

ADMIN_CLUSTER_KUBECONFIG

vsphere-metrics-exporter/cmd/vsphere-metrics-exporter/main.go:68: Failed to watch *v1alpha1.Cluster: failed to list *v1alpha1.Cluster: clusters.cluster.k8s.io is forbidden: User "system:serviceaccount:kube-system:vsphere-metrics-exporter" cannot list resource "clusters" in API group "cluster.k8s.io" in the namespace "default"

해결 방법:

해결 방법 단계 보기

다음 yaml을 관리자 클러스터에 적용합니다.

vsphere-metrics-exporter의 경우

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: vsphere-metrics-exporter
rules:
  - apiGroups:
      - cluster.k8s.io
    resources:
      - clusters
    verbs: [get, list, watch]
  - apiGroups:
      - ""
    resources:
      - nodes
    verbs: [get, list, watch]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  labels:
    k8s-app: vsphere-metrics-exporter
  name: vsphere-metrics-exporter
  namespace: kube-system
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: vsphere-metrics-exporter
subjects:
  - kind: ServiceAccount
    name: vsphere-metrics-exporter
    namespace: kube-system

cluster-health-controller의 경우

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cluster-health-controller-role
rules:
- apiGroups:
  - "*"
  resources:
  - "*"
  verbs:
  - "*"

구성

1.12.1-1.12.3, 1.13.0-1.13.2

OS 이미지 검증 시 `gkectl check-config` 실패

gkectl prepare를 실행하지 않고 gkectl check-config를 실패할 수 있는 알려진 문제입니다. gkectl prepare를 실행하기 전에 명령어를 실행하도록 권장하므로 혼동될 수 있습니다.

gkectl check-config 명령어가 실패하며 다음 오류 메시지가 반환되는 증상을 보입니다.

Validator result: {Status:FAILURE Reason:os images [OS_IMAGE_NAME] don't exist, please run `gkectl prepare` to upload os images. UnhealthyResources:[]}

해결 방법:

옵션 1: gkectl prepare을 실행하여 누락된 OS 이미지를 업로드합니다.

옵션 2: gkectl check-config --skip-validation-os-images를 사용하여 OS 이미지 검증을 건너뜁니다.

업그레이드, 업데이트

1.11, 1.12, 1.13

안티어피니티 그룹 업데이트 시 `gkectl update admin/cluster` 실패

anti affinity groups 업데이트 시 gkectl update admin/cluster를 실패할 수 있는 알려진 문제입니다.

gkectl update 명령어가 실패하며 다음 오류 메시지가 반환되는 증상을 보입니다.

Waiting for machines to be re-deployed...  ERROR
Exit with error:
Failed to update the cluster: timed out waiting for the condition

해결 방법:

해결 방법 단계 보기

업데이트를 적용하려면 실패한 업데이트 after 머신을 다시 만들어야 합니다.

관리자 클러스터 업데이트의 경우 사용자 마스터 및 관리자 부가기능 노드를 다시 만들어야 합니다.

사용자 클러스터 업데이트의 경우 사용자 워커 노드를 다시 만들어야 합니다.

사용자 워커 노드 다시 만들기

옵션 1
노드 풀 업데이트의 안내를 따르고 CPU 또는 메모리를 변경하여 노드의 순차적 재생성을 트리거합니다.

옵션 2
kubectl delete를 사용하여 머신을 한 번에 하나씩 다시 만듭니다.

kubectl delete machines MACHINE_NAME --kubeconfig USER_KUBECONFIG

사용자 마스터 노드 다시 만들기

옵션 1
컨트롤 플레인 크기 조절의 안내를 따라 CPU 또는 메모리를 변경하여 노드의 순차적 재생성을 트리거합니다.

옵션 2
kubectl delete를 사용하여 머신을 한 번에 하나씩 다시 만듭니다.

kubectl delete machines MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG

관리자 부가기능 노드 다시 만들기

kubectl delete를 사용하여 머신을 한 번에 하나씩 다시 만듭니다.

kubectl delete machines MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG

설치, 업그레이드, 업데이트

1.13.0-1.13.8, 1.14.0-1.14.4, 1.15.0

구성된 호스트 이름에 마침표가 포함된 경우 노드를 등록할 수 없음

ipMode.type이 static이고 IP 블록 파일의 구성된 호스트 이름에 마침표가 1개 이상 포함된 경우 클러스터 생성, 업그레이드, 업데이트, 노드 자동 복구 중에 노드 등록이 실패합니다. 이 경우 노드의 인증서 서명 요청(CSR)이 자동으로 승인되지 않습니다.

노드의 대기 중인 CSR을 보려면 다음 명령어를 실행합니다.

kubectl get csr -A -o wide

다음 로그에서 오류 메시지를 확인합니다.

관리자 클러스터에서 clusterapi-controllers 포드의 clusterapi-controller-manager 컨테이너에 대한 로그를 봅니다.

kubectl logs clusterapi-controllers-POD_NAME \
    -c clusterapi-controller-manager -n kube-system \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG

사용자 클러스터에서 동일한 로그를 보려면 다음 명령어를 실행하세요.
```
kubectl logs clusterapi-controllers-POD_NAME \
    -c clusterapi-controller-manager -n USER_CLUSTER_NAME \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
각 항목의 의미는 다음과 같습니다.
- ADMIN_CLUSTER_KUBECONFIG는 관리자 클러스터의 kubeconfig 파일입니다.
- USER_CLUSTER_NAME은 사용자 클러스터 이름입니다.
다음은 표시될 수 있는 오류 메시지의 예시입니다. "msg"="failed to validate token id" "error"="failed to find machine for node node-worker-vm-1" "validate"="csr-5jpx9"
문제가 있는 노드의 kubelet 로그를 봅니다.
```
journalctl --u kubelet
```
다음은 표시될 수 있는 오류 메시지의 예시입니다. "Error getting node" err="node \"node-worker-vm-1\" not found"

IP 블록 파일의 호스트 이름 필드에 도메인 이름을 지정하면 첫 번째 마침표 뒤에 오는 모든 문자가 무시됩니다. 예를 들어 호스트 이름을 bob-vm-1.bank.plc로 지정하면 VM 호스트 이름과 노드 이름이 bob-vm-1로 설정됩니다.

노드 ID 확인이 사용 설정되었으면 CSR 승인자가 노드 이름을 머신 사양의 호스트 이름과 비교하며 이름을 조정하지 못합니다. 승인자가 CSR을 거부하고 노드가 부트스트랩에 실패합니다.

해결 방법:

사용자 클러스터

다음 단계를 완료하여 노드 ID 확인을 중지합니다.

사용자 클러스터 구성 파일에 다음 필드를 추가하세요.

disableNodeIDVerification: true
disableNodeIDVerificationCSRSigning: true

파일을 저장하고 다음 명령어를 실행하여 사용자 클러스터를 업데이트합니다.
```
gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG_FILE
```
다음을 바꿉니다.
- ADMIN_CLUSTER_KUBECONFIG: 관리자 클러스터 kubeconfig 파일의 경로입니다.
- USER_CLUSTER_CONFIG_FILE: 사용자 클러스터 구성 파일의 경로

관리자 클러스터

수정할 OnPremAdminCluster 커스텀 리소스를 엽니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    edit onpremadmincluster -n kube-system

다음 주석을 커스텀 리소스에 추가합니다.

features.onprem.cluster.gke.io/disable-node-id-verification: enabled

관리자 클러스터 컨트롤 플레인에서 kube-controller-manager 매니페스트를 수정합니다.
1. SSH로 관리자 클러스터 컨트롤 플레인 노드에 연결합니다.
2. 수정할 kube-controller-manager 매니페스트를 엽니다.
```
sudo vi /etc/kubernetes/manifests/kube-controller-manager.yaml
```
3. controllers 목록을 찾습니다.
```
--controllers=*,bootstrapsigner,tokencleaner,-csrapproving,-csrsigning
```
4. 아래와 같이 이 섹션을 업데이트합니다.
```
--controllers=*,bootstrapsigner,tokencleaner
```

수정할 Deployment Cluster API 컨트롤러를 엽니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    edit deployment clusterapi-controllers -n kube-system

node-id-verification-enabled 및 node-id-verification-csr-signing-enabled 값을 false로 변경합니다.
```
--node-id-verification-enabled=false
--node-id-verification-csr-signing-enabled=false
```

Networking

1.10, 1.11.0-1.11.3, 1.12.0-1.12.2, 1.13.0

`NetworkGatewayNodes` marked unhealthy from concurrent status update conflict

In networkgatewaygroups.status.nodes, some nodes switch between NotHealthy and Up.

Logs for the ang-daemon Pod running on that node reveal repeated errors:

2022-09-16T21:50:59.696Z ERROR ANGd Failed to report status {"angNode": "kube-system/my-node", "error": "updating Node CR status: sending Node CR update: Operation cannot be fulfilled on networkgatewaynodes.networking.gke.io \"my-node\": the object has been modified; please apply your changes to the latest version and try again"}

NotHealthy 상태일 때는 컨트롤러가 노드에 추가 유동 IP를 할당할 수 없습니다. 이로 인해 다른 노드에 부담이 가중되거나 고가용성을 위한 중복성 부족이 발생할 수 있습니다.

그 외에는 데이터 영역 활동이 영향을 받지 않습니다.

networkgatewaygroup 객체의 경합이 발생하면 재시도 처리의 결함으로 인해 일부 상태 업데이트가 실패합니다. 상태 업데이트가 너무 많이 실패하면 ang-controller-manager에서 노드가 하트비트 시간 제한을 넘었다고 보고 NotHealthy 노드를 표시합니다.

이후 버전에서는 재시도 처리의 결함이 수정되었습니다.

해결 방법:

가능한 경우 수정된 버전으로 업그레이드하세요.

업그레이드, 업데이트

1.12.0~1.12.2, 1.13.0

경합 상태로 인해 업데이트 또는 업그레이드 중에 머신 객체 삭제가 차단됨

이전 머신 객체가 삭제될 때까지 클러스터 업그레이드 또는 업데이트가 중단될 수 있는 알려진 문제입니다. 머신 객체에서 파이널라이저를 삭제할 수 없기 때문에 발생하는 문제입니다. 이 문제는 노드 풀의 순차적 업데이트 작업에 영향을 미칩니다.

다음 오류 메시지와 함께 gkectl 명령어가 시간 초과되는 증상을 보입니다.

E0821 18:28:02.546121   61942 console.go:87] Exit with error:
E0821 18:28:02.546184   61942 console.go:87] error: timed out waiting for the condition, message: Node pool "pool-1" is not ready: ready condition is not true: CreateOrUpdateNodePool: 1/3 replicas are updated
Check the status of OnPremUserCluster 'cluster-1-gke-onprem-mgmt/cluster-1' and the logs of pod 'kube-system/onprem-user-cluster-controller' for more detailed debugging information.

clusterapi-controller 포드 로그에서 이 오류는 다음과 같이 표시됩니다.

$ kubectl logs clusterapi-controllers-[POD_NAME_SUFFIX] -n cluster-1
    -c vsphere-controller-manager --kubeconfig [ADMIN_KUBECONFIG]
    | grep "Error removing finalizer from machine object"
[...]
E0821 23:19:45.114993       1 machine_controller.go:269] Error removing finalizer from machine object cluster-1-pool-7cbc496597-t5d5p; Operation cannot be fulfilled on machines.cluster.k8s.io "cluster-1-pool-7cbc496597-t5d5p": the object has been modified; please apply your changes to the latest version and try again

이 문제가 없어도 성공적인 실행을 위해 몇 분간 동일한 머신에서 오류가 반복됩니다. 대부분은 빠르게 이 과정을 거치지만, 일부 드문 경우 몇 시간 동안 경합 상태에서 중단될 수 있습니다.

문제는 기본 VM이 vCenter에서 이미 삭제되었지만 해당 머신 객체를 삭제할 수 없으며 다른 컨트롤러가 자주 업데이트되어 파이널라이저 삭제가 중단된다는 것입니다. 이로 인해 gkectl 명령어가 시간 초과될 수 있지만 컨트롤러가 클러스터를 계속 조정하므로 결국에는 업그레이드 또는 업데이트 프로세스가 완료됩니다.

해결 방법:

환경 및 요구사항에 따라 이 문제의 여러 완화 옵션을 준비했습니다.

옵션 1: 업그레이드가 자체적으로 완료될 때까지 기다립니다.

환경의 분석 및 재현에 따라 업그레이드는 수동 개입 없이 자체적으로 완료될 수 있습니다. 이 옵션의 주의해야 할 점은 파이널라이저 제거가 각 머신 객체에 적용되는 데 걸리는 시간이 불확실하다는 것입니다. 운이 좋으면 즉시 적용될 수도 있고, 머신 세트 컨트롤러 조정 속도가 너무 빠르고 머신 컨트롤러가 조정 사이에서 파이널라이저를 삭제할 기회가 없을 경우에는 몇 시간이 걸릴 수 있습니다.

다행히 이 옵션은 사용자의 조치가 필요하지 않으며 워크로드가 중단되지 않습니다. 업그레이드가 완료되는 데 시간이 더 걸릴 뿐입니다.
옵션 2: 모든 이전 머신 객체에 자동 복구 주석을 적용합니다.

머신 세트 컨트롤러가 자동 복구 주석과 삭제 타임스탬프가 0이 아닌 머신을 필터링하고 해당 머신에서 삭제 호출을 계속 수행하지 않으므로 경합 상태를 방지하는 데 도움이 됩니다.

단점은 머신의 포드가 제거되는 대신 직접 삭제된다는 점입니다. 즉, PDB 구성을 고려하지 않아 워크로드에 다운타임이 발생할 수 있습니다.

모든 머신 이름을 가져오는 명령어는 다음과 같습니다.
```
kubectl --kubeconfig CLUSTER_KUBECONFIG get machines
```
각 머신에 자동 복구 주석을 적용하는 명령어는 다음과 같습니다.
```
kubectl annotate --kubeconfig CLUSTER_KUBECONFIG \
    machine MACHINE_NAME \
    onprem.cluster.gke.io/repair-machine=true
```

이 문제가 발생하고 오랜 시간이 지나도 업그레이드/업데이트가 여전히 완료되지 않으면 지원팀에 연락하여 완화 방법을 문의하세요.

설치, 업그레이드, 업데이트

1.10.2, 1.11, 1.12, 1.13

`gkectl` prepare OS 이미지 검증 프리플라이트 실패

gkectl prepare 명령어 실패:

- Validation Category: OS Images
    - [FAILURE] Admin cluster OS images exist: os images [os_image_name] don't exist, please run `gkectl prepare` to upload os images.

gkectl prepare의 프리플라이트 검사에 잘못된 검증이 포함되었습니다.

해결 방법:

추가 플래그 --skip-validation-os-images로 같은 명령어를 실행합니다.

설치

1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13

`https://` 또는 `http://` 프리픽스가 있는 vCenter URL로 인해 클러스터 시작 오류 발생

관리자 클러스터 생성 실패:

Exit with error:
Failed to create root cluster: unable to apply admin base bundle to external cluster: error: timed out waiting for the condition, message:
Failed to apply external bundle components: failed to apply bundle objects from admin-vsphere-credentials-secret 1.x.y-gke.z to cluster external: Secret "vsphere-dynamic-credentials" is invalid:
[data[https://xxx.xxx.xxx.username]: Invalid value: "https://xxx.xxx.xxx.username": a valid config key must consist of alphanumeric characters, '-', '_' or '.'
(e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+'), data[https://xxx.xxx.xxx.password]:
Invalid value: "https://xxx.xxx.xxx.password": a valid config key must consist of alphanumeric characters, '-', '_' or '.'
(e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+')]

URL이 '/' 또는 ':'을 지원하지 않는 보안 비밀 키의 일부로 사용됩니다.

해결 방법:

관리자 클러스터 또는 사용자 클러스터 구성 yaml의 vCenter.Address 필드에서 https:// 또는 http:// 프리픽스를 삭제합니다.

설치, 업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13

`util.CheckFileExists`의 `gkectl prepare` 패닉

gkectl prepare는 다음 스택 트레이스로 패닉할 수 있습니다.

panic: runtime error: invalid memory address or nil pointer dereference [signal SIGSEGV: segmentation violation code=0x1 addr=0x18 pc=0xde0dfa]

goroutine 1 [running]:
gke-internal.googlesource.com/syllogi/cluster-management/pkg/util.CheckFileExists(0xc001602210, 0x2b, 0xc001602210, 0x2b) pkg/util/util.go:226 +0x9a
gke-internal.googlesource.com/syllogi/cluster-management/gkectl/pkg/config/util.SetCertsForPrivateRegistry(0xc000053d70, 0x10, 0xc000f06f00, 0x4b4, 0x1, 0xc00015b400)gkectl/pkg/config/util/utils.go:75 +0x85
...

gkectl prepare가 잘못된 권한으로 비공개 레지스트리 인증서 디렉터리를 만드는 것이 문제입니다.

해결 방법:

이 문제를 해결하려면 관리자 워크스테이션에서 다음 명령어를 실행하세요.

sudo mkdir -p /etc/docker/certs.d/PRIVATE_REGISTRY_ADDRESS
sudo chmod 0755 /etc/docker/certs.d/PRIVATE_REGISTRY_ADDRESS

업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13

`gkectl repair admin-master` 및 재개 가능한 관리자 업그레이드가 함께 작동하지 않음

관리자 클러스터 업그레이드 시도 실패 후 gkectl repair admin-master를 실행하지 마세요. 이렇게 하면 관리자 마스터 전원 오류 또는 VM에 액세스 불가와 같은 문제로 인해 후속 관리자 업그레이드 시도가 실패할 수 있습니다.

해결 방법:

이 실패 시나리오가 이미 발생했으면 지원팀에 문의하세요.

운영체제

1.12, 1.13

cgroup v2는 워크로드에 영향을 줄 수 있음

버전 1.12.0에서는 Container Optimized OS(COS) 노드에 cgroup v2(통합)가 기본적으로 사용 설정됩니다. 이 경우 COS 클러스터의 워크로드가 불안정해질 수 있습니다.

해결 방법:

버전 1.12.1에서 cgroup v1(하이브리드)로 다시 전환했습니다. COS 노드를 사용하는 경우 출시되는 즉시 버전 1.12.1로 업그레이드하는 것이 좋습니다.

1.10, 1.11, 1.12, 1.13

ClientConfig 커스텀 리소스

gkectl update가 ClientConfig 커스텀 리소스에서 수행한 수동 변경사항을 되돌립니다.

해결 방법:

수동으로 변경한 후 항상 ClientConfig 리소스를 백업하는 것이 좋습니다.

설치

1.10, 1.11, 1.12, 1.13

`gkectl check-config` 검증 실패: F5 BIG-IP 파티션을 찾을 수 없음

F5 BIG-IP 파티션이 존재하더라도 이를 찾을 수 없어서 검증이 실패합니다.

F5 BIG-IP API 관련 문제로 인해 검사가 실패할 수 있습니다.

해결 방법:

gkectl check-config를 다시 실행해 보세요.

설치

1.12

cert-manager/ca-injector의 리더 선택 문제로 인해 사용자 클러스터 설치 실패

apiserver/etcd가 느릴 때 crashloop의 cert-manager-cainjector로 인해 설치 장애가 발생할 수 있습니다.

# These are logs from `cert-manager-cainjector`, from the command
# `kubectl --kubeconfig USER_CLUSTER_KUBECONFIG -n kube-system
  cert-manager-cainjector-xxx`

I0923 16:19:27.911174       1 leaderelection.go:278] failed to renew lease kube-system/cert-manager-cainjector-leader-election: timed out waiting for the condition

E0923 16:19:27.911110       1 leaderelection.go:321] error retrieving resource lock kube-system/cert-manager-cainjector-leader-election-core:
  Get "https://10.96.0.1:443/api/v1/namespaces/kube-system/configmaps/cert-manager-cainjector-leader-election-core": context deadline exceeded

I0923 16:19:27.911593       1 leaderelection.go:278] failed to renew lease kube-system/cert-manager-cainjector-leader-election-core: timed out waiting for the condition

E0923 16:19:27.911629       1 start.go:163] cert-manager/ca-injector "msg"="error running core-only manager" "error"="leader election lost"

해결 방법:

해결 방법 단계 보기

문제를 해결하려면 다음 명령어를 실행합니다.

변경사항을 cert-manager 배포로 되돌리지 않도록 먼저 monitoring-operator를 축소합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG -n kube-system \
    scale deployment monitoring-operator --replicas=0

복제본 하나만 실행하므로 리더 선택을 중지하도록 cert-manager-cainjector 배포를 수정합니다. 단일 복제본에는 필요 없는 작업입니다.

# Add a command line flag for cainjector: `--leader-elect=false`
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG edit \
    -n kube-system deployment cert-manager-cainjector

cert-manager-cainjector 배포에 대한 관련 YAML 스니펫은 다음 예시와 같아야 합니다.

...
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cert-manager-cainjector
  namespace: kube-system
...
spec:
  ...
  template:
    ...
    spec:
      ...
      containers:
      - name: cert-manager
        image: "gcr.io/gke-on-prem-staging/cert-manager-cainjector:v1.0.3-gke.0"
        args:
        ...
        - --leader-elect=false
...

설치가 완료될 때까지 문제 해결을 위해 monitoring-operator 복제본을 0개로 유지합니다. 그렇지 않으면 변경사항이 되돌려집니다.

설치가 완료되고 클러스터가 작동하면 2일 차 작업을 위해 monitoring-operator를 설정합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG -n kube-system \
    scale deployment monitoring-operator --replicas=1

업그레이드할 때마다 변경사항이 되돌려집니다. 이후 버전에서 이 문제가 수정될 때까지 같은 단계를 다시 수행하여 문제를 완화합니다.

VMware

1.10, 1.11, 1.12, 1.13

7.0U2 미만 버전으로 vCenter 다시 시작 또는 업그레이드

업그레이드 후 7.0U2 미만 버전의 vCenter가 다시 시작되면 vCenter의 VM 정보에 있는 네트워크 이름이 올바르지 않으며 머신이 Unavailable 상태가 됩니다. 그러면 결국 노드가 자동 복구되어 새로운 노드가 생성됩니다.

원격 호스트에서 SSH 연결 종료

Google Distributed Cloud 버전 1.7.2 이상의 경우, Ubuntu OS 이미지는 CIS L1 서버 벤치마크로 강화됩니다.

CIS 규칙 '5.2.16 SSH 유휴 제한 시간 간격이 구성되었는지 확인'을 충족하도록 /etc/ssh/sshd_config가 다음과 같이 설정됩니다.

ClientAliveInterval 300
ClientAliveCountMax 0

이 설정의 목적은 유휴 시간 5분이 지난 후 클라이언트 세션을 종료하는 것입니다. 하지만 ClientAliveCountMax 0 값은 예기치 않은 동작을 가져옵니다. 관리자 워크스테이션 또는 클러스터 노드에서 SSH 세션을 사용하면 SSH 클라이언트가 유휴 상태가 아니더라도 SSH 연결이 끊길 수 있습니다. 예를 들어 시간이 오래 걸리는 명령어를 실행하면 다음 메시지와 함께 명령어가 종료될 수 있습니다.

Connection to [IP] closed by remote host.
Connection to [IP] closed.

해결 방법:

다음 중 원하는 방법을 선택할 수 있습니다.

SSH 연결이 끊길 때 명령어가 종료되지 않도록 nohup를 사용합니다.

nohup gkectl upgrade admin --config admin-cluster.yaml \
    --kubeconfig kubeconfig

0이 아닌 ClientAliveCountMax 값을 사용하도록 sshd_config를 업데이트합니다. CIS 규칙에서는 3보다 작은 값을 사용하는 것을 권장합니다.
```
sudo sed -i 's/ClientAliveCountMax 0/ClientAliveCountMax 1/g' \
    /etc/ssh/sshd_config
sudo systemctl restart sshd
```

SSH 세션을 다시 연결해야 합니다.

설치

1.10, 1.11, 1.12, 1.13

`cert-manager` 설치 충돌

1.13 버전에서 monitoring-operator는 cert-manager 네임스페이스에 cert-manager를 설치합니다. 특정한 이유로 cert-manager를 직접 설치해야 하는 경우 충돌을 피하려면 다음 안내를 따르세요.

이 작업을 각각의 클러스터에 대해 한 번만 적용하면 클러스터 업그레이드 시 변경사항이 유지됩니다.

자체 cert-manager 설치 시 일반적인 증상 중 하나는 cert-manager 버전 또는 이미지(예: v1.7.2)가 이전 버전으로 되돌아갈 수 있다는 것입니다. 이 문제는 monitoring-operator에서 cert-manager 조정을 시도하며 그 과정에서 버전을 되돌리기 때문에 발생합니다.

해결 방법:

<p업그레이드 중 충돌 방지

보유한 cert-manager 버전을 제거합니다. 자체 리소스를 정의한 경우 백업할 수 있습니다.

업그레이드를 수행합니다.

다음 안내에 따라 자체 cert-manager를 복원하세요.

사용자 클러스터에서 고유한 cert-manager 복원

monitoring-operator 배포를 0으로 축소합니다.
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ -n USER_CLUSTER_NAME \ scale deployment monitoring-operator --replicas=0

monitoring-operator에서 관리하는 cert-manager 배포를 0으로 축소합니다.
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \ -n cert-manager scale deployment cert-manager --replicas=0 kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \ -n cert-manager scale deployment cert-manager-cainjector\ --replicas=0 kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \ -n cert-manager scale deployment cert-manager-webhook --replicas=0

cert-manager 버전을 다시 설치합니다. 존재하는 경우 맞춤설정된 리소스를 복원합니다.

업스트림 기본 cert-manager 설치를 사용하거나 cert-manager가 cert-manager 네임스페이스에 설치되어 있는 경우 이 단계를 건너뛸 수 있습니다. 그렇지 않으면 cert-manager에서 metrics-ca cert-manager.io/v1 인증서 및 metrics-pki.cluster.local 발급기관 리소스를 설치된 cert-manager의 클러스터 리소스 네임스페이스에 복사합니다.
relevant_fields=' { apiVersion: .apiVersion, kind: .kind, metadata: { name: .metadata.name, namespace: "YOUR_INSTALLED_CERT_MANAGER_NAMESPACE" }, spec: .spec } ' f1=$(mktemp) f2=$(mktemp) kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \ get issuer -n cert-manager metrics-pki.cluster.local -o json \ | jq "${relevant_fields}" > $f1 kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \ get certificate -n cert-manager metrics-ca -o json \ | jq "${relevant_fields}" > $f2 kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f $f1 kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f $f2

관리자 클러스터에서 고유한 cert-manager 복원

일반적으로 관리자 클러스터는 Google Distributed Cloud 컨트롤 플레인 워크로드만 실행하기 때문에 관리자 클러스터에 인증 관리자를 다시 설치할 필요가 없습니다. 드물지만 관리자 클러스터에 자체 cert-manager를 설치해야 하는 경우에도 다음 안내를 따라 충돌을 방지하세요. Apigee 고객이고 Apigee에 대한 cert-manager만 필요한 경우 관리자 클러스터 명령어를 실행할 필요가 없습니다.

monitoring-operator 배포를 0으로 확장합니다.
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ -n kube-system scale deployment monitoring-operator --replicas=0

monitoring-operator에서 관리하는 cert-manager 배포를 0으로 축소합니다.
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ -n cert-manager scale deployment cert-manager \ --replicas=0 kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ -n cert-manager scale deployment cert-manager-cainjector \ --replicas=0 kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ -n cert-manager scale deployment cert-manager-webhook \ --replicas=0

cert-manager 버전을 다시 설치합니다. 존재하는 경우 맞춤설정된 리소스를 복원합니다.

업스트림 기본 cert-manager 설치를 사용하거나 cert-manager가 cert-manager 네임스페이스에 설치되어 있는 경우 이 단계를 건너뛸 수 있습니다. 그렇지 않으면 cert-manager에서 metrics-ca cert-manager.io/v1 인증서 및 metrics-pki.cluster.local 발급기관 리소스를 설치된 cert-manager의 클러스터 리소스 네임스페이스에 복사합니다.
relevant_fields=' { apiVersion: .apiVersion, kind: .kind, metadata: { name: .metadata.name, namespace: "YOUR_INSTALLED_CERT_MANAGER_NAMESPACE" }, spec: .spec } ' f3=$(mktemp) f4=$(mktemp) kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \n get issuer -n cert-manager metrics-pki.cluster.local -o json \ | jq "${relevant_fields}" > $f3 kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \ get certificate -n cert-manager metrics-ca -o json \ | jq "${relevant_fields}" > $f4 kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f $f3 kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f $f4

</p

운영체제

1.10, 1.11, 1.12, 1.13

docker, containerd, runc 취약점 스캔의 거짓양성

Google Distributed Cloud와 함께 제공되는 Ubuntu OS 이미지의 Docker, 컨테이너 및 runc는 Ubuntu PPA를 사용하여 특수 버전에 고정되어 있습니다. 이렇게 하면 모든 컨테이너 런타임 변경 사항이 각 릴리스 전에 Google Distributed Cloud에 의해 검증됩니다.

하지만 다양한 CVE 스캔 도구에서 취약점 피드로 사용하는 Ubuntu CVE Tracker에 대한 특수 버전은 알려지지 않았습니다. 따라서 Docker, containerd, runc 취약점 스캔 결과에 거짓양성이 표시됩니다.

예를 들어 CVE 스캔 결과에 다음과 같은 거짓양성이 표시될 수 있습니다. Google Distributed Cloud의 최신 패치 버전에서는 이러한 CVE가 이미 수정되었습니다.

CVE 수정사항은 출시 노트를 참조하세요.

해결 방법:

Canonical에서는 이 문제를 인식하고 있으며 수정사항은 https://github.com/canonical/sec-cvescan/issues/73에서 추적됩니다.

업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13

HA가 아닌 클러스터 업그레이드 중에 관리자와 사용자 클러스터 사이의 네트워크 연결이 잠시 중지될 수 있음

HA가 아닌 클러스터를 1.9에서 1.10으로 업그레이드하는 경우 사용자 클러스터에 대한 kubectl exec, kubectl log, 웹훅이 잠시 동안 사용 불가능한 상태인 것을 확인할 수 있습니다. 이러한 다운타임은 최대 1분까지 걸릴 수 있습니다. 이 문제는 수신되는 요청(kubectl exec, kubectl log, 웹훅)이 사용자 클러스터의 kube-apiserver에서 처리되기 때문입니다. 사용자 kube-apiserver는 Statefulset입니다. HA가 아닌 클러스터에는 Statefulset에 대해 복제본이 하나만 있습니다. 따라서 업그레이드하는 동안 새 kube-apiserver가 아직 준비되지 않은 상태에서 이전 kube-apiserver를 사용할 수 없는 경우가 존재합니다.

해결 방법:

이러한 다운타임은 업그레이드 프로세스 중에만 발생합니다. 업그레이드 중 다운타임을 줄이기 위해서는 HA 클러스터로 전환하는 것이 좋습니다.

설치, 업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13

클러스터 생성 또는 업그레이드 후 HA 클러스터를 진단할 때 Konnectivity 준비 검사 실패

HA 클러스터를 생성 또는 업그레이드하는 중 클러스터 진단에서 konnectivity 준비 검사가 실패하더라도, 대부분의 경우에는 Google Distributed Cloud의 기능(kubectl exec, kubectl log, 웹훅)에 영향을 주지 않습니다. 이 문제는 불안정한 네트워킹 또는 다른 문제로 인해 일정 기간 동안 한 두 개의 konnectivity 복제본이 준비되지 않을 수 있기 때문입니다.

해결 방법:

konnectity는 자동으로 복구됩니다. 30분~1시간 정도 기다린 후 클러스터 진단을 다시 실행하세요.

네트워킹

1.10, 1.11, 1.12, 1.13

부하 분산기와 NSX-T 스테이트풀(Stateful) 분산형 방화벽 규칙의 예기치 않은 상호작용

Google Distributed Cloud 버전 1.9 이상을 배포할 때 NSX-T 스테이트풀(Stateful) 분산 방화벽 규칙을 사용하는 환경에 Seesaw 번들 부하 분산기가 있으면 stackdriver-operator이 gke-metrics-agent-conf ConfigMap을 만들지 못하고 gke-connect-agent 포드가 비정상 종료 루프에 빠집니다.

근본적인 문제는 Seesaw가 비대칭 연결 흐름을 사용하기 때문에 스테이트풀(Stateful) NSX-T 분산형 방화벽 규칙에서 Seesaw 부하 분산기를 통한 클라이언트에서 사용자 클러스터 API 서버로의 연결을 종료하는 것입니다. NSX-T 분산형 방화벽 규칙과의 통합 문제는 Seesaw를 사용하는 모든 Google Distributed Cloud 출시 버전에 영향을 미칩니다. 크기가 32K 이상인 대형 Kubernetes 객체를 만들면 애플리케이션에서 비슷한 연결 문제가 발생할 수 있습니다.

해결 방법:

NSX-T 분산형 방화벽 규칙을 중지하거나 Seesaw VM에 스테이트리스(Stateless) 분산형 방화벽 규칙을 사용하려면 이 안내를 따르세요.

클러스터에 수동 부하 분산기가 사용되는 경우 이 안내에 따라 백엔드 노드 장애가 감지되었을 때 클라이언트 연결을 재설정하도록 부하 분산기를 구성합니다. 이 구성을 사용하지 않으면 서버 인스턴스가 작동 중지되었을 때 Kubernetes API 서버의 클라이언트가 몇 분 동안 응답하지 않을 수 있습니다.

로깅 및 모니터링

1.10, 1.11, 1.12, 1.13, 1.14, 1.15

예기치 않은 모니터링 청구

Google Distributed Cloud 버전 1.10~1.15의 경우 일부 고객의 결제 페이지에 Metrics volume에 대한 예기치 않은 높은 요금이 표시될 수 있습니다. 이 문제는 다음 두 조건이 모두 적용되는 경우에만 영향을 미칩니다.

애플리케이션 로깅 및 모니터링이 사용 설정됨(enableStackdriverForApplications=true)
애플리케이션 포드에 prometheus.io/scrap=true 주석 포함 (Cloud Service Mesh를 설치하면 이 주석을 추가할 수도 있습니다.)

이 문제의 영향을 받는지 확인하려면 사용자 정의 측정항목을 나열하세요. external.googleapis.com/prometheus 이름 프리픽스가 있는 원치 않는 측정항목에 대한 결제가 표시되고 kubectl -n kube-system get stackdriver stackdriver -o yaml 응답에서 enableStackdriverForApplications가 true로 설정된 경우 이 문제가 적용됩니다.

해결 방법

이 문제의 영향을 받는 경우 클러스터를 버전 1.12 이상으로 업그레이드하고, enableStackdriverForApplications 플래그 사용을 중지하고, 더 이상 prometheus.io/scrap=true 주석에 의존하지 않는 새로운 애플리케이션 모니터링 솔루션인 managed-service-for-prometheus로 전환하는 것이 좋습니다. 새 솔루션을 사용하면 enableCloudLoggingForApplications 및 enableGMPForApplications 플래그를 각각 사용하여 애플리케이션의 로그 및 측정항목 수집을 개별적으로 제어할 수도 있습니다.

enableStackdriverForApplications 플래그 사용을 중지하려면 수정할 `stackdriver` 객체를 엽니다.

kubectl --kubeconfig=USER_CLUSTER_KUBECONFIG --namespace kube-system edit stackdriver stackdriver

enableStackdriverForApplications: true 줄을 삭제하고 저장한 후 편집기를 닫습니다.

주석 기반 측정항목 수집에서 전환할 수 없는 경우 다음 단계를 따르세요.

원치 않는 청구 측정항목이 있는 소스 포드 및 서비스를 찾습니다.

kubectl --kubeconfig KUBECONFIG \
  get pods -A -o yaml | grep 'prometheus.io/scrape: "true"'
kubectl --kubeconfig KUBECONFIG get \
  services -A -o yaml | grep 'prometheus.io/scrape: "true"'

포드 또는 서비스에서 prometheus.io/scrap=true 주석을 삭제합니다. Cloud Service Mesh로 주석을 추가하는 경우 Prometheus 옵션 없이 Cloud Service Mesh를 구성하거나 Istio 측정항목 병합 기능을 사용 중지하는 것이 좋습니다.

설치

1.11, 1.12, 1.13

vSphere 데이터 디스크를 만들 때 설치 프로그램 오류

커스텀 역할이 잘못된 권한 수준에서 연결되면 Google Distributed Cloud 설치 프로그램이 실패할 수 있습니다.

역할 결합이 잘못되면 govc를 사용하여 vSphere 데이터 디스크 만들기가 중지되고 디스크가 0과 같은 크기로 생성됩니다. 이 문제를 해결하려면 vSphere vCenter 수준(루트)에서 커스텀 역할을 결합해야 합니다.

해결 방법:

DC 수준(또는 루트보다 낮은 수준)에서 커스텀 역할을 결합하려면 루트 vCenter 수준에서 사용자에게 읽기 전용 역할도 결합해야 합니다.

역할 생성에 대한 자세한 내용은 vCenter 사용자 계정 권한을 참조하세요.

로깅 및 모니터링

1.11, 1.12, 1.13

대시보드에서 지원 중단된 측정항목 교체

OOTB 대시보드에서 지원 중단된 측정항목을 사용하면 일부 빈 차트가 표시됩니다. Monitoring 대시보드에서 지원 중단된 측정항목을 찾으려면 다음 명령어를 실행합니다.

gcloud monitoring dashboards list > all-dashboard.json

# find deprecated metrics
cat all-dashboard.json | grep -E \
  'kube_daemonset_updated_number_scheduled\
    |kube_node_status_allocatable_cpu_cores\
    |kube_node_status_allocatable_pods\
    |kube_node_status_capacity_cpu_cores'

지원 중단된 다음 측정항목은 대체 측정항목으로 마이그레이션되어야 합니다.

지원 중단됨	대체
`kube_daemonset_updated_number_scheduled`	`kube_daemonset_status_updated_number_scheduled`
`kube_node_status_allocatable_cpu_cores` `kube_node_status_allocatable_memory_bytes` `kube_node_status_allocatable_pods`	`kube_node_status_allocatable`
`kube_node_status_capacity_cpu_cores` `kube_node_status_capacity_memory_bytes` `kube_node_status_capacity_pods`	`kube_node_status_capacity`
`kube_hpa_status_current_replicas`	`kube_horizontalpodautoscaler_status_current_replicas`

해결 방법:

지원 중단된 측정항목을 교체하려면 다음 안내를 따르세요.

Google Cloud Monitoring 대시보드에서 'GKE On-Prem 노드 상태'를 삭제합니다. 이 안내를 따라 'GKE On-Prem 노드 상태'를 다시 설치합니다.
Google Cloud Monitoring 대시보드에서 'GKE On-Prem 노드 사용률'을 삭제합니다. 이 안내를 따라 'GKE On-Prem 노드 사용률'을 다시 설치합니다.
Google Cloud Monitoring 대시보드에서 'GKE On-Prem vSphere vm health'를 삭제합니다. 이 안내에 따라 'GKE On-Prem vSphere vm health'를 다시 설치합니다.

이러한 지원 중단은 Kubernetes 1.22에 필요한 kube-state-metrics 에이전트를 v1.9에서 v2.4로 업그레이드하면 발생합니다. 커스텀 대시보드나 알림 정책에서 kube_ 프리픽스가 있는 지원 중단된 모든 kube-state-metrics 측정항목을 교체할 수 있습니다.

로깅 및 모니터링

1.10, 1.11, 1.12, 1.13

Cloud Monitoring의 알 수 없는 측정항목 데이터

Google Distributed Cloud 버전 1.10 이상의 경우 Cloud Monitoring의 클러스터 데이터에 다음과 같이 관련이 없는 요약 측정항목이 포함될 수 있습니다.

Unknown metric: kubernetes.io/anthos/go_gc_duration_seconds_summary_percentile

관련 없는 요약 측정항목을 포함할 수 있는 다른 측정항목 유형은 다음과 같습니다.

apiserver_admission_step_admission_duration_seconds_summary
go_gc_duration_seconds
scheduler_scheduling_duration_seconds
gkeconnect_http_request_duration_seconds_summary
alertmanager_nflog_snapshot_duration_seconds_summary

이러한 요약 유형 측정항목은 측정항목 목록에 있지만 현재 gke-metrics-agent에서 지원되지 않습니다.

로깅 및 모니터링

1.10, 1.11, 1.12, 1.13

일부 노드에서 측정항목 누락

모든 노드가 아닌 일부 노드에서 다음 측정항목이 누락될 수 있습니다.

kubernetes.io/anthos/container_memory_working_set_bytes
kubernetes.io/anthos/container_cpu_usage_seconds_total
kubernetes.io/anthos/container_network_receive_bytes_total

해결 방법:

이 문제를 해결하려면 해결 방법으로 다음 단계를 수행합니다. [버전 1.9.5 이상, 1.10.2 이상, 1.11.0]: 1~4단계를 수행하여 gke-metrics-agent의 CPU를 늘립니다.

수정할 stackdriver 리소스를 엽니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system edit stackdriver stackdriver

gke-metrics-agent의 CPU 요청을 10m에서 50m으로 늘리고 CPU 한도를 100m에서 200m으로 늘리려면 다음 resourceAttrOverride 섹션을 stackdriver 매니페스트에 추가합니다.

spec:
  resourceAttrOverride:
    gke-metrics-agent/gke-metrics-agent:
      limits:
        cpu: 100m
        memory: 4608Mi
      requests:
        cpu: 10m
        memory: 200Mi

수정된 리소스는 다음과 비슷하게 표시되어야 합니다.

spec:
  anthosDistribution: on-prem
  clusterLocation: us-west1-a
  clusterName: my-cluster
  enableStackdriverForApplications: true
  gcpServiceAccountSecretName: ...
  optimizedMetrics: true
  portable: true
  projectID: my-project-191923
  proxyConfigSecretName: ...
  resourceAttrOverride:
    gke-metrics-agent/gke-metrics-agent:
      limits:
        cpu: 200m
        memory: 4608Mi
      requests:
        cpu: 50m
        memory: 200Mi

변경사항을 저장하고 텍스트 편집기를 닫습니다.

변경사항이 적용되었는지 확인하려면 다음 명령어를 실행합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system get daemonset gke-metrics-agent -o yaml \
    | grep "cpu: 50m"

수정이 적용된 경우 명령어가 cpu: 50m을 찾습니다.

로깅 및 모니터링

1.11.0~1.11.2, 1.12.0

관리자 클러스터에서 스케줄러 및 컨트롤러 관리자 측정항목 누락

관리자 클러스터가 이 문제의 영향을 받는 경우 이는 스케줄러 및 컨트롤러 관리자 측정항목이 없는 것입니다. 예를 들어 다음 두 측정항목이 누락됩니다.

# scheduler metric example
scheduler_pending_pods
# controller-manager metric example
replicaset_controller_rate_limiter_use

해결 방법:

v1.11.3 이상, v1.12.1 이상 또는 v1.13 이상으로 업그레이드합니다.

1.11.0~1.11.2, 1.12.0

사용자 클러스터에서 스케줄러 및 컨트롤러 관리자 측정항목 누락

사용자 클러스터가 이 문제의 영향을 받는 경우 이는 스케줄러 및 컨트롤러 관리자 측정항목이 없는 것입니다. 예를 들어 다음 두 측정항목이 누락됩니다.

# scheduler metric example
scheduler_pending_pods
# controller-manager metric example
replicaset_controller_rate_limiter_use

해결 방법:

이 문제는 Google Distributed Cloud 버전 1.13.0 이상에서 해결되었습니다. 수정사항이 적용된 버전으로 클러스터를 업그레이드합니다.

설치, 업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13

생성 중 관리자 클러스터 등록 실패

1.9.x 또는 1.10.0 버전의 관리자 클러스터를 만드는 중에 관리자 클러스터를 제공된 gkeConnect 사양으로 등록하지 못하면 다음 오류가 발생합니다.

Failed to create root cluster: failed to register admin cluster: failed to register cluster: failed to apply Hub Membership: Membership API request failed: rpc error:  ode = PermissionDenied desc = Permission 'gkehub.memberships.get' denied on PROJECT_PATH

이 관리자 클러스터를 계속 사용할 수 있지만 나중에 관리자 클러스터를 버전 1.10.y로 업그레이드하려고 하면 다음 오류가 발생합니다.

failed to migrate to first admin trust chain: failed to parse current version "": invalid version: "" failed to migrate to first admin trust chain: failed to parse current version "": invalid version: ""

해결 방법:

해결 방법 단계 보기

이 오류가 발생하면 다음 단계에 따라 클러스터 등록 문제를 해결합니다. 이 문제를 해결한 후 관리자 클러스터를 업그레이드할 수 있습니다.

gkectl update admin을 실행하여 올바른 서비스 계정 키로 관리자 클러스터를 등록합니다.

OnPremAdminCluster 커스텀 리소스를 패치하기 위한 전용 서비스 계정을 만듭니다.

export KUBECONFIG=ADMIN_CLUSTER_KUBECONFIG

# Create Service Account modify-admin
kubectl apply -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: modify-admin
  namespace: kube-system
EOF

# Create ClusterRole
kubectl apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  creationTimestamp: null
  name: modify-admin-role
rules:
- apiGroups:
  - "onprem.cluster.gke.io"
  resources:
  - "onpremadminclusters/status"
  verbs:
  - "patch"
EOF

# Create ClusterRoleBinding for binding the permissions to the modify-admin SA

kubectl apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  creationTimestamp: null
  name: modify-admin-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: modify-admin-role
subjects:
- kind: ServiceAccount
  name: modify-admin
  namespace: kube-system
EOF

ADMIN_CLUSTER_KUBECONFIG를 관리자 클러스터 kubeconfig 파일의 경로로 바꿉니다.

다음 명령어를 실행하여 OnPremAdminCluster 커스텀 리소스를 업데이트합니다.

export KUBECONFIG=ADMIN_CLUSTER_KUBECONFIG

SERVICE_ACCOUNT=modify-admin

SECRET=$(kubectl get serviceaccount ${SERVICE_ACCOUNT} \
    -n kube-system -o json \
    | jq -Mr '.secrets[].name | select(contains("token"))')

TOKEN=$(kubectl get secret ${SECRET} -n kube-system -o json \
    | jq -Mr '.data.token' | base64 -d)

kubectl get secret ${SECRET} -n kube-system -o json \
    | jq -Mr '.data["ca.crt"]' \
    | base64 -d > /tmp/ca.crt

APISERVER=https://$(kubectl -n default get endpoints kubernetes \
    --no-headers | awk '{ print $2 }')

# Find out the admin cluster name and gkeOnPremVersion from the OnPremAdminCluster CR
ADMIN_CLUSTER_NAME=$(kubectl get onpremadmincluster -n kube-system \
    --no-headers | awk '{ print $1 }')
GKE_ON_PREM_VERSION=$(kubectl get onpremadmincluster \
    -n kube-system $ADMIN_CLUSTER_NAME \
    -o=jsonpath='{.spec.gkeOnPremVersion}')

# Create the Status field and set the gkeOnPremVersion in OnPremAdminCluster CR
curl -H "Accept: application/json" \
    --header "Authorization: Bearer $TOKEN" -XPATCH \
    -H "Content-Type: application/merge-patch+json" \
    --cacert /tmp/ca.crt \
    --data '{"status": {"gkeOnPremVersion": "'$GKE_ON_PREM_VERSION'"}}' \
    $APISERVER/apis/onprem.cluster.gke.io/v1alpha1/namespaces/kube-system/onpremadminclusters/$ADMIN_CLUSTER_NAME/status

--disable-upgrade-from-checkpoint 플래그를 사용하여 관리자 클러스터 업그레이드를 다시 시도합니다.
```
gkectl upgrade admin --config ADMIN_CLUSTER_CONFIG \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --disable-upgrade-from-checkpoint
```
ADMIN_CLUSTER_CONFIG를 관리자 클러스터 구성 파일의 경로로 바꿉니다.

1.10, 1.11, 1.12, 1.13

GKE Identity Service를 사용하면 Connect 에이전트가 예기치 않게 다시 시작될 수 있음

GKE Identity Service 기능을 사용하여 GKE Identity Service ClientConfig를 관리하는 경우 Connect 에이전트가 예기치 않게 다시 시작될 수 있습니다.

해결 방법:

기존 클러스터에서 이 문제가 발생한 경우 다음 중 하나를 수행할 수 있습니다.

GKE Identity Service를 중지합니다. GKE Identity Service를 중지해도 배포된 GKE Identity Service 바이너리 또는 GKE Identity Service ClientConfig는 삭제되지 않습니다. GKE Identity Service를 중지하려면 다음 명령어를 실행합니다.
```
gcloud container fleet identity-service disable \
    --project PROJECT_ID
```
PROJECT_ID을 클러스터의 Fleet 호스트 프로젝트 ID로 바꿉니다.
Connect 에이전트 버전을 업그레이드할 수 있도록 클러스터를 버전 1.9.3 이상 또는 버전 1.10.1 이상으로 업데이트합니다.

네트워킹

1.10, 1.11, 1.12, 1.13

Cisco ACI가 직접 서버 반환(DSR)에서 작동하지 않음

Seesaw는 DSR 모드에서 실행되며 기본적으로 데이터 영역 IP 학습 때문에 Cisco ACI에서 작동하지 않습니다.

해결 방법:

가능한 해결 방법은 Cisco Application Policy Infrastructure Controller(APIC)에서 Seesaw IP 주소를 L4-L7 가상 IP로 추가하여 IP 학습을 중지하는 것입니다.

Tenant(테넌트) > Application Profiles(애플리케이션 프로필) > Application EPGs(애플리케이션 EPG) 또는 uSeg EPG로 이동하여 L4-L7 가상 IP 옵션을 구성할 수 있습니다. IP 학습을 중지하지 못하면 IP 엔드포인트가 Cisco API 패브릭의 여러 위치 간에 플랩됩니다.

VMware

1.10, 1.11, 1.12, 1.13

vSphere 7.0 업데이트 3 문제

최근 VMWare에서는 다음과 같은 vSphere 7.0 업데이트 3 버전의 중요 문제를 확인했습니다.

vSphere ESXi 7.0 업데이트 3(빌드 18644231)
vSphere ESXi 7.0 업데이트 3a(빌드 18825058)
vSphere ESXi 7.0 업데이트 3b(빌드 18905247)
vSphere vCenter 7.0 업데이트 3b(빌드 18901211)

해결 방법:

이후 VMWare에서 이러한 버전을 삭제했습니다. ESXi 및 vCenter Server를 최신 버전으로 업그레이드해야 합니다.

운영체제

1.10, 1.11, 1.12, 1.13

COS 노드에서 실행 중인 포드에 emptyDir 볼륨을 `exec`로 마운트할 수 없음

Container-Optimized OS(COS) 이미지를 사용하는 노드에서 실행되는 포드의 경우 emptyDir 볼륨을 exec로 마운트할 수 없습니다. noexec로 마운트되며 exec user process caused: permission denied 오류가 발생합니다. 예를 들어 다음 테스트 포드를 배포하는 경우 이 오류 메시지가 표시됩니다.

apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: test
  name: test
spec:
  containers:
  - args:
    - sleep
    - "5000"
    image: gcr.io/google-containers/busybox:latest
    name: test
    volumeMounts:
      - name: test-volume
        mountPath: /test-volume
    resources:
      limits:
        cpu: 200m
        memory: 512Mi
  dnsPolicy: ClusterFirst
  restartPolicy: Always
  volumes:
    - emptyDir: {}
      name: test-volume

테스트 포드에서 mount | grep test-volume을 실행하면 noexec 옵션이 표시됩니다.

/dev/sda1 on /test-volume type ext4 (rw,nosuid,nodev,noexec,relatime,commit=30)

해결 방법:

해결 방법 단계 보기

예를 들어 다음과 같이 DaemonSet 리소스를 적용합니다.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fix-cos-noexec
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: fix-cos-noexec
  template:
    metadata:
      labels:
        app: fix-cos-noexec
    spec:
      hostIPC: true
      hostPID: true
      containers:
      - name: fix-cos-noexec
        image: ubuntu
        command: ["chroot", "/host", "bash", "-c"]
        args:
        - |
          set -ex
          while true; do
            if ! $(nsenter -a -t 1 findmnt -l | grep -qe "^/var/lib/kubelet\s"); then
              echo "remounting /var/lib/kubelet with exec"
              nsenter -a -t 1 mount --bind /var/lib/kubelet /var/lib/kubelet
              nsenter -a -t 1 mount -o remount,exec /var/lib/kubelet
            fi
            sleep 3600
          done
        volumeMounts:
        - name: host
          mountPath: /host
        securityContext:
          privileged: true
      volumes:
      - name: host
        hostPath:
          path: /

업그레이드, 업데이트

1.10, 1.11, 1.12, 1.13

노드 풀에서 자동 확장을 중지한 후 클러스터 노드 풀 복제본 업데이트가 작동하지 않음

노드 풀에서 자동 확장을 사용 설정하고 중지하면 노드 풀 복제본이 업데이트되지 않습니다.

해결 방법:

해당 노드 풀의 머신 배포에서 cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size 및 cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size 주석을 삭제합니다.

로깅 및 모니터링

1.11, 1.12, 1.13

Windows 모니터링 대시보드에 Linux 클러스터의 데이터 표시

버전 1.11부터 바로 사용할 수 있는 모니터링 대시보드에는 Windows 포드 상태 대시보드와 Windows 노드 상태 대시보드에 Linux 클러스터도 표시됩니다. Windows 노드와 포드 측정항목도 Linux 클러스터에 노출되기 때문입니다.

로깅 및 모니터링

1.10, 1.11, 1.12

CrashLoopBackOff 상수의 `stackdriver-log-forwarder`

Google Distributed Cloud 버전 1.10, 1.11, 1.12에서 디스크에 손상된 버퍼링된 로그가 있으면 stackdriver-log-forwarder DaemonSet에 CrashLoopBackOff 오류가 발생할 수 있습니다.

해결 방법:

이 문제를 완화하려면 노드에서 버퍼링된 로그를 삭제해야 합니다.

예상치 못한 동작을 방지하려면 stackdriver-log-forwarder를 축소하세요.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n kube-system patch daemonset stackdriver-log-forwarder -p '{"spec": {"template": {"spec": {"nodeSelector": {"non-existing": "true"}}}}}'

USER_CLUSTER_KUBECONFIG를 사용자 클러스터 kubeconfig 파일 경로로 바꿉니다.

삭제 DaemonSet를 배포하여 손상된 청크를 삭제합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n kube-system -f - << EOF
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluent-bit-cleanup
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: fluent-bit-cleanup
  template:
    metadata:
      labels:
        app: fluent-bit-cleanup
    spec:
      containers:
      - name: fluent-bit-cleanup
        image: debian:10-slim
        command: ["bash", "-c"]
        args:
        - |
          rm -rf /var/log/fluent-bit-buffers/
          echo "Fluent Bit local buffer is cleaned up."
          sleep 3600
        volumeMounts:
        - name: varlog
          mountPath: /var/log
        securityContext:
          privileged: true
      tolerations:
      - key: "CriticalAddonsOnly"
        operator: "Exists"
      - key: node-role.kubernetes.io/master
        effect: NoSchedule
      - key: node-role.gke.io/observability
        effect: NoSchedule
      volumes:
      - name: varlog
        hostPath:
          path: /var/log
EOF

삭제 DaemonSet가 모든 청크를 삭제했는지 확인하려면 다음 명령어를 실행하면 됩니다. 두 명령어의 출력은 클러스터의 노드 수와 동일합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  logs -n kube-system -l app=fluent-bit-cleanup | grep "cleaned up" | wc -l

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system get pods -l app=fluent-bit-cleanup --no-headers | wc -l

삭제 DaemonSet를 삭제합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system delete ds fluent-bit-cleanup

stackdriver-log-forwarder를 재개합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system patch daemonset stackdriver-log-forwarder --type json -p='[{"op": "remove", "path": "/spec/template/spec/nodeSelector/non-existing"}]'

로깅 및 모니터링

1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16

`stackdriver-log-forwarder`가 Cloud Logging에 로그를 전송하지 않음

클러스터에서 Cloud Logging에 로그가 표시되지 않고 로그에 다음 오류가 표시되는 경우:

2023-06-02T10:53:40.444017427Z [2023/06/02 10:53:40] [error] [input chunk] chunk 1-1685703077.747168499.flb would exceed total limit size in plugin stackdriver.0
2023-06-02T10:53:40.444028047Z [2023/06/02 10:53:40] [error] [input chunk] no available chunk

로그 입력 속도가 Logging 에이전트의 한도를 초과하여 stackdriver-log-forwarder에서 로그를 전송하지 않을 수 있습니다. 이 문제는 모든 Google Distributed Cloud 버전에서 발생합니다.

해결 방법:

이 문제를 완화하려면 Logging 에이전트의 리소스 한도를 늘려야 합니다.

수정할 stackdriver 리소스를 엽니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system edit stackdriver stackdriver

stackdriver-log-forwarder의 CPU 요청을 늘리려면 다음 resourceAttrOverride 섹션을 stackdriver 매니페스트에 추가합니다.

spec:
  resourceAttrOverride:
    stackdriver-log-forwarder/stackdriver-log-forwarder:
      limits:
        cpu: 1200m
        memory: 600Mi
      requests:
        cpu: 600m
        memory: 600Mi

수정된 리소스는 다음과 비슷하게 표시되어야 합니다.

spec:
  anthosDistribution: on-prem
  clusterLocation: us-west1-a
  clusterName: my-cluster
  enableStackdriverForApplications: true
  gcpServiceAccountSecretName: ...
  optimizedMetrics: true
  portable: true
  projectID: my-project-191923
  proxyConfigSecretName: ...
  resourceAttrOverride:
    stackdriver-log-forwarder/stackdriver-log-forwarder:
      limits:
        cpu: 1200m
        memory: 600Mi
      requests:
        cpu: 600m
        memory: 600Mi

변경사항을 저장하고 텍스트 편집기를 닫습니다.

변경사항이 적용되었는지 확인하려면 다음 명령어를 실행합니다.

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system get daemonset stackdriver-log-forwarder -o yaml \
    | grep "cpu: 1200m"

수정이 적용된 경우 명령어가 cpu: 1200m을 찾습니다.

보안

1.13

NodeReady 후 Kubelet 서비스를 일시적으로 사용할 수 없음

단시간 동안 노드가 준비되지만 kubelet 서버 인증서가 준비되지 않습니다. 이 수십 초 동안 kubectl exec 및 kubectl logs를 사용할 수 없습니다. 이는 새 서버 인증서 승인자가 업데이트된 유효한 노드 IP를 확인하는 데 시간이 걸리기 때문입니다.

이 문제는 kubelet 서버 인증서에만 영향을 미치며 포드 예약에는 영향을 주지 않습니다.

업그레이드, 업데이트

1.12

부분 관리자 클러스터 업그레이드가 이후 사용자 클러스터 업그레이드를 차단하지 않음

다음과 같이 사용자 클러스터 업그레이드가 실패합니다.

.LBKind in body is required (Check the status of OnPremUserCluster 'cl-stg-gdl-gke-onprem-mgmt/cl-stg-gdl' and the logs of pod 'kube-system/onprem-user-cluster-controller' for more detailed debugging information.

관리자 클러스터가 완전히 업그레이드되지 않았고 상태 버전이 계속 1.10입니다. 1.12로의 사용자 클러스터 업그레이드가 프리플라이트 검사로 차단되지 않고 버전 차이 문제로 인해 실패합니다.

해결 방법:

먼저 관리자 클러스터를 1.11로 업그레이드한 후 사용자 클러스터를 1.12로 업그레이드합니다.

스토리지

1.10.0~1.10.5, 1.11.0~1.11.2, 1.12.0

Datastore에서 여유 공간이 부족하다고 잘못 보고함

gkectl diagnose cluster 명령어 실패:

Checking VSphere Datastore FreeSpace...FAILURE
    Reason: vCenter datastore: [DATASTORE_NAME] insufficient FreeSpace, requires at least [NUMBER] GB

데이터 스토어 여유 공간의 검증을 기존 클러스터 노드 풀에 사용해서는 안 되는데 gkectl diagnose cluster에 실수로 추가되었습니다.

해결 방법:

오류 메시지를 무시하거나 --skip-validation-infra를 사용하여 검증을 건너뛰면 됩니다.

작업, 네트워킹

1.11, 1.12.0~1.12.1

관리자 클러스터가 MetalLB 부하 분산기 구성으로 설정된 경우 신규 사용자 클러스터를 추가하지 못할 수 있습니다.

사용자 클러스터 삭제 프로세스가 어떤 이유로든 중단되어 MatalLB ConfigMap이 무효화될 수 있습니다. 이 상태에서는 신규 사용자 클러스터를 추가할 수 없습니다.

해결 방법:

사용자 클러스터를 강제 삭제하면 됩니다.

설치, 운영체제

1.10, 1.11, 1.12, 1.13

사용자 클러스터에 Container-Optimized OS(COS) 사용 시 실패

osImageType에서 관리자 클러스터에 cos를 사용하고 관리자 클러스터가 생성되고 사용자 클러스터는 생성되기 전에 gkectl check-config가 실행되면 실패합니다.

Failed to create the test VMs: VM failed to get IP addresses on the network.

사용자 클러스터 check-config에 대해 생성된 테스트 VM은 기본적으로 관리자 클러스터의 동일한 osImageType를 사용하며 현재 테스트 VM은 아직 COS와 호환되지 않습니다.

해결 방법:

테스트 VM을 만드는 느린 프리플라이트 검사를 방지하려면 gkectl check-config --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG --fast를 사용합니다.

로깅 및 모니터링

1.12.0-1.12.1

관리자 클러스터의 Grafana가 사용자 클러스터에 연결할 수 없음

이 문제는 Google Distributed Cloud 버전 1.12.0 및 1.12.1의 사용자 클러스터를 모니터링하기 위해 관리자 클러스터에서 Grafana를 사용하는 고객에게 영향을 미칩니다. 사용자 클러스터의 pushprox-client 인증서가 관리자 클러스터의 pushprox-server의 허용 목록과 일치하지 않기 때문입니다. 사용자 클러스터의 pushprox-client에서 다음과 같은 오류 로그를 출력하는 증상을 보입니다.

level=error ts=2022-08-02T13:34:49.41999813Z caller=client.go:166 msg="Error reading request:" err="invalid method \"RBAC:\""

해결 방법:

해결 방법 단계 보기

다음 단계를 수행합니다.

관리자 클러스터 kube-system 네임스페이스에서 monitoring-operator 배포를 축소합니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --namespace kube-system scale deploy monitoring-operator \
    --replicas=0

관리자 클러스터 kube-system 네임스페이스에서 pushprox-server-rbac-proxy-config ConfigMap을 수정합니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --namespace kube-system edit cm pushprox-server-rbac-proxy-config

external-pushprox-server-auth-proxy 리스너의 principals 줄을 찾고 pushprox-client.metrics-consumers.kube-system.cluster.에서 kube-system 하위 문자열을 삭제하여 모든 사용자 클러스터의 principal_name을 수정합니다. 새 구성은 다음과 같이 표시됩니다.

permissions:
- or_rules:
    rules:
    - header: { name: ":path", exact_match: "/poll" }
    - header: { name: ":path", exact_match: "/push" }
principals: [{"authenticated":{"principal_name":{"exact":"pushprox-client.metrics-consumers.kube-system.cluster.local"}}},{"authenticated":{"principal_name":{"exact":"pushprox-client.metrics-consumers.kube-system.cluster."}}},{"authenticated":{"principal_name":{"exact":"pushprox-client.metrics-consumers.cluster."}}}]

관리자 클러스터에서 pushprox-server 배포를, 영향을 받는 사용자 클러스터에서 pushprox-client 배포를 다시 시작합니다.

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system rollout restart deploy pushprox-server
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG --namespace kube-system rollout restart deploy pushprox-client

앞의 단계를 수행하여 문제를 해결할 수 있습니다. 클러스터가 1.12.2로 업그레이드되고 나중에 문제가 해결되면 파이프라인을 다시 관리할 수 있도록 관리자 클러스터 kube-system monitoring-operator를 수직 확장합니다.
```
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system scale deploy monitoring-operator --replicas=1
```

로깅 및 모니터링

1.11, 1.12, 1.13, 1.14, 1.15, 1.16

권한 거부로 인한 Cloud 감사 로깅 오류

Cloud 감사 로그에는 현재 GKE Hub를 통해 사용자 클러스터에 대해서만 자동으로 수행되는 특별한 권한 설정이 필요합니다. 필요한 권한이 관리자 클러스터에 포함되도록 Cloud 감사 로그에 대해 관리자 클러스터에 동일한 프로젝트 ID 및 서비스 계정을 사용하는 사용자 클러스터를 하나 이상 포함하는 것이 좋습니다.

하지만 관리자 클러스터에서 사용자 클러스터와 다른 프로젝트 ID 또는 다른 서비스 계정이 사용되는 경우에는 관리자 클러스터의 감사 로그를 Google Cloud에 삽입할 수 없습니다. 증상은 관리자 클러스터의 audit-proxy 포드에서 일련의 Permission Denied 오류로 나타납니다.

해결 방법:

해결 방법 단계 보기

이 문제를 해결하려면 cloudauditlogging 허브 특성과 상호작용하여 권한을 설정할 수 있습니다.

먼저 프로젝트에서 Cloud 감사 로그에 허용되는 기존 서비스 계정을 확인합니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://gkehub.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/features/cloudauditlogging

응답에 따라 다음 중 하나를 수행합니다.
- 404 Not_found 오류가 수신되었으면 이 프로젝트 ID에 허용되는 서비스 계정이 없는 것입니다. cloudauditlogging 허브 특성을 사용 설정하여 서비스 계정을 허용할 수 있습니다.
```
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://gkehub.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/features?feature_id=cloudauditlogging -d \
    '{"spec":{"cloudauditlogging":{"allowlistedServiceAccounts":["SERVICE_ACCOUNT_EMAIL"]}}}'
```
- allowlistedServiceAccounts에 "code": "OK"와 함께 "lifecycleState": "ENABLED"가 포함되고 서비스 계정 목록이 포함된 특성 사양이 수신된 경우 이 프로젝트에 허용되는 기존 서비스 계정이 있는 것입니다. 클러스터에서 이 목록의 서비스 계정을 사용하거나 새 서비스 계정을 허용 목록에 추가할 수 있습니다.
```
curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://gkehub.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/features/cloudauditlogging?update_mask=spec.cloudauditlogging.allowlistedServiceAccounts -d \
    '{"spec":{"cloudauditlogging":{"allowlistedServiceAccounts":["SERVICE_ACCOUNT_EMAIL"]}}}'
```
- "code": "FAILED"와 함께 "lifecycleState": "ENABLED"가 포함된 특성 사양이 수신된 경우 권한 설정이 성공하지 않은 것입니다. 응답의 description 필드에서 문제를 해결하도록 시도하거나 현재 허용 목록을 백업하고, cloudauditlogging 허브 특성을 삭제하고, 이 섹션의 1단계에 따라 다시 사용 설정합니다. 다음 방법으로 cloudauditlogging 허브 특성을 삭제할 수 있습니다.
```
curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://gkehub.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/features/cloudauditlogging
```

위 명령어에서 다음을 수행합니다.

PROJECT_ID를 클러스터의 Audit Logging 프로젝트로 바꿉니다.
SERVICE_ACCOUNT_EMAIL을 클러스터의 감사 로깅 서비스 계정의 이메일 주소로 바꿉니다.

운영체제

1.8, 1.9, 1.10, 1.11, 1.12, 1.13

`/var/log/audit/` 때문에 VM의 디스크 공간이 가득 참

/var/log/audit/에 감사 로그가 채워집니다. sudo du -h -d 1 /var/log/audit를 실행하면 디스크 사용량을 확인할 수 있습니다.

관리자 워크스테이션의 특정 gkectl 명령어(예: gkectl diagnose snapshot)는 디스크 공간 사용량에 영향을 줍니다.

Google Distributed Cloud v1.8부터 Ubuntu 이미지는 CIS Level 2 벤치마크로 강화됩니다. 또한 규정 준수 규칙 중 하나인 '4.1.2.2 감사 로그가 자동으로 삭제되지 않도록 확인'으로 auditd 설정 max_log_file_action = keep_logs를 보장합니다. 모든 감사 규칙이 디스크에 유지됩니다.

해결 방법:

해결 방법 단계 보기

관리 워크스테이션

관리자 워크스테이션의 경우 로그를 자동으로 순환하도록 수동으로 auditd 설정을 변경한 후 auditd 서비스를 다시 시작할 수 있습니다.

sed -i 's/max_log_file_action = keep_logs/max_log_file_action = rotate/g' /etc/audit/auditd.conf sed -i 's/num_logs = .*/num_logs = 250/g' /etc/audit/auditd.conf systemctl restart auditd

위 설정을 사용하면 생성된 파일이 250개를 초과하면(각각 8M 크기) auditd 로그가 자동으로 순환됩니다.

클러스터 노드

클러스터 노드의 경우 1.11.5 이상, 1.12.4 이상, 1.13.2 이상 또는 1.14 이상으로 업그레이드합니다. 아직 해당 버전으로 업그레이드할 수 없다면 클러스터에 다음 DaemonSet를 적용하세요.

apiVersion: apps/v1 kind: DaemonSet metadata: name: change-auditd-log-action namespace: kube-system spec: selector: matchLabels: app: change-auditd-log-action template: metadata: labels: app: change-auditd-log-action spec: hostIPC: true hostPID: true containers: - name: update-audit-rule image: ubuntu command: ["chroot", "/host", "bash", "-c"] args: - | while true; do if $(grep -q "max_log_file_action = keep_logs" /etc/audit/auditd.conf); then echo "updating auditd max_log_file_action to rotate with a max of 250 files" sed -i 's/max_log_file_action = keep_logs/max_log_file_action = rotate/g' /etc/audit/auditd.conf sed -i 's/num_logs = .*/num_logs = 250/g' /etc/audit/auditd.conf echo "restarting auditd" systemctl restart auditd else echo "auditd setting is expected, skip update" fi sleep 600 done volumeMounts: - name: host mountPath: /host securityContext: privileged: true volumes: - name: host hostPath: path: /

이 auditd 구성을 변경하면 CIS Level 2 규칙 '4.1.2.2 감사 로그가 자동으로 삭제되지 않도록 확인'을 위반하게 됩니다.

네트워킹

1.10, 1.11.0~1.11.3, 1.12.0~1.12.2, 1.13.0

`NetworkGatewayGroup` 유동 IP가 노드 주소와 충돌

다음과 같은 검증 웹훅 오류로 인해 사용자가 NetworkGatewayGroup 객체를 만들거나 업데이트할 수 없습니다.

[1] admission webhook "vnetworkgatewaygroup.kb.io" denied the request: NetworkGatewayGroup.networking.gke.io "default" is invalid: [Spec.FloatingIPs: Invalid value: "10.0.0.100": IP address conflicts with node address with name: "my-node-name"

영향을 받는 버전에서 kubelet가 노드에 할당된 유동 IP 주소에 잘못 바인딩되고 이를 node.status.addresses에 노드 주소로 보고할 수 있습니다. 검증 웹훅에서 NetworkGatewayGroup 유동 IP 주소를 클러스터의 모든 node.status.addresses와 대조하고 이를 충돌로 간주합니다.

해결 방법:

NetworkGatewayGroup 객체의 생성 또는 업데이트가 실패한 동일한 클러스터에서 ANG 검증 웹훅을 일시적으로 중지하고 변경사항을 제출합니다.

마지막에 복원할 수 있도록 웹훅 구성을 저장합니다.

kubectl -n kube-system get validatingwebhookconfiguration \
    ang-validating-webhook-configuration -o yaml > webhook-config.yaml

웹훅 구성을 수정합니다.

kubectl -n kube-system edit validatingwebhookconfiguration \
    ang-validating-webhook-configuration

웹훅 구성 목록에서 vnetworkgatewaygroup.kb.io 항목을 삭제하고 닫아 변경사항을 적용합니다.
NetworkGatewayGroup 객체를 만들거나 수정합니다.

원래 웹훅 구성을 다시 적용합니다.

kubectl -n kube-system apply -f webhook-config.yaml

네트워킹

1.14.7, 1.15.0-1.15.3, 1.16.0 이전의 모든 버전

Seesaw가 전송한 GARP 회신이 대상 IP를 설정하지 않음

Seesaw가 20초 간격으로 전송하는 주기적인 GARP(Gratuitous ARP)가 ARP 헤더에 대상 IP를 설정하지 않습니다. Cisco ACI와 같은 일부 네트워크에서는 이러한 패킷이 허용되지 않을 수 있습니다. VRRP 패킷 삭제로 인해 분할된 브레인이 복구된 후 서비스 다운타임이 길어질 수 있습니다.

해결 방법:

Seesaw VM에서 sudo seesaw -c failover를 실행하여 Seesaw 장애 조치를 트리거합니다. 그러면 트래픽이 복원됩니다.

운영체제

1.16, 1.28.0-1.28.200

'/etc/kubernetes/manifests'가 워커 노드에 존재하지 않는다는 로그와 함께 kubelet이 오버플로됨

워커 노드에 'staticPodPath'가 잘못 설정되었습니다.

해결 방법:

수동으로 '/etc/kubernetes/manifests' 폴더를 만듭니다.

추가 지원이 필요하면 Cloud Customer Care에 연락합니다.

달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.

최종 업데이트: 2024-12-19(UTC)

VMware 관련 알려진 문제용 Google Distributed Cloud(소프트웨어 전용)

번들 인그레스를 사용 중지할 때 프리플라이트 검사가 실패함

vCenter에 안티어피니티 그룹 규칙이 누락되어 클러스터 업그레이드 실패

보안 비밀 암호화가 사용 설정된 적이 있는 경우 사용자 클러스터를 Controlplane V2로 마이그레이션할 수 없음

보안 비밀 암호화가 사용 설정된 경우 비HA에서 HA로 관리자 클러스터 마이그레이션이 실패함

관리 워크스테이션 업그레이드 중에 credential.yaml이 잘못 재생성됨

업그레이드 전 조정 제한 시간으로 인해 사용자 클러스터 업그레이드 실패

DataplaneV2 ForwardMode를 업데이트해도 anetd DaemonSet 재시작이 자동으로 트리거되지 않음

관리자 클러스터 백업 단계에서 클러스터 업그레이드 중에 etcdctl 명령어를 찾을 수 없음

수동 부하 분산으로 사용자 클러스터 생성 실패

사용자 클러스터를 Controlplane V2로 마이그레이션한 후 관리자 클러스터 metrics-server PDB가 잘못 구성될 수 있음

Binary Authorization 웹훅에서 CNI 플러그인이 시작되어 노드 풀 중 하나가 표시되지 않음

deletionTimestamp가 있는 미러링된 머신으로 인해 CPV2 사용자 클러스터 업그레이드가 중단됨

다른 서브넷의 컨트롤 플레인 VIP로 인해 클러스터 생성 실패

FQDN이 아닌 vCenter 사용자 이름으로 인한 클러스터 생성/업그레이드 실패

버전 1.10 이하에서 만든 클러스터의 경우 관리자 클러스터 업그레이드가 실패합니다.

Dataplane V2가 사용 설정된 클러스터에 대한 잘못된 경고 메시지

HA 관리자 클러스터 설치 프리플라이트 검사에서 잘못된 고정 IP 수를 보고함

HA가 아닌 관리자 클러스터로 마이그레이션한 후 Connect Agent에서 Google Cloud와의 연결이 끊어짐

Docker 브리지 IP가 COS 클러스터 컨트롤 플레인 노드에 172.17.0.1/16을 사용

표준 CNI에서 다중 네트워크 인터페이스를 사용할 수 없음

Netapp trident 종속 항목이 vSphere CSI 드라이버를 방해함

필수 구성을 추가할 때 관리자 클러스터 웹훅에서 업데이트를 차단할 수 있음

manualLB 사양이 비어 있는 경우 controlPlaneNodePort 필드의 기본값은 30968임

Ubuntu OS 이미지에서 nfs-common이 누락됨

관리자 클러스터 구성 템플릿에서 스토리지 정책 필드가 누락됨

Kubernetes Metadata API가 VPC-SC를 지원하지 않음

관리자 클러스터 및 ControlPlane V2가 사용 설정된 사용자 클러스터가 다른 vSphere 사용자 인증 정보를 사용하면 clusterapi-controller가 비정상 종료될 수 있음

etcd의 Prometheus Alert Manager에 실패한 GRPC 요청이 많음

이그레스 NAT 장기 지속 연결이 끊김

CSR 서명자가 인증서 서명 시 spec.expirationSeconds를 무시함

disable_bundled_ingress에 대한 사용자 클러스터 부하 분산기 검증 실패

CA 순환 후 관리자 클러스터 업데이트 실패

포드 시작 실패로 인해 CSI 워크로드 프리플라이트 검사 실패

관리자 클러스터 버전이 1.15인 경우 사용자 클러스터 업데이트 시간 초과

관리자 클러스터 버전이 1.15인 경우 사용자 클러스터 만들기 시간 초과

부가기능 서비스의 프로젝트 또는 위치가 서로 일치하지 않을 경우 관리자 클러스터 업데이트 또는 업그레이드가 실패함

사용자 관리형 관리자 워크스테이션을 사용할 때 사용자 클러스터 삭제가 실패함

외부 서버에 대한 이그레스 NAT 게이트웨이 트래픽이 실패함

상시 보안 비밀 암호화가 사용 설정된 상태에서 관리자 클러스터 업그레이드가 실패함

해결 방법

업그레이드 실패 방지

변경 블록 추적(CBT) 사용 시 디스크 오류 및 연결 실패

여러 호스트에서 공유 파일에 대한 병렬 추가 수행 시 NFSv3의 데이터 손상

kubelet과 Kubernetes 컨트롤 플레인 간의 버전 불일치

CA 버전이 1개를 초과하는 경우 관리자 클러스터 업그레이드 또는 업데이트가 실패함

HA 이외 Controlplane V2 클러스터 삭제가 제한 시간까지 중단됨

버전 1.15 이상으로 업그레이드한 후 트리 내 PVC/PV에 대해 1분마다 지속적인 CNS attachvolume 태스크가 표시됨

PVC에 대한 거짓 경고

여러 키가 만료되었을 때 서비스 계정 키 순환이 실패함

사용자 클러스터 컨트롤러가 1.16으로 업그레이드되면 1.15 사용자 마스터 머신에 예기치 않은 재생성 발생

호스트 이름이 IP 블록 파일에 없으면 프리플라이트 검사가 실패함

HA가 아닌 관리자 클러스터 및 컨트롤 플레인 v1 사용자 클러스터를 사용하는 경우 관리자 클러스터를 업그레이드/업데이트할 때 볼륨 마운트 실패

컨트롤 플레인 노드 생성 실패

동일한 데이터 센터의 중복된 호스트 이름으로 인해 클러스터 업그레이드 또는 생성이 실패함

vSphere 사용자 이름 또는 비밀번호에서 $ 및 `가 지원되지 않음

노드가 동일한 이름으로 다시 생성된 후 PVC 만들기 실패

gkectl repair admin-master가 kubeconfig unmarshall 오류를 반환함

디스크 공간 부족으로 인해 Seesaw VM이 손상됨

관리자 클러스터 업그레이드 또는 업데이트 후 관리자 SSH 공개 키 오류

GKE On-Prem API에 등록된 관리자 클러스터 업그레이드가 실패할 수 있음

등록된 관리자 클러스터의 리소스 링크 주석이 보존되지 않음

CoreDNS orderPolicy가 인식되지 않음

체크포인트와 실제 CR 사이의 OnPremAdminCluster 상태 불일치

조정 프로세스 중 관리자 클러스터에서 관리자 인증서 변경

우선순위 클래스 누락으로 인해 제거되거나 대기 중인 Anthos Network Gateway 구성요소

gcloud로 클러스터를 등록한 후 관리자 클러스터 업그레이드 실패

gkectl diagnose snapshot --log-since가 클러스터 노드에서 실행되는 journalctl 명령어의 기간을 제한하지 못함

gkectl prepare windows 실패

RootDistanceMaxSec 구성이 ubuntu 노드에 적용되지 않음

osImageType 필드가 비어 있어 gkectl update admin이 실패함

SNI가 Controlplane V2를 사용하는 사용자 클러스터에서 작동하지 않음

비공개 레지스트리 사용자 이름의 $로 인해 관리자 컨트롤 플레인 머신 시작 실패

관리자 클러스터 업데이트 중 지원되지 않는 변경사항에 대한 거짓양성 경고

KSA 서명 키 순환 후 사용자 클러스터 업데이트 실패

Terraform이 사용자 클러스터를 삭제할 때 F5 BIG-IP 가상 서버가 삭제되지 않음

종류 클러스터가 docker.io에서 컨테이너 이미지를 가져옴

네트워크에서 중복 GARP 요청을 필터링할 때 HA Controlplane V2 사용자 클러스터 및 관리자 클러스터에서 장애 조치 실패

vCenter 인증서 순환 후 vsphere-csi-controller를 다시 시작해야 함

클러스터 등록 오류 시 관리자 클러스터 생성이 실패하지 않음

관리 워크스테이션 업그레이드 중에 `credential.yaml`이 잘못 재생성됨

`deletionTimestamp`가 있는 미러링된 머신으로 인해 CPV2 사용자 클러스터 업그레이드가 중단됨

`manualLB` 사양이 비어 있는 경우 `controlPlaneNodePort` 필드의 기본값은 30968임

CSR 서명자가 인증서 서명 시 `spec.expirationSeconds`를 무시함

`disable_bundled_ingress`에 대한 사용자 클러스터 부하 분산기 검증 실패

vSphere 사용자 이름 또는 비밀번호에서 `$` 및 `가 지원되지 않음

CoreDNS `orderPolicy`가 인식되지 않음

`gkectl diagnose snapshot --log-since`가 클러스터 노드에서 실행되는 `journalctl` 명령어의 기간을 제한하지 못함

`gkectl prepare windows` 실패

`RootDistanceMaxSec` 구성이 `ubuntu` 노드에 적용되지 않음

`osImageType` 필드가 비어 있어 `gkectl update admin`이 실패함

비공개 레지스트리 사용자 이름의 `$`로 인해 관리자 컨트롤 플레인 머신 시작 실패

종류 클러스터가 `docker.io`에서 컨테이너 이미지를 가져옴

vCenter 인증서 순환 후 `vsphere-csi-controller`를 다시 시작해야 함

`vCenter.dataDisk`에 대한 거짓 오류 메시지

`failed to delete the admin master node object and reboot the admin master VM`으로 인해 `gkectl repair admin-master`가 실패할 수 있음

`gkectl upgrade admin`가 `StorageClass standard sets the parameter diskformat which is invalid for CSI Migration` 와 함께 실패

`vsphere-csi-secret`가 `gkectl update credentials vsphere --admin-cluster` 이후에 업데이트되지 않음

`gkectl update cluster`로 Cloud 감사 로그를 사용 설정할 때 `audit-proxy` 비정상 종료 루프 발생

`gkectl upgrade cluster` 직후의 추가 컨트롤 플레인 재배포

`gke-connect-agent`가 레지스트리 사용자 인증 정보가 업데이트된 후에도 이전 이미지를 계속 사용함

`kube-controller-manager`가 6분 후에 영구 볼륨을 강제로 분리할 수 있음

`gkectl repair admin-master`가 VM 하드웨어 버전을 업그레이드하지 않고 관리자 마스터 VM을 생성함

클러스터 스냅샷 `system` 시나리오에서 ClusterAPI 객체가 누락됨

사용자 클러스터를 삭제한 후 `Cluster Autoscaler` clusterrolebinding 및 clusterrole이 삭제됩니다.

사용자 클러스터 삭제 후 관리자 클러스터 `cluster-health-controller` 및 `vsphere-metrics-exporter`가 작동하지 않음

OS 이미지 검증 시 `gkectl check-config` 실패

안티어피니티 그룹 업데이트 시 `gkectl update admin/cluster` 실패

`NetworkGatewayNodes` marked unhealthy from concurrent status update conflict

`gkectl` prepare OS 이미지 검증 프리플라이트 실패

`https://` 또는 `http://` 프리픽스가 있는 vCenter URL로 인해 클러스터 시작 오류 발생

`util.CheckFileExists`의 `gkectl prepare` 패닉

`gkectl repair admin-master` 및 재개 가능한 관리자 업그레이드가 함께 작동하지 않음

`gkectl check-config` 검증 실패: F5 BIG-IP 파티션을 찾을 수 없음

`cert-manager` 설치 충돌