nomos 명령줄 도구 사용

nomos 명령줄 도구는 구성 동기화 상태와 정보 소스 동기화 상태를 가져오는 데 사용할 수 있는 구성 동기화의 선택적 도구입니다. nomos 도구는 다음 명령어를 제공합니다.

기본 요건

nomos 도구를 사용하여 클러스터와 상호작용하기 전에 구성 동기화가 이미 대상 클러스터에 설치되어 있어야 합니다. 또한 kubectl 명령줄 도구를 설치하고 구성해야 합니다. Google Kubernetes Engine 클러스터와 상호작용하는 경우 gke-gcloud-auth-plugin도 설치해야 합니다.

nomos 도구는 Kustomize 구성 및 Helm 차트 미리보기 및 검증을 지원합니다. 이 기능을 사용하려면 로컬 워크스테이션에 Kustomize 및 Helm을 설치합니다. 정보 소스에 완전히 렌더링된 구성만 포함된 경우 Kustomize 및 Helm은 선택사항입니다.

nomos 도구 설치

nomos 도구는 Go 코드에서 컴파일된 바이너리이며 워크스테이션 또는 노트북과 같이 로컬로 설치할 수 있습니다.

구성 동기화를 설치할 때 nomos 도구는 포함되지 않습니다. Google Cloud CLI를 설치하여 nomos 도구를 설치할 수 있습니다. Cloud Shell을 사용하는 경우 Google Cloud CLI가 사전 설치됩니다.

Google Cloud CLI가 없으면 gcloud components install nomos를 사용하여 nomos 도구를 설치하는 것이 좋습니다. Google Cloud CLI로 nomos 도구를 설치하면 gcloud components update를 사용하여 nomos 도구를 최신 버전으로 업데이트할 수 있습니다.

nomos 도구를 설치하는 다른 방법은 다운로드를 참조하세요.

기본 사용법

기본 명령어 문법을 보려면 --help 인수를 사용합니다.

nomos --help

nomos 도구는 정보 소스의 로컬 클론에서 읽습니다. --path 플래그를 사용하여 정보 소스의 최상위 수준 위치를 지정합니다. 기본적으로 --path는 . 또는 현재 디렉터리로 설정됩니다. 예를 들면 다음과 같습니다.

nomos --path=PATH_TO_SOURCE vet

구성 동기화 상태 확인

nomos status 명령어를 사용하여 등록된 모든 클러스터에서 구성 동기화 상태를 모니터링할 수 있습니다. 각 클러스터에 대해 nomos status는 클러스터에 마지막으로 적용된 커밋의 해시와 최근 변경사항을 적용하려고 시도하는 중에 발생한 모든 오류를 보고합니다.

또한 nomos status를 사용하여 구성 동기화에서 관리되는 리소스가 준비되었는지 확인할 수 있습니다. nomos status는 출력의 Managed resources 섹션에 있는 STATUS 열의 개별 리소스의 상태를 보고합니다.

다음 예시는 nomos status 명령어가 보고할 수 있는 일부 다른 조건을 보여줍니다.

nomos status

출력 예시:

MANAGED_CLUSTER_1
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4
  Managed resources:
   NAMESPACE   NAME                                                                   STATUS
               k8snoexternalservices.constraints.gatekeeper.sh/no-internet-services   Current
               namespace/hello                                                        Current

MANAGED_CLUSTER_2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  PENDING  9edf8444

MANAGED_CLUSTER_3
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR    f52a11e4
  Error:   KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.

MANGED_CLUSTER_4
  --------------------
  NOT INSTALLED

MANAGED_CLUSTER_5
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  Managed resources:
   NAMESPACE   NAME                                                                   STATUS
                namespace/gamestore                                                   Current
                namespace/monitoring                                                  Current
   gamestore    reposync.configsync.gke.io/repo-sync                                  Current
   gamestore    rolebinding.rbac.authorization.k8s.io/gamestore-admin                 Current
   gamestore    rolebinding.rbac.authorization.k8s.io/gamestore-webstore-admin        Current
   monitoring   deployment.apps/prometheus-operator                                   Current
   monitoring   prometheus.monitoring.coreos.com/acm                                  Current
   monitoring   service/prometheus-acm                                                Current
   monitoring   service/prometheus-operator                                           Current
   monitoring   serviceaccount/prometheus-acm                                         Current
   monitoring   serviceaccount/prometheus-operator                                    Current
   monitoring   servicemonitor.monitoring.coreos.com/acm-service                      Current
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8
  Managed resources:
   NAMESPACE   NAME                                 STATUS
   gamestore   configmap/store-inventory            Current
   gamestore   webstore.marketplace.com/gameplace   Current

