Argo CD のインストールから Git の YAML を反映するまで
- 公開日
- カテゴリ：ArgoCD
- タグ：Kubernetes,ArgoCD,学習メモ
Argo CD は、クラスタの中で動き、Git リポジトリにある YAML を Kubernetes に反映し続けるプログラム。（何をするものかは「Argo CD の概要と仕組み」を参照）
この記事では、Argo CD を手元のクラスタに入れ、GitHub に置いた Deployment の YAML を kubectl apply を打たずにクラスタに入れるところまでを確認する。
contents
- 今回作るもの
- Argo CD をインストールする
- 画面にログインする
- Git に Deployment の YAML を置く
- private リポジトリを Argo CD に登録する
- Application を書く
- Sync する
- どこで何が動いているか
- 用語メモ
- 参考 URL
今回作るもの
上から順に作る。クラスタは kind（Docker の上に作る Kubernetes）で、Control Plane 1 つと Worker 2 つ。Argo CD は v3.5.5。
| 作るもの | どこにできるか |
|---|---|
| Argo CD | クラスタの argocd namespace に Pod が 7 つ |
GitHub の private リポジトリ argocd-study | GitHub。中身は web/deployment.yaml の 1 ファイル |
Application web | クラスタの argocd namespace のデータ |
最後の Application を入れると、Argo CD が GitHub の web/deployment.yaml を読んで、default namespace に Deployment を作る。
Argo CD をインストールする
Argo CD は Kubernetes の一部ではなく、あとから入れるプログラム。公式が 1 ファイルにまとめた install.yaml を kubectl apply する。
$ kubectl create namespace argocd
# => namespace/argocd created
$ kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
-n argocd:install.yamlには namespace が書いていないので、ここで指定する。公式がargocdという名前を前提にしている（権限の設定にこの名前が書いてある）--server-side --force-conflicts: 公式の Getting Started のとおりに付ける。install.yamlの中に、通常の apply では大きすぎて入らない定義（CRD）があるため
Pod が全部 Running になるまで待つ。
$ kubectl get pods -n argocd
NAME READY STATUS RESTARTS AGE
argocd-application-controller-0 1/1 Running 0 42s
argocd-applicationset-controller-66d7f7865d-ltblh 1/1 Running 0 42s
argocd-dex-server-6d8ddc4748-49nrf 1/1 Running 0 42s
argocd-notifications-controller-6bdf867f45-pfd4v 1/1 Running 0 42s
argocd-redis-5fbd54c8cc-8jjhr 1/1 Running 0 42s
argocd-repo-server-66875c66b4-4vkmv 1/1 Running 0 42s
argocd-server-7f85776b5c-jfkjx 1/1 Running 0 42s
Pod が 7 つ。どれも argocd namespace で動くプログラム。この記事で関わるのは 3 つ。
| Pod | 何をするプログラムか |
|---|---|
argocd-server | ブラウザに画面を出す |
argocd-repo-server | GitHub からファイルを取ってくる |
argocd-application-controller | Git の内容とクラスタの中身を比べ、違っていれば apply する |
Pod のほかに、新しい種類のデータが 3 つ書けるようになる。Argo CD が CRD（Custom Resource Definition。Kubernetes に新しい kind を追加する仕組み）で足したもの。
$ kubectl api-resources | grep argoproj
applications app,apps argoproj.io/v1alpha1 true Application
applicationsets appset,appsets argoproj.io/v1alpha1 true ApplicationSet
appprojects appproj,appprojs argoproj.io/v1alpha1 true AppProject
この記事で書くのは Application だけ。Deployment や Service と同じく、YAML を書いて kubectl apply すると etcd に保存されるデータ。
画面にログインする
画面を出しているのは argocd-server で、クラスタの中の Pod。手元のブラウザからそのままでは届かないので、kubectl port-forward でつなぐ。
kubectl port-forward は、手元の localhost:8080 への接続を、クラスタの中の Service argocd-server の 443 番に中継し続けるコマンド。打っているあいだだけ有効で、Ctrl+C で止まる。別のターミナルで打ちっぱなしにする。
$ kubectl port-forward svc/argocd-server -n argocd 8080:443
Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080
ブラウザで https://localhost:8080 を開く。argocd-server が自分で作った証明書（自己署名証明書）を使っているので、ブラウザが「この接続ではプライバシーが保護されません」のような警告を出す。手元のクラスタなので、「詳細設定」から進む。
ユーザー名は admin。パスワードは、Argo CD が最初の起動時にランダムに作って、argocd namespace の Secret argocd-initial-admin-secret に入れてある。Secret の値は base64 でエンコードされているので、base64 -d で戻す。
$ kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath='{.data.password}' | base64 -d; echo
# => （ランダムな文字列。これがパスワード）
ログインすると Applications の一覧画面が開く。まだ 1 つもない。
画面から Application を作ることもできる（+ NEW APP）が、この記事では YAML を書いて kubectl apply する。画面で作ると、何を入れたかが手元のファイルに残らないため。
Git に Deployment の YAML を置く
Argo CD が読むのは GitHub にあるファイルで、手元のファイルは読まない。GitHub に private リポジトリ argocd-study を作り、web/deployment.yaml を 1 つ push する。
nginx を 1 つ動かす Deployment。namespace は書かない（どの namespace に入れるかは、あとで書く Application で決める）。
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 1
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.27
ports:
- containerPort: 80
Argo CD はファイル 1 つではなく、ディレクトリ 1 つを読む。web というディレクトリに置いたのは、あとで Service や ConfigMap を同じディレクトリに足すため。
private リポジトリを Argo CD に登録する
private リポジトリなので、argocd-repo-server がそのまま取りに行くと GitHub に断られる。公式ドキュメント（Private Repositories）のとおり、ユーザー名と Personal Access Token を Argo CD に登録する。（Personal Access Token を使うのは学習用のため。公式ドキュメントには SSH 鍵や GitHub App での登録方法もある）
Personal Access Token は、GitHub がパスワードの代わりに発行する文字列。「どのリポジトリを」「何していいか（読むだけ、など）」を絞って作れる。
GitHub でトークンを作る
GitHub の Settings → Developer settings → Personal access tokens → Fine-grained tokens から作る。
| 項目 | 値 |
|---|---|
| Repository access | Only select repositories → argocd-study |
| Repository permissions → Contents | Read-only |
Argo CD がやるのは git fetch（ファイルを読む）だけなので、Contents の読み取りだけで足りる。生成されたトークンは 1 回しか表示されないので、コピーしておく。
Argo CD の画面に登録する
左のメニューの Settings → Repositories → + CONNECT REPO。
| 項目 | 値 |
|---|---|
| Choose your connection method | VIA HTTPS |
| Type | git |
| Project | default |
| Repository URL | https://github.com/example-user/argocd-study.git |
| Username | GitHub のユーザー名 |
| Password | 上で作ったトークン |
CONNECT を押すと、Argo CD がその場で GitHub につなぎに行く。一覧に argocd-study の行が出て、CONNECTION STATUS が Successful になれば登録できている。
画面から入れた URL・ユーザー名・トークンは、argocd namespace の Secret に保存される。
$ kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=repository
NAME TYPE DATA AGE
repo-xxxxxxxxxx Opaque 5 1m
Application を書く
Application は「どの Git の、どのディレクトリを、どの namespace に入れるか」を書いたデータ。Argo CD の仕事の単位で、これを 1 つ apply すると Argo CD が仕事を始める。
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: web
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/example-user/argocd-study.git
targetRevision: HEAD
path: web
destination:
server: https://kubernetes.default.svc
namespace: default
| フィールド | 何を決めているか | 今回の値 |
|---|---|---|
spec.source | どの Git の、どのブランチの、どのディレクトリを読むか | 上のリポジトリ。HEAD は既定のブランチの最新。web ディレクトリ |
spec.destination | どのクラスタの、どの namespace に入れるか | https://kubernetes.default.svc は「Argo CD 自身が動いているクラスタ」を指す決まった書き方。namespace は default |
spec.project | Application をまとめるグループ | Argo CD を入れた時点である default |
metadata.namespace は argocd。Application は Argo CD が読むデータなので、Argo CD と同じ namespace に置く。Deployment ができる先の default ではない。
このファイルは GitHub には置かず、手元から apply する。
$ kubectl apply -f application.yaml
# => application.argoproj.io/web created
$ kubectl get applications -n argocd
NAME SYNC STATUS HEALTH STATUS
web OutOfSync Missing
apply の直後は SYNC STATUS が Unknown のことがある。数秒待ってもう一度打つと OutOfSync になる。
画面の Applications の一覧にも web が出る。クリックすると、Application web の右に、点線で deploy web がぶら下がった図になる。
| 画面の表示 | 意味 | 今の状態 |
|---|---|---|
SYNC STATUS OutOfSync | Git の内容とクラスタの中身が違う | GitHub には Deployment web があるが、クラスタにはまだない |
APP HEALTH Missing | Git に書いてあるものがクラスタにない | 同上 |
Argo CD は Application を読んだ時点で GitHub を取りに行き、Git とクラスタを比べた。比べただけで、まだ何も入れていない。この Application には「自動で入れてよい」と書いていないので（画面にも Auto sync is not enabled. とある）、人がボタンを押すまで待っている。
Sync する
Sync は、Git の内容をクラスタに反映すること。中身は kubectl apply 相当で、やるのは argocd-application-controller。
Application web の画面の上の SYNC → 右に出るパネルの SYNCHRONIZE を押す。押す前に、別のターミナルで default namespace の Pod を -w で見ておく。SYNCHRONIZE を押すと、kubectl apply を打っていないのに、default namespace に Pod が作られる。
$ kubectl get pods -n default -w
NAME READY STATUS RESTARTS AGE
web-557577df75-5m5lr 0/1 Pending 0 0s
web-557577df75-5m5lr 0/1 ContainerCreating 0 0s
web-557577df75-5m5lr 1/1 Running 0 7s
Deployment と Application も見る。
$ kubectl get deployment,pods -n default
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/web 1/1 1 1 49s
NAME READY STATUS RESTARTS AGE
pod/web-557577df75-5m5lr 1/1 Running 0 49s
$ kubectl get applications -n argocd
NAME SYNC STATUS HEALTH STATUS
web Synced Healthy
画面では、点線が実線になり、Deployment → ReplicaSet → Pod まで見える。
| 画面の表示 | 意味 |
|---|---|
SYNC STATUS Synced | Git の内容とクラスタの中身が一致している |
APP HEALTH Healthy | 入れたものが正常に動いている。Deployment なら「replicas の数だけ Pod が新しい定義で揃っている」 |
Healthy になる前は、Pod が起動中のあいだ Progressing が出る。Application の Health は、入れたものの中でいちばん悪いものに合わせる。
どこで何が動いているか
ここまでで作ったものを、GitHub とクラスタの 2 つの場所と、その両方を操作する自分に分けて描く。角が二重の箱は動くプログラム（Pod）、それ以外は etcd に保存されたデータ。
- 自分が
kubectl applyしたのは Application だけ。Deployment はargocd-application-controllerが入れた - Deployment の中身は、自分で apply したときと同じ etcd のデータ。違うのは「誰が入れたか」だけ
- namespace はマシンではなく、etcd のデータに付いた名前の区切り。Argo CD のデータは
argocd、Git から入れた Deployment はdefaultに分かれている - Pod は Node の上
用語メモ
| 用語 | 読み方 | 意味 |
|---|---|---|
| Application | アプリケーション | 「どの Git の、どのディレクトリを、どの namespace に入れるか」を書いたデータ。Argo CD の仕事の単位 |
| Sync | シンク | Git の内容をクラスタに反映すること。kubectl apply 相当 |
| Synced | シンクト | Git の内容とクラスタの中身が一致している |
| OutOfSync | アウトオブシンク | Git の内容とクラスタの中身が違う |
| Healthy | ヘルシー | 入れたものが正常に動いている |
| Progressing | プログレッシング | 入れたものが起動中 |
| Missing | ミッシング | Git に書いてあるものがクラスタにない |
| Personal Access Token | パーソナルアクセストークン | GitHub がパスワードの代わりに発行する文字列。対象のリポジトリと、できることを絞れる |
まとめ
- Argo CD は、公式の
install.yamlをkubectl applyで入れる。argocdnamespace に Pod が 7 つ作られ、Application という新しい種類のデータが書けるようになる - 画面は
argocd-serverが出す。kubectl port-forwardでhttps://localhost:8080につなぎ、adminと Secretargocd-initial-admin-secretのパスワードでログインする - private リポジトリは、画面の Settings / Repositories からユーザー名と Personal Access Token を登録する。登録した値は
argocdnamespace の Secret に保存される - Application の YAML に書くのは、どの Git のどのディレクトリを読むか（
source）と、どのクラスタのどの namespace に入れるか（destination）。Argo CD と同じargocdnamespace に apply する - 画面の
OutOfSync/Syncedは「Git とクラスタが違う / 一致している」。Missing/Progressing/Healthyは「クラスタにない / 起動中 / 正常に動いている」 - 自分で apply したのは Application だけで、Deployment は Sync のときに Argo CD が入れた
参考 URL
- [official] Getting Started - Argo CD
- [official] Private Repositories - Argo CD
- [official] Declarative Setup - Argo CD
- [official] Resource Health - Argo CD
[Prev] Argo CD の概要と仕組み
