search

hashnao / gitops-practice

Install operators via OpenShift GitOps Operator
0 stars 0 forks source link

readme

:toc: auto :imagesdir: images

= Onboarding

GitOps Operator を用いて以下のタスクを実施します。

NOTE: 環境に応じて変数を代入するため Helm Charts (values.yaml) を用います。

NOTE: 一つの ApplicationSet CR を作成して <<Namespace & Group>> と <> を一度に実施する想定ではなく、まず <<Namespace & Group>> を実行する ApplicationSet CR を作成して Namespace やグループの作成が完了した後に <> を実行する ApplicationSet CR を作成し、Camel-K Operator をインストールします。

== Prerequisites

NOTE: この時点では Camel K Operator をインストールしていないため、該当する Cluster Role も作成されておらず、Warning: role 'integrationplatforms.camel.apache.org-v1-edit' not found と出力されますが、そのまま進めます。

== Namespace & Group

. ApplicationSet CR を作成する +

oc apply -f ./applicationsets/namespace/applicationset.yaml

NOTE: サンプルの tenant-projects/namespace/values.yaml を Main ブランチに配置しているため ApplicationSet CR を作成すると Application CR が生成され、Namespace などを作成する Helm Charts が実行されます。 そのためこの時点で camelk-test0{,1} Namespace が作成されます。

. Branch を作成する +

export BRANCH=my-team git branch ${BRANCH} git checkout ${BRANCH}

. サンプルから values.yaml を作成し必要な値を定義する +

cp -r tenant-projects/namespace/sample tenant-projects/namespace/${BRANCH} vim tenant-projects/namespace/${BRANCH}/values.yaml

NOTE: Namespace, グループ名、ユーザ名を変更します。 + .https://github.com/hashnao/gitops-practice/blob/main/tenant-projects/namespace/sample/values.yaml[tenant-projects/namespace/sample/values.yaml]

include::tenant-projects/namespace/sample/values.yaml[]

. 変更をコミットし、Remote にプッシュする +

git add tenant-projects/${BRANCH} git commit tenant-projects/${BRANCH} git push -u origin ${BRANCH}

