Argo CD最短導入ガイド（macOS + microk8s編）

Kubernetest-inagaki

1. はじめに

GitOpsとは、アプリケーションやインフラの設定をGitリポジトリで管理し、自動的に環境に反映する手法です。Argo CDはその代表的なツールで、Kubernetes環境におけるGitOpsを実現します。

本記事のゴール：

  • macOS上にmicrok8sを立てる
  • Argo CDをインストールしてWeb UIにアクセス
  • サンプルアプリをデプロイしてGitOpsを体感する

2. 前提条件

  • macOS (Apple Silicon)
  • Homebrewがインストール済み

3. microk8sのセットアップ

Homebrewでmicrok8sをインストールします。

brew install ubuntu/microk8s/microk8s
microk8s install

microk8sを起動します。

microk8s start

microk8sの状態確認とアドオンの有効化をします。

microk8s status --wait-ready
microk8s enable dns storage ingress

microk8sのサブコマンドのエイリアス設定をします。恒久的に設定したい場合は、お好みで ~/.bashrc や ~/.zshrc に以下を追加してください。

alias kubectl="microk8s kubectl"
alias helm="microk8s helm"

4. Argo CDのインストール

公式のHelm Chartのリポジトリを登録し、Argo CDをインストールします。1

helm repo add argo https://argoproj.github.io/argo-helm
helm repo list
helm --namespace argocd install argocd argo/argo-cd --create-namespace

Podが起動するまで以下コマンドを何度か打って待機しましょう。

kubectl --namespace argocd get pods

以下PodがRunningになっていることを確認します。

  • argocd-application-controller
  • argocd-applicationset-controller
  • argocd-dex-server
  • argocd-notifications-controller
  • argocd-redis
  • argocd-repo-server
  • argocd-server
NAME                                                READY   STATUS    RESTARTS   AGE
argocd-application-controller-0                     1/1     Running   0          102s
argocd-applicationset-controller-6bb7fc84d8-gdxz5   1/1     Running   0          102s
argocd-dex-server-694c4879c6-pqpws                  1/1     Running   0          102s
argocd-notifications-controller-5b6df94c56-hhctm    1/1     Running   0          102s
argocd-redis-69dcc6cbc9-kxjxr                       1/1     Running   0          102s
argocd-repo-server-645b6f6d76-qwb85                 1/1     Running   0          102s
argocd-server-585669dd97-jdzxr                      1/1     Running   0          102s

5. Argo CD CLIのインストール

手元のPCからArgo CDを操作できるようにArgo CD CLIをインストールします。

brew install argocd

6. Argo CDへのポートフォワード

Argo CDにログインするためにポートフォワードを行います。

kubectl --namespace argocd port-forward services/argocd-server 8443:443

7. Argo CD CLIログイン

adminユーザーの初期パスワードを取得します。

argocd admin initial-password --namespace argocd

Argo CD CLIを使って先程インストールしたArgo CDにログインします。今回は初期パスワードをそのまま使用します。

argocd login localhost:8443 --port-forward-namespace argocd

8.サンプルアプリをデプロイ

guestbookアプリ（Argo公式サンプル）を登録してみましたが、筆者の環境はCPUアーキテクチャがarm64なので exec format error エラーが発生したためbitnami/nginxをサンプルとしてデプロイしました。

またオリジナルのbitnamiリポジトリは今回のデモでは不要なhelm chartを多数含んでいるため、bitnami/nginxだけを継承したnginx-demoを作成しました。自身のリポジトリとすることでGitOpsの動作検証をしやすくする狙いがあります。

皆さんが検証する場合は私のリポジトリをForkして検証するのがやりやすいと思います。

kubectl create namespace nginx-demo
argocd app list
argocd app create nginx-demo \
  --repo https://github.com/ingktds/nginx-demo \
  --path . \
  --dest-namespace nginx-demo \
  --dest-server https://kubernetes.default.svc \
  --sync-policy automated

nginxのPodの状態を確認します。現状はPodは1つのみの状態です。

