コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

nomos コマンドライン ツールを使用する

nomos コマンドライン ツールは、Config Sync のオプション ツールです。nomos ツールでは、次のコマンドを使用できます。

コマンド 用途
nomos status Config Sync のステータスを確認する
nomos vet リポジトリ内のエラーを確認する
nomos hydrate リポジトリ内のすべての構成ファイルを表示する
nomos bugreport バグレポートを作成する
nomos migrate ConfigManagement から RootSync に移行する
nomos init 階層型リポジトリを初期化する

前提条件

nomos ツールを使用してクラスタを操作する前に、ターゲット クラスタに Config Sync がインストールされている必要があります。また、kubeconfig エントリを生成することで、ターゲット クラスタの認証を行うように kubectl コマンドライン ツールを構成する必要があります。

nomos ツールは、Kustomize 構成と Helm チャートのプレビューと検証をサポートしています。この機能を使用するには、ローカル ワークステーションに Kustomize と Helm をインストールします。リポジトリに完全にレンダリングされた構成のみが含まれている場合、Kustomize と Helm はオプションです。

nomos ツールをインストールする

nomos ツールは、Go コードからコンパイルされたバイナリです。ワークステーションやノートパソコンなどのローカルにインストールできます。

Config Sync のインストール時に 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 ツールをインストールする別の方法については、Anthos Config Management のダウンロードをご覧ください。

基本的な使い方

基本的なコマンド構文を確認する場合は、--help 引数を使用します。

nomos --help

nomos ツールは、リポジトリのローカル クローンから読み取ります。リポジトリの最上位の場所を指定する場合は、--path フラグを使用します。デフォルトでは、--path は . または現在のディレクトリに設定されています。例:

nomos --path=PATH_TO_REPOSITORY vet

Config Sync のステータスを確認する

登録済みすべてのクラスタの Config Sync のステータスをモニタリングするには、nomos status コマンドを使用します。nomos status は、クラスタごとに、クラスタに最後に適用された Git commit のハッシュと、最近の変更の適用中に発生したエラーを報告します。

nomos status を使用して、Config Sync で管理されているリソースの準備が完了しているかどうかを確認することもできます。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 によりエラーが発生したため、変更が適用されませんでした。この例では、他のクラスタがインストールした CustomResourceDefinition（CRD）が存在しないため、MANAGED_CLUSTER_3 にエラー KNV1021 が表示されます。
  • MANAGED_CLUSTER_4 には Config Sync がインストールされていません。
  • MANAGED_CLUSTER_5 は 2 つの Git リポジトリから同期しています。<root> リポジトリはクラスタ管理者に属し、bookstore リポジトリはアプリケーション開発チームに属している可能性があります。

マネージド リソースのステータス

マネージド リソースのステータスは、次のいずれかの値になります。

  • InProgress: リソースの実際の状態が、リソース マニフェストで指定した状態になっていません。このステータスは、リソースの調整がまだ完了していないことを意味します。通常、新しく作成されたリソースはこのステータスから始まりますが、ConfigMap などの一部のリソースは、すぐに Current になります。

  • Failed: 実際の状態を目的の状態と調整するプロセスでエラーが発生したか、進行が不十分です。

  • Current: リソースの実際の状態が、必要な状態と一致しています。調整プロセスは、必要な状態または実際の状態に対する変更があるまで完了とみなされます。

  • Terminating: リソースは削除中です。

  • NotFound: リソースがクラスタに存在しません。

  • Unknown: Config Sync でリソースのステータスを判別できません。

リソースレベルのステータス表示をオフにするには、nomos status コマンドに --resources=false を追加します。

最新の同期 commit について

nomos status コマンドは、クラスタに適用された最新の Git commit ハッシュを 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 は、Namespace リポジトリを作成した Namespace に置き換えます。

出力例:

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

この commit は、クラスタに対する最新の commit を表しています。ただし、クラスタ内のすべてのリソースが各 commit の影響を受けるわけではありません。特定のリソースに対する最新の commit を確認するには、特定のリソースのクエリを実行して、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 status のフラグ