. GitHub (https://github.com) で PR を作成し、マージする + NOTE: エラーなどでマージした設定を修正する場合はローカルで変更をコミットし、Remote にプッシュした後、GitHub で PR をマージします。 ArgoCD は Git Repository (GitHub) にデフォルトで 3 分毎にポーリングし変更の有無をチェックします。 これは Argo CD の環境変数 https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/#automated-sync-semantics[ARGOCD_RECONCILIATION_TIMEOUT] に基づきます。 ROSA (OCP) も同様です、詳細は https://access.redhat.com/solutions/7012592[Configure applications sync frequency on GitOps / ArgoCD on RHOCP4] を参照下さい。

. Argo CD Web Console の URL を取得し WEB ブラウザからリンクを開く +

oc -n openshift-gitops get route openshift-gitops-server -ojsonpath='{.spec.host}{"\n"}'

.Example Output +

openshift-gitops-server-openshift-gitops.apps.rosa-lfqzn.thtb.p1.openshiftapps.com

NOTE: OpenShift Web Console から Argo CD Web Console を開くこともできます。 + image::rosa_console.png[]

. Argo CD Web Console からアプリケーション (Application CR) の進捗を確認する + image::app_namespace_completed.png[]

. 該当する Application CR の Sync と Health ステータスが正常であることを確認する +

oc -n openshift-gitops get app

.Example Output +

NAME SYNC STATUS HEALTH STATUS namespace-sample Synced Healthy

NOTE: 少なくとも HEALTH STATUS が Healthy であれば Application CR が生成する Namespace やグループが作成されています。

. Namespace (camelk-test0{0,1}) が作成されることを確認する +

oc get project -l argocd.argoproj.io/managed-by=openshift-gitops

.Example Output +

NAME DISPLAY NAME STATUS camelk-test00 Active camelk-test01 Active

. グループ (sample-teams) にユーザ (apple, banana) を追加されることを確認する +

oc get group sample-teams

.Example Output +

NAME USERS sample-teams apple, banana

. グループ (sample-teams) に Namespace (camelk-test0{0,1}) に対する admin 権限が付与されることを確認する +

oc -n camelk-test00 get rolebinding sample-teams -oyaml

.Example Output +

kind: RoleBinding ... namespace: camelk-test00 ... subjects:

== Camel K Operator

. ApplicationSet CR を修正し、ディレクトリや Nexus の認証情報を定義する +

vim applicationsets/camelk/applicationset.yaml

NOTE: ApplicationSet CR は GitHub にプッシュする必要はありません。 以下は diff の結果です、修正する箇所は # がコメントしている箇所が該当します。 +

$ git diff applicationsets/camelk/applicationset.yaml diff --git a/applicationsets/camelk/applicationset.yaml b/applicationsets/camelk/applicationset.yaml index 80df157..d7bc022 100644 --- a/applicationsets/camelk/applicationset.yaml +++ b/applicationsets/camelk/applicationset.yaml @@ -33,12 +33,11 @@ spec:

. ApplicationSet CR を作成する +

oc apply -f ./applicationsets/camelk/applicationset.yaml

NOTE: サンプルの tenant-projects/camelk/sample/values.yaml を Main ブランチに配置しているため ApplicationSet CR を作成すると Application CR が生成され、Camel K Operator をインストールする Helm Charts が実行されます。 そのためこの時点で camelk-test0{,1} Namespace に Camel K Operator がインストールされます。 + image::app_camelk_completed.png[]

. Branch を作成する +

export BRANCH=my-team git branch ${BRANCH} git checkout ${BRANCH}

. サンプルから values.yaml を作成し必要な値を定義する +

cp -r tenant-projects/camelk/sample tenant-projects/camelk/${BRANCH} vim tenant-projects/camelk/${BRANCH}/values.yaml

NOTE: 主に Camel K Operator をインストールする namespace を修正します、設定例は以下のサンプルを参照下さい。 + .https://github.com/hashnao/gitops-practice/blob/main/tenant-projects/camelk/sample[tenant-projects/camelk/sample/values.yaml]

include::tenant-projects/camelk/sample/values.yaml[]

. 変更をコミットし、Remote にプッシュする +

git add tenant-projects/${BRANCH} git commit tenant-projects/${BRANCH} git push -u origin ${BRANCH}

. GitHub で PR を作成し、マージする + NOTE: PR をマージすると Argo CD が差分 (追加した values.yaml) を検出し、values.yaml に定義した Namespace に Camel K Operator をインストールします。

. Argo CD Web Console からアプリケーション (Application CR) の進捗を確認する + NOTE: Operator のインストールに要する時間は Namespace の作成するケースとは異なり数分かかるため、全体の相関や進捗を確認するには Web Console の方が便利です。 Application CR のステータスは <> の手順で示している様に OpenShift CLI (oc get/describe app) からも確認することができますが、作成される API リソースの相関は表示されません。 以下は正常に完了した際の画像です。 + image::app_camelk_completed.png[]

正常に完了しない際は <> の手順に従い調査します。

== AMQ Streams Operator

. Secret を作成し、Oracle DB に接続させるためのユーザ名とパスワードを定義する +

export NAMESPACE=camelk-test00 oc -n ${NAMESPACE} create secret generic oracle-credentials --from-literal=username= --from-literal=password=

NOTE: ${NAMESPACE} に Debezium をデプロイする Namespace を指定します。 複数の Namespace に Debezium をデプロイする際は Namespace 毎に Secret を作成します。 この Secret は https://github.com/hashnao/gitops-practice/blob/main/clusters/helper-operator/templates/jobs/kafkaconnector.yaml [KafkaConnect CR] spec.config フィールドの database.user と database.password が参照します。

. ApplicationSet CR を作成する +

oc apply -f ./applicationsets/amqs/applicationset.yaml

NOTE: サンプルの [tenant-projects/amqs/sample/values.yaml] を Main ブランチに配置しているため ApplicationSet CR を作成すると Application CR が生成され、AMQ Streams Operator をインストールする Helm Charts が実行され、camelk-test0{,1} Namespace に AMQ Streams Operator がインストールされます。 サンプルで利用する applicationset.yaml の概要は <<ApplicationSet (AMQ Streams Operator)>> を参照下さい。 以下は検証を目的に camelk-test00 Namespace だけを対象とした実行結果です。 + image::app_amqs_completed.png[] NOTE: Kafka Cluster への認証はパスワード認証をベースとした https://access.redhat.com/documentation/en-us/red_hat_amq_streams/2.5/html-single/deploying_and_managing_amq_streams_on_openshift/index#scram_sha_512_authentication[SCRAM-SHA-512 authentication] を利用します。 KafakUser CR を作成すると以下の Kafaka User とデフォルトで自動生成されたパスワードを含む Secret が作成されます。 Secret の命名規則は Prefix に kafkauser- がセットされ、その後ろに KafakUser CR の metadata.name フィールド (i.e. user-information) が付与されます。 https://github.com/hashnao/gitops-practice/blob/main/clusters/helper-operator/templates/jobs/kafkaconnect.yaml[KafkaConnect CR] は認証にこのユーザ名と Secret 名をデフォルトで利用する様に設定しており、spec.authentication フィールドが該当します。 +

$ oc get -n camelk-test00 secret kafkauser-user-information NAME TYPE DATA AGE kafkauser-user-information Opaque 2 20h $ oc get -n camelk-test00 kafkauser user-information NAME CLUSTER AUTHENTICATION AUTHORIZATION READY user-information api-infra scram-sha-512 simple True

. Branch を作成する +

export BRANCH=my-team git branch ${BRANCH} git checkout ${BRANCH}

. サンプルから values.yaml を作成し必要な値を定義する +

cp -r tenant-projects/amqs/sample tenant-projects/amqs/${BRANCH} vim tenant-projects/amqs/${BRANCH}/values.yaml

NOTE: 主に AMQ Streams Operator をインストールする namespace を修正します、設定例は以下のサンプルを参照下さい。 + .https://github.com/hashnao/gitops-practice/blob/main/tenant-projects/amqs/sample[tenant-projects/amqs/sample/values.yaml]

include::tenant-projects/amqs/sample/values.yaml[]

. 変更をコミットし、Remote にプッシュする +

git add tenant-projects/${BRANCH} git commit tenant-projects/${BRANCH} git push -u origin ${BRANCH}

. GitHub で PR を作成し、マージする + NOTE: PR をマージすると Argo CD が差分 (追加した values.yaml) を検出し、values.yaml に定義した Namespace に AMQ Streams Operator をインストールします。

. Argo CD Web Console からアプリケーション (Application CR) の進捗を確認する

== Troubleshooting

=== Out Of Sync

HEALTH STATUS は正常 (Healthy) ですが SYNC STATUS が異常 (OutOfSync) となり、Argo CD と Git Repository との間で Out Of Sync により同期に失敗しているケースです。

. Application CR のステータスを確認する +

$ oc -n openshift-gitops get app

NOTE: ApplicationSet CR を作成すると ApplicationSet CR が自動で Application CR を生成します。 自動で生成される Application CR 名はユーザの values.yaml を配置する tenant-projects/camelk/sample のディレクトリ名から生成しています。 + .Example Output

NAME SYNC STATUS HEALTH STATUS camelk-sample-01 OutOfSync Healthy

. Application CR の詳細を確認する +

oc -n openshift-gitops describe app camelk-sample-01

NOTE: 以下は頻繁には起きませんが、Argo CD の Service Account が権限が不足しており IntegrationPlatform CR を修正できないケースです。 Service Account (system:serviceaccount:openshift-gitops:openshift-gitops-argocd-application-controller) は全ての Namespace (cluster-wide) な権限を与えられているわけではないため、権限の問題で作成できない場合に OutOfSync が置きます。 + .Example Output

... Status: Conditions: Last Transition Time: 2023-11-16T04:45:38Z Message: Failed sync attempt to e8ec3aa6e4282a14ce242d15e0564078d3c96065: one or more objects failed to apply, reason: integrationplatforms.camel.apache.org "camel-k" is forbidden: User "system:serviceaccount:openshift-gitops:openshift-gitops-argocd-application-controller" cannot patch resource "integrationplatforms" in API group "camel.apache.org" in the namespace "camelk-test02" Type: SyncError

=== Sync failed

始めて ROSA Cluster に Camelk K Operator をインストールする場合、Argo CD Console を開くと次の様に SYNC STATUS は OutOfSync で APP CONDITIONS は 1 Error が表示されるケースがあります。

image::app_camelk_failed.png[]

以下は CLI の結果で IntegrationPlatform CR を作成しようとするが、Camel K Operator がインストールされていないため、IntegrationPlatform CRD 自体がまだ作成されてないことが原因です。

$ oc describe app camelk-sample ... Status: Last Transition Time: 2023-11-17T06:43:45Z Message: Failed sync attempt to 30a0b737bc75757013cd2e50d7af85dfa359ad73: one or more synchronization tasks are not valid (retried 5 times). Type: SyncError Controller Namespace: openshift-gitops Health: Status: Healthy Operation State: Finished At: 2023-11-17T06:43:45Z Message: one or more synchronization tasks are not valid (retried 5 times). Operation: Initiated By: Automated: true Retry: Limit: 5 Sync: Revision: 30a0b737bc75757013cd2e50d7af85dfa359ad73 Phase: Failed Retry Count: 5 Started At: 2023-11-17T06:38:35Z Sync Result: Resources: Group: camel.apache.org Kind: IntegrationPlatform Message: The Kubernetes API could not find camel.apache.org/IntegrationPlatform for requested resource camelk-test00/camel-k. Make sure the "IntegrationPlatform" CRD is installed on the destination cluster.

この様な場合は同期に失敗して処理が停止し、Application が作成すべき API リソースがまだ作成されていない可能性があるため、まず Camel K Operator がインストールされることを確認します。 OperatorGroup -> Subscription -> ClusterRoleBinding -> IntegrationPlatform -> ConfigMap の順番で SYNC させ、状況を確認します。

. SYNC ボタンをクリックして RETRY と OPERATORGROUP をチェックし、SYNCRONIZE ボタンをクリックする + image::sync_og.png[]

. 同様の手順で残りの リソース を順番に Sync する

== Appendix

=== ApplicationSet (Namespace & Group)

以下は <<Namespace & Group>> のセクションで利用する ApplicationSet CR (applicationsets/namespace/applicationset.yaml) に定義するフィールドを解説します。 <> で利用する ApplicationSet の構造も同じです。 設定を変更する際に参考にして下さい。

(1) ApplicationSet CR を削除すると Application CR が作成した Namespace などの API リソースが削除されます。 https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Controlling-Resource-Modification/#prevent-an-applications-child-resources-from-being-deleted-when-the-parent-application-is-deleted[preserveResourcesOnDeletion] を true に設定することで API リソースを残します。

(2) Namespace やグループ名など環境毎に変数を定義する values.yaml のパスを示します。 https://argocd-applicationset.readthedocs.io/en/stable/Generators-Git/[Git Generator] を利用することで tenant-projects/namespace/my-team/values.yaml の様に新たにディレクトリとファイルを追加して PR をマージすることで Application CR に設定を追加する必要なく values.yaml に定義した設定をもとに Namespace やグループを新たに生成します。

(3) ApplicationSet CR を作成すると ApplicationSet CR が自動で Application CR を生成します。 自動で生成される Application CR 名は tenant-projects/camelk/sample のディレクトリ名から生成しています。

(4) 設定を適用する ROSA Cluster のエンドポイントを示します。 GitOps Operator を ROSA (OCP) Cluster 上にデプロイしているため、https://...:6443/ の様な FQDN でなく Service 名を指定しています。

(5) Argo CD の Application をデプロイする Argo CD 上のプロジェクトを指定します。 Application CR を作成する OpenShift のプロジェクト (Namespace) ではありません。

(6) Helm Chart などを含む Git Repository の URL を指定します。 Cf. https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Template/#template-fields[Template fields]

(7) ターゲットとする Git Repository のブランチを指定します。 この例では Argo CD は main ブランチにマージした設定を対象とします。

(8) ターゲットとする Git Repository のディレクトリを指定します。 path に指定したディレクトリだけを対象とし、再帰的に配下のディレクトリは参照しません。Cf. https://argo-cd.readthedocs.io/en/stable/user-guide/directory/#enabling-recursive-resource-detection[Enabling Recursive Resource Detection]

(9) files で指定したパスの values.yaml をインクルードします。

(10) グローバルに設定する values.yaml のパスを示します。 例えば GitOps Operator をインストールする openshift-gitops Namespace を定義します。

(11) automated を指定することで自動で Git Repository から同期します。指定しない場合は Argo CD Console から手動で Sync する必要があります。 Cf. https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/[Automated Sync Policy]

(12) prune: false を指定するとデフォルトで Argo CD は Git Repository から削除された設定を検出するとリソースを削除しません。 prune: true を指定するとリソースを削除します。Cf. https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/#automatic-pruning[Automatic Pruning]

(13) デフォルトでクラスタに適用した変更は automated sync を実行しません。 selfHeal: true は Argo CD はデプロイされたアプリケーションの状態を常に監視し Git Repository のマニフェストとクラスタのライブの変更の違いを検出し、自動で修正します。 Cf. https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/#automatic-self-healing[Automatic Self-Healing]

.https://github.com/hashnao/gitops-practice/blob/main/applicationsets/namespace/applicationset.yaml[applicationsets/namespace/applicationset.yaml]

apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: onboarding namespace: openshift-gitops spec: goTemplate: true syncPolicy: preserveResourcesOnDeletion: true (1) generators:

NOTE: Namespace を作成するには values.yaml に Namespace を定義して Git Repository にプッシュする必要がありますが、Git Repository にプッシュせずに Namespace を作成する場合は ApplicationSet CR に以下の様に指定します。

spec: template: spec: source: helm: parameters:

=== ApplicationSet (Camel K Operator)

以下は <> のセクションで利用する ApplicationSet CR (applicationsets/camelk/applicationset.yaml) に定義するフィールドを解説します。 主要な差分だけを対象とします。

(1) Nexus Repository Manager のユーザ名を指定する

(2) Nexus Repository Manager のパスワードを指定する

(3) Maven Repository (Nexus Repository Manager) の Kubernetes Service 経由の URL を指定する i.e. http://nexusrepo-sonatype-nexus-service.dev-tool.svc.cluster.local:8081/repository/maven-public/

.https://github.com/hashnao/gitops-practice/blob/main/applicationsets/camelk/applicationset.yaml[applicationsets/camelk/applicationset.yaml]

      parameters:
      - name: "nexus.username"
        value: <USERNAME> (1)
      - name: "nexus.password"
        value: <PASSWORD> (2)
      - name: "nexus.mirror_url"
        value: <NEXUS_URL> (3)
  syncPolicy:
    automated:
      prune: false
      selfHeal: true

=== ApplicationSet (AMQ Streams Operator)

以下は <> のセクションで利用する ApplicaitonSet CR (https://github.com/hashnao/gitops-practice/blob/main/applicationsets/amqs/applicationset.yaml[applicationsets/amqs/applicationset.yaml]) に定義するフィールドの設定例です。 Kafak Cluster, Zookeeper, Kafka Connect Cluster の Pod Replica はデフォルトで 3 ですが、GitOps の動作検証など最小構成で検証するために Pod Replica を 1 に上書きするために設定しています。 検証以外の用途では該当するフィールドを削除します。

spec: template: spec: source: helm: parameters:

=== Nexus Repository Manager Server Passowrd Encryption

https://github.com/hashnao/gitops-practice/blob/main/tenant-projects/camelk/sample/values.yaml[tenant-projects/camelk/sample/values.yaml] に定義する Nexus Repository Manager のパスワードを暗号化します。 詳細は https://maven.apache.org/guides/mini/guide-encryption.html[Apache Maven Project Password Encryption] を参照下さい。

. Maven コンテナを起動、コンテナ内でシェルを起動する +

podman run -it docker.io/library/maven:latest /bin/bash

NOTE: ここではコンテナイメージを利用しますが、mvn コマンドが利用できれば作業用のホストに maven をインストールするなどの方法でも構いません。

. Master Password を生成する +

MASTER_PASSWORD=$(mvn --encrypt-master-password )

NOTE: <MASTER_PASSWORD> に任意の文字列を指定します。

. settings-security.xml を作成し Master Password を定義する +

cat > ~/.m2/settings-security.xml <<EOF

${MASTER_PASSWORD}

EOF

. Nexus Repository Manager のパスワードを暗号化する +

mvn --encrypt-password

NOTE: <NEXUS_PASSWORD> に Nexus Repository Manager のパスワードを指定します。 + .Example Output

{+ORKcatQya0HQsu/G+qiJKoyXEKoPLsQPbTqUCm798w=}

. values.yaml の operators.camelk-operator.nexus.password フィールドに出力された文字列を定義する + NOTE: { と } を含みます。

operators: ... nexus: username: nexus password: "{+ORKcatQya0HQsu/G+qiJKoyXEKoPLsQPbTqUCm798w=}" mirror_url: http://nexusrepo-sonatype-nexus-service.dev-tool.svc.cluster.local:8081/repository/maven-public/