8. コンテナーおよびインスタンスグループ¶

8.1.1. automationcontroller グループのポリシー¶

ノードを定義する際には、以下の基準を使用します。

• automationcontroller グループのノードは、node_type hostvar を hybrid (デフォルト) または control に定義できます。

• execution_nodes グループのノードは、node_type hostvar を execution (デフォルト) または hop に定義できます。

instance_group_* を使用してグループに名前を付けることで、インベントリーファイルでカスタムグループを定義できます。* は API のグループの名前になります。または、インストールが完了した後に API でカスタムインスタンスグループを作成できます。

現在の動作では、instance_group_* のメンバーが automationcontroller または execution_nodes グループのメンバーであることを想定しています。このシナリオ例を挙げています。

[automationcontroller]
126-addr.tatu.home ansible_host=192.168.111.126  node_type=control

[automationcontroller:vars]
peers=execution_nodes

[execution_nodes]

[instance_group_test]
110-addr.tatu.home ansible_host=192.168.111.110 receptor_listener_port=8928

インストーラーを実行すると、以下のエラーが発生します。

TASK [ansible.automation_platform_installer.check_config_static : Validate mesh topology] ***
fatal: [126-addr.tatu.home -> localhost]: FAILED! => {"msg": "The host '110-addr.tatu.home' is not present in either [automationcontroller] or [execution_nodes]"}

これを修正するには、ボックス 110-addr.tatu.home を execution_node グループに移動します。

[automationcontroller]
126-addr.tatu.home ansible_host=192.168.111.126  node_type=control

[automationcontroller:vars]
peers=execution_nodes

[execution_nodes]
110-addr.tatu.home ansible_host=192.168.111.110 receptor_listener_port=8928

[instance_group_test]
110-addr.tatu.home

その結果、以下のようになります。

TASK [ansible.automation_platform_installer.check_config_static : Validate mesh topology] ***
ok: [126-addr.tatu.home -> localhost] => {"changed": false, "mesh": {"110-addr.tatu.home": {"node_type": "execution", "peers": [], "receptor_control_filename": "receptor.sock", "receptor_control_service_name": "control", "receptor_listener": true, "receptor_listener_port": 8928, "receptor_listener_protocol": "tcp", "receptor_log_level": "info"}, "126-addr.tatu.home": {"node_type": "control", "peers": ["110-addr.tatu.home"], "receptor_control_filename": "receptor.sock", "receptor_control_service_name": "control", "receptor_listener": false, "receptor_listener_port": 27199, "receptor_listener_protocol": "tcp", "receptor_log_level": "info"}}}

コントローラー 4.0 以前からアップグレードすると、レガシーの instance_group_ メンバーには awx コードがインストールされている可能性があります。これにより、ノードが automationcontroller グループに配置されます。

8.1.2. API からのインスタンスグループの設定¶

インスタンスグループは、システム管理者として /api/v2/instance_groups に POST 要求を出すことで作成できます。

インスタンスグループを作成したら、インスタンスをインスタンスグループに関連付けることができます。

