구성 동기화의 알려진 문제

이 페이지에는 지원되는 구성 동기화 버전에 대한 알려진 문제가 나와 있습니다.

여기에 나열된 문제는 대부분 해결되었습니다. 수정 버전 열은 수정사항이 도입된 버전을 나타냅니다. 이 수정사항을 받으려면 나열된 버전 이상으로 업그레이드하세요.

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

구성 동기화 버전을 선택합니다.

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

또는 알려진 문제를 필터링합니다.

카테고리 식별된 버전 수정된 버전 문제 및 해결 방법
구성요소 상태 1.15.0 1.17.0

해결됨: Autopilot에서 조정자 컨테이너 OOMKilled 발생

Autopilot 클러스터에서 구성 동기화 구성요소 컨테이너에는 CPU 및 메모리에 대해 설정된 리소스 한도가 있습니다. 부하가 걸렸을 때 너무 많은 메모리를 사용하여 kubelet 또는 커널에 의해 이러한 컨테이너가 종료될 수 있습니다.

해결 방법:

버전 1.17.0 이상으로 업그레이드할 수 없는 경우 리소스 재정의를 사용하여 더 높은 메모리 한도를 지정합니다.

버전 1.17.0에서는 대부분의 사용 사례에서 메모리 부족 오류를 방지하기 위해 기본 CPU 및 메모리 한도가 조정되었습니다.
구성요소 상태 1.15.0

조정자 예약할 수 없음

구성 동기화 조정자에는 RootSync 또는 RepoSync의 구성에 따라 다양한 양의 리소스가 필요합니다. 특정 구성은 다른 구성보다 더 많은 리소스가 필요합니다.

조정자를 예약할 수 없는 경우 노드에서 사용할 수 있는 리소스보다 많은 리소스를 요청했기 때문일 수 있습니다.

Standard 모드 GKE 클러스터를 사용하는 경우 조정자 리소스 요청이 매우 낮게 설정됩니다. 이 설정은 제한 및 성능 저하가 발생하더라도 예약을 허용하기 위해 선택되었으므로 구성 동기화가 소규모 클러스터와 노드에서 작동합니다. 하지만 GKE Autopilot 클러스터에서는 동기화 중 사용량을 보다 현실적으로 나타내기 위해 조정자 요청이 더 높게 설정됩니다.

해결 방법:

노드 자동 프로비저닝이 사용 설정된 GKE Autopilot 또는 GKE Standard는 요청된 리소스 수를 확인하고 예약을 허용하도록 적절한 크기의 노드를 만들 수 있어야 합니다. 하지만 노드 또는 노드 인스턴스 크기를 수동으로 구성하는 경우 조정자 포드 리소스 요구사항을 수용하도록 해당 설정을 조정해야 할 수 있습니다.
KNV 오류 1.15.0 Kubernetes 버전 1.27

해결됨: 구성이 성공적으로 적용되더라도 KNV1067 오류 발생

OpenAPI v2의 문제로 인해 구성이 성공적으로 적용되더라도 KNV1067 오류가 표시될 수 있습니다.

해결 방법:

클러스터에서 1.27 이전 버전의 Kubernetes를 실행하는 경우 기본 TCP를 사용하는 경우에도 spec: containers: ports:에서 protocol 필드를 명시적으로 설정하세요.

KNV 오류 1.15.0 1.16.0, Kubernetes 버전 1.28

해결됨: KNV2002 오류로 구성 동기화 조정 실패

KNV2002 error로 구성 동기화 조정에 실패하는 경우 client-go 문제로 인한 알려진 문제 때문일 수 있습니다. 이 문제가 발생하면 external.metrics.k8s.io/v1beta1 API 그룹에 RootSync 또는 RepoSync 객체의 오류 메시지나 다음과 같은 조정자 로그와 함께 빈 리소스 목록이 표시됩니다.

KNV2002: API discovery failed: APIServer error: unable to retrieve the complete list of server APIs: external.metrics.k8s.io/v1beta1: received empty response for:
external.metrics.k8s.io/v1beta1
측정항목 1.15.0 1.17.2

해결됨: 내보내기 실패: 인식할 수 없는 측정항목 라벨

버전 1.15.0에서 구성 동기화는 여러 측정항목에 type 및 commit 라벨을 추가했습니다. 이러한 라벨로 측정항목 카디널리티가 증가하여 내보내는 측정항목 수가 증가했습니다. Cloud Monarch로 내보낼 때 이러한 라벨을 필터링하기 위해 속성 처리도 추가되었지만 이 필터링이 잘못 구성되어 otel-collector 로그에 변환 오류가 발생했습니다.
측정항목 1.15.0 1.16.1

해결됨: 카디널리티가 높은 측정항목 및 변환 오류

버전 1.15.0에서 구성 동기화는 여러 측정항목에 type 및 commit 라벨을 추가했습니다. 이러한 라벨로 측정항목 카디널리티가 증가하여 내보내는 측정항목 수가 증가했습니다. Cloud Monarch로 내보낼 때 이러한 라벨을 필터링하기 위해 속성 처리도 추가되었지만 이 필터링이 잘못 구성되어 otel-collector 로그에 변환 오류가 발생했습니다.