이 출력에서 각 항목의 의미는 다음과 같습니다.

• MANAGED_CLUSTER_1에서 정보 소스의 최신 변경사항을 동기화했고 모든 관리형 리소스 상태는 Current입니다. Current 상태는 리소스 상태가 원하는 상태와 일치함을 나타냅니다.
• MANAGED_CLUSTER_2가 아직 동기화하는 중입니다.
• MANAGED_CLUSTER_3에 오류가 발생하여 변경사항이 적용되지 않았습니다. 이 예시에서 MANAGED_CLUSTER_3에는 다른 클러스터가 설치한 CRD가 누락되었기 때문에 KNV1021 오류가 포함됩니다.
• MANAGED_CLUSTER_4에 구성 동기화가 설치되지 않았습니다.
• MANAGED_CLUSTER_5는 2개의 Git 저장소에서 동기화됩니다. <root> 정보 소스는 클러스터 관리자에 속하며 bookstore 정보 소스는 애플리케이션 개발팀에 속할 수 있습니다.

관리형 리소스 상태

관리형 리소스 상태는 다음 값 중 하나일 수 있습니다.

• InProgress: 리소스의 실제 상태가 리소스 매니페스트에 지정된 상태에 아직 도달하지 않았습니다. 이 상태는 리소스 조정이 아직 완료되지 않았음을 의미합니다. ConfigMaps와 같은 일부 리소스는 즉시 Current 상태지만 새로 생성된 리소스는 일반적으로 이 상태로 시작합니다.

• Failed: 원하는 상태로 실제 상태를 조정하는 과정 중 오류가 발생했거나 충분히 진행되지 않았습니다.

• Current: 리소스의 실제 상태가 원하는 상태와 일치합니다. 조정 프로세스는 원하는 상태 또는 실제 상태가 변경될 때까지 완료된 것으로 고려됩니다.

• Terminating: 리소스를 삭제하는 중입니다.

• NotFound: 리소스가 클러스터에 리소스에 존재하지 않습니다.

• Unknown: 구성 동기화가 리소스 상태를 확인할 수 없습니다.

리소스 수준 상태를 표시하지 않으려면 nomos status 명령어에 --resources=false를 추가합니다.

마지막으로 동기화된 커밋 정보

nomos status 명령어는 출력에서 status.sync.commit 아래의 출력에 있는 클러스터에 적용된 최신 커밋 해시를 표시합니다. 이 값을 가져오려면 RootSync 또는 RepoSync 객체를 쿼리하고 status.sync 필드를 확인합니다.

예를 들어 RootSync 객체를 쿼리하려면 다음 명령어를 실행합니다.

kubectl get rootsyncs.configsync.gke.io -n config-management-system root-sync -o yaml

출력 예시:

apiVersion: configsync.gke.io/v1beta1
kind: RootSync
status:
  sync:
    commit: f1739af550912034139aca51e382dc50c4036ae0
    lastUpdate: "2021-04-20T00:25:01Z"

RepoSync 객체를 쿼리하려면 다음 명령어를 실행합니다.

kubectl get reposync.configsync.gke.io -n NAMESPACE repo-sync -o yaml

NAMESPACE를 네임스페이스 정보 소스를 만든 네임스페이스로 바꿉니다.

출력 예시:

apiVersion: configsync.gke.io/v1beta1
kind: RepoSync
status:
  sync:
    commit: ed95b50dd918cf65d8908f7561cb8d8d1f179c2f
    lastUpdate: "2021-04-20T00:25:20Z"

이 커밋은 클러스터에 대한 최근 커밋입니다. 하지만 각 커밋에 의해 클러스터의 모든 리소스가 영향을 받는 것은 아닙니다. 특정 리소스의 최신 커밋을 보려면 특정 리소스를 쿼리하고 metadata.annotations.configmanagement.gke.io/token을 확인합니다. 예를 들면 다음과 같습니다.

kubectl get clusterroles CLUSTER_ROLE_NAME -o yaml

CLUSTER_ROLE_NAME을 쿼리하려는 클러스터 역할의 이름으로 바꿉니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
    configmanagement.gke.io/token: ed95b50dd918cf65d8908f7561cb8d8d1f179c2f

