Operator のプロジェクトを最新にアップグレードする方法

https://groups.google.com/g/operator-framework/c/kVG1MqaNG6c に投稿された、Operator SDK/Kubebuilder の統合に伴うって、自分のOperator プロジェクトを最新のバージョンにしておく方法のドキュメントを日本語化と若干の追記をしたものです。

Transcript

1. Operator のプロジェクトを 最新にアップグレードする方法 1 日本語訳版: as of 2021/03/31
2. 日本語訳版のおことわり • この資料は以下Operator Framework コミュニティのメーリングリストに投稿された資料の簡易 日本語訳です(as of 2021/03/31) ◦ https://groups.google.com/g/operator-framework/c/kVG1MqaNG6c ◦ 資料はRed Hatのメンバーが作成したものですが、クレジットとしてレッドハットのロゴなどは入っていません ので、Operator Frameworkコミュニティでの活動として捉えてください ◦ 最新でない可能性があるので常にオリジナルおよび資料内で参照されているリンク先も確認してください ◦ 理解の助けのために、日本語版で若干のスライド追加を行っています(明示しています) • この日本語訳はTakahiro Hashimoto<thashimo@redhat.com>がやりました。日本語の内容の 質問があってもオリジナルの作者に連絡しないようにご注意ください。 • 技術的な内容はの質問は、積極的にぜひ Openな場所(Slackチャンネルやメーリングリストで、こ の資料にも記載があります )などでのコミュニケーションにチャレンジしていただけると嬉しいです
3. このドキュメントの対象 Operator SDKかKubebuilderを使ってOperatorを開発している人に向けて、以下の情報 を提供します • なぜ最新のOperator SDK[1](1.5以降) または Kubebuilder[2](v3.0.0以降、v3.0.0 の安定リリースが直近に予定 )に更新すべきかとその方法 • 自分のOperatorプロジェクトを簡単にアップデートとメンテナンスできるようにしてお く方法 • 変更点と便利な支援ツールの理解 • Kubernetes コミュニティによって提案されたレイアウトの理解 • 最新のOperator SDKの便利な機能 使用したリンク: [1] - https://github.com/operator-framework/operator-sdk [2] - https://github.com/kubernetes-sigs/kubebuilder
4. なぜ Operator SDK 1.0 から新しいレイアウトを採用したのですか Operator SDK は Kubebuilder と統合されました。どちらのプロジェクトも Operator Framework と Kubernetes コミュニティが推進する同じベースレイアウトを生成します 詳細はこちら[1] Operator SDK を使ったプロジェクトで Kubebuilder のドキュメントは利用できますか はい、こちら https://book.kubebuilder.io/ をごらんください その時はこんな風に インストラクションを読んでください : $ kubebuilder <command> を $ operator-sdk <command> に置きかえる 使用したリンク: [1] - https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/integrating-kubebuilder-and-osdk.md
5. Operator SDKとKubebuilderの違い Operator SDK は Kubebuilder が提供する基本的な project scaffold に下記の追加機能を提供し ます • プロジェクトをOLM(Operator Lifecycle Manager)と統合するためのヘルパー ◦ 例. operator bundle をビルド、アップグレード、テストするためのヘルパー • カスタムテストを作成できるようにするための Scorecard • その他 その他の Kubebuilder to Operator SDK の関連性についてはこちらの ブログ記事[1]を参照してく ださい 使用したリンク: [1] - https://www.openshift.com/blog/operator-sdk-reaches-v1.0?extIdCarryOver=true&sc_cid=701f2000001Css5AAC
6. なぜ私のプロジェクトをアップグレードしないといけないのでしょうか • 現在と将来に提供されるヘルパーや機能を使えるようにする • webhooks を利用できるようにする • Scorecard によるカスタムテストを作成、利用できるようにする • 廃止された package manifest を取り除き、新しい Bundle format の利用の開始する • コミュニティに支援されているレイアウトを採用し以下のメリットを享受する ◦ コミュニティにとって貢献をより容易にする ◦ メンテナンス性の向上 • 自分の Operator プロジェクトにある技術負債と依存関係のアップグレードに関する問題を解決する • 自分のプロジェクトがテストされ、推奨された特定のバージョンを利用することを保証する • CRDとWebhook(使用していれば)で使われているAPIをマイグレーションする(下記参照) CRD: apiextensions/v1beta1 Webhook: admissionregistration.k8s.io/v1beta1 の2つは Kubernetes 1.16で deprecated, 1.22 で削除される予定です それぞれ新しいAPI version (v1) を使用する必要があります
7. Operator SDK v0.19 以前からのレイアウト変更点 deploy ディレクトリが was config ディレク トリに置き換えられました: • deploy/crds/ にあった CRD manifest は config/crd/bases へ • deploy/crds/ にあった CR manifest は config/samples へ • Controller manifest deploy/operator.yaml は config/manager/manager.yaml に 変更 • deploy にあった RBAC manifests は config/rbac/ へ deploy/olm-catalog/ は bundle/ に 置き換えられました 例:deploy/olm-catalog/<name>-ope rator/manifests/ は bundle/manifests となります cmd/manager/main.go はroot ディレクトリに移動 pkg/apis と pkg/controllers はルー トディレクトリに置かれます. build/Dockerfile はルートデレクトリに移動 しました
8. /argocd-operator ├── 0.0.12 │ ├── Dockerfile │ ├── manifests │ │ ├── argocd-operator.v.0.0.12.clusterserviceversion.yaml │ │ ├── argoproj.io_applications_crd.yaml │ │ ├── argoproj.io_appprojects_crd.yaml │ │ ├── argoproj.io_argocdexports_crd.yaml │ │ └── argoproj.io_argocds_crd.yaml │ └── metadata │ ├── annotations.yaml │ └── dependencies.yaml └── 0.0.11 ├── Dockerfile ├── manifests │ ├── argocd-operator.v.0.0.11.clusterserviceversion.yaml │ ├── argoproj.io_applications_crd.yaml │ ├── argoproj.io_appprojects_crd.yaml │ ├── argoproj.io_argocdexports_crd.yaml │ └── argoproj.io_argocds_crd.yaml └── metadata ├── annotations.yaml └── dependencies.yaml /argocd-operator ├── 0.0.12 │ ├── argocd-operator.v.0.0.12.clusterserviceversion.yaml │ ├── argoproj.io_applications_crd.yaml │ ├── argoproj.io_appprojects_crd.yaml │ ├── argoproj.io_argocdexports_crd.yaml │ └── argoproj.io_argocds_crd.yaml ├── 0.0.11 │ ├── argocd-operator.v.0.0.11.clusterserviceversion.yaml │ ├── argoproj.io_applications_crd.yaml │ ├── argoproj.io_appprojects_crd.yaml │ ├── argoproj.io_argocdexports_crd.yaml │ └── argoproj.io_argocds_crd.yaml ├── 0.0.9 ├── 0.0.8 ├── … └── argocd-operator.package.yaml Package Manifest Format Bundle Format Legacy Format New Format Bundle Formatは、「manifests」「metadata」ディレクトリで構成 され、Bundle拡張が容易になっている Operator SDK 1.0 以降でのManifest構成の変更(metadataの追加) 使用したリンク: [1] - https://github.com/operator-framework/community-operators/tree/master/upstream-community-operators/argocd-operator ArgoCD operator[1] を仮にBundle Formatに変更した場合の例 日本語版追加スライド
9. SDK のツールで生成されたプロジェクトをカスタマイズできますか CLI でプロジェクトを作成した後は、それを元にして自分の最適な形に変更すること ができますが、自分が何をやっているかよくわからない場合、提案されているレイア ウトから外れることは推奨しません 例えば、scaffold として用意されたファイルを移動させるのは控えるべきです。そう してしまうと、将来あなたのプロジェクトをアップグレードするのが難しくなってしまう からです。また CLIの持つ機能やヘルパーなどが動作しなくなるでしょう。プロジェク トレイアウトに関する詳細な情報はこちら[1] のドキュメントに記載があります 使用したリンク: [1] - https://master.sdk.operatorframework.io/docs/overview/project-layout/
10. マイグレーション処理の動作: レガシーレイアウト(1.0未満)から最新(1.5以上) アップグレードのための最も簡単な方法は、プロジェクトと APIをre-scaffoldすることです。単 純にあなたの書いたコードを新しいレイアウトのプロジェクトにコピーするだけです 今後SDK における破壊的な変更はバージョン 2.0のリリースまで発生しません。そしてこの やり方は将来はより簡単になっていくでしょう。
11. 技術的には可能です。しかし困難な方法でエラーを誘発しがちですしお勧めしません レガシーレイアウトと最新のバージョン (1.5以降)ではとても多くの変更点があり、手作業で 追従するのは大変な作業になります。また、 CLIやその現在および将来のオプションが想定 どおりに稼動するために、それぞれのリソースや変更点のすべての必要なデータを保存す るPROJECTファイルを更新する必要があります。 最もわかりやすい方法は、新しい scaffoldを作成して、そこに自分の実装やカスタマイズした ものを配置しなおすことです。これを一度行えば、今後の SDKの機能追加やバグフィックス の際に、マイグレーションガイド [1] に記載のステップに従ってアップグレードできるようになり ます プロジェクト再作成とre-scaffolding なしに手作業で 最新レイアウトへ変更できますか 使用したリンク: [1] - https://master.sdk.operatorframework.io/docs/upgrading-sdk-version/
12. 実際どのようにアップデートをしたらよいですか このステップ[1]を参考にしてください。これは Memcached sample operator[2] を0。19から 最新のバージョンへマイグレーションする例となっています。通常これに倣えば、それより旧 バージョン(0.15.x, 0.16.x, 0.17.x, 0.18.x) で作成されたoperatorであっても、同じようにプロ ジェクトを最新バージョンにアップデートできます。 Operator SDK のコマンドおよびヘルパーのチートシート[3]に もう少し詳しい情報があるので確認してください 使用したリンク: [1] - https://master.sdk.operatorframework.io/docs/building-operators/golang/migration/ [2] - https://github.com/operator-framework/operator-sdk-samples/tree/v0.19.2/go/memcached-operator [3] - https://master.sdk.operatorframework.io/docs/overview/cheat-sheet/
13. マイグレーションでどんな問題が発生する可能性があり 発生したらどのように解決すればよいですか もしかするとこのステップでカバーできていない問題が発生するかもしれません。例えば、破 壊的な変更が存在するとても古いバージョンの controller-runtime[1] を使用している場合、 プロジェクトのビルド時にエラーが発生するでしょう。問題を解決するためには、マイグレー ションガイド(現 在のバージョンから 0.19まで。0.13を使っていれば0.13から0.19までのすべ てのガイド)に記載されているエラーコードを出力しているコードを探しましょう。おそらく "CodeXをCodeYで置き換える" といったような解決策を見つけることができます。 また、いつでもSlack(https://kubernetes.slack.com)のチャンネル(#operator-sdk-dev, #kubebuilder) で相談することができますし、 operator framework のリポジトリのissueとメー リングリスト <operator-framework@googlegroups.com> で問題を追うこともでます 使用したリンク: [1] - https://github.com/kubernetes-sigs/controller-runtime [2] - https://master.sdk.operatorframework.io/docs/upgrading-sdk-version/
14. 私のOperatorはnamespace内でのみ権限を要求します。 マイグレーションの後どのように変更したらよいでしょうか OperatorSDKがKubebuilderと統合される前は、すべてのプロジェクトは namespace内での み有効(namespace-scoped)なパーミッションつきで作成されていました。現在はすべての プロジェクトは cluster scope なパーミッション(cluster-scoped) で作成されるのがデフォルト の動作となります。しかしもちろんこれは変更可能です。詳細は こちら[1]を確認してください ポイント: • RBAC manifestは: config/rbac ディレクトリにあります • "Updating your Service Account"[2] のステップを必ず確認してください • Operator SDK 1.6.0以降のリリースで、AnsibleとHelm ベースのOperatorもそれぞ れ独自のService Accountを持つようになります : 詳細: #4653 使用したリンク: [1] - https://sdk.operatorframework.io/docs/building-operators/golang/operator-scope/ [2] - https://master.sdk.operatorframework.io/docs/building-operators/golang/migration/#updating-your-serviceaccount [3] - https://github.com/operator-framework/operator-sdk/pull/4653
15. 私は Helm/Ansible を使っており、Go を使っていません 手 順は同じような感じです。 Helmのガイド[1]およびAnsibleのガイド[2]を確 認してください。 AnsibleでもHelmでも基 本は同じレイアウトに従いますが、それぞれの選 択に合うように scaffold が準備されます 使用したリンク: [1] - https://master.sdk.operatorframework.io/docs/building-operators/helm/migration/ [2] -https://master.sdk.operatorframework.io/docs/building-operators/ansible/migration/
16. 私はKubebuilderを使用しており、Operator SDKを使用したくありません。私も自分のプロ ジェクトをマイグレーションすることについて気にする必要がありますか はい、必要です。Kubebuilderもまた変更されました。そして同様の理由によりあ なたのプロジェクトをアップグレードすることを推奨します。最新のKubebuilder CLI(3.0.0以降) をインストールし、同じようなステップでv1またはv2のプロジェクトを v3にアップデートする必要があるでしょう 何を行えばよいかについての詳細な情報はこちら[1]を参照してください Note: Kubebuilder 3.0.0 の安定版はまもなくリリース予定です もしKubebuilderを使用していて、OLMをサポートしたいとお考えであれば、 Operator SDKにスイッチすることを検討するのがよいです 使用したリンク: [1] - https://master.book.kubebuilder.io/migration/migration_guide_v2tov3.html
17. Operator Lifecycle Manager(OLM) について知りたくなりました 使用したリンク: [1] - https://speakerdeck.com/shkitayama/operatorlifecyclemanager-101 [2] - https://olm.operatorframework.io/docs/ [3] - https://docs.openshift.com/container-platform/4.7/operators/understanding/olm/olm-understanding-olm.html Operator Lifecycle Managerについて日本語で説明した資料 [1]が公開されていますので、 理解の助けになるかと思います。また OLM公式のドキュメント[2]と、OpenShift のドキュメン ト[3]にもOLMについての言及がありますので、こちらも理解の助けになると思います 日本語版追加スライド