버전 1.16.1에서는 유형 필드가 삭제되고 필터링이 수정되었으며 커밋 필드가 Cloud Monitoring에서 추가로 필터링되었습니다. 이렇게 해서 오류가 수정되고 측정항목의 카디널리티가 감소했습니다.
측정항목 1.15.0

내보낼 수 없습니다. 권한 거부됨

기본적으로 조정자 관리자가 애플리케이션 기본 사용자 인증 정보를 감지하면 otel-collector는 측정항목을 Prometheus, Cloud Monitoring, Monarch로 내보내도록 구성됩니다.

해결 방법:

otel-collector는 Cloud Monitoring을 구성하거나 Cloud Monitoring 및 Cloud Monarch를 사용 중지하지 않은 경우 오류를 로깅합니다.
측정항목 1.15.0

커스텀 구성과 함께 otel-collector가 비정상 종료됨

기본 ConfigMap(otel-collector 또는 otel-collector-google-cloud) 중 하나를 수정하거나 삭제하려고 시도하면 otel-collector가 필요한 ConfigMap을 로드할 수 없어서 오류가 발생하거나 비정상 종료될 수 있습니다.

해결 방법:

측정항목 내보내기 구성을 맞춤설정하려면 config-management-monitoring 네임스페이스에 otel-collector-custom이라는 ConfigMap을 만듭니다.
nomos cli 1.15.0 1.17.2

해결됨: nomos status 및 nomos bugreport가 포드에서 작동하지 않습니다.

nomos 버전 1.17.2 이전에서는 nomos bugreport 및 nomos status가 Kubernetes 포드 내에서 실행될 때만 로컬 클러스터에 연결할 수 있었습니다. nomos 버전 1.17.2에서는 승인 방법이 kubectl과 비슷하게 변경되었습니다. 이러한 변경으로 인해 로컬 클러스터가 기본적으로 타겟팅됩니다. KUBECONFIG 환경 변수를 지정하여 구성을 재정의할 수 있습니다.
해결

자체적으로 싸우는 구성 동기화

구성 동기화가 자체적인 컨트롤러 경합을 하는 것으로 보일 수 있습니다. 이 문제는 Git 저장소에서 리소스의 선택적 필드에 대한 기본값을 설정하는 경우에 발생합니다. 예를 들어 RoleBinding의 주제에 대한 apiGroup: ""을 설정하면 apiGroup 필드는 선택사항이고 빈 문자열이 기본값이기 때문에 이 문제가 트리거됩니다. 문자열, 부울, 정수 필드의 기본값은 각각 "", false, 0입니다.

해결 방법:

리소스 선언에서 이 필드를 삭제합니다.
해결

구성 커넥터 리소스와 싸우는 구성 동기화

구성 동기화는 StorageBucket과 같은 리소스를 두고 구성 커넥터와 경합하는 것으로 보일 수 있습니다. 이 문제는 정보 소스에서 spec.lifecycleRule.condition.withState 리소스의 선택적 필드 값을 설정하지 않은 경우에 발생합니다.

해결 방법:

리소스 선언에 withState=ANY 필드를 추가하면 이 문제를 방지할 수 있습니다. 또는 cnrm.cloud.google.com/state-into-spec: absent 주석을 사용하여 리소스를 폐기했다가 다시 획득할 수도 있습니다.

정보 소스 1.17.3 1.18.3

수정됨: GitHub에서 Git SSH 인증 실패

git-sync v4.2.1에는 SSH를 사용할 때 저장소 URL에서 사용자 이름을 삭제하는 버그가 있습니다. 이로 인해 GitHub에 연결할 때 인증이 실패하며, 사용자가 git여야 합니다.

git의 오류 메시지는 다음과 같습니다. git-sync@github.com: Permission denied (publickey).\r\nfatal: Could not read from remote repository.

해결 방법:

다른 인증 방법을 사용하세요
정보 소스 1.16.1 1.16.2

해결됨: 주기적으로 소스 링크를 평가할 수 없음

조정자가 시작될 때 구성 동기화에서 주기적으로 소스 링크를 평가할 수 없는 문제가 발생할 수 있습니다. 이 문제는 git-sync가 아직 소스 저장소를 클론하지 않았기 때문에 발생합니다.

버전 1.16.2 이상에서는 이 오류가 일시적인 오류이므로 로깅되지만 오류로 보고되지 않습니다.
정보 소스 1.15.0 1.18.0

해결됨: Cloud Source Repositories의 사용자 인증 정보가 주기적으로 잘못됨

구성 동기화에서는 Cloud Source Repositories에 대한 인증 토큰이 만료되면 주기적으로 오류가 발생할 수 있습니다. 이 문제는 토큰이 만료되기를 기다렸다가 토큰을 새로고침하기 때문에 발생합니다.

