5.5. Ansible ベース Operator
5.5.1. Ansible ベースの Operator の Operator SDK の使用を開始する
Operator プロジェクトを生成するための Operator SDK には、Go コードを作成せずに Kubernetes リソースを統一されたアプリケーションとしてデプロイするために、既存の Ansible Playbook およびモジュールを使用するオプションがあります。
Operator SDK によって提供されるツールおよびライブラリーを使用して Ansible ベースの Operator をセットアップし、実行するための基本を示すには、Operator 開発者は Ansible ベースの Memcached Operator のサンプルをビルドして、分散キー/値のストアを作成し、クラスターへデプロイすることができます。
5.5.1.1. 前提条件
- Operator SDK CLI がインストールされていること。
-
OpenShift CLI (
oc
) v4.9+ がインストールされていること。 - Ansible バージョン v2.9.0
- Ansible Runner バージョン v1.1.0+
- Ansible Runner HTTP Event Emitter プラグイン バージョン v1.0.0+
- OpenShift Python クライアント バージョン v0.11.2+
-
cluster-admin
パーミッションを持つアカウントを使用して、oc
で OpenShift Container Platform 4.9 クラスターにログインしていること。 - クラスターがイメージをプルできるようにするには、イメージをプッシュするリポジトリーを public として設定するか、またはイメージプルシークレットを設定する必要があります。
5.5.1.2. Ansible ベース Operator の作成およびデプロイ
Operator SDK を使用して、Memcached の単純な Ansible ベースの Operator をビルドし、デプロイできます。
手順
プロジェクトを作成します。
プロジェクトディレクトリーを作成します。
$ mkdir memcached-operator
プロジェクトディレクトリーに移動します。
$ cd memcached-operator
ansible
プラグインを指定してoperator-sdk init
コマンドを実行し、プロジェクトを初期化します。$ operator-sdk init \ --plugins=ansible \ --domain=example.com
API を作成します。
単純な Memcached API を作成します。
$ operator-sdk create api \ --group cache \ --version v1 \ --kind Memcached \ --generate-role 1
- 1
- API の Ansible ロールを生成します。
Operator イメージをビルドし、プッシュします。
デフォルトの
Makefile
ターゲットを使用して Operator をビルドし、プッシュします。プッシュ先となるレジストリーを使用するイメージのプル仕様を使用してIMG
を設定します。$ make docker-build docker-push IMG=<registry>/<user>/<image_name>:<tag>
Operator を実行します。
CRD をインストールします。
$ make install
プロジェクトをクラスターにデプロイします。
IMG
をプッシュしたイメージに設定します。$ make deploy IMG=<registry>/<user>/<image_name>:<tag>
サンプルカスタムリソース (CR) を作成します。
サンプル CR を作成します。
$ oc apply -f config/samples/cache_v1_memcached.yaml \ -n memcached-operator-system
Operator を調整する CR を確認します。
$ oc logs deployment.apps/memcached-operator-controller-manager \ -c manager \ -n memcached-operator-system
出力例
... I0205 17:48:45.881666 7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator {"level":"info","ts":1612547325.8819902,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"} {"level":"info","ts":1612547325.98242,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"} {"level":"info","ts":1612547325.9824686,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4} {"level":"info","ts":1612547348.8311093,"logger":"runner","msg":"Ansible-runner exited successfully","job":"4037200794235010051","name":"memcached-sample","namespace":"memcached-operator-system"}
CR を削除する
次のコマンドを実行して CR を削除します。
$ oc delete -f config/samples/cache_v1_memcached.yaml -n memcached-operator-system
クリーンアップします。
以下のコマンドを実行して、この手順の一部として作成されたリソースをクリーンアップします。
$ make undeploy
5.5.1.3. 次のステップ
- Ansible ベースの Operator のビルドに関する詳細な手順は、Ansible ベース Operator の Operator SDK チュートリアル を参照してください。
5.5.2. Ansible ベース Operator の Operator SDK チュートリアル
Operator 開発者は、Operator SDK での Ansible のサポートを利用して、Ansible ベースの Memcached Operator のサンプルをビルドして、分散キー/値のストアを作成し、そのライフサイクルを管理することができます。このチュートリアルでは、以下のプロセスについて説明します。
- Memcached デプロイメントを作成します。
-
デプロイメントのサイズが、
Memcached
カスタムリソース (CR) 仕様で指定されたものと同じであることを確認します。 -
ステータスライターを使用して、
Memcached
CR ステータスをmemcached
Pod の名前で更新します。
このプロセスは、Operator Framework の 2 つの重要な設定要素を使用して実行されます。
- Operator SDK
-
operator-sdk
CLI ツールおよびcontroller-runtime
ライブラリー API - Operator Lifecycle Manager (OLM)
- クラスター上の Operator のインストール、アップグレード、ロールベースのアクセス制御 (RBAC)
このチュートリアルでは、Ansible ベースの Operator の Operator SDK の使用を開始する よりも詳細に説明します。
5.5.2.1. 前提条件
- Operator SDK CLI がインストールされていること。
-
OpenShift CLI (
oc
) v4.9+ がインストールされていること。 - Ansible バージョン v2.9.0
- Ansible Runner バージョン v1.1.0+
- Ansible Runner HTTP Event Emitter プラグイン バージョン v1.0.0+
- OpenShift Python クライアント バージョン v0.11.2+
-
cluster-admin
パーミッションを持つアカウントを使用して、oc
で OpenShift Container Platform 4.9 クラスターにログインしていること。 - クラスターがイメージをプルできるようにするには、イメージをプッシュするリポジトリーを public として設定するか、またはイメージプルシークレットを設定する必要があります。
5.5.2.2. プロジェクトの作成
Operator SDK CLI を使用して memcached-operator
というプロジェクトを作成します。
手順
プロジェクトのディレクトリーを作成します。
$ mkdir -p $HOME/projects/memcached-operator
ディレクトリーに切り替えます。
$ cd $HOME/projects/memcached-operator
ansible
プラグインを指定してoperator-sdk init
コマンドを実行し、プロジェクトを初期化します。$ operator-sdk init \ --plugins=ansible \ --domain=example.com
5.5.2.2.1. PROJECT ファイル
operator-sdk init
コマンドで生成されるファイルの 1 つに、Kubebuilder の PROJECT
ファイルがあります。プロジェクトルートから実行される後続の operator-sdk
コマンドおよび help
出力は、このファイルを読み取り、プロジェクトタイプが Ansible であることを認識しています。以下に例を示します。
domain: example.com layout: ansible.sdk.operatorframework.io/v1 projectName: memcached-operator version: 3
5.5.2.3. API の作成
Operator SDK CLI を使用して Memcached API を作成します。
手順
以下のコマンドを実行して、グループ
cache
、バージョン、v1
、および種類Memcached
を指定して API を作成します。$ operator-sdk create api \ --group cache \ --version v1 \ --kind Memcached \ --generate-role 1
- 1
- API の Ansible ロールを生成します。
API の作成後に、Operator プロジェクトは以下の構造で更新します。
- Memcached CRD
-
サンプル
Memcached
リソースが含まれます。 - Manager
以下を使用して、クラスターの状態を必要な状態に調整するプログラム。
- reconciler (Ansible ロールまたは Playbook のいずれか)
-
Memcached
リソースをmemcached
Ansible ロールに接続するwatches.yaml
ファイル
5.5.2.4. マネージャーの変更
Operator プロジェクトを更新して、Ansible ロールの形式で reconcile ロジックを提供します。これは、Memcached
リソースが作成、更新、または削除されるたびに実行されます。
手順
roles/memcached/tasks/main.yml
ファイルを以下の構造で更新します。--- - name: start memcached community.kubernetes.k8s: definition: kind: Deployment apiVersion: apps/v1 metadata: name: '{{ ansible_operator_meta.name }}-memcached' namespace: '{{ ansible_operator_meta.namespace }}' spec: replicas: "{{size}}" selector: matchLabels: app: memcached template: metadata: labels: app: memcached spec: containers: - name: memcached command: - memcached - -m=64 - -o - modern - -v image: "docker.io/memcached:1.4.36-alpine" ports: - containerPort: 11211
この
memcached
ロールは、memcached
デプロイメントが存在することを確実にし、デプロイメントサイズを設定します。roles/memcached/defaults/main.yml
ファイルを編集して、Ansible ロールで使用される変数のデフォルト値を設定します。--- # defaults file for Memcached size: 1
以下の構造で、
config/samples/cache_v1_memcached.yaml
ファイルのMemcached
サンプルリソースを更新します。apiVersion: cache.example.com/v1 kind: Memcached metadata: name: memcached-sample spec: size: 3
カスタムリソース (CR) 仕様のキー/値のペアは、追加の変数として Ansible に渡されます。
spec
フィールドのすべての変数の名前は、Ansible の実行前に Operator によってスネークケース (小文字 + アンダースコア) に変換されます。たとえば、仕様の serviceAccount
は Ansible では service_account
になります。
watches.yaml
ファイルで snakeCaseParameters
オプションを false
に設定して、このケース変換を無効にすることができます。Ansible で変数についてのタイプの検証を実行し、アプリケーションが予想される入力を受信していることを確認することが推奨されます。
5.5.2.5. プロキシーサポートの有効化
Operator の作成者は、ネットワークプロキシーをサポートする Operator を開発できるようになりました。クラスター管理者は、Operator Lifecycle Manager (OLM) によって処理される環境変数のプロキシーサポートを設定します。Operator は以下の標準プロキシー変数の環境を検査し、値をオペランドに渡して、プロキシーされたクラスターをサポートする必要があります。
-
HTTP_PROXY
-
HTTPS_PROXY
-
NO_PROXY
このチュートリアルでは、HTTP_PROXY
を環境変数の例として使用します。
前提条件
- クラスター全体の egress プロキシーが有効にされているクラスター。
手順
以下で
roles/memcached/tasks/main.yml
ファイルを更新して、環境変数をデプロイメントに追加します。... env: - name: HTTP_PROXY value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}' - name: http_proxy value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}' ...
以下を
config/manager/manager.yaml
ファイルに追加して、Operator デプロイメントに環境変数を設定します。containers: - args: - --leader-elect - --leader-election-id=ansible-proxy-demo image: controller:latest name: manager env: - name: "HTTP_PROXY" value: "http_proxy_test"
5.5.2.6. Operator の実行
Operator SDK CLI を使用して Operator をビルドし、実行する方法は 3 つあります。
- クラスター外で Go プログラムとしてローカルに実行します。
- クラスター上のデプロイメントとして実行します。
- Operator をバンドルし、Operator Lifecycle Manager (OLM) を使用してクラスター上にデプロイします。
5.5.2.6.1. クラスター外でローカルに実行する。
Operator プロジェクトをクラスター外の Go プログラムとして実行できます。これは、デプロイメントとテストを迅速化するという開発目的において便利です。
手順
以下のコマンドを実行して、
~/.kube/config
ファイルに設定されたクラスターにカスタムリソース定義 (CRD) をインストールし、Operator をローカルで実行します。$ make install run
出力例
... {"level":"info","ts":1612589622.7888272,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"} {"level":"info","ts":1612589622.7897573,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"} {"level":"info","ts":1612589622.789971,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"} {"level":"info","ts":1612589622.7899997,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"} {"level":"info","ts":1612589622.8904517,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"} {"level":"info","ts":1612589622.8905244,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8}
5.5.2.6.2. クラスター上でのデプロイメントとしての実行
Operator プロジェクトは、クラスター上でのデプロイメントとして実行することができます。
手順
以下の
make
コマンドを実行して Operator イメージをビルドし、プッシュします。以下の手順のIMG
引数を変更して、アクセス可能なリポジトリーを参照します。Quay.io などのリポジトリーサイトにコンテナーを保存するためのアカウントを取得できます。イメージをビルドします。
$ make docker-build IMG=<registry>/<user>/<image_name>:<tag>
注記Operator の SDK によって生成される Dockerfile は、
go build
についてGOARCH=amd64
を明示的に参照します。これは、AMD64 アーキテクチャー以外の場合はGOARCH=$TARGETARCH
に修正できます。Docker は、-platform
で指定された値に環境変数を自動的に設定します。Buildah では、そのために-build-arg
を使用する必要があります。詳細は、Multiple Architectures を参照してください。イメージをリポジトリーにプッシュします。
$ make docker-push IMG=<registry>/<user>/<image_name>:<tag>
注記両方のコマンドのイメージの名前とタグ (例:
IMG=<registry>/<user>/<image_name>:<tag>
) を Makefile に設定することもできます。IMG ?= controller:latest
の値を変更して、デフォルトのイメージ名を設定します。
以下のコマンドを実行して Operator をデプロイします。
$ make deploy IMG=<registry>/<user>/<image_name>:<tag>
デフォルトで、このコマンドは
<project_name>-system
の形式で Operator プロジェクトの名前で namespace を作成し、デプロイメントに使用します。このコマンドは、config/rbac
から RBAC マニフェストもインストールします。Operator が実行されていることを確認します。
$ oc get deployment -n <project_name>-system
出力例
NAME READY UP-TO-DATE AVAILABLE AGE <project_name>-controller-manager 1/1 1 1 8m
5.5.2.6.3. Operator のバンドルおよび Operator Lifecycle Manager を使用したデプロイ
5.5.2.6.3.1. Operator のバンドル
Operator Bundle Format は、Operator SDK および Operator Lifecycle Manager (OLM) のデフォルトパッケージ方法です。Operator SDK を使用して OLM に対して Operator を準備し、バンドルイメージをとして Operator プロジェクトをビルドしてプッシュできます。
前提条件
- 開発ワークステーションに Operator SDK CLI がインストールされていること。
-
OpenShift CLI (
oc
) v4.9+ がインストールされていること。 - Operator プロジェクトが Operator SDK を使用して初期化されていること。
手順
以下の
make
コマンドを Operator プロジェクトディレクトリーで実行し、Operator イメージをビルドし、プッシュします。以下の手順のIMG
引数を変更して、アクセス可能なリポジトリーを参照します。Quay.io などのリポジトリーサイトにコンテナーを保存するためのアカウントを取得できます。イメージをビルドします。
$ make docker-build IMG=<registry>/<user>/<operator_image_name>:<tag>
注記Operator の SDK によって生成される Dockerfile は、
go build
についてGOARCH=amd64
を明示的に参照します。これは、AMD64 アーキテクチャー以外の場合はGOARCH=$TARGETARCH
に修正できます。Docker は、-platform
で指定された値に環境変数を自動的に設定します。Buildah では、そのために-build-arg
を使用する必要があります。詳細は、Multiple Architectures を参照してください。イメージをリポジトリーにプッシュします。
$ make docker-push IMG=<registry>/<user>/<operator_image_name>:<tag>
Operator SDK
generate bundle
およびbundle validate
のサブコマンドを含む複数のコマンドを呼び出すmake bundle
コマンドを実行し、Operator バンドルマニフェストを作成します。$ make bundle IMG=<registry>/<user>/<operator_image_name>:<tag>
Operator のバンドルマニフェストは、アプリケーションを表示し、作成し、管理する方法を説明します。
make bundle
コマンドは、以下のファイルおよびディレクトリーを Operator プロジェクトに作成します。-
ClusterServiceVersion
オブジェクトを含むbundle/manifests
という名前のバンドルマニフェストディレクトリー -
bundle/metadata
という名前のバンドルメタデータディレクトリー -
config/crd
ディレクトリー内のすべてのカスタムリソース定義 (CRD) -
Dockerfile
bundle.Dockerfile
続いて、これらのファイルは
operator-sdk bundle validate
を使用して自動的に検証され、ディスク上のバンドル表現が正しいことを確認します。-
以下のコマンドを実行し、バンドルイメージをビルドしてプッシュします。OLM は、1 つ以上のバンドルイメージを参照するインデックスイメージを使用して Operator バンドルを使用します。
バンドルイメージをビルドします。イメージをプッシュしようとするレジストリー、ユーザー namespace、およびイメージタグの詳細で
BUNDLE_IMG
を設定します。$ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>
バンドルイメージをプッシュします。
$ docker push <registry>/<user>/<bundle_image_name>:<tag>
5.5.2.6.3.2. Operator Lifecycle Manager を使用した Operator のデプロイ
Operator Lifecycle Manager (OLM) は、Kubernetes クラスターで Operator (およびそれらの関連サービス) をインストールし、更新し、ライフサイクルを管理するのに役立ちます。OLM はデフォルトで OpenShift Container Platform にインストールされ、Kubernetes 拡張として実行されるため、追加のツールなしにすべての Operator のライフサイクル管理機能に Web コンソールおよび OpenShift CLI (oc
) を使用できます。
Operator Bundle Format は、Operator SDK および OLM のデフォルトパッケージ方法です。Operator SDK を使用して OLM でバンドルイメージを迅速に実行し、適切に実行されるようにできます。
前提条件
- 開発ワークステーションに Operator SDK CLI がインストールされていること。
- ビルドされ、レジストリーにプッシュされる Operator バンドルイメージ。
-
(OpenShift Container Platform 4.9 など、
apiextensions.k8s.io/v1
CRD を使用する場合は v1.16.0 以降の) Kubernetes ベースのクラスターに OLM がインストールされていること。 -
cluster-admin
パーミッションのあるアカウントを使用してoc
でクラスターへログインしていること。
手順
以下のコマンドを入力してクラスターで Operator を実行します。
$ operator-sdk run bundle \ [-n <namespace>] \1 <registry>/<user>/<bundle_image_name>:<tag>
- 1
- デフォルトで、このコマンドは
~/.kube/config
ファイルの現在アクティブなプロジェクトに Operator をインストールします。-n
フラグを追加して、インストールに異なる namespace スコープを設定できます。
このコマンドにより、以下のアクションが行われます。
- バンドルイメージをインジェクトしてインデックスイメージを作成します。インデックスイメージは不透明で一時的なものですが、バンドルを実稼働環境でカタログに追加する方法を正確に反映します。
- 新規インデックスイメージを参照するカタログソースを作成します。これにより、OperatorHub が Operator を検出できるようになります。
-
OperatorGroup
、Subscription
、InstallPlan
、および RBAC を含むその他の必要なオブジェクトすべてを作成して、Operator をクラスターにデプロイします。
5.5.2.7. カスタムリソースの作成
Operator のインストール後に、Operator によってクラスターに提供されるカスタムリソース (CR) を作成して、これをテストできます。
前提条件
-
クラスターにインストールされている
Memcached
CR を提供する Memcached Operator の例
手順
Operator がインストールされている namespace へ変更します。たとえば、
make deploy
コマンドを使用して Operator をデプロイした場合は、以下のようになります。$ oc project memcached-operator-system
config/samples/cache_v1_memcached.yaml
でMemcached
CR マニフェストのサンプルを編集し、以下の仕様が含まれるようにします。apiVersion: cache.example.com/v1 kind: Memcached metadata: name: memcached-sample ... spec: ... size: 3
CR を作成します。
$ oc apply -f config/samples/cache_v1_memcached.yaml
Memcached
Operator が、正しいサイズで CR サンプルのデプロイメントを作成することを確認します。$ oc get deployments
出力例
NAME READY UP-TO-DATE AVAILABLE AGE memcached-operator-controller-manager 1/1 1 1 8m memcached-sample 3/3 3 3 1m
ステータスが Memcached Pod 名で更新されていることを確認するために、Pod および CR ステータスを確認します。
Pod を確認します。
$ oc get pods
出力例
NAME READY STATUS RESTARTS AGE memcached-sample-6fd7c98d8-7dqdr 1/1 Running 0 1m memcached-sample-6fd7c98d8-g5k7v 1/1 Running 0 1m memcached-sample-6fd7c98d8-m7vn7 1/1 Running 0 1m
CR ステータスを確認します。
$ oc get memcached/memcached-sample -o yaml
出力例
apiVersion: cache.example.com/v1 kind: Memcached metadata: ... name: memcached-sample ... spec: size: 3 status: nodes: - memcached-sample-6fd7c98d8-7dqdr - memcached-sample-6fd7c98d8-g5k7v - memcached-sample-6fd7c98d8-m7vn7
デプロイメントサイズを更新します。
config/samples/cache_v1_memcached.yaml
ファイルを更新し、Memcached
CR のspec.size
フィールドを3
から5
に変更します。$ oc patch memcached memcached-sample \ -p '{"spec":{"size": 5}}' \ --type=merge
Operator がデプロイメントサイズを変更することを確認します。
$ oc get deployments
出力例
NAME READY UP-TO-DATE AVAILABLE AGE memcached-operator-controller-manager 1/1 1 1 10m memcached-sample 5/5 5 5 3m
このチュートリアルの一環として作成したリソースをクリーンアップします。
Operator のテストに
make deploy
コマンドを使用した場合は、以下のコマンドを実行します。$ make undeploy
Operator のテストに
operator-sdk run bundle
コマンドを使用した場合は、以下のコマンドを実行します。$ operator-sdk cleanup <project_name>
5.5.2.8. 関連情報
- Operator SDK によって作成されるディレクトリー構造の詳細は、Ansible ベース Operator のプロジェクトレイアウト を参照してください。
- クラスター全体の egress プロキシーが設定されている場合 に、クラスター管理者は Operator Lifecycle Manager(OLM) で実行される特定の Operator の プロキシー設定を上書きしたり、 カスタム CA 証明書を挿入したり できます。
5.5.3. Ansible ベース Operator のプロジェクトレイアウト
operator-sdk
CLI は、各 Operator プロジェクトに多数のパッケージおよびファイルを生成、または スキャフォールディング することができます。
5.5.3.1. Ansible ベースのプロジェクトレイアウト
operator-sdk init --plugins ansible
コマンドを使用して生成される Ansible ベースの Operator プロジェクトには、以下のディレクトリーおよびファイルが含まれます。
ファイルまたはディレクトリー | 目的 |
---|---|
| Operator のコンテナーイメージをビルドするための Dockerfile。 |
| Operator バイナリーをラップするコンテナーイメージのビルド、公開、デプロイに使用するターゲット、およびカスタムリソース定義 (CRD) のインストールおよびアンインストールに使用するターゲット。 |
| Operator のメタデータ情報が含まれる YAML ファイル。 |
|
ベース CRD ファイルおよび |
|
デプロイメント用のすべての Operator マニフェストを収集します。 |
| コントローラーマネージャーデプロイメント。 |
|
Operator をモニターリングするための |
| リーダー選択および認証プロキシーのロールとロールバインディング。 |
| CRD 用に作成されたサンプルリソース。 |
| テスト用の設定例。 |
| 実行する Playbook のサブディレクトリー。 |
| 実行するロールツリーのサブディレクトリー。 |
|
監視するリソースの group/version/kind (GVK) および Ansible 呼び出しメソッド。新しいエントリーは、 |
| ビルド時にインストールする Ansible コレクションおよびロールの依存関係が含まれる YAML ファイル。 |
| ロールおよび Operator のエンドツーエンドのテストを行う Molecule シナリオ。 |
5.5.4. Operator SDK における Ansible サポート
5.5.4.1. カスタムリソースファイル
Operator は Kubernetes の拡張メカニズムであるカスタムリソース定義 (CRD) を使用するため、カスタムリソース (CR) は、組み込み済みのネイティブ Kubernetes オブジェクトのように表示され、機能します。
CR ファイル形式は Kubernetes リソースファイルです。オブジェクトには、必須およびオプションフィールドが含まれます。
フィールド | 説明 |
---|---|
| 作成される CR のバージョン。 |
| 作成される CR の種類。 |
| 作成される Kubernetes 固有のメタデータ。 |
| Ansible に渡される変数のキーと値の一覧。このフィールドは、デフォルトでは空です。 |
|
オブジェクトの現在の状態の概要を示します。Ansible ベースの Operator の場合、 |
| CR に付加する Kubernetes 固有のアノテーション。 |
CR アノテーションの以下の一覧は Operator の動作を変更します。
アノテーション | 説明 |
---|---|
|
CR の調整間隔を指定します。この値は標準的な Golang パッケージ |
Ansible ベースの Operator アノテーションの例
apiVersion: "test1.example.com/v1alpha1" kind: "Test1" metadata: name: "example" annotations: ansible.operator-sdk/reconcile-period: "30s"
5.5.4.2. watches.yaml ファイル
group/version/kind(GVK) は Kubernetes API の一意の識別子です。watches.yaml
ファイルには、その GVK によって特定される、カスタムリソース (CR) から Ansible ロールまたは Playbook へのマッピングの一覧が含まれます。Operator はこのマッピングファイルが事前に定義された場所の /opt/ansible/watches.yaml
にあることを予想します。
フィールド | 説明 |
---|---|
| 監視する CR のグループ。 |
| 監視する CR のバージョン。 |
| 監視する CR の種類。 |
|
コンテナーに追加される Ansible ロールへのパスです。たとえば、 |
|
コンテナーに追加される Ansible Playbook へのパスです。この Playbook の使用はロールを呼び出す方法になります。このフィールドは |
| ロールまたは Playbook が特定の CR について実行される調整期間および頻度。 |
|
|
watches.yaml
ファイルの例
- version: v1alpha1 1 group: test1.example.com kind: Test1 role: /opt/ansible/roles/Test1 - version: v1alpha1 2 group: test2.example.com kind: Test2 playbook: /opt/ansible/playbook.yml - version: v1alpha1 3 group: test3.example.com kind: Test3 playbook: /opt/ansible/test3.yml reconcilePeriod: 0 manageStatus: false
5.5.4.2.1. 高度なオプション
高度な機能は、それらを GVK ごとに watches.yaml
ファイルに追加して有効にできます。それらは group
、version
、kind
および playbook
または role
フィールドの下に移行できます。
一部の機能は、CR のアノテーションを使用してリソースごとに上書きできます。オーバーライドできるオプションには、以下に指定されるアノテーションが含まれます。
機能 | YAML キー | 説明 | 上書きのアノテーション | デフォルト値 |
---|---|---|---|---|
調整期間 |
| 特定の CR についての調整実行の間隔。 |
|
|
ステータスの管理 |
|
Operator は各 CR の |
| |
依存するリソースの監視 |
| Operator は Ansible によって作成されるリソースを動的に監視できます。 |
| |
クラスタースコープのリソースの監視 |
| Operator は Ansible によって作成されるクラスタースコープのリソースを監視できます。 |
| |
最大 Runner アーティファクト |
| Ansible Runner が各リソースについて Operator コンテナーに保持する アーティファクトディレクトリー の数を管理します。 |
|
|
高度なオプションを含む watches.yml ファイルの例
- version: v1alpha1 group: app.example.com kind: AppService playbook: /opt/ansible/playbook.yml maxRunnerArtifacts: 30 reconcilePeriod: 5s manageStatus: False watchDependentResources: False
5.5.4.3. Ansible に送信される追加変数
追加の変数を Ansible に送信し、Operator で管理できます。カスタマーリソース (CR) の spec
セクションでは追加変数としてキーと値のペアを渡します。これは、ansible-playbook
コマンドに渡される追加変数と同等です。
また Operator は、CR の名前および CR の namespace についての meta
フィールドの下に追加の変数を渡します。
以下は CR の例になります。
apiVersion: "app.example.com/v1alpha1" kind: "Database" metadata: name: "example" spec: message: "Hello world 2" newParameter: "newParam"
追加変数として Ansible に渡される構造は以下のとおりです。
{ "meta": { "name": "<cr_name>", "namespace": "<cr_namespace>", }, "message": "Hello world 2", "new_parameter": "newParam", "_app_example_com_database": { <full_crd> }, }
message
および newParameter
フィールドは追加変数として上部に設定され、meta
は Operator に定義されるように CR の関連メタデータを提供します。meta
フィールドは、Ansible のドット表記などを使用してアクセスできます。
--- - debug: msg: "name: {{ ansible_operator_meta.name }}, {{ ansible_operator_meta.namespace }}"
5.5.4.4. Ansible Runner ディレクトリー
Ansible Runner はコンテナーに Ansible 実行についての情報を維持します。これは /tmp/ansible-operator/runner/<group>/<version>/<kind>/<namespace>/<name>
に置かれます。
関連情報
-
runner
ディレクトリーについての詳細は、Ansible Runner ドキュメント を参照してください。
5.5.5. Kubernetes Collection for Ansible
Ansible を使用して Kubernetes でアプリケーションのライフサイクルを管理するには、Kubernetes Collection for Ansible を使用できます。この Ansible モジュールのコレクションにより、開発者は既存の Kubernetes リソースファイル (YAML で作成されている) を利用するか、またはネイティブの Ansible でライフサイクル管理を表現することができます。
Ansible を既存の Kubernetes リソースファイルと併用する最大の利点の 1 つに、Ansible のいくつかを変数のみを使う単純な方法でのリソースのカスタマイズを可能にする Jinja テンプレートを使用できる点があります。
このセクションでは、Kubernetes コレクションの使用法を詳細に説明します。使用を開始するには、Playbook を使用してローカルワークステーションにコレクションをインストールし、これをテストしてから、Operator 内での使用を開始します。
5.5.5.1. Kubernetes Collection for Ansible のインストール
Kubernetes Collection for Ansible をローカルワークステーションにインストールできます。
手順
Ansible 2.9+ をインストールします。
$ sudo dnf install ansible
OpenShift python クライアント パッケージをインストールします。
$ pip3 install openshift
以下の方法のいずれかを使用して、Kubernetes コレクションをインストールします。
コレクションは、Ansible Galaxy から直接インストールできます。
$ ansible-galaxy collection install community.kubernetes
Operator がすでに初期化されている場合は、プロジェクトのトップレベルに
requirements.yml
ファイルがあるかもしれません。このファイルは、Operator が機能するためにインストールする必要のある Ansible 依存関係を指定します。デフォルトで、このファイルはcommunity.kubernetes
コレクションとoperator_sdk.util
コレクションをインストールします。これは、Operator 固有の機能のモジュールおよびプラグインを提供します。requirements.yml
ファイルから依存モジュールをインストールするには、以下を実行します。$ ansible-galaxy collection install -r requirements.yml
5.5.5.2. Kubernetes コレクションのローカルでのテスト
Operator 開発者は、毎回 Operator を実行し、再ビルドするのではなく、Ansible コードをローカルマシンから実行することができます。
前提条件
- Ansible ベースの Operator プロジェクトを初期化し、Operator SDK を使用して、生成された Ansible ロールを持つ API を作成します。
- Kubernetes Collection for Ansible をインストールします。
手順
Ansible ベースの Operator プロジェクトディレクトリーで、必要な Ansible ロジックを使用して
roles/<kind>/tasks/main.yml
ファイルを変更します。roles/<kind>/
ディレクトリーは、API の作成時に--generate-role
フラグを使用する場合に作成されます。<kind>
を置き換え可能なものは、API に指定した kind と一致します。以下の例では、
state
という名前の変数の値に基づいた設定マップを作成し、削除します。--- - name: set ConfigMap example-config to {{ state }} community.kubernetes.k8s: api_version: v1 kind: ConfigMap name: example-config namespace: default 1 state: "{{ state }}" ignore_errors: true 2
デフォルトで
state
をpresent
に設定するように、roles/<kind>/defaults/main.yml
ファイルを変更します。--- state: present
プロジェクトディレクトリーのトップレベルに
playbook.yml
ファイルを作成して Ansible playbook を作成し、<kind>
ロールを追加します。--- - hosts: localhost roles: - <kind>
Playbook を実行します。
$ ansible-playbook playbook.yml
出力例
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all' PLAY [localhost] ******************************************************************************** TASK [Gathering Facts] ******************************************************************************** ok: [localhost] TASK [memcached : set ConfigMap example-config to present] ******************************************************************************** changed: [localhost] PLAY RECAP ******************************************************************************** localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
設定マップが作成されたことを確認します。
$ oc get configmaps
出力例
NAME DATA AGE example-config 0 2m1s
state
をabsent
に設定して Playbook を再実行します。$ ansible-playbook playbook.yml --extra-vars state=absent
出力例
[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all' PLAY [localhost] ******************************************************************************** TASK [Gathering Facts] ******************************************************************************** ok: [localhost] TASK [memcached : set ConfigMap example-config to absent] ******************************************************************************** changed: [localhost] PLAY RECAP ******************************************************************************** localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
設定マップが削除されたことを確認します。
$ oc get configmaps
5.5.5.3. 次のステップ
- カスタムリソース (CR) の変更時に、Operator 内でカスタム Ansible ロジックをトリガーする方法については、Operator 内での Ansible の使用 参照してください。
5.5.6. Operator 内での Ansible の使用
Kubernetes Collection for Ansible をローカルで使用すること に慣れたら、カスタムリソース (CR) の変更時に Operator 内で同じ Ansible ロジックをトリガーできます。この例では、Ansible ロールを、Operator が監視する特定の Kubernetes リソースにマップします。このマッピングは watches.yaml
ファイルで実行されます。
5.5.6.1. カスタムリソースファイル
Operator は Kubernetes の拡張メカニズムであるカスタムリソース定義 (CRD) を使用するため、カスタムリソース (CR) は、組み込み済みのネイティブ Kubernetes オブジェクトのように表示され、機能します。
CR ファイル形式は Kubernetes リソースファイルです。オブジェクトには、必須およびオプションフィールドが含まれます。
フィールド | 説明 |
---|---|
| 作成される CR のバージョン。 |
| 作成される CR の種類。 |
| 作成される Kubernetes 固有のメタデータ。 |
| Ansible に渡される変数のキーと値の一覧。このフィールドは、デフォルトでは空です。 |
|
オブジェクトの現在の状態の概要を示します。Ansible ベースの Operator の場合、 |
| CR に付加する Kubernetes 固有のアノテーション。 |
CR アノテーションの以下の一覧は Operator の動作を変更します。
アノテーション | 説明 |
---|---|
|
CR の調整間隔を指定します。この値は標準的な Golang パッケージ |
Ansible ベースの Operator アノテーションの例
apiVersion: "test1.example.com/v1alpha1" kind: "Test1" metadata: name: "example" annotations: ansible.operator-sdk/reconcile-period: "30s"
5.5.6.2. Ansible ベース Operator のローカルでのテスト
Operator プロジェクトのトップレベルディレクトリーから make run
コマンドを使用して、ローカルで実行中の Ansible ベースの Operator 内でロジックをテストできます。make run
Makefile ターゲットは、ansible-operator
バイナリーをローカルで実行します。これは watches.yaml
ファイルを読み取り、~/.kube/config
ファイルを使用して k8s
モジュールが実行するように Kubernetes クラスターと通信します。
環境変数 ANSIBLE_ROLES_PATH
を設定するか、または ansible-roles-path
フラグを使用して、ロールパスをカスタマイズすることができます。ロールが ANSIBLE_ROLES_PATH
の値にない場合、Operator は {{current directory}}/roles
で検索します。
前提条件
- Ansible Runner バージョン v1.1.0+
- Ansible Runner HTTP Event Emitter プラグイン バージョン v1.0.0+
- Kubernetes コレクションをローカルでテストするための前述の手順を実施済みである。
手順
カスタムリソース定義 (CRD) およびカスタムリソース (CR) の適切なロールベースアクセス制御 (RBAC) 定義をインストールします。
$ make install
出力例
/usr/bin/kustomize build config/crd | kubectl apply -f - customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com created
make run
コマンドを実行します。$ make run
出力例
/home/user/memcached-operator/bin/ansible-operator run {"level":"info","ts":1612739145.2871568,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.10.1","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"} ... {"level":"info","ts":1612739148.347306,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":":8080"} {"level":"info","ts":1612739148.3488882,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2} {"level":"info","ts":1612739148.3490262,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false} {"level":"info","ts":1612739148.3490646,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"} {"level":"info","ts":1612739148.350217,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"} {"level":"info","ts":1612739148.3506632,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"} {"level":"info","ts":1612739148.350784,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"} {"level":"info","ts":1612739148.5511978,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"} {"level":"info","ts":1612739148.5512562,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8}
Operator が CR のイベントを監視していることから、CR の作成により、Ansible ロールの実行がトリガーされます。
注記config/samples/<gvk>.yaml
CR マニフェストの例を見てみましょう。apiVersion: <group>.example.com/v1alpha1 kind: <kind> metadata: name: "<kind>-sample"
spec
フィールドが設定されていないため、Ansible は追加の変数なしで起動します。CR から Ansible へ追加の変数を渡すことについては、別のセクションで説明します。Operator に妥当なデフォルトを設定することは重要です。デフォルト変数
state
をpresent
に設定し、CR インスタンスを作成します。$ oc apply -f config/samples/<gvk>.yaml
example-config
設定マップが作成されたことを確認します。$ oc get configmaps
出力例
NAME STATUS AGE example-config Active 3s
state
フィールドをabsent
に設定するように、config/samples/<gvk>.yaml
ファイルを変更します。以下に例を示します。apiVersion: cache.example.com/v1 kind: Memcached metadata: name: memcached-sample spec: state: absent
変更を適用します。
$ oc apply -f config/samples/<gvk>.yaml
設定マップが削除されていることを確認します。
$ oc get configmap
5.5.6.3. クラスター上での Ansible ベース Operator のテスト
Operator 内でカスタム Ansible ロジックをローカルでテストした後に、OpenShift Container Platform クラスターの Pod 内で Operator をテストすることができます。これは実稼働環境での使用が推奨されます。
Operator プロジェクトは、クラスター上でのデプロイメントとして実行することができます。
手順
以下の
make
コマンドを実行して Operator イメージをビルドし、プッシュします。以下の手順のIMG
引数を変更して、アクセス可能なリポジトリーを参照します。Quay.io などのリポジトリーサイトにコンテナーを保存するためのアカウントを取得できます。イメージをビルドします。
$ make docker-build IMG=<registry>/<user>/<image_name>:<tag>
注記Operator の SDK によって生成される Dockerfile は、
go build
についてGOARCH=amd64
を明示的に参照します。これは、AMD64 アーキテクチャー以外の場合はGOARCH=$TARGETARCH
に修正できます。Docker は、-platform
で指定された値に環境変数を自動的に設定します。Buildah では、そのために-build-arg
を使用する必要があります。詳細は、Multiple Architectures を参照してください。イメージをリポジトリーにプッシュします。
$ make docker-push IMG=<registry>/<user>/<image_name>:<tag>
注記両方のコマンドのイメージの名前とタグ (例:
IMG=<registry>/<user>/<image_name>:<tag>
) を Makefile に設定することもできます。IMG ?= controller:latest
の値を変更して、デフォルトのイメージ名を設定します。
以下のコマンドを実行して Operator をデプロイします。
$ make deploy IMG=<registry>/<user>/<image_name>:<tag>
デフォルトで、このコマンドは
<project_name>-system
の形式で Operator プロジェクトの名前で namespace を作成し、デプロイメントに使用します。このコマンドは、config/rbac
から RBAC マニフェストもインストールします。Operator が実行されていることを確認します。
$ oc get deployment -n <project_name>-system
出力例
NAME READY UP-TO-DATE AVAILABLE AGE <project_name>-controller-manager 1/1 1 1 8m
5.5.6.4. Ansible ログ
Ansible ベースの Operator は、Ansible の実行に関するログを提供します。これは、Ansible タスクのデバッグに役立ちます。ログには、Operator の内部および Kubernetes との対話に関する詳細情報を含めることもできます。
5.5.6.4.1. Ansible ログの表示
前提条件
- Ansible ベースの Operator が、デプロイメントとしてクラスター上で実行されている。
手順
Ansible ベースの Operator からログを表示するには、以下のコマンドを実行します。
$ oc logs deployment/<project_name>-controller-manager \ -c manager \1 -n <namespace> 2
出力例
{"level":"info","ts":1612732105.0579333,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.10.1","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"} {"level":"info","ts":1612732105.0587437,"logger":"cmd","msg":"WATCH_NAMESPACE environment variable not set. Watching all namespaces.","Namespace":""} I0207 21:08:26.110949 7 request.go:645] Throttling request took 1.035521578s, request: GET:https://172.30.0.1:443/apis/flowcontrol.apiserver.k8s.io/v1alpha1?timeout=32s {"level":"info","ts":1612732107.768025,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":"127.0.0.1:8080"} {"level":"info","ts":1612732107.768796,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2} {"level":"info","ts":1612732107.7688773,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false} {"level":"info","ts":1612732107.7688901,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"} {"level":"info","ts":1612732107.770032,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"} I0207 21:08:27.770185 7 leaderelection.go:243] attempting to acquire leader lease memcached-operator-system/memcached-operator... {"level":"info","ts":1612732107.770202,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"} I0207 21:08:27.784854 7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator {"level":"info","ts":1612732107.7850506,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"} {"level":"info","ts":1612732107.8853772,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"} {"level":"info","ts":1612732107.8854098,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4}
5.5.6.4.2. ログでの Ansible のすべての結果の有効化
環境変数 ANSIBLE_DEBUG_LOGS
を True
に設定すると、Ansible のすべての結果をログで確認できるようになります。これはデバッグの際に役立ちます。
手順
config/manager/manager.yaml
ファイルおよびconfig/default/manager_auth_proxy_patch.yaml
ファイルを編集し、以下の設定を追加します。containers: - name: manager env: - name: ANSIBLE_DEBUG_LOGS value: "True"
5.5.6.4.3. ログでの詳細デバッグの有効化
Ansible ベースの Operator の開発中は、ログでの追加のデバッグの有効化が役立つ場合があります。
手順
ansible.sdk.operatorframework.io/verbosity
アノテーションをカスタムリソースに追加して、必要な詳細レベルを有効にします。以下に例を示します。apiVersion: "cache.example.com/v1alpha1" kind: "Memcached" metadata: name: "example-memcached" annotations: "ansible.sdk.operatorframework.io/verbosity": "4" spec: size: 4
5.5.7. カスタムリソースのステータス管理
5.5.7.1. Ansible ベースの Operator でのカスタムリソースのステータスについて
Ansible ベースの Operator は、以前の Ansible 実行に関する一般的な情報を使用して、カスタムリソース (CR) ステータス
サブリソース を自動的に更新します。これには、以下のように成功したタスクおよび失敗したタスクの数と関連するエラーメッセージが含まれます。
status: conditions: - ansibleResult: changed: 3 completion: 2018-12-03T13:45:57.13329 failures: 1 ok: 6 skipped: 0 lastTransitionTime: 2018-12-03T13:45:57Z message: 'Status code was -1 and not [200]: Request failed: <urlopen error [Errno 113] No route to host>' reason: Failed status: "True" type: Failure - lastTransitionTime: 2018-12-03T13:46:13Z message: Running reconciliation reason: Running status: "True" type: Running
さらに Ansible ベースの Operator は、Operator の作成者が operator_sdk.util
コレクション に含まれる k8s_status
Ansible モジュールでカスタムのステータス値を指定できるようにします。これにより、作成者は必要に応じ、任意のキー/値のペアを使って Ansible から status
を更新できます。
デフォルトでは、Ansible ベースの Operator には、上記のように常に汎用的な Ansible 実行出力が含まれます。アプリケーションのステータスが Ansible 出力で更新 されない ようにする必要がある場合は、アプリケーションからステータスを手動で追跡することができます。
5.5.7.2. カスタムリソースステータスの手動による追跡
operator_sdk.util
コレクションを使用して Ansible ベースの Operator を変更し、アプリケーションからカスタムリソース (CR) ステータスを手動で追跡できます。
前提条件
- Operator SDK を使用して Ansible ベースの Operator プロジェクトが作成済みである。
手順
manageStatus
フィールドをfalse
に設定してwatches.yaml
ファイルを更新します。- version: v1 group: api.example.com kind: <kind> role: <role> manageStatus: false
operator_sdk.util.k8s_status
Ansible モジュールを使用して、サブリソースを更新します。たとえば、キーtest
および値data
を使用して更新するには、operator_sdk.util
を以下のように使用することができます。- operator_sdk.util.k8s_status: api_version: app.example.com/v1 kind: <kind> name: "{{ ansible_operator_meta.name }}" namespace: "{{ ansible_operator_meta.namespace }}" status: test: data
スキャフォールディングされた Ansible ベースの Operator に含まれるロールの
meta/main.yml
ファイルで、コレクションを宣言することができます。collections: - operator_sdk.util
ロールのメタでコレクションを宣言すると、
k8s_status
モジュールを直接起動することができます。k8s_status: ... status: key1: value1