오류 참조

구성 동기화 오류 메시지는 KNV1234 형식(1234는 고유 번호)의 오류 ID, 문제에 대한 설명, 권장 해결 방법으로 구성됩니다. K는 Kubernetes 규칙에서 상속되며, N 프리픽스가 있는 규칙은 nomos 전용입니. 저장소 및 클러스터의 초기 상태에서 감지할 수 있는 오류 코드는 KNV1XXX 형식입니다. 런타임에서만 감지될 수 있는 오류 코드는 KNV2XXX 형식입니다.

이 페이지에서는 이러한 각 오류 메시지와 오류 해결 단계를 설명합니다.

구성 동기화 문제 해결 소개 및 알려진 문제도 참고할 수 있습니다.

KNV1000: InternalError

구성 동기화 1.6.1을 사용하여 InternalError의 ID가 KNV9998로 변경되었습니다.

KNV1001: ReservedDirectoryNameError

구성 동기화 1.3에서 지원 중단되었습니다.

KNV1002: DuplicateDirectoryNameError

구성 동기화 1.3에서 지원 중단되었습니다.

KNV1003: IllegalNamespaceSubdirectoryError

계층적 저장소 구조를 사용하는 경우 네임스페이스 구성이 포함된 디렉터리에 하위 디렉터리가 없어야 합니다.

네임스페이스 구성이 없는 디렉터리는 추상 네임스페이스 디렉터리이고 이 디렉터리에서 상속되는 디렉터리가 있으므로 하위 디렉터리가 있어야 합니다. 네임스페이스 구성이 포함된 디렉터리는 상속될 수 없는 네임스페이스 디렉터리이므로 이 디렉터리에 하위 디렉터리가 있어서는 안 됩니다.

이 오류를 해결하려면 상위 디렉터리에서 네임스페이스 구성을 삭제하거나 하위 디렉터리를 다른 위치로 이동합니다.

네임스페이스가 포함된 디렉터리에 하위 디렉터리가 있으면 이 문제가 발생할 수 있습니다.

namespaces/
└── prod/
    ├── namespace.yaml
    └── us_west_1/

# namespaces/prod/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: prod

위와 같은 디렉터리 구조와 namespace.yaml의 콘텐츠로 인해 다음 오류가 발생합니다.

KNV1003: A Namespace directory MUST NOT have subdirectories. Remove the
         Namespace policy from "prod", or move "us_west_1" to an Abstract
         Namespace:

path: namespaces/prod/us_west_1
name: us_west_1

KNV1004: IllegalSelectorAnnotationError

클러스터 범위 객체는 configmanagement.gke.io/namespace-selector 주석을 선언하면 안 됩니다. NamespaceSelector는 네임스페이스 범위 객체에만 선언될 수 있습니다.

이 오류를 해결하려면 metadata.annotations 필드에서 configmanagement.gke.io/namespace-selector를 삭제합니다.

다음 ClusterRole 구성은 이 오류를 발생합니다.

# cluster/namespace-reader-clusterrole.yaml
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: namespace-reader
  annotations: {
    "configmanagement.gke.io/namespace-selector" : "shipping-dev",
  }
rules:
- apiGroups: [""]
  resources: ["namespaces"]
  verbs: ["get", "watch"]

이 ClusterRole을 클러스터에 포함하려고 하면 nomos vet이 다음 오류를 반환합니다.

KNV1004: Cluster-scoped objects may not be namespace-selected, and so MUST NOT declare the annotation 'configmanagement.gke.io/namespace-selector'. To fix, remove `metadata.annotations.configmanagement.gke.io/namespace-selector` from:
source: cluster/namespace-reader-clusterrole.yaml
metadata.name: namespace-reader
group: rbac.authorization.k8s.io
version: v1
kind: ClusterRole

클러스터 객체는 configmanagement.gke.io/cluster-selector 주석을 선언하면 안 됩니다. 이 오류를 해결하려면 metadata.annotations에서 configmanagement.gke.io/cluster-selector를 삭제합니다.

클러스터 객체가 configmanagement.gke.io/cluster-selector를 선언하면 nomos vet은 다음 오류를 반환합니다.

KNV1004: Clusters may not be cluster-selected, and so MUST NOT declare the annotation 'configmanagement.gke.io/cluster-selector'. To fix, remove `metadata.annotations.configmanagement.gke.io/cluster-selector` from:

source: clusterregistry/cluster.yaml
metadata.name: default-name
group: clusterregistry.k8s.io
version: v1alpha1
kind: Cluster

KNV1005: IllegalManagementAnnotationError

관리 주석에 유효한 유일한 설정은 configmanagement.gke.io/managed=disabled입니다. 이 설정은 구성을 체크인된 상태로 두고 Git 저장소의 리소스를 명시적으로 관리 중지하는 데 사용됩니다. configmanagement.gke.io/managed=enabled 주석은 필요하지 않습니다. 자세한 내용은 객체 관리를 참조하세요.

다른 주석을 설정하면 다음과 같은 오류가 발생합니다.

KNV1005: Config has invalid management annotation configmanagement.gke.io/managed=invalid. If set, the value must be "disabled".

source: namespaces/foo/role.yaml
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1006: ObjectParseError

이 오류는 저장소에서 선언된 객체를 파싱할 수 없을 때 발생합니다. 이 오류를 해결하려면 kubectl --validate와 같은 도구를 사용하여 yaml 형식의 유효성을 검사하세요.

예를 들면 다음과 같습니다.

KNV1006: The following config could not be parsed as a rbac.authorization.k8s.io/v1, Kind=Role:

source: namespaces/foo/role.yaml
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1007: IllegalAbstractNamespaceObjectKindError

구조화되지 않은 저장소를 사용하는 경우 추상 네임스페이스 디렉터리에서 구성을 선언하면 안 됩니다. 구조화되지 않은 저장소 사용에 대한 자세한 내용은 구조화되지 않은 저장소 사용을 참조하세요.

KNV1007: Config "default-name" illegally declared in an abstract namespace directory. Move this config to a namespace directory:

source: namespaces/foo/bar/role.yaml
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1009: IllegalMetadataNamespaceDeclarationError

계층적 저장소 구조를 사용하는 경우 구성에 따라 이를 포함하는 네임스페이스 디렉터리와 일치하는 네임스페이스를 선언하거나 필드를 생략합니다.

다음은 오류를 트리거하는 역할 구성의 예시입니다.

# namespaces/shipping-prod/pod-reader-role.yaml
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: pod-reader
  namespace: shipping-dev
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "watch", "list"]

이러한 네임스페이스로 구성을 선언하면 다음 오류가 발생합니다.

KNV1009: A config MUST either declare a `namespace` field exactly matching the directory containing the config, "shipping-prod", or leave the field blank:

source: namespaces/shipping-prod/pod-reader-role.yaml
namespace: shipping-dev
metadata.name: pod-reader
group: rbac.authorization.k8s.io
version: v1
kind: Role

계층적 저장소 구조에 대한 자세한 내용은 계층적 저장소 구조를 참조하세요.

KNV1010: IllegalAnnotationDefinitionError

구성은 configmanagement.gke.io로 시작하는 지원되지 않는 주석을 선언해서는 안 됩니다.

지원되는 주석은 다음과 같습니다.

configmanagement.gke.io/managed: 사용에 대한 자세한 내용은 객체 관리를 참조하세요.
configmanagement.gke.io/namespace-selector: 사용에 대한 자세한 내용은 네임스페이스 범위 객체를 참조하세요.
configmanagement.gke.io/cluster-selector: 사용에 대한 자세한 내용은 ClusterSelector를 참조하세요.

오류 예시:

KNV1010: Configs MUST NOT declare unsupported annotations starting with
         "configmanagement.gke.io/". The config has invalid annotations:
         "configmanagement.gke.io/invalid", "configmanagement.gke.io/sync-token"

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1011: IllegalLabelDefinition

구성에는 configmanagement.gke.io/로 시작하는 키가 있는 라벨이 없어야 합니다. 이 라벨 키 프리픽스는 구성 동기화에서 사용하도록 예약되어 있습니다.

다음은 이 오류를 트리거하는 ConfigMap의 예시입니다.

# namespaces/prod/mymap.yaml
kind: ConfigMap
apiVersion: v1
metadata:
  name: my-map
  labels:
    configmanagement.gke.io/bad-label: label-value
data:
  mydata: moredata

이러한 라벨을 사용하여 구성을 선언하면 다음 오류가 발생합니다.

KNV1011: Configs MUST NOT declare labels starting with "configmanagement.gke.io/". The config has disallowed labels: "configmanagement.gke.io/bad-label"

source: namespaces/prod/mymap.yaml
metadata.name: my-map
group:
version: v1
kind: ConfigMap

KNV1012: NamespaceSelectorMayNotHaveAnnotation

구성 동기화 1.3에서 지원 중단되었습니다.

KNV1013: ObjectHasUnknownSelector

구성이 존재하지 않는 ClusterSelector 또는 NamespaceSelector를 참조합니다. 구성의 주석에서 선택기를 사용하려면 먼저 선택기가 있어야 합니다.

선택기가 삭제된 경우 이를 참조하는 모든 구성도 삭제합니다. 다음 예시에서는 저장소의 clusterregistry/ 디렉터리에 unknown-cluster-selector ClusterSelector가 없다고 가정합니다.

# namespaces/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: foo
  annotations:
    configmanagement.gke.io/cluster-selector: unknown-cluster-selector

이로 인해 다음 오류가 발생합니다.

KNV1013: Config "foo" MUST refer to an existing ClusterSelector, but has
         annotation
         "configmanagement.gke.io/cluster-selector=unknown-cluster-selector",
         which maps to no declared ClusterSelector

NamespaceSelector 주석에는 참조된 NamespaceSelector가 구성 참조와 동일한 디렉터리 또는 상위 디렉터리에 정의되어야 한다는 추가 요구사항이 있습니다. 그렇지 않으면 다음 오류가 발생합니다.

