nomos コマンドの使用

nomos コマンド(Windows の場合は nomos.exe)は、ワークステーションやノートパソコンなど、ローカルにインストールできるオプションのコマンドライン ツールです。nomos コマンドを使用することで、Config Management Operator の操作、構成ファイルリポジトリに commit する前の構文確認や、Config Sync、クラスタ、リポジトリの問題のデバッグを行うことができます。

前提条件

nomos コマンドを使用してクラスタを操作する前に、ターゲット クラスタに Operator がすでにインストールされている必要があります。また、ターゲット クラスタに対して認証を行うように kubectl コマンドを構成する必要があります。詳細については、kubeconfig エントリの生成をご覧ください。

nomos コマンドをインストールする

nomos コマンドは、Go コードからコンパイルされたバイナリです。これはオプションであり、デフォルトでインストールされた Config Sync には含まれていません。

Config Sync のバージョンに対応する nomos コマンドをダウンロードする方法については、ダウンロードをご覧ください。

注: Config Sync には有効な Anthos の権利付与が必要です。使用権がない場合、ダウンロードは 404 File not found エラーで失敗します。
詳細については、Anthos の料金をご覧ください。

macOS と Linux クライアントの追加手順

バイナリをダウンロードした後、次のコマンドを使用してバイナリを実行可能にします。

chmod +x /path/to/nomos

システムがバイナリを検索する場所(/usr/local/bin など)にコマンドを移動するか、バイナリの完全修飾パスを使用してコマンドを実行します。

基本的な使い方

nomos コマンドと nomos.exe コマンドには、リポジトリの初期化構文エラーのチェック登録されたクラスタのステータスの取得、一連の CustomResourceDefinitions としてのリポジトリの表示、などを行うサブコマンドがあります。

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

nomos --help

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

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

インストール ステータスを確認する

nomos status コマンドを使用すると、すべてのクラスタで Config Sync が正しくインストールされ、構成されていることを確認できます。このコマンドを実行すると、Config Sync の実行を妨げているエラーが報告されます。次に例を示します。

nomos status
my_managed_cluster-1
  --------------------
  NOT INSTALLED

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR
  Error:   git-creds not found. Create git-creds secret in config-management-system namespace.

my_managed_cluster-3
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

この出力を見ると、Config Sync は managed-cluster-1 にインストールされていません。managed-cluster-2 にインストールされていますが、正しく構成されていません。managed-cluster-3 に正しくインストールされ、実行されています。

また、git-creds Secret が存在しないため、managed-cluster-2 が正しく構成されていません。

nomos status のフラグ

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

フラグ 説明
--contexts strings マルチクラスタ コマンドで使用するコンテキストのカンマ区切りのリストを指定できます。デフォルトはすべてのコンテキストです。コンテキストがない場合は「""」を使用します。
-h または --help nomos status コマンドのヘルプ。
--namespace string ステータスを取得する Namespace リポジトリ(マルチリポジトリの場合のみ。すべてのリポジトリを取得する場合はこれを設定しません)。
--poll duration ポーリング間隔(1 回だけ実行する場合はこれを設定しません)。
--timeout duration 各クラスタへの接続のタイムアウト(デフォルトは 3 秒)。

新しいリポを初期化する

新しい Config Sync リポジトリを初期化するには、空のディレクトリを作成してそこに移動し、新しい Git リポジトリを初期化します。

mkdir my-repo
cd my-repo
git init

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

nomos init

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

リポジトリ内のエラーをチェックする

リポに構成を 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 の場合は、リポジトリが非構造化リポジトリとして検証されます。非構造化リポジトリを使用している場合、このフラグは必要です。

サーバー側の検証

タイプが Namespace であるかどうかを nomos vet が判別できない場合、nomos は API サーバーに接続します。nomos はデフォルトで Kubernetes のコアタイプと Config Sync CRD を認識できるため、CR に対応する CRD が宣言されていない場合にのみ、API サーバーへの接続を試みます。この場合、API サーバーに CRD が適用されていないと、nomos vetエラーを返します。このチェックを無効にして、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 CLI の動作にのみ影響します。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 によりこの構成ファイルがクラスタに適用されます。

出力ディレクトリの名前を指定する場合は、コマンドの引数としてディレクトリ パスを指定します。

nomos hydrate [/path/to/directory]

出力を単一クラスタまたはクラスタのリストに制限するには、--clusters フラグを使用して、クラスタ名のカンマ区切りリストを指定します。

nomos view の動作をエミュレートして、有効な構成を単一のファイルに保存するには、--flat フラグを使用します。

詳細については、--help フラグをご覧ください。

nomos hydrate --flat

nomos view

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

nomos view --path=/path/to/your/repo

クラスタのエラーを確認する

Git commit をリポジトリに push するたびに、Operator が変更を検出し、登録済みのすべてのクラスタに新しい構成を適用します。登録済みすべてのクラスタの Config Sync のステータスをモニタリングするには、nomos status コマンドを使用します。クラスタごとに、クラスタに最後に適用された Git commit のハッシュと、最近の変更の適用中に発生したエラーが報告されます。次に例を示します。

nomos status
my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

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

my_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.

my_managed_cluster-4
  --------------------
  NOT INSTALLED

my_managed_cluster-5
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  SYNCED   f52a11e4

2 つのクラスタが最新の変更を同期し、1 つのクラスタがまだ同期中で、もう 1 つのクラスタで変更が適用されないという問題が発生しています。この場合、managed-cluster-3 は他のクラスタがインストールした CRD を検出していません。

デフォルトでは、nomos status コマンドは各クラスタのステータスを出力して終了します。ただし、poll フラグを使用してコマンドを継続的に実行すると、ステータス テーブルを定期的に出力できます。

nomos status --poll 2s

クラスタでのエラーを確認する(マルチリポジトリ)

クラスタのマルチリポジトリ オプションを有効にしている場合は、複数の Git リポジトリから同期できます。nomos status コマンドを実行すると、クラスタ別にグループ化された各リポジトリのステータスが出力されます。次に例を示します。

nomos status
my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

my_managed_cluster-2
  --------------------
  <root>   git@github.com:foo-corp/acme@main
  ERROR    f52a11e4
  Error:   KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

各クラスタは 2 つの Git リポジトリで構成されています。<root> リポジトリはクラスタ管理者に属し、bookstore リポジトリはアプリケーション開発チームに属している可能性があります。

デフォルトでは、nomos status コマンドはクラスタのすべてのリポジトリのステータスを出力します。ただし、namespace フラグを使用すると、コマンドを特定の Namespace リポジトリに制限できます。これにより、アプリケーション チームはリポジトリに nomos status を使用できます。

nomos status --namespace bookstore

最新の同期 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

バグレポートの作成

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

nomos bugreport

このコマンドを使用すると、kubectl コンテキストで設定された Kubernetes クラスタに関する情報を含むタイムスタンプ付きの zip ファイルが生成されます。

このファイルには、Config Sync Pod のログが含まれています。Config Sync と同期されているリソースの情報は含まれません。

トラブルシューティング

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)

次のステップ