nomos 상태 플래그

nomos status 명령어를 맞춤설정하려면 다음 플래그를 추가합니다.

필수 권한

프로젝트 소유자는 cluster-admin RBAC 역할이 있으며, 추가 권한을 추가하지 않고도 프로젝트의 모든 클러스터에 nomos status 명령어를 사용할 수 있습니다. cluster-admin 역할이 없으면 다음 ClusterRole을 만들어 nomos status를 사용할 수 있습니다.

1. nomos-status-reader.yaml이라는 파일을 만들고 이 파일에 다음 ClusterRole을 복사하여 붙여넣습니다. 필요한 규칙은 RootSync 및 RepoSync 객체 사용 여부에 따라 다릅니다.

   RootSync 및 RepoSync 객체 사용

   # nomos-status-reader.yaml
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: nomos-status-reader
   rules:
   - apiGroups: ["configsync.gke.io"]
     resources: ["reposyncs", "rootsyncs"]
     verbs: ["get"]
   - nonResourceURLs: ["/"]
     verbs: ["get"]
   

   RootSync 및 RepoSync 객체를 사용하지 않음

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: nomos-status-reader
   rules:
   - apiGroups: ["configmanagement.gke.io"]
     resources: ["configmanagements", "repos"]
     verbs: ["get", "list"]
   - nonResourceURLs: ["/"]
     verbs: ["get"]
   

2. nomos-status-reader.yaml 파일을 적용합니다.

   kubectl apply -f nomos-status-reader.yaml
   

정보 소스에서 오류 확인

구성을 정보 소스로 커밋하기 전에 nomos vet 명령어를 사용하여 정보 소스에 있는 구성의 문법과 유효성을 검사합니다.

nomos vet

문법 오류가 발견되면 nomos vet 명령어가 0이 아닌 상태로 종료되고 오류 메시지를 STDERR에 로깅합니다.

nomos vet 플래그

nomos vet 명령어를 맞춤설정하려면 다음 플래그를 추가합니다.

서버 측 유효성 검사

nomos vet 명령어로 유형이 네임스페이스인지 여부를 판별할 수 없는 경우 nomos 도구는 API 서버에 연결됩니다. nomos는 기본적으로 핵심 Kubernetes 유형 및 구성 동기화 CRD를 이해하므로 해당하는 선언된 CRD가 없는 CR이 있는 경우에만 API 서버에 연결을 시도합니다. 이 경우 API 서버에 CRD가 적용되지 않으면 nomos vet 명령어는 error KNV1021을 반환합니다. 이 점검을 사용 불가능하게 하고 누락된 CRD로 인한 오류를 억제하려면 --no-api-server-check 플래그를 전달하세요.

API 서버 메타데이터 캐싱

API 서버 확인을 표시하지 않고 nomos vet 명령어에 대해 API 서버의 데이터를 캐시할 수 있습니다. api-resources를 캐시하려면 다음 단계를 완료하세요.

1. 정보 소스에 필요한 모든 CRD가 있는 클러스터에 연결합니다. 클러스터에서 구성 동기화를 사용 설정하지 않아도 됩니다.
2. 정보 소스의 policyDir로 이동합니다. 이는 ConfigManagement 또는 RootSync 리소스에 지정된 디렉터리와 동일합니다.
3. 다음 명령어를 실행합니다. kubectl api-resources > api-resources.txt 이 명령어는 kubectl api-resources의 정확한 출력을 포함하는 api-resources.txt라는 파일을 만듭니다.

이제부터 정보 소스 내에서 nomos vet를 실행하면 해당 유형 정의가 인식됩니다. api-resources.txt 파일이 삭제되거나 이름이 변경된 경우 nomos vet는 파일을 찾을 수 없습니다. nomos vet는 --no-api-server-check가 전달되지 않는 한 api-resources.txt에 선언되지 않은 유형의 매니페스트를 찾을 경우 클러스터에 연결을 시도합니다.

api-resources.txt 파일은 nomos 도구 작동 방식에만 영향을 미칩니다. 구성 동기화의 동작은 어떤 방식으로도 수정되지 않습니다.

검증 중인 정보 소스에 없는 유형의 경우 api-resources.txt 파일에 추가 항목이 있어도 괜찮습니다. nomos vet는 정의를 가져오지만 결합은 수행하지 않습니다.

api-resources.txt 업데이트

원하는 모든 CRD가 클러스터에 있는지 확인한 후 다음 명령어를 실행합니다.

