この記事でやること

IBM Cloud Kubernetes Service（IKS）にArgo CD（v3系前提）を導入し、IKS特有の制約に合わせて GitOps CD基盤として“実際に回る状態”まで持っていく。

単なる kubectl apply で終わらせず、次まで扱う。

IKSのIngress(ALB)でArgo CD UI / API を安全に公開
VPCクラスタの “Secure by Default” ネットワークで詰まらない設定
Pod Security Admission（restricted）環境でも壊れない前提整理
運用（RBAC/Project分離/アップグレード/バックアップ）までの勘所

Argo CDとは

Kubernetes向けのGitOps型Continuous Deliveryツール。
Gitに置いたマニフェスト（Helm/Kustomize含む）を「正」としてクラスタ状態を自動で追従させる。CIは別（Tekton / GitHub Actions等）に置き、CDをArgo CDに寄せるのが一般的。(Medium)

重要な前提：Argo CD 3系を使う

Argo CD 2.14系は2025-11-04でEOL。新規導入なら3系。
この記事は v3.2相当の手順で書く（stableマニフェスト or タグ固定を推奨）。(GitHub)

全体アーキテクチャ（最小＋実運用）

Argo CDをIKSに入れるとコンポーネントはこう動く。

argocd-server
UIとAPI（gRPC/HTTPS）。外部公開対象。
argocd-repo-server
Git/Helm repoからソース取得・レンダリング。
argocd-application-controller
差分検知とSync実行。
Redis
状態キャッシュ。HA構成だと外部RedisやHA内蔵を使う。

運用で効くのは 「どのinstallマニフェストを使うか」 と 「外部公開の方式」。

0. IKSへ接続

（クラスタ作成は省略。既存クラスタ想定）

ibmcloud login

ibmcloud ks cluster config --cluster <CLUSTER_NAME_OR_ID>

kubectl config current-context
kubectl get nodes

1. インストール方式の選定

選択肢

install.yaml（標準）
- Argo CDが動く同一クラスタにデプロイする前提
- ClusterRoleBindingで強い権限を作る
ha/install.yaml
- 上のHA版（実運用の基本）
namespace-install.yaml
- Argo CD自体はnamespace権限で動き、デプロイ先は“外部クラスタ/別権限”を入力して管理
- 複数チーム用インスタンスや権限分離に有利

公式的には、本番はHA版推奨。(Argo CD)

このブログでは「まずHA無しで動作確認 → 次にHA/権限分離」までやる。

2. Argo CD本体の導入（まずは標準）

kubectl create namespace argocd

# stableを使うと最新版追従。運用ではタグ固定が安全。
kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

起動確認。

kubectl get pods -n argocd
kubectl get svc  -n argocd

argocd-server / repo-server / application-controller / redis がRunningになればOK。

3. IKS向けに必須な追加設定

3-1. Ingress(ALB)でUI/APIを公開する

IKSのIngressクラス

IKSのALB（Ingress Controller）は IngressClass名が固定。

Public ALB: public-iks-k8s-nginx
Private ALB: private-iks-k8s-nginx (IBM Cloud)

Argo CD公式は「argocd-serverをIngressで公開する」前提設計なので、IKSのclass指定だけ正しくやればよい。(Argo CD)

Ingress例（Public + TLS）

※IBM提供サブドメインでも独自ドメインでも可。TLS Secretは事前作成。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd
  namespace: argocd
  annotations:
    kubernetes.io/ingress.class: "public-iks-k8s-nginx"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: public-iks-k8s-nginx
  tls:
  - hosts:
    - argocd.<YOUR_DOMAIN>
    secretName: argocd-tls
  rules:
  - host: argocd.<YOUR_DOMAIN>
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 443

適用。

kubectl apply -f argocd-ingress.yaml

ALBとルーティング確認。

ibmcloud ks ingress alb ls -c <CLUSTER>
kubectl describe ingress argocd -n argocd

gRPC（argocd CLI）を通す場合

IKSのnginx ALBはgRPCを通せるが、環境差があり得る。
CLI必須なら 最初はport-forward運用にしてからIngress gRPC化を詰めるのが安全。

kubectl port-forward svc/argocd-server -n argocd 8080:443
argocd login localhost:8080 --insecure

3-2. VPCクラスタの “Secure by Default” に注意

IKS v1.30+ のVPCクラスタは「必要最小限の通信だけ許可」になり、Ingress経由のNodePort転送がセキュリティグループで落ちる場合がある。
その場合、VPC security groupでALB→worker NodePortの通信許可が必要。(IBM Cloud)

