はじめに
0.13.0 までの AWX Operator は、Kubernetes の クラスタスコープ で動作していました。default ネームスペースに AWX Operator がただ一つ存在していて、同じクラスタ内であればネームスペースを問わず AWX リソースを管理できる状態です。AWX Operator の 0.14.0 では、これが ネームスペーススコープ に変更されています。すなわち、AWX Operator 自身が存在しているネームスペース内でしか AWX リソースを管理できません。
また、AWX Operator のデプロイ方法も、GitHub 上のマニフェストファイルを kubectl apply する従来の方法から、0.14.0 では make を使った方法に変更 されています。
従来、AWX Operator をアップグレードしたい場合（すなわち AWX をアップグレードしたい場合）、AWX リソースのパラメータに互換性がある範囲であれば、単に新しいバージョンのマニフェストファイルを kubectl apply すれば充分でした。しかしながら、前述の変更を踏まると、0.13.0 以前から 0.14.0 以降へアップグレードする際は、不要なリソースの削除など少しだけ追加の手順が必要です。
前提とする環境
本エントリでは、過去の別エントリ “AWX を AWX Operator でシングルノード K3s にホストする” で紹介している環境を踏まえて、アップグレード前後のバージョンとそれぞれのリソースが動作するネームスペースは、次の状態を前提としています。
| 状態 | AWX Operator | AWX 本体 |
| アップグレード前 | 0.13.0 @ default | 19.3.0 @ awx |
| アップグレード後 | 0.14.0 @ awx | 19.4.0 @ awx |
アップグレード前は、AWX Operator は default ネームスペースで動作していますが、AWX 本体は awx ネームスペースで動作しています。ここから、アップグレード後にはすべてが awx ネームスペースで動作している状態を目指します。
手順
大まかには、次の手順で行います。
- バックアップの取得
- 古い AWX Operator の削除
- 古い AWX 本体の削除（任意）
- 新しい AWX Operator のデプロイ
- 完了の待機
AWX Operator の公式のドキュメントでは、現時点では細かな手順は紹介されていませんが、README.md では少しだけ触れられている ので、そちらも参考にできます。また、本エントリとほぼ同じ内容を ぼくのリポジトリ にも置いています。
バックアップの取得
何はともあれ、失敗しても大丈夫なように、AWX 本体のバックアップを取得します。以前のエントリ “AWX Operator による AWX のバックアップとリストア” で紹介しています。
古い AWX Operator の削除
AWX Operator を awx ネームスペースにデプロイする前に、default ネームスペースから削除します。また、AWX Operator の動作するスコープが変わったため、これまでの AWX Operator が利用していたクラスタロールなどが不要になります。併せて削除します。
kubectl delete deployment awx-operator
kubectl delete serviceaccount awx-operator
kubectl delete clusterrolebinding awx-operator
kubectl delete clusterrole awx-operator
削除したのは AWX Operator だけで、AWX リソースの CRD は削除していないので、この段階ではまだ AWX リソース awx は（awx ネームスペースで）動作しています。
古い AWX 本体の削除（任意）
後続の手順で新しい AWX Operator をデプロイすると、AWX Operator によって AWX 本体を司るデプロイメントリソースでロールアウトが行われます。この過程では、新しい AWX の Pod ができてから古い AWX の Pod が削除されるため、CPU とメモリの リクエスト値が一時的に Pod ふたつ分消費 されます。
このため、Kubernetes クラスタのノードに充分な空きリソースがない場合は、新しい AWX の Pod のスケジュールができずにアップグレードが失敗します。あらかじめ古い AWX 本体を削除しておけば、ロールアウトの過程で確保すべきリクエスト値を Pod ひとつ分に抑制できます。ただし、ロールアウトの履歴は失われます。
kubectl -n awx delete deployment awx
なお、クラスタに充分な空きリソースがある場合 は、この手順は不要 です。
新しい AWX Operator のデプロイ
あとは、新しい AWX Operator をデプロイするだけです。0.14.0 以降の新しいデプロイ手順 に則って、make deploy します。環境変数 NAMWESPACE には、AWX 本体が動作している（いた）ネームスペース名を与えます。
# リポジトリのクローンと特定のバージョンのチェックアウト
git clone https://github.com/ansible/awx-operator.git
cd awx-operator
git checkout 0.14.0
# AWX Operator が動作する名前空間の指定とデプロイ
export NAMESPACE=awx
make deploy
これにより、awx ネームスペースに AWX Operator がデプロイされます。必要なロールやサービスアカウントも作成され、CRD も併せて更新されます。
完了の待機
AWX Operator が動作を開始すると、新しい CRD と既存の AWX リソースのパラメータを基に、デプロイメントのロールアウトが自動でトリガされます。これにより、AWX 本体が新しいバージョンにアップグレードされます。
あとは待つだけです。進捗はログで確認できます。
$ kubectl -n awx logs -f deployments/awx-operator-controller-manager -c manager
...
----- Ansible Task Status Event StdOut (awx.ansible.com/v1beta1, Kind=AWX, awx/awx) -----
PLAY RECAP *********************************************************************
localhost : ok=56 changed=0 unreachable=0 failed=0 skipped=35 rescued=0 ignored=0
----------
完了すると、AWX Operator と AWX 本体の両方のすべてが awx ネームスペースで動作している状態になります。
$ kubectl -n awx get awx,all,ingress,secrets
NAME AGE
awx.awx.ansible.com/awx 13m
NAME READY STATUS RESTARTS AGE
pod/awx-postgres-0 1/1 Running 0 13m
pod/awx-operator-controller-manager-68d787cfbd-59wr8 2/2 Running 0 3m42s
pod/awx-84d5c45999-xdspl 4/4 Running 0 3m23s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/awx-operator-controller-manager-metrics-service ClusterIP 10.43.81.63 <none> 8443/TCP 3m42s
service/awx-postgres ClusterIP None <none> 5432/TCP 13m
service/awx-service ClusterIP 10.43.248.150 <none> 80/TCP 13m
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/awx-operator-controller-manager 1/1 1 1 3m42s
deployment.apps/awx 1/1 1 1 3m23s
NAME DESIRED CURRENT READY AGE
replicaset.apps/awx-operator-controller-manager-68d787cfbd 1 1 1 3m42s
replicaset.apps/awx-84d5c45999 1 1 1 3m23s
NAME READY AGE
statefulset.apps/awx-postgres 1/1 13m
NAME CLASS HOSTS ADDRESS PORTS AGE
ingress.networking.k8s.io/awx-ingress <none> awx.example.com 192.168.0.100 80, 443 13m
NAME TYPE DATA AGE
secret/default-token-gq4k7 kubernetes.io/service-account-token 3 13m
secret/awx-admin-password Opaque 1 13m
secret/awx-broadcast-websocket Opaque 1 13m
secret/awx-secret-tls kubernetes.io/tls 2 13m
secret/awx-postgres-configuration Opaque 6 13m
secret/awx-secret-key Opaque 1 13m
secret/awx-token-vpc22 kubernetes.io/service-account-token 3 13m
secret/awx-operator-controller-manager-token-6m4k9 kubernetes.io/service-account-token 3 3m42s
secret/awx-app-credentials Opaque 3 13m
補足
アップグレードとはあまり関係ない部分での補足です。
- AWX の
19.3.0（AWX Operator0.13.0に対応）には、LDAP の認証が正常に動作しないバグ（ansible/awx#10883）がありました。このバグは19.4.0（AWX Operator0.14.0）で修正されています（19.2.2以前にはこのバグは含まれません）。 - AWX の
19.2.2（AWX Operator0.12.0）までは、デフォルトで利用される Execution Environment のイメージはバージョンが指定（quay.io/ansible/awx-ee:0.5.0など）されていましたが、19.3.0以降では同イメージのlatestタグに変更されています。そのまま使うと、Ansible や Collections など中身のバージョンがある日突然変わる事態に遭遇しうるため、バージョンを指定したものか自前の EE に置き換える方が安心して使えそうです。
おわりに
AWX Operator の 0.14.0 以降へのアップグレード手順を取り扱いました。
根本的には AWX Operator は、バージョンが 0.x.x であることからも（セマンティックバージョニング的な意味で）伺える通り、まだまだ開発中で、今後も大幅な変更が入ることは充分に考えられます。この意味では、商用環境で本気で使いたい際は Ansible Automation Controller（旧 Ansible Tower）を選ぶ方が安心感はあるかもしれないですね。
dear sir,
i’m a new learner of awx,could you let me know how to create a manual source type ‘project_data_dir=/var/lib/awx/projects’ based on your git project , thank you for sharing
Thanks for leaving comment 🙂
If you’ve followed my guide, your `/data/projects` on your K3s host is mounted as `/var/lib/awx/projects` in AWX’s container.
So the answer is pretty simple; just create your own project directory under your `/data/projects` on your K3s host e.g. `/data/projects/manual-project` and place your playbook in the directory. Then your `manual-project` is ready to be detected on the “Create New Project” screen on your AWX.