HTTP POST /api/v2/instance_groups/x/instances/ {'id': y}`

インスタンスグループに追加したインスタンスは、自動的にグループの作業キューをリッスンするように再設定されます。詳細は、以下の「インスタンスグループのポリシー」セクションを参照してください。

8.1.3. インスタンスグループのポリシー¶

policy を定義することにより、オンラインになると自動的にインスタンスグループに参加するようにコントローラーインスタンスを設定できます。これらのポリシーは、新しいインスタンスがオンラインになるたびに評価されます。

インスタンスグループポリシーは、Instance Group の 3 つの任意フィールドにより制御されます。

• policy_instance_percentage: これは、0 ~ 100 の間の数字で指定します。これにより、確実に、アクティブなコントローラーインスタンスの割合が対象のインスタンスグループに追加されるようになります。新しいインスタンスがオンラインになると、このグループのインスタンス数が、インスタンスの全体数に対して、指定の割合より少ない場合には、指定の割合の条件を満たすまで、新しいインスタンスが追加されます。

• policy_instance_minimum: このポリシーは、インスタンスグループに配置するように試行する最小インスタンス数を指定します。利用可能なインスタンス数がこの最小数よりも少ない場合には、すべてのインスタンスがこのインスタンスグループに配置されます。

• policy_instance_list: これは、このインスタンスグループに常に含めるインスタンス名の固定一覧です。

automation controller ユーザーインターフェースのインスタンスグループ一覧ビューでは、インスタンスグループのポリシーをもとにした各インスタンスグループのキャパシティーレベルの概要がわかります。

8.1.4. 主なポリシーの考慮事項¶

• policy_instance_percentage および policy_instance_minimum はいずれも、最小割り当てレベルを指定します。このグループに割り当てる数が多いルールが適用されます。たとえば、policy_instance_percentage が 50%、policy_instance_minimum が 2 の場合に、6 台のインスタンスを起動すると、3 台がこのインスタンスグループに割り当てられます。クラスター内のインスタンス総数を 2 に減らすと、policy_instance_minimum の条件を満たすために、この 2 台のインスタンスがいずれも、インスタンスグループに割り当てられます。こうすることで、利用可能なリソースの制限に合わせて、低い値を設定できます。

• ポリシーは、自発的にインスタンスが複数のインスタンスグループに割り当てられないように規制するわけではありませんが、割合を合計すると 100 になるように指定すると実質的に、複数のインスタンスグループに割り当てないようにできます。インスタンスグループが 4 つあり、割合の値が 25 に割り当てると、インスタンスは重複することなく分散されます。

8.1.5. 固有のグループへのインスタンスの手動固定¶

インスタンスが特別で、特定のインスタンスグループだけに割り当てる必要があり、「percentage」または「minimum」のポリシーで他のグループに自動的に参加させない場合には、以下を行います。

1. インスタンスを 1 つまたは複数のインスタンスグループの policy_instance_list に追加します。

2. インスタンスの managed_by_policy プロパティーを False に更新します。

こうすることで、割合や最小ポリシーをもとに、インスタンスが他のグループに自動的に追加されないようにします。手動で割り当てたグループにのみ所属するようになります。

HTTP PATCH /api/v2/instance_groups/N/
{
"policy_instance_list": ["special-instance"]
}

HTTP PATCH /api/v2/instances/X/
{
"managed_by_policy": False
}

8.1.6. ジョブランタイムの動作¶

インスタンスグループに関連付けられたジョブを実行する場合は、以下の動作に注意してください。

• クラスターを複数のインスタンスグループに分類する場合は、クラスター全体の動作と類似します。インスタンス 2 台がグループに割り当てられると、同じグループ内の他のインスタンスと同様に、いずれかのインスタンスがジョブを受信する可能性が高いです。

• コントローラーインスタンスがオンラインになると、システムの作業容量が効率的に拡張されます。これらのインスタンスがインスタンスグループにも置かれている場合、そのグループの容量も拡張されます。複数のグループに所属するインスタンスが作業を実行する場合は、所属する全グループから容量が削減されます。インスタンスのプロビジョニングを解除すると、インスタンスの割当先のクラスターから容量がなくなります。詳細については「インスタンスのプロビジョニング解除」のセクションを参照してください。

8.1.7. ジョブ実行場所の制御¶

ジョブテンプレート、インベントリー、または組織にインスタンスグループが割り当てられている場合には、対象のジョブテンプレートから実行されたジョブはデフォルトの動作を実行する資格はありません。つまり、これら 3 つのリソースに関連付けられたインスタンスグループに所属する全インスタンスに十分な容量がない場合には、容量が使用可能になるまでジョブは保留状態のままになります。

ジョブの送信先のインスタンスグループを決定する場合の優先順位は、以下のとおりです。

1. ジョブテンプレート

2. インベントリー

3. 組織 (プロジェクトの形式)

インスタンスグループがジョブテンプレートと関連付けられており、いずれも許容容量内である場合には、ジョブはインベントリーで指定したインスタンスグループ、次に組織で指定したインスタンスグループに送信されます。リソースがあるので、ジョブはこれらのグループ内で、任意の順番で実行してください。

グローバルの default グループは、Playbook で定義されるカスタムのインスタンスグループと同様に、リソースと関連付けることができます。これは、ジョブテンプレートやインベントリーに希望のインスタンスグループを指定するのに使用できますが、容量が足りない場合にはジョブは別のインスタンスに送信できます。

たとえば、ジョブテンプレートと group_a を関連付けたり、インベントリーと default``グループを関連付けたりすることで、``group_a の容量が足りなくなると、 default グループをフォールバックとして使用できるようになります。

さらに、インスタンスグループにリソースを関連付けずに、フォールバックとして別のリソースを指定することができます。たとえば、ジョブテンプレートにインスタンスグループを割り当てずに、インベントリーや組織のインスタンスグループにフォールバックするように設定できます。

この設定には、優れたユースケースが他に 2 つあります。

1. (ジョブテンプレートをインスタンスグループに割り当てずに) インスタンスグループにインベントリーを関連付けることで、特定のインベントリーに対して実行される Playbook が関連付けられたグループでのみ実行されるようにすることができます。これらのインスタンスのみが管理ノードに直接関連付けられている場合に非常に便利です。

2. 管理者は、インスタンスグループに組織を割り当てることができます。これにより、管理者はインフラストラクチャー全体をセグメントに分け、各組織が他の組織のジョブ実行機能を妨げずに、ジョブを実行できるように保証します。

同様に、以下のシナリオのように、管理者は希望に合わせて複数のグループを各組織に割り当てることもできます。

• A、B、C の 3 つのインスタンスグループがあり、Org1 および Org2 の 2 つの組織がある場合

• 管理者が Org1 にグループ A を、Org2 にグループ B を、容量が余分に必要となる可能性があるのでオーバーフロー用として Org1 および Org2 両方にグループ C を割り当てる場合

• 組織の管理者が自由にインベントリーまたはジョブテンプレートを希望のグループに割り当てる (か、組織からのデフォルトの順番を継承する) 場合

このような方法でリソースを割り当てると柔軟性が高くなります。また、インスタンスが 1 つしか含まれないインスタンスグループを作成することができるため、コントローラークラスターの固有のホストに作業を割り当てることができるようになります。

8.1.8. インスタンスグループのプロビジョニング解除¶

Playbook の設定を再実行しても、自動的にインスタンスのプロビジョニングが解除されるわけではありません。これは現在、インスタンスがオフラインになった理由が意図的なのか、障害が原因なのかをクラスターでは識別できないためです。代わりに、コントローラーインスタンスの全サービスをシャットダウンしてから、他のインスタンスからプロビジョニング解除ツールを実行します。

1. automation-controller-service stop のコマンドで、インスタンスをシャットダウンするか、サービスを停止します。

2. 別のインスタンスから、プロビジョニング解除のコマンド $ awx-manage deprovision_instance --hostname=<name used in inventory file> を実行して、コントローラーのクラスターレジストリーから削除します。

   例: awx-manage deprovision_instance --hostname=hostB

同様に、プロビジョニングを解除しても、多くの場合、コントローラーのインスタンスグループが使用されないにも関わらず、コントローラーのインスタンスグループのプロビジョニングを解除しても、インスタンスグループが自動的に削除されたり、プロビジョニングが解除されたりしません。そのまま API エンドポイントに表示されたり、統計が監視されたりする可能性があります。これらのグループは、以下のコマンドを使用すると、削除することができます。

例: awx-manage unregister_queue --queuename=<name>

このインベントリーファイルのインスタンスグループから、インスタンスのメンバーシップを削除して、Playbook の設定を再実行しても、インスタンスがグループに再度追加されなくなるわけではありません。インスタンスがグループに追加されないようにするには、API 経由で削除し、インベントリーファイルからも削除するか、インベントリーファイルでインスタンスグループの定義をなくします。automation controller ユーザーインターフェースでインスタンスグループのトポロジーを管理することも可能です。UI でのインスタンスグループの管理に関する詳細は、『Automation Controller User Guide』の「Instance Groups」を参照してください。

8.2.1. コンテナーグループの作成¶

A ContainerGroup is a type of InstanceGroup that has an associated Credential that allows for connecting to an OpenShift cluster. To set up a container group, you must first have the following:

• A namespace you can launch into (every cluster has a “default” namespace, but you may want to use a specific namespace)

• この namespace で Pod を起動および管理可能なロールを持つサービスアカウント

• プライベートレジストリーで execution environments を使用する場合は、オートメーションコントローラーでコンテナーレジストリー認証情報が関連付けられている場合、サービスアカウントには、名前空間で秘密を取得、作成、および削除するためのロールも必要です。これらのロールをサービスアカウントに付与したくない場合は、ImagePullSecrets を事前に作成して、および ContainerGroup の Pod 仕様でそれらを指定します。この場合は、execution environment コンテナーレジストリー認証情報を関連付けないでください。関連付けられていない場合、コントローラーは名前空間に秘密を作成しようとします。

• A token associated with that service account (OpenShift or Kubernetes Bearer Token)

• クラスターに関連付けられた CA 証明書

This section describes creating a Service Account in an Openshift cluster (or K8s) in order to be used to run jobs in a container group via automation controller. After the Service Account is created, its credentials are provided to the controller in the form of an Openshift or Kubernetes API bearer token credential. Below describes how to create a service account and collect the needed information for configuring automation controller.

To configure the controller:

1. To create a service account, you may download and use this sample service account, containergroup sa and modify it as needed to obtain the above credentials.

2. Apply the configuration from containergroup-sa.yml:

   oc apply -f containergroup-sa.yml
   

3. Get the secret name associated with the service account:

   export SA_SECRET=$(oc get sa containergroup-service-account -o json | jq '.secrets[0].name' | tr -d '"')
   

4. Get the token from the secret:

   oc get secret $(echo ${SA_SECRET}) -o json | jq '.data.token' | xargs | base64 --decode > containergroup-sa.token
   

5. Get the CA cert:

   oc get secret $SA_SECRET -o json | jq '.data["ca.crt"]' | xargs | base64 --decode > containergroup-ca.crt
   

6. Use the contents of containergroup-sa.token and containergroup-ca.crt to provide the information for the OpenShift または Kubernetes API Bearer トークン required for the container group.

コンテナーグループを作成するには、以下を実行します。

1. Use the controller user interface to create an OpenShift または Kubernetes API Bearer トークン credential that will be used with your container group, see 新規認証情報の追加 in the Automation Controller User Guide for detail.

2. 左側のナビゲーションバーから インスタンスグループ をクリックして、インスタンスグループ設定ウィンドウに移動して、新しいコンテナーグループを作成します。

3. Add ボタンをクリックして、Create Container Group を選択します。

4. 新しいコンテナーグループの名前を入力し、以前に作成した資格情報を選択して、コンテナーグループに割り当てます。

8.2.2. Pod 仕様のカスタマイズ¶

Ansible Automation Platform provides a simple default Pod specification, however, you can provide a custom YAML (or JSON) document that overrides the default Pod spec. This field uses any custom fields (i.e. ImagePullSecrets) that can be "serialized" as valid Pod JSON or YAML. A full list of options can be found in the OpenShift documentation.

Pod の仕様をカスタマイズするには、トグルを使用して Pod Spec Override フィールドで名前空間を指定し、Pod Spec Override フィールドを有効にして展開し、作業が完了したら Save をクリックします。

必要に応じて、追加のカスタマイズを指定できます。カスタマイズウィンドウ全体を表示するには、Expand をクリックします。

コンテナーグループが正常に作成されると、新規に作成されたコンテナーグループの Details タブがそのまま表示され、コンテナーグループの情報をレビューして編集することができます。これは、Instance Group リンクから編集 () ボタンをクリックして開くメニューと同じです。また、Instances を編集して、このインスタンスグループに関連付けられた Jobs をレビューすることも可能です。

コンテナーグループとインスタンスグループは適宜ラベル付けされます。

8.2.3. コンテナーグループ機能の検証¶

コンテナーのデプロイと終了を確認するには、以下を実行します。

1. 模擬インベントリーを作成し、インスタンスグループ フィールドにコンテナーグループの名前を入力してコンテナーグループをそのインベントリーに関連付けます。詳細については、『Automation Controller User Guide』の「新規インベントリーの追加」を参照してください。

2. 以下の変数を使用して、インベントリーに「localhost」ホストを作成します。

{'ansible_host': '127.0.0.1', 'ansible_connection': 'local'}

3. ping または setup モジュールを使用して、localhost に対してアドホックジョブを起動します。マシンの認証情報 フィールドは必須ですが、このシンプルなテストではどちらを選択してもかまいません。

ジョブの詳細ビューに、アドホックジョブの 1 つを使用してコンテナーに正常に到達したことが表示されます。

If you have an OpenShift UI, you can see Pods appear and disappear as they deploy and terminate. Alternatively, you can use the CLI to perform a get pod operation on your namespace to watch these same events occurring in real-time.

8.2.4. コンテナーグループジョブの表示¶

When you run a job associated with a container group, you can see the details of that job in the Details view and its associated container group and the execution environment that spun up.

8.2.5. Kubernetes API failure conditions¶

When running a container group and the Kubernetes API responds that the resource quota has been exceeded, the controller keeps the job in pending state. Other failures result in the traceback of the Error Details field showing the failure reason, similar to the example here:

8.2.6. コンテナーの容量制限¶

コンテナーの容量制限と割り当ては、Kubernetes API のオブジェクトを介して定義されます。

• To set limits on all pods within a given namespace, use the LimitRange object. Refer to the OpenShift documentation for Quotas and Limit Ranges.

• To set limits directly on the pod definition launched by the controller, see Customize the Pod spec and refer to the OpenShift documentation to set the options to compute resources.