nomos status コマンドをカスタマイズするには、次のフラグを追加します。

フラグ 説明
--contexts マルチクラスタ コマンドで使用するコンテキストのカンマ区切りのリストを指定できます。デフォルトはすべてのコンテキストです。コンテキストがない場合は「""」を使用します。
-h または --help nomos status コマンドのヘルプ。
--namespace 文字列で記述します。コマンドを特定の名前空間リポジトリに制限するには、namespace フラグを使用します。すべてのリポジトリを取得するには、未設定のままにします。このフラグは、複数のリポジトリからの同期を有効にしている場合にのみ使用できます。
--poll nomos status を継続的に実行し、ステータス テーブルを定期的に出力するには、poll フラグを使用します。例: 3snomos status を 1 回だけ実行するには、このフラグを未設定のままにします。
--resources true または false を指定します。true の場合、nomos status は複数のリポジトリから同期するときに、ルート リポジトリまたは Namespace リポジトリのリソースレベルのステータスを表示します。デフォルト値は true です。
--timeout 各クラスタへの接続のタイムアウト。デフォルト値は 3s です。

必要な権限

プロジェクト オーナーの場合、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

リポジトリ内のエラーを確認する

リポジトリに構成ファイルを commit する前に、nomos vet コマンドを使用して、リポジトリ内の構成ファイルの構文と有効性を確認します。

nomos vet

構文エラーが見つかると、nomos vet コマンドはゼロ以外のステータスで終了し、エラー メッセージを STDERR に記録します。

nomos Vet フラグ

nomos vet コマンドをカスタマイズするには、次のフラグを追加します。

フラグ 説明
--clusters マルチクラスタ コマンドで使用するクラスタ名のカンマ区切りのリストを指定できます。デフォルトはすべてのクラスタです。クラスタがない場合は、"" を使用します。
-h または --help nomos vet コマンドのヘルプ。
--namespace 文字列で記述します。設定すると、リポジトリが指定した名前の Namespace リポジトリとして検証されます。--source-format=unstructured が自動で設定されます。
--no-api-server-check ブール値を指定します。true の場合、検出のため API サーバーとの通信を無効にします。このフラグの詳細については、サーバー側の検証をご覧ください。
--path 文字列で記述します。Config Sync リポジトリのルート ディレクトリへのパスです。デフォルトは . です。
--source-format hierarchy または unstructured を指定します。hierarchy に設定するか未設定のままにした場合は、リポジトリが階層型リポジトリとして検証されます。unstructured の場合は、リポジトリが非構造化リポジトリとして検証されます。非構造化リポジトリを使用している場合、このフラグは必要です。
--keep-output ブール値を指定します。true の場合、レンダリングされた出力は、--output フラグで指定できる場所に保存されます。
--output 文字列で記述します。レンダリングされた出力へのパス。デフォルトは compiled ディレクトリです。--keep-output が false に設定されている場合、このフラグは無視されます。
--format yaml または json を指定します。出力の形式。デフォルト値は yaml です。

サーバー側の検証

タイプが名前空間であるかどうかを nomos vet コマンドが判別できない場合、nomos ツールは API サーバーに接続します。nomos ツールはデフォルトで Kubernetes のコアタイプと Config Sync CRD を認識できるため、CR に対応する CRD が宣言されていない場合にのみ、API サーバーへの接続を試みます。この場合、API サーバーに CRD が適用されていないと、nomos vet コマンドはエラー KNV1021 を返します。このチェックを無効にして、CRD の欠落によるエラーを抑制するには、--no-api- server-check フラグを渡します。

API サーバー メタデータのキャッシュ保存

