nomos コマンドの使用

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

前提条件

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

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

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

Anthos Config Management の各バージョンの nomos コマンドをダウンロードするには、ダウンロードをご覧ください。

注: Anthos Config Management の使用には、有効な 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 status

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

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

nomos status
Context             Status           Last Synced Token
-------             ------           -----------------
managed-cluster-1   NOT INSTALLED
managed-cluster-2   NOT CONFIGURED
managed-cluster-3   SYNCED           f52a11e4

Config Management Errors:
managed-cluster-2   missing git-creds Secret

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

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

新しいリポを初期化する

新しい Anthos Config Management リポジトリを初期化するには、空のディレクトリを作成してそこに移動し、新しい Git リポジトリを初期化してから、nomos init コマンドを実行します。

mkdir my-repo
cd my-repo
git init
nomos init

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

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

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

nomos vet

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

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

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

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

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

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

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

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

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

nomos status
Context                 Status      Last Synced Token
-------                 ------      -----------------
managed-cluster-1       SYNCED      f52a11e4
managed-cluster-2       PENDING     9edf8444
managed-cluster-3       ERROR       9edf8444
managed-cluster-4       NOT INSTALLED
managed-cluster-5       SYNCED      f52a11e4

Config Management Errors:
managed-cluster-3       KNV1021: No CustomResourceDefinition is defined for the resource in the cluster.

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

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

nomos status --poll 2s

最終同期トークンについて

nomos status は、クラスタに適用された最新の Git commit ハッシュを Last Synced Token の出力に表示します。この値を取得するには、Repo オブジェクトをクエリして status.sync フィールドを確認します。

kubectl get repos.configmanagement.gke.io -o yaml
apiVersion: v1
kind: Repo
items:
- status:
    sync:
      lastUpdate: "2019-09-26T10:17:57Z"
      latestToken: f1739af550912034139aca51e382dc50c4036ae0

この commit は、クラスタに対する最新の commit を表しています。ただし、クラスタ内のすべての名前空間が各 commit の影響を受けるわけではありません。特定の名前空間での最新の commit を確認するには、特定の NamespaceConfig オブジェクトをクエリし、status フィールドを調べます。次に例を示します。

kubectl get namespaceconfigs.configmanagement.gke.io my-namespace -o yaml
apiVersion: configmanagement.gke.io/v1
kind: NamespaceConfig
status:
  syncState: synced
      lastUpdate: "2019-09-26T08:24:32Z"
      latestToken: 1850bad9419d3baec8af220c15d5e952dbeb3b25

名前空間が commit の影響を受けるような場合でも、名前空間内のすべてのリソースが影響を受けるとは限りません。特定のリソースの最新の同期 commit を見つけるには、特定のリソースのクエリを実行し、metadata.annotations.configmanagement.gke.io/token を確認します。次に例を示します。

kubectl get clusterrolebindings.rbac.authorization.k8s.io my-role-binding -o yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/token: e56b09554ca8004a2c38185a4ed11364fd6986c4

バグレポートの作成

Google Cloud サポートの支援が必要な Anthos Config Management に問題がある場合は、nomos bugreport コマンドを使用して有益なデバッグ情報を提供できます。

nomos bugreport

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

このファイルには、Anthos Config Management Pod のログが含まれています。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)

次のステップ