kubectl api-resources > api-resources.txt

커밋할 때 문법 오류 자동 검사

JSON 또는 YAML 오류로 파일을 커밋하면 구성 동기화가 변경사항을 적용하지 않습니다. 그러나 클라이언트 측 또는 서버 측 후크를 사용하면 이러한 유형의 오류가 정보 소스로 전환되지 않도록 방지할 수 있습니다.

커밋 전 후크에서 nomos vet 사용

저장소의 로컬 Git 클론에 변경사항을 커밋할 때 문법 오류를 검사하도록 nomos vet를 실행하는 커밋 전 후크를 구성할 수 있습니다. 커밋 전 후크가 0이 아닌 상태로 종료되면 git commit 작업이 실패합니다.

nomos vet 명령어를 커밋 전 후크로 실행하려면 정보 소스에서 .git/hooks/pre-commit 파일을 수정합니다(.git는 . 문자로 시작됨). 이 파일을 수동으로 만들어야 할 수도 있습니다. 스크립트에서 새 줄에 nomos vet 명령어를 추가합니다. --path 인수는 선택사항입니다.

nomos vet --path=/path/to/repo

pre-commit 파일이 실행 가능한지 확인합니다.

chmod +x .git/hooks/pre-commit

이제 정보 소스 클론에서 git commit 명령어를 실행하면 nomos vet가 자동으로 실행됩니다.

.git/ 디렉터리의 콘텐츠는 정보 소스 자체에서 추적되지 않으며 같은 위치에 있는 정보 소스에 커밋될 수 없습니다. Git 후크의 정보 소스에 디렉터리를 만들 수 있습니다. 그러면 정보 소스를 사용하는 사용자는 후크를 자신의 로컬 클론에 있는 적절한 위치에 복사할 수 있습니다.

서버 측 후크에서 nomos vet 사용

Git은 git push 작업 중에 클라이언트가 아닌 서버에서 검사를 실행하는 메커니즘을 제공합니다. 검사가 실패하면 git push도 실패합니다. 이러한 서버 측 후크는 클라이언트에서 우회될 수 없습니다. 서버 측 후크를 구성하는 방법은 Git 서버가 호스팅된 방식에 따라 다릅니다. 자세한 내용은 다음 링크 중 하나를 참조하거나 Git 호스팅 서비스 관련 문서를 확인하세요.

• GitHub
• Cloud Source Repositories
• Bitbucket
• GitLab
• 자체 호스팅 Git 서버

정보 소스의 모든 구성 보기

nomos hydrate 명령어를 사용하여 등록된 각 클러스터에 있는 정보 소스의 조합된 콘텐츠를 볼 수 있습니다.

옵션 없이 nomos hydrate를 실행하면 현재 작업 디렉터리에 compiled/ 디렉터리가 생성됩니다. 이 디렉터리 내에 등록된 각 클러스터에 대한 하위 디렉터리가 Operator에서 클러스터에 적용할 완전히 확인된 구성과 함께 생성됩니다.

이 명령어는 compiled/ 디렉터리의 콘텐츠를 사용하여 계층적 정보 소스를 비정형 정보 소스 하나 이상으로 변환할 수도 있습니다.

nomos hydrate 플래그

nomos hydrate 명령어를 맞춤설정하려면 다음 플래그를 추가합니다.

버그 신고 작성

Google Cloud 지원의 도움이 필요한 구성 동기화 문제가 있는 경우 nomos bugreport 명령어를 사용하여 유용한 디버깅 정보를 제공할 수 있습니다. 단일 정보 소스와 여러 저장소에 이 명령어를 사용할 수 있습니다.

nomos bugreport

이 명령어는 kubectl 컨텍스트에서 설정된 Kubernetes 클러스터에 대한 정보가 있는 타임스탬프 zip 파일을 생성합니다. 이 파일에는 또한 구성 동기화 포드의 로그가 포함됩니다. 구성 동기화로 동기화된 리소스의 정보는 포함되지 않습니다. zip 파일 콘텐츠에 대한 자세한 내용은 nomos 버그 신고 참조를 확인하세요.

제한사항

개별 파일이 1GiB를 초과하면 nomos bugreport 명령어가 실패하고 불완전한 ZIP 파일이 생성됩니다. 이는 로그 파일이 클 때 발생하는 경우가 많습니다.

다음 표에는 대용량 로그 파일의 가장 일반적인 원인과 해결 방법이 나와 있습니다.