KNV1013: Config "default-name" MUST refer to a NamespaceSelector in its directory or a parent directory. Either remove the annotation "configmanagement.gke.io/namespace-selector=default-ns-selector" from "default-name" or move NamespaceSelector "default-ns-selector" to a parent directory of "default-name".

    source: namespaces/bar/selector.yaml
    metadata.name: default-ns-selector
    group: configmanagement.gke.io
    version: v1
    kind: NamespaceSelector

    source: namespaces/foo/role.yaml
    metadata.name: default-name
    group: rbac.authorization.k8s.io
    version: v1
    kind: Role

KNV1014: InvalidSelectorError

ClusterSelector 및 NamespaceSelector 구성이 올바른 구문을 사용하지만 구문 오류가 발견되었습니다. 이 문제를 해결하려면 적절한 데이터 스키마에 따라 구성을 지정해야 합니다.

예를 들어 다음은 잘못된 ClusterSelector입니다.

kind: ClusterSelector
apiVersion: configmanagement.gke.io/v1
metadata:
  name: selector-1
spec:
  selector:
    someUnknownField:  # This field is not defined for a LabelSelector
      foo: bar

다음 오류가 발생합니다.

KNV1014: ClusterSelector has validation errors that must be corrected: invalid field "someUnknownField"
    source: clusterregistry/cs.yaml
    metadata.name: selector-1
    group: configmanagement.gke.io
    version: v1
    kind: ClusterSelector

특히 ClusterSelector 및 NamespaceSelector 정의는 spec.selector 필드를 정의합니다. 그렇지 않으면 다음 오류가 발생합니다.

   KNV1014: NamespaceSelectors MUST define `spec.selector`

    source: namespaces/ns.yaml
    metadata.name: ns-selector-1
    group: configmanagement.gke.io
    version: v1
    kind: NamespaceSelector

KNV1016: PolicyManagementNotInstalledError

구성 동기화 1.3.2에서 지원 중단되었습니다.

KNV1017: MissingRepoError

계층적 저장소 구조를 사용하는 경우 저장소 구성이 저장소의 system/ 디렉터리에 있어야 하며 저장소의 시맨틱 버전과 같은 필수 정보를 포함해야 합니다.

저장소 구성이 없으면 다음 오류가 발생합니다.

KNV1017: The system/ directory must declare a Repo Resource.
path: system/

To fix, define at least a minimal Repo config.

# system/repo.yaml
kind: Repo
apiVersion: configmanagement.gke.io/v1
metadata:
  name: repo
spec:
  version: "0.1.0"

계층적 저장소 구조에 대한 자세한 내용은 계층적 저장소 구조를 참조하세요.

KNV1018: IllegalSubdirectoryError

구성 동기화 1.3에서 지원 중단되었습니다.

KNV1019: IllegalTopLevelNamespaceError

계층적 저장소 구조를 사용하는 경우 namespaces/에서 네임스페이스를 직접 선언하면 안 됩니다.

다음은 오류를 트리거하는 구성입니다.

# namespaces/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: namespaces
source: namespaces/namespace.yaml
metadata.name: namespaces
group:
version: v1
kind: Namespace

   KNV1019: Namespaces MUST be declared in subdirectories of 'namespaces/'. Create a subdirectory for the following Namespace configs:

    source: namespaces/namespace.yaml
    metadata.name: namespaces
    group:
    version: v1
    kind: Namespace

계층적 저장소 구조에 대한 자세한 내용은 계층적 저장소 구조를 참조하세요.

KNV1020: InvalidNamespaceNameError

계층적 저장소 구조를 사용하는 경우 네임스페이스 구성으로 metadata.name이 선언되고 해당 값이 네임스페이스의 디렉터리 이름과 일치해야 합니다. 이 오류를 해결하려면 네임스페이스의 metadata.name 또는 관련 디렉터리를 수정합니다.

다음은 오류를 트리거하는 구성입니다.

# namespaces/prod/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: dev

KNV1020: A Namespace MUST declare `metadata.name` that matches the name of its
         directory.

expected `metadata.name`: prod

source: namespaces/prod/namespace.yaml
metadata.name: dev
group:
version: v1
kind: Namespace

계층적 저장소 구조에 대한 자세한 내용은 계층적 저장소 구조를 참조하세요.

KNV1021: UnknownObjectError

KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.
         Resource types that are not native Kubernetes objects must have a
         CustomResourceDefinition.

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1024: IllegalKindInSystemError

KNV1024: Configs of this Kind may not be declared in the `system/` directory of
         the repo:

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1027: UnsupportedRepoSpecVersion

저장소 구성의 spec.version 필드는 저장소의 시맨틱 버전을 나타냅니다. 이 오류는 지원되지 않는 버전을 사용하고 있음을 나타냅니다.

저장소 형식이 지원되는 버전과 호환되면 spec.version 필드를 업데이트하세요.

업그레이드해야 하는 경우 출시 노트의 안내를 따릅니다.

# system/repo.yaml
kind: Repo
apiVersion: configmanagement.gke.io/v1
metadata:
  name: repo
spec:
  version: "0.0.0"

이로 인해 다음 오류가 발생합니다.

KNV1027: Unsupported Repo spec.version: "0.0.0". Must use version "main"

source: system/repo.yaml
name: repo
group: configmanagement.gke.io
version: v1
kind: Repo

KNV1028: InvalidDirectoryNameError

KNV1028: Directory names have fewer than 64 characters, consist of lower case
         alphanumeric characters or '-', and must start and end with an
         alphanumeric character. Rename or remove directory:

path: namespaces/a.b`c
name: a.b`c

KNV1029: MetadataNameCollisionError

KNV1029: Configs of the same Kind MUST have unique names in the same Namespace
         and their parent abstract namespaces:

source: namespaces/foo/r1.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

source: namespaces/foo/r2.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1030: MultipleSingletonsError

KNV1030: Multiple Namespace resources cannot exist in the same directory. To fix, remove the duplicate config(s) such that no more than 1 remains:

source: namespaces/foo/namespace.yaml
metadata.name: foo
group:
version: v1
kind: Namespace

source: namespaces/foo/namespace.yaml
metadata.name: foo
group:
version: v1
kind: Namespace

KNV1031: MissingObjectNameError

모든 구성은 metadata.name을 선언해야 합니다. 이 오류를 해결하려면 문제가 있는 구성에 metadata.name 필드를 추가합니다.

KNV1031: A config must declare metadata.name:

source: namespaces/foo/role.yaml
metadata.name:
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1032: IllegalHierarchicalKindErrorCode

KNV1032: The type Repo.configmanagement.gke.io is not allowed if `sourceFormat` is set to `unstructured`. To fix, remove the problematic config, or convert your repo to use `sourceFormat: hierarchy`.

source: system/repo.yaml
metadata.name: repo
group: configmanagement.gke.io
version: v1
kind: Repo

KNV1033: IllegalSystemResourcePlacementError

일부 종류는 system/ 디렉터리 내에서만 선언할 수 있습니다. 다음은 system/ 디렉터리에만 존재할 수 있는 종류의 목록입니다. - HierarchyConfig - Repo

KNV1033: A config of the below Kind MUST NOT be declared outside system/:

source: namespaces/foo/repo.yaml
metadata.name: repo
group: configmanagement.gke.io
version: v1
kind: Repo

KNV1034: IllegalNamespaceError

config-management-system 네임스페이스 또는 그 안에 있는 리소스를 선언하는 것은 금지되어 있습니다. 이 오류를 해결하려면 config-management-system 네임스페이스와 해당 네임스페이스 내 구성을 삭제하세요.

KNV1034: Configs must not be declared in the "config-management-system" namespace

source: namespaces/config-management-system/role.yaml
namespace: namespaces/config-management-system
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1034: The "config-management-system" namespace must not be declared

source: namespaces/config-management-system/namespace.yaml
metadata.name: config-management-system
group:
version: v1
kind: Namespace

구성 동기화 버전 1.17.0부터 정보 소스에서 resource-group-system 및 config-management-monitoring 네임스페이스를 선언할 수 없습니다. 또한 resource-group-system 및 config-management-monitoring 네임스페이스 아래에 리소스를 선언하는 것은 권장되지 않습니다.

정보 소스에 이러한 두 네임스페이스가 포함된 경우 구성 동기화가 다음 오류를 보고합니다.

KNV1034: The "config-management-system" namespace must not be declared

source: namespaces/config-management-monitoring/namespace.yaml
metadata.name: config-management-monitoring
group:
version: v1
kind: Namespace

이 문제를 해결하고 컨트롤러 네임스페이스를 안전하게 관리 해제하려면 다음 안내를 따릅니다.

구성 동기화를 업데이트하여 네임스페이스 관리를 중지하고 그 아래에 선언된 리소스 관리를 중지합니다.
동기화를 기다린 후 해당 리소스가 클러스터에서 여전히 사용할 수 있지만 nomos status에서 사용할 수 없는지 확인합니다.
소스에서 컨트롤러 네임스페이스 YAML 파일을 삭제합니다.
구성 동기화가 리소스 관리를 재개하도록 허용합니다.

이전에 계층 구조 저장소로 동기화했고 리소스와 함께 컨트롤러 네임스페이스를 선언해야 한 경우에는 소스 구조의 유연성 향상을 위해 구조화되지 않은 저장소로 전환을 고려하세요.

KNV1036: InvalidMetadataNameError

제공된 metadata.name의 형식이 잘못되었습니다. 유효한 metadata.name은 254자 미만이어야 하고, 소문자 영숫자 문자, ‘-’ 또는 ‘.’으로 구성되어야 하며, 시작과 끝이 영숫자 문자여야 합니다.

이 오류를 해결하려면 이전 조건을 충족하도록 metadata.name을 변경하세요.

KNV1036: Configs MUST define a metadata.name that is shorter than 254
        characters, consists of lower case alphanumeric characters, '-' or '.',
         and must start and end with an alphanumeric character. Rename or remove
         the config:

