ランタイム プレーン コンポーネントを管理する

このトピックでは、Apigee ハイブリッドのランタイム プレーン コンポーネントの構成と管理方法について説明します。構成できるランタイム プレーン コンポーネントの一覧については、ランタイム サービスの構成の概要をご覧ください。

オーバーライド ファイルについて

クラスタに初めてハイブリッド ランタイムをインストールするときに、構成のオーバーライド ファイルを作成する必要があります。このファイルにより、デフォルトの構成値を必要に応じてオーバーライドできます。また、環境の構成、TLS 証明書とサービス アカウント キーのパスの指定、特定のハイブリッド コンポーネントへの Kubernetes ノードプールの割り当てなどの操作を行うことができます。

ハイブリッドのインストール手順を見ると、オーバーライド ファイルを作成してクラスタに構成を適用するプロセスがわかります。後で構成を変更する場合は、作成したオーバーライド ファイルを変更して再度適用します。

構成の変更

ハイブリッド ランタイム プレーン コンポーネントの構成を変更するには、オーバーライド ファイルを編集し、apigeectl を使用して変更を適用します。

たとえば、Message Processor のレプリカ数を変更する手順は次のとおりです。

  1. OVERRIDES.yaml ファイルを開きます。ハイブリッド ランタイムをクラスタにインストールしたときに使用したオーバーライド ファイルを使用してください。
  2. ファイル内で runtime 要素を探します。次に例を示します。
    ...
runtime:
  nodeSelector:
    key: cloud.google.com/gke-nodepool
    value: apigee-runtime
  replicaCountMin: 1
  replicaCountMax: 2
...
  3. 必要に応じてレプリカ数のプロパティを変更します。次に例を示します。
    ...
runtime:
  nodeSelector:
    key: cloud.google.com/gke-nodepool
    value: apigee-runtime
  replicaCountMin: 2
  replicaCountMax: 4
...
  4. apigeectl を使用して変更をクラスタに適用します。 
    apigeectl apply -f ./OVERRIDES.yaml --org --env ENV_NAME

変更可能な構成プロパティ

構成可能なプロパティの一覧については、構成プロパティのリファレンスをご覧ください。このリファレンスに記載されているのは変更可能なプロパティだけです。ここにないプロパティを変更しようとしても、その変更は無視されます。

構成リファレンスの使用方法

構成プロパティのリファレンスでは、構成要素をドット表記で記述しています。最初の項目は最上位の要素名で、その後ろにプロパティと子プロパティが続いています。次に例を示します。

authz.image.pullPolicy

オーバーライド ファイルでは、プロパティは適切な YAML 形式で記述します。上記の例では、最上位の authz 要素が左にインデントされ、下位要素のプロパティはその下にインデントされています。YAML では、各要素と下位要素の末尾にコロンを付ける必要があります。

たとえば、authz.image.pullPolicy プロパティを Always に設定するには、オーバーライド ファイル内で該当する YAML スタンザを探して次のように設定します。

authz:
  image:
    pullPolicy: Always

次の例では、プロパティ cassandra.auth.admin.password（構成プロパティのリファレンスの表記に準拠）を使用して Cassandra の管理者パスワードを設定しています。これを変更するには、オーバーライド ファイルで次の YAML を探して、次のように設定します。

cassandra:
  auth:
    admin:
      password: abc123

構成プロパティのリファレンスには、ハイブリッド ランタイム プレーン コンポーネントで設定可能なすべてのプロパティが記載されています。クラスタに変更を適用する前に、上のパターンに従ってオーバーライド ファイルでこの要素を変更します。

事前定義されたサンプル オーバーライド ファイルの使用

ハイブリッド ランタイムを初めてインストールする場合は、事前定義のサンプル オーバーライド ファイルのいずれかを使用することをおすすめします。これらのサンプル ファイルには、本番環境やテスト環境の設定など、具体的なインストール シナリオに合わせてすべての構成プロパティがあらかじめ記述されています。ユーザーが行うことは、プロパティに適切な値を設定してオーバーライド ファイルをクラスタに適用することだけです。詳細については、ステップ 6: クラスタを構成するをご覧ください。

構成のデフォルトについて

デフォルトのコンポーネント構成は HYBRID_ROOT_DIR/config/values.yaml というファイルに保持されています。オーバーライド ファイルは values.yaml と同じ YAML 構造です。

通常、オーバーライド ファイルには values.yaml に記述された構成プロパティの一部だけが含まれます。すべてのプロパティが編集可能なわけではありません。クラスタに構成を適用すると、オーバーライドがデフォルトと結合され、完全な Kubernetes クラスタ構成が作成されます。結合された構成をテストするもご覧ください。

次のコードは、values.yaml に含まれる mart コンポーネントのデフォルト構成を示します。デフォルト値が設定されているものもあれば、されていないものもあります（sslCertPath や sslKeyPath など）。インストール手順で説明されているように、値がないプロパティに値を設定する必要があります。デフォルト値を変更する場合は、構成プロパティのリファレンスを参照して、そのプロパティが編集可能であることを確認してください。

...
mart:
  replicaCountMin: 2
  replicaCountMax: 4
  targetCPUUtilizationPercentage: 75
  terminationGracePeriodSeconds: 30
  sslCertPath:
  sslKeyPath:
  hostAlias:
  nodeSelector:
    key:
    value:
  revision: blue
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-mart-server"
    tag: "1.3.6"
    pullPolicy: IfNotPresent
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
  initCheckCF:
    resources:
      requests:
        cpu: 10m
  livenessProbe:
    timeoutSeconds: 1
    failureThreshold: 12
    periodSeconds: 5
    initialDelaySeconds: 15
  readinessProbe:
    timeoutSeconds: 1
    successThreshold: 1
    failureThreshold: 2
    periodSeconds: 5
    initialDelaySeconds: 15
  metricsURL: "/v1/server/metrics"
  cwcAppend: |