症状：

Ingressは作れるが外からつながらない
ALBのHealth checkがUnhealthy

対処：

IKSドキュメントの「Secure by Default VPC networking」手順に沿ってSGを調整

3-3. Pod Security Admission(restricted)環境

Argo CDは近年のマニフェストでrestricted準拠へ寄せられている（securityContext強化）。(GitHub)
ただし、次のパターンで違反しやすい。

sidecar型プラグイン（vault-plugin等）を追加
独自RepoServerイメージに差し替え
initContainerでrootが必要な処理を入れる

restrictedを厳格運用している場合は、
「Argo CD本体は通るが、プラグインで落ちる」 を前提に、追加コンテナ側のsecurityContextもrestricted準拠させる。

4. 初期ログイン & パスワード管理

初期管理者は admin。初期パスワードはargocd-server Pod名。

kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath="{.data.password}" | base64 -d; echo

ログイン後、即変更。

argocd account update-password

本番では argocd-initial-admin-secret を削除しておく。

kubectl delete secret argocd-initial-admin-secret -n argocd

5. GitOpsの最小ハンズオン（IKSへデプロイ）

5-1. サンプルApplication

「Gitのk8s/配下を同期する」最小。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hello-iks
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/<YOUR_ORG>/<YOUR_REPO>.git
    targetRevision: main
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: hello
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

適用。

kubectl apply -f app-hello.yaml

Argo CD UIで Synced/Healthy になれば成功。

6. 実運用で必須の設計ポイント

6-1. AppProjectでチーム分離

default projectを使い続けると権限が破綻する。
チーム/サービス単位でProjectを切り、許可Repo/許可Namespaceを狭める。

許可Git repoのホワイトリスト化
destination namespace・cluster縛り
Resource whitelist/blacklistで危険なCRDを禁止

6-2. RBACの最小化

install.yamlはcluster-admin相当。
運用で怖いなら、

namespace-install.yaml を使う
デプロイ先クラスタは argocd cluster add で個別の限定権限を渡す

で権限を段階的に落とす。(Argo CD)

6-3. 差分ノイズ（IKS管理フィールド）

IKS側が自動で付与する managedFields / ALB関連annotation でdiffが出続けることがある。
その場合は argocd-cm の resource.customizations.ignoreDifferences を設定して抑える。(Argo CD)

例（全リソースでmanagedFields無視）：

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  resource.customizations.ignoreDifferences.all: |
    managedFieldsManagers:
    - kube-controller-manager

反映後はargocd-server / controller再起動。

7. HA化（本番移行手順の型）

7-1. HAマニフェストへ切替

新規なら最初からHAでOK。

kubectl delete -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml

7-2. 永続化/バックアップ

Argo CDの状態は基本「Gitが正」なので、バックアップ対象は主に

argocd namespaceのSecret（repo credentials, SSO設定, cluster credentials）
Application / AppProject 定義

Gitに宣言的に寄せるほどバックアップ負担は軽い。(Argo CD)

8. ありがちな詰まりどころ（IKS特化）

(1) Ingressは作れたが外から繋がらない

VPC Secure by Default のSG未許可
ingressClass指定ミス（public-iks-k8s-nginx 以外は基本効かない）

確認：

kubectl describe ingress argocd -n argocd
ibmcloud ks ingress status-report get -c <CLUSTER>

(2) UIは開くがSyncが失敗する

Argo CD側のServiceAccount権限不足
AppProject destination制限に引っかかっている

確認：

kubectl logs deploy/argocd-application-controller -n argocd

(3) restricted PSAで突然Pod作成拒否

Argo CD本体より repo-server拡張やプラグイン側が原因 のことが多い。
追加コンテナのsecurityContextをrestrictedへ寄せる。

9. アンインストール

検証後の掃除。

kubectl delete ns argocd

まとめ

IKSでArgo CDを使うと、“IKSで動くアプリの理想状態”をGitで一本化できる。
ただしIKSはマネージド要素が強いので、

Ingress(ALB)クラスの正確な指定
VPC Secure by Default の通信許可
PSA/restrictedとプラグイン適合
Project/RBACでの多人数運用設計

を最初から押さえると、後で崩れない。

参照（最低限）

Argo CD v3系 install/HA/namespace-install の公式手順 (GitHub)
Argo CD 2.14系EOLと3系推奨 (GitHub)
IKS Ingress(ALB)クラス名と設定 (IBM Cloud)
IKS VPC Secure by Default Networking 注意点 (IBM Cloud)
PSA/restrictedとArgo CD securityContextの流れ (Kubernetes)