source: namespaces/foo/role.yaml
metadata.name: a`b.c
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1037: IllegalKindInClusterregistryError

구성 동기화 1.3에서 지원 중단되었습니다.

KNV1038: IllegalKindInNamespacesError

KNV1038: Configs of the below Kind may not be declared in `namespaces/`:

source: cluster/cr.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: ClusterRole

KNV1039: IllegalKindInClusterError

네임스페이스 범위 객체를 namespace/ 외부에서 선언하거나 클러스터 범위 객체를 cluster/ 외부에서 선언하는 것은 금지되어 있습니다. 이 오류를 해결하려면 문제가 있는 구성을 법적 디렉터리에 재배치하세요.

클러스터 범위 객체에 대한 자세한 내용은 클러스터 범위 객체를 참조하세요.

네임스페이스 범위 객체에 대한 자세한 내용은 네임스페이스 범위 객체를 참조하세요.

KNV1039: Namespace-scoped configs of the below Kind must not be declared in
         cluster/:

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1040: UnknownResourceInHierarchyConfigError

구성 동기화 1.3에서 지원 중단되었습니다.

KNV1041: UnsupportedResourceInHierarchyConfigError

KNV1041: This Resource Kind MUST NOT be declared in a HierarchyConfig:

source: system/hc.yaml
group: configmanagement.gke.io
kind: Repo

KNV1042: IllegalHierarchyModeError

HierarchyConfig에서 잘못된 HierarchyMode 값이 감지되었습니다. HierarchyMode는 none 또는 inherit여야 합니다.

HierarchyConfig에 대한 자세한 내용은 객체 유형에 상속 사용 중지를 참조하세요.

KNV1042: HierarchyMode invalid is not a valid value for the APIResource Role.rbac.authorization.k8s.io. Allowed values are [none,inherit].

source: system/hc.yaml
metadata.name: default-name
group: configmanagement.gke.io
version: v1
kind: HierarchyConfig

KNV1043: UnsupportedObjectError

KNV1043: Config Sync cannot configure this object. To fix, remove this
         config from the repo.

source: namespaces/foo/role.yaml
metadata.name: role
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1044: UnsyncableResourcesErrorCode

KNV1044: An Abstract Namespace directory with configs MUST have at least one
Namespace subdirectory. To fix, do one of the following: add a Namespace
directory below "bar", add a Namespace config to "bar", or remove the configs in
"bar":

path: namespaces/foo/bar/

KNV1045: IllegalFieldsInConfigError

오류 메시지 예시:

KNV1045: Configs with "metadata.ownerReference" specified are not allowed. To
fix, either remove the config or remove the "metadata.ownerReference" field in
the config:

source: namespaces/foo/replicaset.yaml
metadata.name: replicaSet
group: apps
version: v1
kind: ReplicaSet

status 필드가 이 오류를 일으키는 잘못된 필드 중 하나입니다. 다른 컨트롤러가 클러스터의 status 필드를 동적으로 관리하고 업데이트해야 하므로 구성 동기화를 사용하여 status 필드를 동기화하는 것은 허용되지 않습니다. 구성 동기화가 status 필드의 원하는 상태를 제어하려고 하면 status 필드 관리를 담당하는 컨트롤러와 충돌하게 됩니다.

이 오류를 해결하려면 소스 저장소에서 status 필드를 삭제하세요. 소유하지 않은 타사 구성의 경우 kustomize 패치를 사용하여 매니페스트에 지정된 status 필드를 대량으로 삭제합니다.

KNV1046: ClusterScopedResourceInHierarchyConfigError

KNV1046: This HierarchyConfig references the APIResource "ClusterSelector.configmanagement.gke.io" which has cluster scope. Cluster scoped objects are not permitted in HierarchyConfig.

source: system/hc.yaml
metadata.name: hierarchyconfig
group: configmanagement.gke.io
version: v1
kind: HierarchyConfig

KNV1047: UnsupportedCRDRemovalError

KNV1047: Removing a CRD and leaving the corresponding Custom Resources in the
repo is disallowed. To fix, remove the CRD along with the Custom Resources.

source: cluster/crd.yaml
metadata.name: customResourceDefinition
group: apiextensions.k8s.io
version: v1beta1
kind: CustomResourceDefinition

KNV1048: InvalidCRDNameError

KNV1048: The CustomResourceDefinition has an invalid name. To fix, change the
name to `spec.names.plural+"."+spec.group`.

source: cluster/crd.yaml
metadata.name: customResourceDefinition
group: apiextensions.k8s.io
version: v1beta1
kind: CustomResourceDefinition

KNV1050: DeprecatedGroupKindError

KNV1050: The config is using a deprecated Group and Kind. To fix, set the Group and Kind to "Deployment.apps"

source: namespaces/deployment.yaml
metadata.name: default-name
group: extensions
version: v1beta1
kind: Deployment

KNV1052: IllegalNamespaceOnClusterScopedResourceError

KNV1052: cluster-scoped resources MUST NOT declare metadata.namespace

namespace: foo
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: ClusterRole

KNV1053: MissingNamespaceOnNamespacedResourceError

KNV1053: namespace-scoped resources MUST either declare either metadata.namespace or metadata.annotations.configmanagement.gke.io/namespace-selector

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1054: InvalidAnnotationValueError

구성에 잘못된 주석 값이 포함되면 이 오류가 발생합니다.

오류 예시:

KNV1054: Values in metadata.annotations MUST be strings. To fix, add quotes around the values. Non-string values for:

metadata.annotations.foo
metadata.annotations.bar

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1055: InvalidNamespaceError

이 오류는 metadata.namespace 값이 적합한 Kubernetes 네임스페이스 이름이 아님을 나타냅니다.

오류 예시:

KNV1055: metadata.namespace MUST be valid Kubernetes Namespace names. Rename "FOO" so that it:

1. has a length of 63 characters or fewer;
2. consists only of lowercase letters (a-z), digits (0-9), and hyphen '-'; and
3. begins and ends with a lowercase letter or digit.

namespace: FOO
metadata.name: repo
group: configmanagement.gke.io
version: v1
kind: Repo

KNV1056: ManagedResourceInUnmanagedNamespace

이 오류는 리소스가 관리되지 않는 네임스페이스에 선언되었음을 나타냅니다. 이를 해결하려면 configmanagement.gke.io/managed: disabled 주석을 삭제하거나 선언된 리소스에 주석을 추가합니다.

오류 예시:

KNV1056: Managed resources must not be declared in unmanaged Namespaces. Namespace "foo" is declared unmanaged but contains managed resources. Either remove the managed: disabled annotation from Namespace "foo" or declare its resources as unmanaged by adding configmanagement.gke.io/managed:disabled annotation.

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1057: IllegalDepthLabel

이 오류는 리소스에 잘못된 라벨이 있음을 나타냅니다. 이를 해결하려면 .tree.hnc.x-k8s.io/depth로 끝나는 라벨을 삭제합니다.

오류 예시:

KNV1057: Configs MUST NOT declare labels ending with ".tree.hnc.x-k8s.io/depth". The config has disallowed labels: "label.tree.hnc.x-k8s.io/depth"

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV1058: BadScopeError

네임스페이스 저장소는 저장소가 적용되는 네임스페이스의 네임스페이스 범위 리소스만 선언할 수 있습니다. 예를 들어 shipping 네임스페이스 저장소의 저장소는 shipping 네임스페이스의 리소스만 관리할 수 있습니다.

metadata.namespace 값은 선택사항입니다. 기본적으로 구성 동기화는 네임스페이스 저장소의 모든 리소스가 해당 네임스페이스에 속한다고 가정합니다.

예를 들어 shipping 네임스페이스 저장소의 구성이 metadata.namespace: billing을 선언하면 nomos 명령어는 다음 오류를 출력합니다.

KNV1058: Resources in the "shipping" repo must either omit metadata.namespace or declare metadata.namespace="shipping"

namespace: billing
metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

KNV 1059: MultipleKptfilesError

네임스페이스 저장소는 Kptfile 리소스를 최대 1개까지 선언할 수 있습니다.

예를 들어 네임스페이스 저장소가 두 개의 Kptfile을 선언한 경우 nomos 명령어는 다음 오류를 출력합니다.

KNV1059: Namespace Repos may contain at most one Kptfile

metadata.name: package-a
group: kpt.dev
version: v1alpha1
kind: Kptfile

metadata.name: package-b
group: kpt.dev
version: v1alpha1
kind: Kptfile

For more information, see https://g.co/cloud/acm-errors#knv1059

KNV 1060: ManagementConflictError

여러 정보 소스에서 객체를 관리할 때 동일한 객체(일치하는 그룹, 종류, 이름, 네임스페이스)가 둘 이상의 소스에서 선언되면 충돌이 발생할 수 있습니다.

충돌을 일으킬 수 있는 몇 가지 시나리오는 다음과 같습니다.

RootSync와 RepoSync 비교: 동일한 객체가 RootSync 및 RepoSync에서 관리되는 경우 RootSync가 우선합니다. RootSync가 먼저 적용되는 경우 RepoSync는 KNV1060 상태 오류를 보고합니다. RepoSync가 먼저 적용되면 RootSync가 RepoSync의 객체를 덮어쓰고 RepoSync는 업데이트를 볼 때 KNV1060 상태 오류를 보고합니다.
RepoSync와 RepoSync 비교: 동일한 객체가 2개의 RepoSync에서 관리되는 경우 첫 번째 RepoSync가 우선합니다. 적용할 두 번째 RepoSync는 첫 번째 RepoSync에서 객체가 이미 관리되고 있음을 확인하고 KNV1060 상태 오류를 보고합니다.
허용 웹훅이 사용 설정된 경우 RootSync 간 비교: 동일한 객체가 2개의 RootSync에서 관리되고 허용 웹훅이 사용 설정된 경우 객체를 적용하는 첫 번째 RootSync가 우선 적용됩니다. 적용할 두 번째 RootSync는 허용 웹훅에서 객체가 이미 관리되고 있다는 오류를 수신하고 KNV1060 상태 오류를 보고합니다.
허용 웹훅이 사용 중지된 경우 RootSync 간 비교: 동일한 객체가 2개의 RootSync에서 관리되고 허용 웹훅이 사용 중지된 경우 두 RootSync 객체는 객체의 소유권을 채택하기 위해 지속적으로 싸우고 둘 다 KNV1060 상태 오류를 보고합니다.

충돌하는 오류의 예시는 다음과 같습니다.

KNV1060: The root reconciler detects a management conflict for a resource declared in another repository. Remove the declaration for this resource from either the current repository, or the repository managed by root-reconciler.

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

오류가 발생하면 다른 정보 소스와 일치하도록 구성을 업데이트하거나 소스 중 하나에서 충돌하는 객체를 삭제하여 충돌을 해결할 수 있습니다.

KNV 1061: InvalidRepoSyncError

구성 동기화가 네임스페이스 저장소의 구성을 동기화하려면 RepoSync 객체가 올바르게 구성되어야 합니다. InvalidRepoSyncError는 RepoSync가 잘못 구성되었음을 알려주며 이를 해결하기 위한 방법을 분명하게 설명하는 메시지가 표시됩니다.

예를 들어 shipping 저장소에 repo-sync라는 RepoSync가 있어야 하지만 RepoSync의 이름이 invalid이면 nomos 명령어가 다음 오류를 출력합니다.

KNV1061: RepoSyncs must be named "repo-sync", but the RepoSync for Namespace "shipping" is named "invalid"

metadata.name: invalid
group: configsync.gke.io
version: v1alpha1
kind: RepoSync

KNV1062: InvalidKptfileError

이 오류는 Kptfile에 유효한 인벤토리 필드가 없는 경우에 발생합니다. Kptfile에는 식별자 및 네임스페이스가 모두 지정된 비어 있지 않은 인벤토리 필드가 있어야 합니다. 이를 해결하려면 Kptfile에서 .inventory.identifier 및 .inventory.namespace 값을 지정해야 합니다.

오류 예시는 다음과 같습니다.

KNV1062: Invalid inventory invalid name

metadata.name: default-name
group: kpt.dev
version: v1alpha1
kind: Kptfile

KNV1063: KptfileExistError

이 오류는 Kptfiles가 루트 저장소에서 확인되는 경우에 발생합니다. kptfiles는 네임스페이스 범위의 저장소에서만 지원됩니다.

이 오류를 해결하려면 루트 저장소에서 Kptfiles를 삭제합니다.

오류 예시는 다음과 같습니다.

KNV1063: Found Kptfile(s) in the Root Repo. Kptfile(s) are only supported in Namespace Repos. To fix, remove the Kptfile(s) from the Root Repo.

namespace: namespace
metadata.name: default-name
group: kpt.dev
version: v1alpha1
kind: Kptfile

For more information, see https://g.co/cloud/acm-errors#knv1063

KNV1064: InvalidAPIResourcesError

이 오류는 저장소의 api-resources.txt 파일을 파싱할 수 없음을 나타냅니다.

오류 예시는 다음과 같습니다.

KNV1064: invalid NAMESPACED column value "other" in line:
rbac      other     Role

Re-run "kubectl api-resources > api-resources.txt" in the root policy directory

path: /api-resources.txt

For more information, see https://g.co/cloud/acm-errors#knv1064

KNV1064: unable to find APIVERSION column. Re-run "kubectl api-resources > api-resources.txt" in the root policy directory

path: /api-resources.txt

For more information, see https://g.co/cloud/acm-errors#knv1064

KNV1064: unable to read cached API resources: missing file permissions

path: /api-resources.txt

For more information, see https://g.co/cloud/acm-errors#knv1064

또한 nomos 버전 1.16.1 이하에서 이 오류가 표시됩니다.

KNV1064: unable to find APIGROUP column. Re-run "kubectl api-resources > api-resources.txt" in the root policy directory

path: /api-resources.txt

For more information, see https://g.co/cloud/acm-errors#knv1064

이는 APIGROUP에서 APIVERSION으로 변경된 열 이름으로 인해 발생합니다. 이 문제를 해결하려면 api-resources.txt에서 APIVERSION을 수동으로 APIGROUP으로 바꿉니다.

KNV1065: MalformedCRDError

이 오류는 CustomResourceDefinition이 기형인 경우 발생합니다. 이 오류를 해결하려면 오류 메시지에서 지정한 필드를 확인하고 값의 형식이 올바르게 지정되었는지 확인합니다.

오류 예시는 다음과 같습니다.

KNV1065: malformed CustomResourceDefinition: spec.names.shortNames accessor error: foo is of the type string, expected []interface{}.

path: namespaces/foo/crd.yaml

For more information, see https://g.co/cloud/acm-errors#knv1065

KNV1066: ClusterSelectorAnnotationConflictError

구성 객체는 반드시 하나의 클러스터 선택기 주석만 선언해야 합니다. 이 오류는 기존 주석(configmanagement.gke.io/cluster-selector)과 인라인 주석(configsync.gke.io/cluster-name-selector)이 모두 존재하는 경우에 발생합니다.

이 오류를 해결하려면 metadata.annotations 필드에서 주석 중 하나를 삭제합니다.

예를 들어 네임스페이스 구성이 두 주석을 모두 선언한 경우 nomos 명령어는 다음 오류를 출력합니다.

KNV1066: Config "my-namespace" MUST declare ONLY ONE cluster-selector annotation, but has both inline annotation "configsync.gke.io/cluster-name-selector" and legacy annotation "configmanagement.gke.io/cluster-selector". To fix, remove one of the annotations from:

metadata.name: my-namespace
group:
version: v1
kind: Namespace

For more information, see https://g.co/cloud/acm-errors#knv1066

KNV1067: EncodeDeclaredFieldError

이 오류는 조정자가 선언된 필드를 서버 측 적용과 호환되는 형식으로 인코딩하지 못할 때 발생합니다. 오래된 스키마로 인해 발생할 수 있습니다. 이를 해결하려면 오류 메시지에 지정된 필드를 확인하고 리소스 종류의 스키마와 일치하는지 확인합니다.

오류 예시는 다음과 같습니다.

KNV1067: failed to encode declared fields: .spec.version not defined

metadata.name: my-namespace
group:
version: v1
kind: Namespace

For more information, see https://g.co/cloud/acm-errors#knv1067

Kubernetes 1.27 이전 버전을 실행하는 클러스터에서 이 오류가 발생할 수 있는 문제가 알려져 있습니다. 이 문제를 해결하려면 기본 TCP을 사용하는 경우에도 spec: containers: ports:에 protocol 필드를 명시적으로 설정하세요.

KNV1068: ActionableRenderingError

이 오류는 렌더링 프로세스에 사용자 작업 가능한 문제가 발생했음을 나타냅니다.

한 가지 예시는 Git 저장소에 Kustomize 구성이 포함되지만 Git 동기화 디렉터리에 kustomization.yaml 파일이 없는 경우입니다.

KNV1068: Kustomization config file is missing from the sync directory 'foo/bar'. To fix, either add kustomization.yaml in the sync directory to trigger the rendering process, or remove kustomization.yaml from all sub directories to skip rendering.

For more information, see https://g.co/cloud/acm-errors#knv1068

kustomize build 오류로 인해 오류가 발생한 경우 Git 저장소에서 Kustomize 구성을 업데이트해야 할 수 있습니다. 각각 nomos hydrate 및 nomos vet을 사용하여 업데이트된 구성을 로컬로 미리보고 검증할 수 있습니다. 업데이트된 구성이 성공적으로 렌더링되었으면 새 커밋을 푸시하여 KNV1068 오류를 해결할 수 있습니다. 자세한 내용은 저장소에서 모든 구성 결과 보기 및 저장소에서 오류 확인을 참조하세요.

kustomize build 오류 예시:

KNV1068: Error in the hydration-controller container: unable to render the source configs in /repo/source/3b724d1a17314c344fa24512239cb3b22b9d90ec: failed to run kustomize build ...

For more information, see https://g.co/cloud/acm-errors#knv1068

공개 저장소에서 원격 기반을 가져올 때 kustomize build 오류가 발생하면 spec.override.enableShellInRendering을 true로 설정해야 합니다.

kustomize build 오류 예시:

KNV1068: failed to run kustomize build in /repo/source/0a7fd88d6c66362584131f9dfd024024352916af/remote-base, stdout:...
no 'git' program on path: exec: "git": executable file not found in $PATH

For more information, see https://g.co/cloud/acm-errors#knv1068

KNV1069: SelfManageError

이 오류는 조정자가 자체 RootSync 또는 RepoSync 객체를 조정할 때 발생합니다. RootSync 객체는 다른 RootSync 및 RepoSync 객체를 관리할 수 있지만 RepoSync 객체는 다른 RepoSync 객체를 관리할 수 있지만 자체 관리는 할 수 없습니다. 이 문제를 해결하려면 객체가 동기화되는 정보 소스에서 RootSync 또는 RepoSync 객체를 삭제할 수 있습니다.

오류 예시는 다음과 같습니다.

KNV1069: RootSync config-management-system/root-sync must not manage itself in its repo

namespace: config-management-system
metadata.name: root-sync
group: configsync.gke.io
version: v1beta1
kind: RootSync

For more information, see https://g.co/cloud/acm-errors#knv1069

KNV2001: pathError

이 오류는 파일 시스템 리소스에 액세스하는 OS 수준 시스템 호출이 실패하면 발생합니다.

잘못된 YAML 구성

YAML 파일에 잘못된 구성이 있으면 다음과 유사한 오류 메시지가 표시될 수 있습니다.

KNV2001: yaml: line 2: did not find expected node content path:...

이 문제를 해결하려면 YAML 파일을 확인하고 구성 문제를 해결하세요. 이 문제는 저장소 내 YAML 구성으로 인해 발생할 수 있습니다.

경로 이름의 특수문자

파일 이름 또는 경로 이름에 특수문자가 있으면 다음과 유사한 오류 메시지가 표시될 수 있습니다.

KNV2001: yaml: control characters are not allowed path:
/repo/source/.../._pod.yaml

이 예시에서 ._pod.yaml은 유효한 파일 이름이 아닙니다.

이 문제를 해결하려면 파일 또는 경로 이름에서 특수문자를 삭제하세요.

KNV2002: apiServerError

이 오류는 API 서버에 액세스하는 요청이 실패하면 발생합니다.

KNV2003: osError

이 오류는 일반적인 OS 수준 시스템 호출이 실패하면 발생합니다.

KNV2004: SourceError

이 오류는 구성 동기화가 정보 소스에서 읽을 수 없음을 나타냅니다. 일반적으로 다음 오류 중 하나가 원인일 수 있습니다.

클러스터 내에서 Git 저장소에 연결할 수 없습니다.

git-sync 컨테이너의 로그에 저장소에 연결할 수 없음을 나타내는 오류가 발생합니다. 예를 들면 ssh: connect to host source.developers.google.com port 2022: Network is unreachable입니다. 이 문제를 해결하려면 클러스터의 방화벽 또는 네트워크 구성을 조정하세요.

잘못된 구성 디렉터리

ConfigManagement 객체의 policyDir 값 또는 RootSync 또는 RepoSync 객체의 spec.git.dir 또는 spec.oci.dir과 같은 잘못된 값을 확인합니다. 디렉터리 값이 오류에 포함됩니다. Git 저장소 또는 OCI 이미지와 비교하여 값을 확인합니다.

잘못된 차트 이름

Helm 저장소에서 동기화할 때 spec.helm.chart에 대해 올바른 값을 설정해야 합니다. 차트 이름에는 차트 버전 또는 .tgz가 포함되지 않습니다. helm template 명령어로 차트 이름을 확인할 수 있습니다.

잘못된 Git 또는 Helm 사용자 인증 정보

다음 오류 중 하나에 대해 git-sync 또는 helm-sync 컨테이너 로그를 확인합니다.

Could not read from remote repository. Ensure you have the correct access rights and the repository exists.
Invalid username or password. Authentication failed for ...
401 Unauthorized

Git 저장소의 경우 Git 사용자 인증 정보 및 git-creds 보안 비밀이 올바르게 구성되었는지 확인합니다.

Helm 저장소의 경우 Helm 사용자 인증 정보가 올바르게 구성되었는지 확인합니다.

잘못된 Git 저장소 URL

git-sync 컨테이너의 로그를 통해 Repository not found.와 같은 오류가 있는지 확인합니다.

사용 중인 URL 형식이 올바른지 확인합니다. 예를 들어 SSH 키 쌍을 사용하여 Git 저장소 인증을 수행하는 경우 구성 동기화를 구성할 때 Git 저장소에 입력하는 URL에 SSH 프로토콜이 사용되는지 확인합니다.

잘못된 Helm 저장소 URL

helm-sync 컨테이너의 로그를 통해 ...not a valid chart repository와 같은 오류가 있는지 확인합니다. 사용 중인 URL 형식이 올바른지 확인합니다. 예를 들어 OCI 레지스트리에서 동기화하는 경우 URL이 oci://로 시작합니다. helm template 명령어를 사용하여 Helm 저장소 URL을 확인할 수 있습니다.

잘못된 Git 브랜치

git-sync 컨테이너의 로그를 통해 Remote branch BRANCH_NAME not found in upstream origin 또는 warning: Could not find remote branch BRANCH_NAME to clone.와 같은 오류가 있는지 확인합니다. 기본 브랜치는 지정하지 않은 경우 master로 설정됩니다.

서버 인증서 확인 실패

이 오류는 Git 서버가 git-sync 클라이언트에서 인식할 수 없는 인증 기관(CA)에서 발급한 인증서를 사용하는 경우 HTTPS를 통해 Git 서버에 연결할 때 발생할 수 있습니다.

자체 CA를 관리하는 경우 Git 서버가 CA에서 인증서를 발급받고 caCertSecretRef 필드가 올바르게 구성되어 있는지 확인합니다.

Google 서비스 계정 사용 시 권한 문제

리더 액세스 누락

Google 서비스 계정(spec.git.gcpServiceAccountEmail, spec.oci.gcpServiceAccountEmail, spec.helm.gcpServiceAccountEmail)을 사용하여 Cloud Source Repositories, Artifact Registry 또는 Artifact Registry에 인증하는 경우 Google 서비스 계정에는 다음과 같은 리더 액세스 권한이 있어야 합니다.

Cloud Source Repositories: roles/source.reader
Artifact Registry: roles/artifactregistry.reader

그렇지 않으면 git-sync, oci-sync, helm-sync가 다음 오류와 함께 실패합니다.

failed to pull image us-docker.pkg.dev/...: GET https://us-docker.pkg.dev/v2/token?scope=repository...: DENIED: Permission \"artifactregistry.repositories.downloadArtifacts\" denied on resource \"projects/.../locations/us/repositories/...\" (or it may not exist)

또는 "Err":"failed to render the helm chart: exit status 1, stdout: Error: failed to download ... 이 문제를 해결하려면 올바른 리더 액세스 권한이 있는 서비스 계정을 부여하세요.

워크로드 아이덴티티를 사용할 때 IAM 정책 바인딩 누락

인증에 Google 서비스 계정을 사용하는 경우 Google 서비스 계정과 Kubernetes 서비스 계정 간에 IAM 정책 바인딩이 필요합니다. IAM 정책 바인딩이 없으면 다음 오류가 발생합니다.

KNV2004: unable to sync repo Error in the git-sync container: ERROR: failed to call ASKPASS callback URL: auth URL returned status 500, body: "failed to get token from credentials: oauth2/google: status code 403: {\n \"error\": {\n \"code\": 403,\n \"message\": \"The caller does not have permission\",\n \"status\": \"PERMISSION_DENIED\"\n }\n}\n"

이 문제를 해결하려면 다음 IAM 정책 바인딩을 만드세요.

gcloud iam service-accounts add-iam-policy-binding \
   --role roles/iam.workloadIdentityUser \
   --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

다음을 바꿉니다.

PROJECT_ID: GKE 워크로드 아이덴티티를 사용하는 경우 조직의 프로젝트 ID를 추가합니다. Fleet 워크로드 아이덴티티를 사용하는 경우 두 개의 서로 다른 프로젝트 ID를 사용할 수 있습니다. serviceAccount:PROJECT_ID에서 클러스터가 등록된 Fleet의 프로젝트 ID를 추가합니다. GSA_NAME@PROJECT_ID에서 Cloud Source Repositories의 저장소에 대한 읽기 액세스 권한이 있는 프로젝트의 프로젝트 ID를 추가합니다.
KSA_NAME: 조정자의 Kubernetes 서비스 계정입니다. 루트 저장소의 경우 RootSync 이름이 root-sync이면 KSA_NAME이 root-reconciler입니다. 그렇지 않은 경우 root-reconciler-ROOT_SYNC_NAME입니다.

네임스페이스 저장소의 경우 RepoSync 이름이 repo-sync이면 KSA_NAME이 ns-reconciler-NAMESPACE입니다. 그렇지 않은 경우 ns-reconciler-NAMESPACE-REPO_SYNC_NAME입니다.
GSA_NAME: Cloud Source Repositories에 연결하기 위해 사용하려는 커스텀 Google 서비스 계정입니다. 선택한 Google 서비스 계정에 source.reader 역할이 있는지 확인합니다.

Cloud Source Repositories에 액세스할 수 있는 `cloud-platform` 범위 누락

Google 서비스 계정에 Cloud Source Repositories의 Git 저장소에 대한 액세스 권한을 부여할 경우 해당 클러스터 노드의 액세스 범위에 읽기 전용 범위가 포함되어야 합니다.

클러스터를 만들 때 지정된 --scopes 목록에 cloud-source-repos-ro를 포함하거나 클러스터를 만들 때 cloud-platform 범위를 사용하여 읽기 전용 범위를 추가할 수 있습니다. 예를 들면 다음과 같습니다.

gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform

읽기 전용 범위가 누락된 경우 다음과 비슷한 오류가 표시됩니다.

Error in the git-sync container: {"Msg":"unexpected error syncing repo, will retry","Err":"Run(git clone -v --no-checkout -b main --depth 1 https://source.developers.google.com/p/PROJECT_ID/r/csr-auth-test /repo/source): exit status 128: { stdout: \"\", stderr: \"Cloning into '/repo/source'...\\nremote: INVALID_ARGUMENT: Request contains an invalid argument\\nremote: [type.googleapis.com/google.rpc.LocalizedMessage]\\nremote: locale: \\\"en-US\\\"\\nremote: message: \\\"Invalid authentication credentials. Please generate a new identifier: https://source.developers.google.com/new-password\\\"\\nremote: \\nremote: [type.googleapis.com/google.rpc.RequestInfo]\\nremote: request_id: \\\"fee01d10ba494552922d42a9b6c4ecf3\\\"\\nfatal: unable to access 'https://source.developers.google.com/p/PROJECT_ID/r/csr-auth-test/': The requested URL returned error: 400\\n\" }","Args":{}}

Artifact Registry에 액세스할 수 있는 `storage-ro` 범위 누락

이미지 레이어는 Cloud Storage 버킷에 보관됩니다. Artifact Registry에서 Google 서비스 계정에 OCI 이미지 또는 Helm 차트에 대한 액세스 권한을 부여할 때는 클러스터의 노드에 대해 읽기 전용 범위만 액세스 범위에 포함되어야 합니다.

클러스터를 만들 때 지정된 --scopes 목록에 storage-ro를 포함하거나 클러스터를 만들 때 cloud-platform 범위를 사용하여 읽기 전용 범위를 추가할 수 있습니다. 예를 들면 다음과 같습니다.

gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform

읽기 전용 범위가 누락된 경우 다음과 비슷한 오류가 표시됩니다.

Error in the oci-sync container: {"Msg":"unexpected error fetching package, will retry","Err":"failed to pull image us-docker.pkg.dev/...: GET https://us-docker.pkg.dev/v2/token?scope=repository%3A...%3Apull\u0026service=us-docker.pkg.dev: UNAUTHORIZED: failed authentication","Args":{}}

오류 메시지는 오류 원인에 대한 세부정보를 전부 포함하지 않을 수 있지만 자세한 정보가 포함된 git-sync 컨테이너의 로그를 출력하는 명령어를 제공합니다.

RootSync 또는 RepoSync API를 사용하는 경우:

kubectl logs -n config-management-system -l app=reconciler -c git-sync

RootSync 또는 RepoSync API를 사용 설정하지 않는 경우:

kubectl logs -n config-management-system -l app=git-importer -c git-sync

`remote did not send all necessary objects` 오류와 함께 `git fetch` 실패

구성 동기화는 Git 저장소의 부분 클론을 만듭니다. 일부 드문 경우에는 구성 동기화가 부분 클론에서 커밋을 찾지 못할 수 있습니다. 이 경우 구성 동기화는 인출할 Git 커밋 수를 늘립니다.

RootSync 또는 RepoSync 객체에서 spec.override.gitSyncDepth 필드를 설정하여 가져올 Git 커밋 수를 설정해 보세요.

이 필드를 제공하지 않으면 구성 동기화가 이를 자동으로 구성합니다.
이 필드가 0이면 구성 동기화는 전체 클론을 수행하고 이 필드가 0보다 크면 부분 클론을 수행합니다.
이 필드를 음수로 설정하는 것은 허용되지 않습니다.

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 구성 동기화를 설치한 경우 spec.override.gitSyncDepth를 설정할 수 있도록 수정 가능한 RootSync 객체를 만드세요. 자세한 내용은 kubectl 명령어로 구성 동기화 구성을 참조하세요.

다음은 가져올 Git 커밋 수를 88로 설정하는 예시입니다.

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: root-sync
  namespace: config-management-system
spec:
  override:
    gitSyncDepth: 88
  git:
    ...

다음 명령어를 실행하여 변경사항이 적용되는지 확인합니다(root-reconciler-git-sync ConfigMap의 data 필드에서 GIT_SYNC_DEPTH를 88로 설정해야 함).

kubectl get cm root-reconciler-git-sync -n config-management-system -o yaml

마찬가지로 네임스페이스 조정자에서 가져올 Git 커밋의 수를 재정의할 수 있습니다.

Git 보안 비밀을 마운트할 수 없음

git-sync가 보안 비밀을 사용해서 저장소를 동기화하려고 시도할 때 다음 오류가 수신되면 Git 보안 비밀이 git-sync 컨테이너에 성공적으로 마운트되지 않은 것입니다.

KNV2004: unable to sync repo Error in the git-sync container: ERROR: can't configure SSH: can't access SSH key: stat /etc/git-secret/ssh: no such file or directory: lstat /repo/root/rev: no such file or directory

이 오류는 Git 저장소 인증 유형을 none, gcenode, gcpserviceaccount에서 보안 비밀이 필요한 다른 유형으로 전환할 때 발생할 수 있습니다.

이 문제를 해결하려면 다음 명령어를 실행하여 조정자 관리자 및 조정자를 다시 시작합니다.

# Stop the reconciler-manager Pod. The reconciler-manager Deployment will spin
# up a new Pod which can pick up the latest `spec.git.auth`.
kubectl delete po -l app=reconciler-manager -n config-management-system

# Delete the reconciler Deployments. The reconciler-manager will recreate the
# reconciler Deployments with correct volume mount.
kubectl delete deployment -l app=reconciler -n config-management-system

KNV2005: ResourceFightError

이 오류는 구성 동기화가 리소스를 두고 다른 컨트롤러와 싸우고 있음을 나타냅니다. 이러한 싸움은 많은 양의 리소스를 소비하므로 성능이 저하될 수 있습니다. 싸움을 리소스 경합이라고도 합니다.

구성 동기화 버전 1.15.0 이상에서 RootSync 또는 RepoSync API를 사용하는 경우 nomos status 명령어를 사용하거나 RootSync 또는 RepoSync 객체의 상태 필드를 확인하여 Fight 오류를 검토할 수 있습니다.

구성 동기화 1.15.0 이전 버전에서 RootSync 또는 RepoSync API를 사용하는 경우 다음 명령어를 실행하여 구성 동기화 reconciler의 로그를 검토할 수 있습니다.

kubectl logs -n config-management-system -l app=reconciler -c reconciler

RootSync 또는 RepoSync API가 사용 설정되지 않은 경우 싸움을 감지하려면 다음 명령어를 실행하여 구성 동기화 git-importer 로그를 확인합니다.

kubectl logs --namespace config-management-system deployment/git-importer -c importer

결과에 KNV2005가 표시되면 리소스 싸움이 있는 것입니다.

리소스 충돌에 대한 자세한 내용을 보려면 다음 명령어를 실행하여 리소스의 YAML 파일 업데이트를 확인하세요.

 kubectl get resource --watch -o yaml

resource를 충돌하는 대상 리소스의 종류로 바꿉니다. 로그 결과에 따라 추가할 리소스를 확인할 수 있습니다.

이 명령어는 업데이트가 API 서버에 적용된 후 리소스의 상태 스트림을 반환합니다. 파일 비교 도구를 사용하여 출력을 비교할 수 있습니다.

일부 리소스는 다른 컨트롤러에 속해야 합니다(예: 일부 연산자는 CRD를 설치하거나 유지보수합니다). 이러한 다른 컨트롤러는 구성 동기화 관련 메타데이터를 자동으로 삭제합니다. Kubernetes 클러스터의 다른 구성요소가 구성 동기화 메타데이터를 삭제하는 경우 리소스 관리를 중지하세요. 이 작업을 수행하는 방법에 대한 자세한 내용은 관리형 객체 관리 중지를 참조하세요. 또는 구성 동기화가 존재한 이후 클러스터에서 객체 상태를 유지하길 원하지 않는 경우, 구성 동기화로 변형을 무시하려는 객체에 client.lifecycle.config.k8s.io/mutation: ignore 주석을 추가할 수 있습니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 객체 변형 무시를 참조하세요.

KNV2006: Config Management Errors

실수로 인한 삭제를 방지하기 위해 구성 동기화에서는 단일 커밋으로 모든 네임스페이스나 클러스터 범위 리소스를 삭제할 수 없습니다.

모든 리소스를 삭제하려는 시도에서 변경사항을 커밋한 경우 원래 상태로 수정한 후 두 단계로 삭제해야 합니다.

구성 동기화 허용 웹훅이 중지되면 모든 리소스를 삭제하는 커밋을 되돌릴 수 있습니다.

구성 동기화 허용 웹훅이 사용 설정되었으면 네임스페이스 종료가 중단될 수 있습니다. 이를 해결하려면 다음 단계를 실행합니다.

구성 동기화를 사용 중지하고 모든 리소스가 삭제되거나 안정 상태가 될 때까지 기다립니다. 예를 들어 kubectl get ns를 실행해서 네임스페이스가 삭제되었는지 확인할 수 있습니다.
구성 동기화를 다시 사용 설정합니다.
모든 리소스를 삭제하는 커밋을 되돌립니다.

삭제 방법

관리 중인 전체 리소스 집합을 삭제하려면 다음 2단계를 수행해야 합니다.

첫 번째 커밋에서 네임스페이스 또는 클러스터 범위 리소스를 하나만 제외한 채로 모두 삭제하고 구성 동기화가 변경사항을 동기화하도록 허용합니다.
두 번째 커밋에서 최종 리소스를 삭제합니다.

KNV2008: APIServerConflictError

이 유형의 오류는 API 서버의 리소스가 수정 또는 삭제되었을 때 구성 동기화에서도 API 서버의 리소스를 수정하려 하는 경우에 발생합니다. 이러한 유형의 오류가 시작 시에만 또는 드물게만 발생하는 경우 이러한 오류를 무시해도 됩니다.

이러한 오류가 일시적이 아닌 경우(몇 분에 걸쳐) 이는 중대한 문제를 나타내는 것일 수 있으며 nomos status는 리소스 충돌을 보고합니다.

오류 예시는 다음과 같습니다.

KNV2008: tried to create resource that already exists: already exists

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

For more information, see https://g.co/cloud/acm-errors#knv2008

KNV2008: tried to update resource which does not exist: does not exist

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

For more information, see https://g.co/cloud/acm-errors#knv2008

KNV2008: tried to update with stale version of resource: old version

metadata.name: default-name
group: rbac.authorization.k8s.io
version: v1
kind: Role

For more information, see https://g.co/cloud/acm-errors#knv2008

KNV2009: ApplyError

이 오류는 구성 동기화가 일부 구성을 클러스터에 동기화할 수 없음을 나타내는 일반적인 오류입니다. 오류 예시:

KNV2009: no matches for kind "Anvil" in group "acme.com".

특정 리소스에 대한 작업이 금지됨

다음과 유사한 오류가 표시되는 경우:

KNV2009: failed to list demo.foobar.com/v1, Kind=Cluster: clusters.demo.foobar.com is forbidden: User "system:serviceaccount:config-management-system:ns-reconciler-abc" cannot list resource "clusters" in API group "demo.foobar.com" in the namespace "abc"

이 오류는 네임스페이스 조정자에게 클러스터에 구성을 적용하는 데 필요한 액세스 권한이 없음을 의미합니다. 이 문제를 해결하려면 2개 이상의 정보 소스에서 동기화 구성의 단계를 따라 RoleBinding을 구성하여 오류 메시지에 누락이 표시된 항목을 기반으로 네임스페이스 조정자의 서비스 계정에 권한을 부여합니다.

허용 웹훅 요청 I/O 제한 시간

조정자가 클러스터에 구성 적용을 시도할 때 다음 오류가 수신되면 방화벽에 따라 제어 영역 네트워크에 대해 허용 웹훅 포트 8676이 차단되었기 때문일 수 있습니다.

KNV2009: Internal error occurred: failed calling webhook "v1.admission-webhook.configsync.gke.io": Post https://admission-webhook.config-management-system.svc:8676/admission-webhook?timeout=3s: dial tcp 10.1.1.186:8676: i/o timeout

이 문제를 해결하려면 방화벽 규칙을 추가하여 구성 동기화 허용 웹훅이 드리프트 방지에 사용하는 포트 8676를 허용합니다.

허용 웹훅 연결이 거부됨

조정자가 클러스터에 구성을 적용하려고 할 때 다음 오류가 표시될 수 있습니다.

KNV2009: Internal error occurred: failed calling webhook "v1.admission-webhook.configsync.gke.io": Post "https://admission-webhook.config-management-system.svc:8676/admission-webhook?timeout=3s": dial tcp 10.92.2.14:8676: connect: connection refused

이 오류는 허용 웹훅이 아직 준비되지 않았음을 의미합니다. 구성 동기화를 부트스트랩할 때 발생할 수 있는 일시적인 오류입니다.

문제가 지속되면 허용 웹훅 배포를 살펴보고 포드가 예약될 수 있고 정상 상태인지 확인합니다.

kubectl describe deploy admission-webhook -n config-management-system

kubectl get pods -n config-management-system -l app=admission-webhook

ResourceGroup 리소스가 `etcd` 객체 크기 한도를 초과함

조정자가 클러스터에 구성을 적용하려고 할 때 다음 오류가 발생하는 경우:

KNV2009: too many declared resources causing ResourceGroup.kpt.dev, config-management-system/root-sync failed to be applied: task failed (action: "Inventory", name: "inventory-add-0"): Request entity too large: limit is 3145728. To fix, split the resources into multiple repositories.

이 오류는 ResourceGroup 리소스가 etcd 객체 크기 한도를 초과했음을 의미합니다. Git 저장소를 여러 저장소로 분할하는 것이 좋습니다. Git 저장소를 분할할 수 없으면 구성 동기화 v1.11.0 이상에서 상태 데이터 표시를 사용 중지하여 문제를 해결할 수 있습니다. 이 작업은 RootSync 또는 RepoSync 객체 .spec.override.statusMode 필드를 disabled로 설정하여 수행됩니다. 이렇게 하면 구성 동기화가 ResourceGroup 객체에서 관리형 리소스 상태 업데이트를 중지합니다. ResourceGroup 객체 크기를 줄입니다. 하지만 nomos status 또는 gcloud alpha anthos config sync에서 관리형 리소스 상태를 볼 수 없습니다.

종속 항목 적용 조정 제한 시간

조정자가 config.kubernetes.io/depends-on 주석이 있는 객체를 클러스터에 적용하려고 하면 다음 예시와 비슷한 오류를 수신할 수 있습니다.

KNV2009: skipped apply of Pod, bookstore/pod4: dependency apply reconcile timeout: bookstore_pod3__Pod  For more information, see https://g.co/cloud/acm-errors#knv2009

이 오류는 종속 항목 객체가 기본 조정 제한 시간인 5분 이내에 조정되지 않았음을 의미합니다. config.kubernetes.io/depends-on 주석의 경우 구성 동기화가 원하는 순서로만 객체를 적용하기 때문에 구성 동기화가 종속 객체를 적용할 수 없습니다. spec.override.reconcileTimeout을 설정하여 기본 조정 제한 시간을 더 긴 시간으로 재정의할 수 있습니다.

nil인 인벤토리 정보

조정자가 클러스터에 구성을 적용하려고 할 때 다음 오류가 발생하면 인벤토리에 리소스가 없거나 매니페스트에 관리되지 않는 주석이 있을 수 있습니다.

KNV2009: inventory info is nil\n\nFor more information, see https://g.co/cloud/acm-errors#knv2009

이 문제를 해결하려면 다음을 시도해 보세요.

구성 동기화가 하나 이상의 리소스를 관리하도록 하여 모든 리소스에 configmanagement.gke.io/managed: disabled 주석이 있는 동기화를 설정하지 않도록 합니다.
이 주석 없이 리소스의 초기 동기화를 완료한 후에만 configmanagement.gke.io/managed: disabled 주석을 추가합니다.

여러 인벤토리 객체 템플릿

조정자가 클러스터에 구성을 적용하려고 할 때 다음 오류가 발생하면 Git 소스(예: Git 저장소)에 kpt의 인벤토리 구성이 있을 수 있습니다.

KNV2009: Package has multiple inventory object templates.  The package should have one and only one inventory object template.   For more information, see https://g.co/cloud/acm-errors#knv2009

이 문제는 구성 동기화가 자체 인벤토리 구성을 관리하기 때문에 발생합니다. 이 문제를 해결하려면 정보 소스에서 인벤토리 구성을 삭제합니다.

KNV2010: resourceError

이 오류는 리소스나 리소스 집합에 문제가 있음을 나타내는 일반 오류입니다. 오류를 발생시킨 특정 리소스가 오류 메시지에 포함됩니다.

KNV2010: Resources were improperly formatted.

Affected resources:
source: system/hc.yaml
group: configmanagement.gke.io
kind: Repo

KNV2011: MissingResourceError

이 오류는 계속하려면 특정 리소스가 필요하지만 리소스를 찾을 수 없음을 나타냅니다. 예를 들어 ConfigManagement Operator가 리소스를 업데이트하려 했지만 업데이트를 계산하는 동안 리소스가 삭제되었습니다.

KNV2012: MultipleSingletonsError

이 오류는 APIResource 인스턴스가 한 개만 허용되는 상황에서 APIResource 인스턴스가 두 개 이상 발견되었음을 나타냅니다. 예를 들어 저장소 리소스 한 개만 클러스터에 있을 수 있습니다.

KNV2013: InsufficientPermissionError

이 오류는 네임스페이스 조정 화면에 리소스를 관리할 수 있는 권한이 충분하지 않은 경우 발생합니다. 이 오류를 해결하려면 조정 화면에 충분한 권한이 있는지 확인합니다.

오류 예시는 다음과 같습니다.

KNV2013: could not create resources: Insufficient permission. To fix, make sure the reconciler has sufficient permissions.: deployments.apps is forbidden: User 'Bob' cannot create resources

For more information, see https://g.co/cloud/acm-errors#knv2013

KNV2014: InvalidWebhookWarning

이 경고는 구성 동기화 웹훅 구성이 잘못 수정되는 경우에 발생합니다. 잘못된 웹훅 구성은 무시됩니다.

경고 예시:

KNV2014: invalid webhook

KNV2015: InternalRenderingError

이 오류는 렌더링 프로세스에 내부 문제가 발생했음을 나타냅니다. 한 가지 예시는 파일 시스템에 액세스할 수 없는 경우입니다. 포드가 정상이 아님을 나타낼 수 있습니다. 다음 명령어를 실행하여 조정자 포드를 다시 시작할 수 있습니다.

# restart a root reconciler
kubectl delete pod -n config-management-system -l configsync.gke.io/reconciler=root-reconciler

# restart a namespace reconciler
kubectl delete pod -n config-management-system -l configsync.gke.io/reconciler=ns-reconciler-<NAMESPACE>

다시 시작 후에도 오류가 지속되면 버그 신고를 작성합니다.

KNV2016: TransientError

이 오류는 나중에 자동으로 해결되는 일시적인 문제를 나타냅니다.

예를 들어 파일을 나열하는 동안 소스 커밋이 변경되면 다음 오류가 발생할 수 있습니다.

KNV2016: source commit changed while listing files, was 90c1d9e9633a988ee3c3fc4dd145e62af30e9d1f, now 1d60597c56ebe07b269cc0d5ff126f638626c3b7. It will be retried in the next sync

For more information, see https://g.co/cloud/acm-errors#knv2016

또 다른 예시로는 렌더링 상태가 소스 구성과 일치하지 않는 경우가 있습니다.

sync source contains only wet configs and hydration-controller is running

For more information, see https://g.co/cloud/acm-errors#knv2016

KNV9998: InternalError

KNV9998은 nomos 명령어 자체에 문제가 있음을 나타냅니다. 실행한 명령어 및 표시된 메시지와 함께 버그를 신고하세요.

오류 예시는 다음과 같습니다.

KNV9998: we made a mistake: internal error

For more information, see https://g.co/cloud/acm-errors#knv9998

KNV9999: UndocumentedError

문서화된 오류 메시지가 없는 오류가 발생했습니다. 발생한 오류와 관련된 문서가 아직 작성되지 않았습니다.

기타 오류 메시지

KNV 프리픽스는 구성 동기화마다 고유하지만 KNV 프리픽스 없이 오류 메시지가 표시되는 경우도 있습니다.

내보내기 도구를 빌드할 수 없음

Open Telemetry Collector의 구성요소가 동일한 네임스페이스에서 기본 서비스 계정에 액세스할 수 없는 경우 config-management-monitoring 아래의 otel-collector 포드가 CrashLoopBackoff 상태임을 알 수 있거나 다음 메시지 중 하나와 유사한 오류 메시지가 표시될 수 있습니다.

Error: cannot build exporters: error creating stackdriver exporter: cannot configure Google Cloud metric exporter: stackdriver: google: could not find default credentials. See https://developers.google.com/accounts/docs/application-default-credentials for more information.

Error: Permission monitoring.timeSeries.create denied (or the resource may not exist).

이 문제는 일반적으로 클러스터에서 워크로드 아이덴티티가 사용 설정되면 발생합니다.

이 문제를 해결하려면 구성 동기화 모니터링의 안내에 따라 기본 서비스 계정에 측정항목 쓰기 권한을 부여합니다.

IAM 설정 후 오류가 계속되면 변경사항을 적용하기 위해 otel-collector 포드를 다시 시작합니다.

커스텀 모니터링 솔루션을 사용 중이지만 기본 otel-collector-googlecloud ConfigMap을 포크한 경우 모든 차이점을 확인하고 리베이스합니다.

서버 인증서 확인 실패

git-sync 컨테이너가 Git 저장소를 클론하지 못하면 다음 오류 메시지가 표시될 수 있습니다.

server certificate verification failed. CAfile:/etc/ca-cert/cert CRLfile: none

이 메시지는 Git 서버가 커스텀 인증 기관(CA)의 인증서로 구성되었음을 나타냅니다. 그러나 커스텀 CA가 올바르게 구성되지 않아 git-sync 컨테이너가 Git 저장소를 클론하지 못합니다.

먼저 RootSync 또는 RepoSync 객체에 spec.git.caCertSecretRef.name 필드가 지정되었는지 확인하고 보안 비밀 객체가 존재하는지도 확인할 수 있습니다.

필드가 구성되었고 보안 비밀 객체가 있는 경우 보안 비밀 객체에 전체 인증서가 포함되어 있는지 확인하세요.

커스텀 CA는 프로비저닝 방법에 따라 전체 인증서를 확인하는 방법이 달라질 수 있습니다.

다음은 서버 인증서를 나열하는 방법의 예시입니다.

echo -n | openssl s_client -showcerts -connect HOST:PORT -servername SERVER_NAME 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'

네트워크 관리팀에 CA 인증서를 가져오도록 요청할 수 있습니다.

pull 보안 비밀을 가져올 수 없음. 이미지 가져오기에 성공하지 못할 수 있음

VMware용 GKE에서 비공개 레지스트리를 사용하는 경우 구성 동기화 설치 또는 업그레이드가 중단될 수 있습니다. 다음과 비슷한 오류가 표시됩니다.

Error message: "MESSAGE": "Unable to retrieve pull secret, the image pull may not succeed." pod="config-management-system/config-management-operator-7d84fccc5c-khrx4" secret="" err="secret \"private-registry-creds\" not found"",

이 문제를 해결하려면 구성 동기화를 설치하거나 업그레이드하기 전에 비공개 레지스트리를 사용하여 정책 컨트롤러, 구성 동기화, 구성 컨트롤러 업데이트의 단계를 수행합니다.

웹훅 오류

다음 섹션에서는 구성 동기화 허용 웹훅을 사용할 때 발생할 수 있는 오류를 자세히 설명합니다. 웹훅에 대한 자세한 내용은 구성 드리프트 방지를 참조하세요.

모든 리소스 유형을 삭제할 수 없음

Terminating 단계에서 멈추는 네임스페이스는 다음 조건을 갖습니다.

    message: 'Failed to delete all resource types, 1 remaining: admission webhook
      "v1.admission-webhook.configsync.gke.io" denied the request: system:serviceaccount:kube-system:namespace-controller
      is not authorized to delete managed resource "_configmap_bookstore_cm1"'
    reason: ContentDeletionFailed
    status: "True"
    type: NamespaceDeletionContentFailure

이 오류는 루트 저장소에서 네임스페이스를 삭제하려고 시도하지만 네임스페이스 아래의 일부 객체가 네임스페이스 조정자에서 여전히 관리되고 있는 경우에 발생합니다. 네임스페이스가 삭제되면 해당 서비스 계정이 system:serviceaccount:kube-system:namespace-controller인 네임스페이스 컨트롤러가 해당 네임스페이스에서 모든 객체를 삭제하려고 시도합니다. 하지만 구성 동기화 허용 웹훅은 루트 또는 네임스페이스 조정자만 이러한 객체를 삭제하도록 허용하고, 네임스페이스 컨트롤러가 이러한 객체를 삭제하는 것은 거부합니다.

이 문제를 해결하려면 구성 동기화 허용 웹훅을 삭제합니다.

kubectl delete deployment.apps/admission-webhook -n config-management-system

ConfigManagement Operator는 구성 동기화 허용 웹훅을 다시 만듭니다.

이 방법이 작동하지 않으면 구성 동기화를 다시 설치해야 합니다.

오류가 다시 발생하지 않도록 하려면 네임스페이스를 삭제하기 전에 네임스페이스 저장소를 삭제합니다.

ValidatingWebhookConfiguration에서 웹훅 필드를 찾을 수 없음

root-reconciler가 클러스터에 리소스를 동기화하지 않은 경우 kubectl logs -n config-management-system -l app=admission-webhook을 실행할 때 구성 동기화 허용 웹훅 로그에 다음 오류가 표시됩니다.

cert-rotation "msg"="Unable to inject cert to webhook." "error"="`webhooks` field not found in ValidatingWebhookConfiguration" "gvk"={"Group":"admissionregistration.k8s.io","Version":"v1","Kind":"ValidatingWebhookConfiguration"} "name"="admission-webhook.configsync.gke.io"
controller-runtime/manager/controller/cert-rotator "msg"="Reconciler error" "error"="`webhooks` field not found in ValidatingWebhookConfiguration" "name"="admission-webhook-cert" "namespace"="config-management-system"

이 오류는 root-reconciler가 아직 준비되지 않았거나 Git 저장소에서 동기화할 항목이 없기 때문일 수 있습니다(예: 동기화 디렉터리가 비어 있음). 문제가 계속되면 root-reconciler의 상태를 점검하세요.

kubectl get pods -n config-management-system -l configsync.gke.io/reconciler=root-reconciler

root-reconciler가 비정상 종료되거나 OOMKilled 오류가 발생하면 리소스 한도를 늘립니다.

허용 웹훅이 요청을 거부함

구성 동기화에서 관리되는 필드에 변경사항을 적용하려고 시도할 때 다음 오류가 표시되면 변경사항 충돌이 발생했기 때문일 수 있습니다.

error: OBJECT could not be patched: admission webhook "v1.admission-webhook.configsync.gke.io"
denied the request: fields managed by Config Sync can not be modified

구성에서 필드를 선언하고 저장소가 클러스터에 동기화되면 구성 동기화가 해당 필드를 관리합니다. 이 필드에 시도하는 모든 변경사항이 충돌하는 변경사항입니다.

예를 들어 저장소에 environment:prod 라벨이 포함된 배포 구성이 있고 클러스터에서 라벨을 environment:dev로 변경하려고 시도하면 변경사항이 충돌하고 위의 오류 메시지가 표시됩니다. 하지만 배포에 tier:frontend와 같은 새 라벨을 추가하는 것은 충돌이 되지 않습니다.

구성 동기화가 객체에 대한 모든 변경사항을 무시하도록 하려면 객체 변형 무시에 설명된 주석을 추가할 수 있습니다.

권한이 거부됨

구성 동기화를 구성하려고 시도할 때 다음 예시와 비슷한 오류가 수신되면 GKE Hub 관리자 역할이 없기 때문일 수 있습니다.

Permission 'gkehub.features.create' denied on 'projects/PROJECT_ID/locations/global/features/configmanagement'

필요한 권한이 있는지 확인하려면 필요한 IAM 역할이 부여되었는지 확인합니다.

다음 단계

Config Sync 모니터링 알아보기
추가 지원이 필요하면 Cloud Customer Care에 문의하세요.

오류 참조

KNV1000: InternalError

KNV1001: ReservedDirectoryNameError

KNV1002: DuplicateDirectoryNameError

KNV1003: IllegalNamespaceSubdirectoryError

KNV1004: IllegalSelectorAnnotationError

KNV1005: IllegalManagementAnnotationError

KNV1006: ObjectParseError

KNV1007: IllegalAbstractNamespaceObjectKindError

KNV1009: IllegalMetadataNamespaceDeclarationError

KNV1010: IllegalAnnotationDefinitionError

KNV1011: IllegalLabelDefinition

KNV1012: NamespaceSelectorMayNotHaveAnnotation

KNV1013: ObjectHasUnknownSelector

KNV1014: InvalidSelectorError

KNV1016: PolicyManagementNotInstalledError

KNV1017: MissingRepoError

KNV1018: IllegalSubdirectoryError

KNV1019: IllegalTopLevelNamespaceError

KNV1020: InvalidNamespaceNameError

KNV1021: UnknownObjectError

KNV1024: IllegalKindInSystemError

KNV1027: UnsupportedRepoSpecVersion

KNV1028: InvalidDirectoryNameError

KNV1029: MetadataNameCollisionError

KNV1030: MultipleSingletonsError

KNV1031: MissingObjectNameError

KNV1032: IllegalHierarchicalKindErrorCode

KNV1033: IllegalSystemResourcePlacementError

KNV1034: IllegalNamespaceError

KNV1036: InvalidMetadataNameError

KNV1037: IllegalKindInClusterregistryError

KNV1038: IllegalKindInNamespacesError

KNV1039: IllegalKindInClusterError

KNV1040: UnknownResourceInHierarchyConfigError

KNV1041: UnsupportedResourceInHierarchyConfigError

KNV1042: IllegalHierarchyModeError

KNV1043: UnsupportedObjectError

KNV1044: UnsyncableResourcesErrorCode

KNV1045: IllegalFieldsInConfigError

KNV1046: ClusterScopedResourceInHierarchyConfigError

KNV1047: UnsupportedCRDRemovalError

KNV1048: InvalidCRDNameError

KNV1050: DeprecatedGroupKindError

KNV1052: IllegalNamespaceOnClusterScopedResourceError

KNV1053: MissingNamespaceOnNamespacedResourceError

KNV1054: InvalidAnnotationValueError

KNV1055: InvalidNamespaceError

KNV1056: ManagedResourceInUnmanagedNamespace

KNV1057: IllegalDepthLabel

KNV1058: BadScopeError

KNV 1059: MultipleKptfilesError

KNV 1060: ManagementConflictError

KNV 1061: InvalidRepoSyncError

KNV1062: InvalidKptfileError

KNV1063: KptfileExistError

KNV1064: InvalidAPIResourcesError

KNV1065: MalformedCRDError

KNV1066: ClusterSelectorAnnotationConflictError

KNV1067: EncodeDeclaredFieldError

KNV1068: ActionableRenderingError

KNV1069: SelfManageError

KNV2001: pathError

잘못된 YAML 구성

경로 이름의 특수문자

KNV2002: apiServerError

KNV2003: osError

KNV2004: SourceError

클러스터 내에서 Git 저장소에 연결할 수 없습니다.

잘못된 구성 디렉터리

잘못된 차트 이름

잘못된 Git 또는 Helm 사용자 인증 정보

잘못된 Git 저장소 URL

잘못된 Helm 저장소 URL

잘못된 Git 브랜치

서버 인증서 확인 실패

Google 서비스 계정 사용 시 권한 문제

리더 액세스 누락

워크로드 아이덴티티를 사용할 때 IAM 정책 바인딩 누락

Cloud Source Repositories에 액세스할 수 있는 cloud-platform 범위 누락

Cloud Source Repositories에 액세스할 수 있는 `cloud-platform` 범위 누락

Artifact Registry에 액세스할 수 있는 `storage-ro` 범위 누락

`remote did not send all necessary objects` 오류와 함께 `git fetch` 실패

ResourceGroup 리소스가 `etcd` 객체 크기 한도를 초과함