버전 1.18.0 이상에서는 토큰 만료 후 5분 이내에 첫 번째 요청에서 토큰이 새로고침됩니다. 이렇게 하면 사용자 인증 정보가 실제로 유효하지 않은 경우를 제외하고 잘못된 사용자 인증 정보 오류를 방지할 수 있습니다.
정보 소스 1.15.0 1.17.0

해결됨: 저장소 동기화 오류: 컨텍스트 기한 초과

1.17.0 이전 버전에서는 구성 동기화가 기본적으로 전체 Git 저장소 기록을 확인했습니다. 이로 인해 커밋이 많은 대용량 저장소에서 가져오기 요청 시간이 초과될 수 있습니다.

버전 1.17.0 이상에서는 최신 커밋만 가져오는 --depth=1로 Git Fetch를 수행합니다. 이렇게 하면 소스 가져오기 속도가 빨라지고 대부분의 시간 제한이 방지되며 Git 서버 로드가 줄어듭니다.

업그레이드 후에도 이 문제가 발생하는 경우 정보 소스에 파일이 많거나 Git 서버가 느리게 응답하거나 다른 네트워킹 문제가 있을 수 있습니다.
동기화 중 1.15.0

감사 로그에 비효율적인 PATCH 요청 수가 많음

구성 동기화 조정자는 테스트 실행을 사용하여 드리프트를 감지합니다. 이로 인해 PATCH가 지속되지 않은 경우에도 PATCH 요청이 감사 로그에 표시될 수 있습니다. 감사 로그는 테스트 실행과 일반 요청을 구분하지 않기 때문입니다.

해결 방법:

감사 로그는 테스트 실행 요청과 테스트 실행 이외의 요청을 구분할 수 없으므로 PATCH 요청을 무시해도 됩니다.
동기화 중 1.17.0 1.17.3

해결됨: 구성 동기화가 브랜치에서 최신 커밋을 가져오지 못함

구성 동기화 버전 1.17.0, 1.17.1, 1.17.2에서는 동일한 브랜치가 여러 원격 브랜치에서 참조되고 동기화되지 않았을 때 구성 동기화가 특정 브랜치의 HEAD에서 최신 커밋을 가져오지 못하는 문제가 발생할 수 있습니다. 예를 들어 원격 저장소 origin의 main 브랜치가 원격 저장소 upstream의 동일한 브랜치보다 앞에 있을 수 있지만 구성 동기화는 마지막 행에서 최신 커밋이 아닐 수도 있는 커밋 SHA만 가져옵니다.

다음 예시는 이와 같은 문제를 보여줍니다.

git ls-remote -q [GIT_REPOSITORY_URL] main  main^{}
244999b795d4a7890f237ef3c8035d68ad56515d    refs/heads/main               # the latest commit
be2c0aec052e300028d9c6d919787624290505b6    refs/remotes/upstream/main    # the commit Config Sync pulls from

버전 1.17.3 이상에서는 git-sync 종속 항목이 다른 가져오기 메커니즘을 사용하여 업데이트되었습니다.

업그레이드할 수 없는 경우 Git 브랜치(spec.git.branch)에 설정된 값에 관계없이 Git 버전(spec.git.revision)을 최신 커밋 SHA로 설정할 수 있습니다. Git 구성에 대한 자세한 내용은 Git 저장소 구성을 참조하세요.
비공개 레지스트리 1.19.0

구성 동기화가 조정자 배포에 비공개 레지스트리를 사용하지 않음

구성 동기화는 비공개 레지스트리가 구성된 경우 모든 배포의 이미지를 바꿉니다. 하지만 구성 동기화는 조정자 배포의 이미지에 대해 이미지 레지스트리를 대체하지 않습니다.

해결 방법:

이 문제의 해결 방법은 containerd에서 이미지 레지스트리 미러를 구성하는 것입니다.

동기화 중 1.17.0 1.18.3

해결됨: 구성 동기화 조정자가 비정상 종료 루프를 실행함

구성 동기화 버전 1.17.0 이상에서는 조정자가 일부 Kubernetes 공급업체에서 나머지 구성을 만들지 못하는 문제가 발생할 수 있습니다.

다음 예시는 이와 같은 문제가 조정자 로그에서 어떻게 표시되는지 보여줍니다.

Error creating rest config: failed to build rest config: reading local kubeconfig: loading REST config from "/.kube/config": stat /.kube/config: no such file or directory
Terraform Terraform 버전 5.41.0

Terraform을 사용하여 구성 동기화를 설치하거나 업그레이드할 수 없음

Terraform 버전 5.41.0에서는 google_gke_hub_feature_membership에 새로운 필드 config_sync.enabled를 도입했습니다. 이 필드의 기본값은 false이므로 Terraform이 버전 5.41.0으로 업그레이드되면 구성 동기화 설치가 실패합니다.

해결 방법:

  • google_gke_hub_feature_membership 리소스를 사용하는 경우 config_sync.enabled를 true로 수동으로 설정합니다.
  • acm 하위 모듈을 사용하는 경우 구성 동기화를 설치하는 다른 방법으로 전환하는 것이 좋습니다. 전환할 수 없는 경우 v33.0.0으로 업그레이드하세요.

맨 위로

다음 단계