kubectl --namespace nginx-demo get pods
NAME                          READY   STATUS    RESTARTS   AGE
nginx-demo-6b449494f6-8l7tb   1/1     Running   0          6m4s

9. GitOpsの動作確認

values.yamlのreplicaCountを変更し、実際のkubernetes上のPod数が変わることを確認します。

replicaCountを1から3に変更します。

cd path/to/nginx-demo
vim values.yaml

diffはこちら。

git diff
diff --git a/values.yaml b/values.yaml
index 2777d3d..8dada7d 100644
--- a/values.yaml
+++ b/values.yaml
@@ -3,7 +3,7 @@
 # Declare variables to be passed into your templates.

 # This will set the replicaset count more information can be found here: https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/
-replicaCount: 1
+replicaCount: 3

 # This sets the container image more information can be found here: https://kubernetes.io/docs/concepts/containers/images/
 image:

Indexへの追加とコミットを行います。

git commit -a -m 'Change replicaCount form 1 to 3'

pushします。

git push

アプリケーションの状態を確認します。

argocd app get nginx-demo
Name:               argocd/nginx-demo
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          nginx-demo
URL:                https://argocd.example.com/applications/nginx-demo
Source:
- Repo:             https://github.com/ingktds/nginx-demo
  Target:
  Path:             .
SyncWindow:         Sync Allowed
Sync Policy:        Automated
Sync Status:        Synced to  (9763c86)
Health Status:      Healthy

CONDITION                MESSAGE                                                                                       LAST TRANSITION
RepeatedResourceWarning  Resource /Service/nginx-demo/nginx-demo appeared 2 times among application resources.         2025-09-08 09:08:24 +0900 JST
RepeatedResourceWarning  Resource /ServiceAccount/nginx-demo/nginx-demo appeared 2 times among application resources.  2025-09-08 09:32:12 +0900 JST
RepeatedResourceWarning  Resource apps/Deployment/nginx-demo/nginx-demo appeared 2 times among application resources.  2025-09-08 09:32:12 +0900 JST


GROUP              KIND                 NAMESPACE   NAME            STATUS  HEALTH   HOOK  MESSAGE
networking.k8s.io  NetworkPolicy        nginx-demo  nginx-demo      Synced                 networkpolicy.networking.k8s.io/nginx-demo configured
policy             PodDisruptionBudget  nginx-demo  nginx-demo      Synced  Healthy        poddisruptionbudget.policy/nginx-demo configured
                   ServiceAccount       nginx-demo  nginx-demo      Synced                 serviceaccount/nginx-demo unchanged
                   Secret               nginx-demo  nginx-demo-tls  Synced                 secret/nginx-demo-tls configured
                   Service              nginx-demo  nginx-demo      Synced  Healthy        service/nginx-demo unchanged
apps               Deployment           nginx-demo  nginx-demo      Synced  Healthy        deployment.apps/nginx-demo configured

nginxのPodの状態を確認します。Pod数は3つに変わりました。

kubectl --namespace nginx-demo get pods
NAME                          READY   STATUS    RESTARTS   AGE
nginx-demo-6b449494f6-4m8m7   1/1     Running   0          2m9s
nginx-demo-6b449494f6-8l7tb   1/1     Running   0          25m
nginx-demo-6b449494f6-hlj44   1/1     Running   0          2m9s

10. トラブルシューティング（よくあるつまづき）

  • argocd-server にアクセスできない
    • ポートフォワード忘れ
  • kubectlやhelmコマンドが見つからない 
    • microk8s kubectlや microk8s helm を使用。本記事では冒頭でそれぞれのコマンドをaliasコマンドで書き換えています。
  • ArgoCD公式のサンプルアプリのguestbookが起動できない

11. まとめ

いかかがでしたでしょうか。microk8s + Argo CDでGitOpsをローカル体験することができました。GitHubで変更した内容がmicrok8sにデプロイされることが確認できたと思います。

12. 参考資料

  1. 公式ドキュメントではKubernetesのマニフェストをインストールする手順ですが、可能な限りhelm chartを使いたいので今回はhelm chart版でインストールします。 ↩︎

新規CTA