API サーバー チェックを抑制するのではなく、nomos vet コマンド用のデータを API サーバーのキャッシュに保存できます。api-resources をキャッシュに保存するには、次の手順を行います。

  1. リポジトリに必要なすべての CRD が含まれるクラスタに接続します。クラスタで Config Sync を有効にする必要はありません。
  2. リポジトリの policyDir に移動します。これは、ConfigManagement または RootSync リソースで指定されたディレクトリと同じです。
  3. コマンド kubectl api-resources > api-resources.txt を実行します。このコマンドは kubectl api-resources の正確な出力を含む api-resources.txt というファイルを作成します。

これ以降、リポジトリ内で nomos vet を実行すると、これらの型定義が認識されるようになります。api-resources.txt ファイルを削除するか、名前を変更すると、nomos vet はそのファイルを検出できなくなります。api-resources.txt で宣言されていないタイプのマニフェストが見つかった場合、--no-api-server-check が渡されない限り、nomos vet は引き続きクラスタへの接続を試みます。

api-resources.txt ファイルは、nomos ツールの動作にのみ影響します。Config Sync の動作が変更されることはありません。

検証対象のリポジトリにないタイプのエントリが api-resources.txt ファイルにある場合でも問題ありません。nomos vet は定義をインポートしますが、それに対して何も行いません。

api-resources.txt を更新する

目的の CRD がすべてクラスタに存在することを確認したら、次のコマンドを実行します。

kubectl api-resources > api-resources.txt

commit 時に構文エラーを自動的にチェックする

JSON または YAML エラーのあるファイルを commit すると、Config Sync は変更を適用しません。ただし、クライアント側またはサーバー側のフックを使用することで、この種のエラーがリポジトリに入り込まないようにすることができます。

Git pre-commit フックで nomos vet を使用する

リポのローカル Git クローンに変更を commit するときに nomos vet コマンドを実行して構文エラーをチェックする pre-commit フックを構成できます。pre-commit フックがゼロ以外のステータスで終了した場合、git commit オペレーションは失敗します。

nomos vet コマンドを pre-commit フックとして実行するには、リポジトリ内の .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/ ディレクトリの内容はリポジトリ自体によって追跡されず、同じ場所のリポジトリに commit することはできません。Git フック用のディレクトリをリポジトリに作成し、リポジトリを使用するユーザーにそれらのフックを各自のローカル クローンの適切な場所にコピーさせることができます。

サーバー側フックで nomos vet を使用する

Git には、git push オペレーション中にクライアントではなくサーバーでチェックを実行するメカニズムが用意されています。チェックが失敗すると、git push も失敗します。これらのサーバー側フックをクライアントがバイパスすることはできません。サーバー側フックを構成する方法は、Git サーバーがどのようにホストされているかによって異なります。詳細については、次のリンクのいずれかを参照するか、ご利用の Git ホスティング サービスのドキュメントを確認してください。

リポジトリ内のすべての構成ファイルを表示する

nomos hydrate コマンドを使用して、登録されたクラスタごとにリポジトリのコンテンツを組み合わせて表示できます。

オプションを指定せずに nomos hydrate を実行すると、現在の作業ディレクトリに compiled/ ディレクトリが作成されます。このディレクトリで、登録済みのクラスタごとにサブディレクトリが作成され、完全に解決された構成ファイルが保存されます。Operator によりこの構成がクラスタに適用されます。

このコマンドにより、compiled/ ディレクトリのコンテンツを使用して、階層リポジトリを 1 つ以上の構造化されていないリポジトリに変換することもできます。

nomos hydrate フラグ

nomos hydrate コマンドをカスタマイズするには、次のフラグを追加します。