ConfigManagement 객체에서 RootSync 객체로 마이그레이션

nomos migrate 명령어를 실행하여 ConfigManagement 객체에서 RootSync 객체로 마이그레이션하여 RootSync 및 RepoSync API를 사용 설정할 수 있습니다.

spec.enableLegacyFields를 사용하여 RootSync를 부트스트랩한 경우 nomos migrate를 사용하는 대신 가이드를 따라 기존 필드를 사용 중지하세요. 버전 1.19.0부터 기존 필드는 지원되지 않습니다.

nomos migrate는 마이그레이션 프로세스 미리보기를 위한 테스트 실행을 지원합니다.

nomos migrate는 클러스터에서 직접 ConfigManagement 객체를 수정합니다. nomos migrate를 통해 수행된 변경사항을 되돌리지 않으려면 정보 소스로 ConfigManagement 객체를 선택하지 않아야 합니다.

nomos migrate --contexts=KUBECONFIG_CONTEXTS --dry-run

테스트 실행 결과가 적합하면 nomos migrate를 사용하여 ConfigManagement 객체를 마이그레이션할 수 있습니다.

nomos migrate --contexts=KUBECONFIG_CONTEXTS

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

--------------------
Enabling the multi-repo mode on cluster "my_managed_cluster-1" ...
- A RootSync object is generated and saved in "/tmp/nomos-migrate/my_managed_cluster-1/root-sync.yaml".
- The original ConfigManagement object is saved in "/tmp/nomos-migrate/my_managed_cluster-1/cm-original.yaml".
- The ConfigManagement object is updated and saved in "/tmp/nomos-migrate/my_managed_cluster-1/cm-multi.yaml".
- Resources for the multi-repo mode have been saved in a temp folder. If the migration process is terminated, it can be recovered manually by running the following commands:
  kubectl apply -f /tmp/nomos-migrate/my_managed_cluster-1/cm-multi.yaml && \
  kubectl wait --for condition=established crd rootsyncs.configsync.gke.io && \
  kubectl apply -f /tmp/nomos-migrate/my_managed_cluster-1/root-sync.yaml.
- Updating the ConfigManagement object ....
- Waiting for the RootSync CRD to be established ....
- The RootSync CRD has been established.
- Creating the RootSync object ....
- Waiting for the reconciler-manager Pod to be ready ....
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
-   Haven't detected running Pods with the label selector "app=reconciler-manager".
- The reconciler-manager Pod is running.
- Waiting for the root-reconciler Pod to be ready ....
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
-   Haven't detected running Pods with the label selector "configsync.gke.io/reconciler=root-reconciler".
- The root-reconciler Pod is running.
- The migration process is done. Please check the sync status with `nomos status`.

Finished migration on all the contexts. Please check the sync status with `nomos status`.

이전 구성으로 롤백

nomos migrate로 마이그레이션을 수행한 후 롤백이 필요하면 원래 ConfigManagement 객체를 적용합니다. nomos migrate는 원래 ConfigManagement 객체를 파일에 저장하고 이름을 터미널에 출력합니다. 파일 이름은 /tmp/nomos-migrate/CURRENT_CONTEXT/cm-original.yaml 형식입니다.

이전 구성으로 롤백하려면 cm-original.yaml의 파일 경로를 복사하고 파일을 클러스터에 적용합니다.

kubectl apply -f CM_ORIGINAL_PATH

nomos migrate 플래그

nomos migrate 명령어를 맞춤설정하려면 다음 플래그를 추가합니다.

계층적 정보 소스 초기화

비정형 정보 소스를 사용하는 경우 정보 소스를 임의로 구성할 수 있습니다. 계층적 정보 소스를 사용하는 경우에는 nomos init 명령어를 실행하여 계층적 디렉터리를 초기화해야 합니다.

nomos init

그러면 system/, cluster/, namespaces/ 디렉터리를 포함하여 계층적 정보 소스의 기본 디렉터리 구조가 생성됩니다.

nomos init 플래그

nomos init를 맞춤설정하려면 다음 플래그를 추가합니다.

문제 해결

Linux에서는 nomos 명령어를 실행할 때 다음 오류가 표시될 수 있습니다.

failed to create client configs: while getting config path: failed to get current user: user: Current not implemented on linux/amd64

이 문제를 해결하려면 USER 환경 변수를 만듭니다.

export USER=$(whoami)

다음 단계

• 구성 동기화 시작하기