...

コンポーネントのデフォルトを変更するときに、そのコンポーネントがオーバーライド ファイルに含まれていない場合は、values.yaml から該当する YAML をオーバーライド ファイルにコピーし、オーバーライド ファイルでプロパティを変更します。

サンプル オーバーライド ファイル

Apigee ハイブリッドには、ハイブリッド デプロイメントの設定に役立つサンプル オーバーライド ファイルがいくつか用意されています。インストール要件に最も近いオーバーライド ファイルをコピーして、そのファイルを変更することをおすすめします。

次のサンプル ファイルが HYBRID_ROOT_DIR/examples ディレクトリにあります。

サンプル オーバーライド ファイル 説明
overrides-small.yaml このサンプルはすぐに使い始める場合に適しています。最小限の推奨フットプリントでハイブリッド ランタイム コンポーネントが起動します。このサンプル構成は、デフォルトの設定と値に可能な限り従っています。レプリカの最小数はすべて 1 に設定されています。
overrides-medium.yaml このサンプルは、テスト環境や QA 環境の出発点として適しています。追加のトラフィックを処理できるように、より高レベルのリソースが個々のコンポーネントに与えられています。パフォーマンスを考慮して、Cassandra では SSD が使用されます。この環境では、ステートフル コンポーネントとステートレス コンポーネントを別々のノードにインストールすることをおすすめします。専用ノードを構成するをご覧ください。
overrides-large.yaml このサンプルは、本番前環境や本番環境などの高パフォーマンス環境の出発点として適しています。このサンプルには、暗号鍵やパスワードなどを設定するプロパティが含まれています。個々のコンポーネントには、少なくとも 2 つのレプリカがあります。

カスタム アノテーション

アノテーションは、Apigee ハイブリッド Kubernetes Pod にメタデータを追加するために使用する Key-Value マップです。カスタム アノテーションは、構成プロパティのリファレンスに記載されている次のプロパティに作成できます。

カスタム アノテーションを追加するには、それぞれのコンポーネントの OVERRIDES.yaml ファイルにスタンザを追加します。

次の例は、runtime Pod でアノテーションを指定する方法を示しています。

runtime:
  annotations:
    businessunit: "bu1"

結合された構成をテストする

apigeectl に --dry-run フラグを指定することで、クラスタに構成を適用せずに、結合された構成ファイルをテストできます。この方法を使用すると、何がクラスタに適用されるかが正確に示されるため、インストールに関する問題のデバッグに役立ちます。また、構成をテストしてソース管理システムに保存しておくと、クラスタにインストールされているリソースとその構成を後で参照できるので便利です。

Apigee ハイブリッドでは、実行する kubectl のバージョンによって --dry-run フラグの構文が異なります。次のコマンドで kubectl のバージョンを確認します。

kubectl version

kubectl バージョン 1.17 以前:

APIGEECTL_HOME/apigeectl init -f overrides/OVERRIDES.yaml --dry-run=true

kubectl バージョン 1.18 以降:

APIGEECTL_HOME/apigeectl init -f overrides/OVERRIDES.yaml --dry-run=client

詳細については、apigeectl をご覧ください。

必要に応じて複数のオーバーライド ファイルを作成する

オーバーライド ファイルは、用途に合わせていくつでも作成できます。たとえば、本番環境クラスタを調整するためのオーバーライド ファイルと、テストクラスタを作成するためのオーバーライド ファイルを別々に用意できます。作成したファイルはソース管理システムで管理できます。

apigeectl apply  -f ./test_env_override.yaml

詳細については、apigeectl をご覧ください。

ハイブリッド固有のランタイム プレーン コンポーネントを削除する

ハイブリッドに固有のランタイム プレーン コンポーネントをクラスタから削除するには、apigeectl delete コマンドを使用します。これらのコンポーネントには、synchronizer、mart、runtime、cassandra、udca などがあります。そのランタイム コンポーネントのインストールに使用したオーバーライド ファイルを必ず指定してください。

次に例を示します。

apigeectl delete -f ./OVERRIDES.yaml

apigeectl apply コマンドを使用すると、特定のコンポーネントを再作成できます。 

apigeectl apply --org --env ENV_NAME -f ./OVERRIDES.yaml

詳細については、apigeectl をご覧ください。

特定のコンポーネントを削除する

特定のコンポーネントのみを削除する場合は、apigeectl delete で -c オプションを使用します。そのランタイム コンポーネントのインストールに使用したオーバーライド ファイルを必ず指定してください。

たとえば、synchronizer コンポーネントを削除するには、次のコマンドを使用します。

apigeectl delete --org --env ENV_NAME -f ./OVERRIDES.yaml

その後、apigeectl apply コマンドを使用してコンポーネントを再作成できます。

apigeectl apply --org --env ENV_NAME -f ./OVERRIDES.yaml

詳細については、apigeectl をご覧ください。

すべてのコンポーネントを削除する

ハイブリッドのすべてのクラスタ コンポーネント（apigeectl init コマンドで作成されたものを含む）を削除するには、apigeectl delete コマンドで --all フラグを使用します。そのランタイム コンポーネントのインストールに使用したオーバーライド ファイルを必ず指定してください。

次に例を示します。

apigeectl delete -f ./OVERRIDES.yaml --all

詳細については、apigeectl をご覧ください。