フラグ 説明
--clusters クラスタ名のカンマ区切りのリストを指定します。このフラグを使用して、出力を単一クラスタまたはクラスタのリストに限定します。デフォルトはすべてのクラスタです。クラスタがない場合は、"" を使用します。
--flat 有効にすると、すべての出力が 1 つのファイルに出力されます。nomos view の動作をエミュレートする場合は、このフラグを使用します。
-h または --help nomos hydrate コマンドのヘルプ。
--format yaml または json を指定します。出力の形式。デフォルト値は yaml です。
--no-api-server-check ブール値を指定します。true の場合、検出のため API サーバーとの通信を無効にします。このフラグの詳細については、サーバー側の検証をご覧ください。
--output 文字列で記述します。ハイドレート構成を書き込む場所。デフォルトは compiled ディレクトリです。--flat が有効になっていない場合は、各リソース マニフェストが個別のファイルとして書き込まれます。--flat が有効になっている場合、単一のファイルにすべてのリソース マニフェストが書き込まれます。
--path 文字列で記述します。Config Sync リポジトリのルート ディレクトリへのパスです。デフォルトは . です。
--source-format hierarchy または unstructured を指定します。hierarchy に設定するか未設定のままにした場合は、リポジトリが階層型リポジトリとして検証されます。unstructured の場合は、リポジトリが非構造化リポジトリとして検証されます。非構造化リポジトリを使用している場合、このフラグは必要です。

nomos view

Config Sync は、リポジトリから構成ファイルをインポートし、タイプが ClusterConfig または NamespaceConfig の CRD に変換します。nomos view コマンドを使用すると、リポジトリの現在の状態から生成された CRD を JSON 形式で表示できます。これは、変更を commit する前や、nomos vet コマンドではわからない構成ファイルの問題をデバッグする際に役立ちます。

nomos view --path=PATH_TO_REPOSITORY

バグレポートを作成する

Config Sync で問題が発生し、Google Cloud サポートのサポートが必要な場合は、nomos bugreport コマンドを使用して有益なデバッグ情報をサポートチームに提供できます。このコマンドは、単独のリポジトリに対しても、複数のリポジトリに対しても使用できます。

nomos bugreport

このコマンドを使用すると、kubectl コンテキストで設定された Kubernetes クラスタに関する情報を含むタイムスタンプ付きの zip ファイルが生成されます。このファイルには、Config Sync Pod のログも含まれています。Config Sync と同期されているリソースの情報は含まれません。

ConfigManagement オブジェクトから RootSync オブジェクトに移行する

nomos migrate コマンドを実行して、ConfigManagement オブジェクトから RootSync オブジェクトに移行し、RootSync と RepoSync API を有効にできます。このコマンドは、nomos バージョン 1.10.0 以降で使用できます。

nomos migrate では、移行プロセスのプレビューをドライランでサポートしています。

nomos migrate --dry-run

ドライランの結果に問題がなければ、nomos migrate を使用して ConfigManagement オブジェクトを移行できます。

nomos migrate

出力は次のようになります。

--------------------
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 コマンドをカスタマイズするには、次のフラグを追加します。

フラグ 説明
--connect-timeout 期間を指定します。各クラスタへの接続のタイムアウト時間。デフォルトは 3s です。
--contexts マルチクラスタ環境で使用するコンテキストのカンマ区切りのリストを指定します。デフォルトは現在のコンテキストです。すべてのコンテキストの場合は "all" を使用します。
--dry-run ブール値を指定します。true の場合、移行出力のみを出力します。
-h または --help nomos migrate コマンドのヘルプ。
--wait-timeout 期間を指定します。Kubernetes リソースの条件が true になるのを待機するタイムアウト時間。デフォルトは 10m です。

階層型リポジトリを初期化する

非構造化リポジトリを使用している場合は、リポジトリを自由に編成できます。階層型リポジトリを使用している場合は、nomos init コマンドを実行して階層的なディレクトリを初期化する必要があります。

nomos init

これにより、system/、cluster/、namespaces/ ディレクトリなど、階層型リポジトリの基本的なディレクトリ構造が作成されます。

nomos init フラグ

nomos init をカスタマイズするには、次のフラグを追加します。

フラグ 説明
--force 空でない場合もディレクトリへの書き込みを行い、競合するファイルを上書きします。
-h または --help nomos init コマンドのヘルプ。
--path 文字列で記述します。Anthos Config Management リポジトリで使用するルート ディレクトリ。デフォルト値は "." です。

トラブルシューティング

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)

次のステップ