2026.10.19 インフラ・クラウド

ArgoCDでHelm chartを使う方法：valueFiles・マルチソースの設定とargo-cd chartでのインストール【3.5系】

Q: Argo CDで入れたアプリがhelm lsに表示されないのはなぜですか？

Argo CDはHelmをテンプレートの描画にだけ使い、 helm install を実行しないためです。Helmのリリース情報が作られないので、 helm ls や helm rollback では確認も操作もできません。状態の確認と切り戻しは、Argo CDのUIやCLI、またはGitのコミット履歴から行います。

Q: valueFilesに書いたファイルが反映されないときは何を確認しますか？

まず優先順位を確認します。 parameters ・ valuesObject ・ values のどれかに同じキーがあると、valueFilesの値より優先されます。次に確認するのは、パスがchartのディレクトリ基準、マルチソースなら ref を持つリポジトリのルート基準になっているかという点です。 ignoreMissingValueFiles: true を付けている場合は、パスの誤りでもエラーにならない点に注意が要ります。

Q: Argo CD 3.5に上げるとHelm chartの描画は変わりますか？

3.5からchartの描画に使うHelmはv4だけになりました。 helm.version: v3 の指定は無視されますが、書いたままでもエラーにはなりません。影響が出やすいのは平文HTTPのOCIレジストリで、リポジトリ設定に insecureOCIForceHttp を足す必要があります。描画結果の差は、更新前後で argocd app manifests の出力を比べて確かめると確実です。

Q: Argo CD本体はkubectl applyとHelm chartのどちらで入れるべきですか？

検証環境で動作を確かめるだけなら、公式マニフェストを kubectl apply で入れるほうが手早く済みます。本番でHA構成やIngress、SSOの設定を継続して管理するなら、argo-helmの argo-cd chartとvaluesファイルで入れる方法を選びます。どちらの場合も、同梱されるArgo CDの版を確かめて固定してください。

ArgoCDでHelm chartを使う方法：valueFiles・マルチソースの設定とargo-cd chartでのインストール【3.5系】

Argo CDとHelmの組み合わせには、2つの方向があります。1つはHelm chartで書かれたアプリをArgo CDのApplicationとして同期する方向、もう1つはArgo CD自体をHelm chartでクラスターへ入れる方向です。この記事では両方を扱い、spec.source.helm での values の渡し方、values.yamlを別のGitリポジトリに置くマルチソース構成、Helm hookとランダム値が起こす差分への対処、argo-helmの argo-cd chartでのインストールまでを、Argo CD 3.5系（2026年10月時点）の公式ドキュメントに沿ってYAML付きで示します。

まとめ：Argo CDでHelm chartを扱う2つの方向と設定の要点

Argo CDはHelm chartを helm template で描画するだけで、helm install は実行しません。リリースの管理はArgo CD側が持つため、helm ls にはアプリが表示されません。ここを理解しておくと、hookの挙動や差分の出方にも納得がいきます。

values の渡し方は、valueFiles・values・valuesObject・parameters の4通りで、後ろに書いたものほど優先されます。環境ごとに値を変えるなら、chartはHelmリポジトリから取り、values.yamlだけを自社のGitに置くマルチソース構成が扱いやすい形です。

Argo CD 3.5系からは、chartの描画に使うHelmがv4だけになりました。helm.version: v3 を書いていても無視されます。平文HTTPのOCIレジストリを使っている構成は、更新前に設定の追加が必要です。Argo CD本体は、argo-helmの argo-cd chart（10.10系がv3.5.5を同梱）で入れるとvaluesで設定を管理でき、HA構成への切り替えも値の変更で済みます。

Argo CDがHelm chartを描画して差分を同期する仕組み

最初に、Argo CDの中でHelmがどう呼ばれているかを押さえます。Argo CDそのものの基本はArgoCDとは？GitOpsの仕組みとインストール・Sync設定をコード付きで解説、Helmのチャート・リポジトリ・リリースの概念はHelmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説で整理しています。

helm installを使わないためhelm lsにリリースが出ない理由

公式のFAQは、Argo CDがHelmを「テンプレートの仕組みとしてのみ」使っていると明記しています。chartを描画して得たマニフェストを、Git上の宣言として扱い、クラスターの実状態と比べて同期する流れです。

結果として、Helmのリリース情報（Secretに保存される履歴）は作られません。helm ls や helm rollback でArgo CDのアプリを操作することはできず、切り戻しはGitのコミットを戻すか、Argo CDの履歴から行います。手でHelmコマンドを打つ運用に慣れたチームほど、ここで戸惑います。

Argo CD 3.5系でレンダリングがHelm v4に一本化された影響

v3.4から3.5へのアップグレードガイドによると、3.5でArgo CDに同梱されるHelmは4.2系に上がりました。Helmのユーザーガイドも、3.5以降にchartの描画で使うHelmはv4だけだと書いています。spec.source.helm.version はHelm 2から3への移行期の名残で、値はそのまま残してかまいません。

実務で影響が出やすいのはOCIレジストリです。Helm v4はOCIの扱いが厳格になり、TLSを使わない平文HTTPのレジストリは、リポジトリ設定に insecureOCIForceHttp: "true" を足さないと取得できません。依存chartを平文HTTPのOCIから取っている場合は、依存側のリポジトリも明示的な登録が必要です。社内の検証用レジストリを平文で立てている構成は、3.5へ上げる前に洗い出してください。

Helmリポジトリのchartをspec.source.helmで同期する書き方

ここからは、公開されているchartをApplicationとして同期する手順です。chartの取得元がHelmリポジトリの場合、repoURL にリポジトリのURL、chart にchart名、targetRevision にchartのバージョンを書きます。

chart・repoURL・targetRevisionで公開chartを指定する最小例

公式ガイドの例を、values の上書きまで含めて書き直したものです。targetRevision はchartのバージョンで、アプリのバージョンではありません。範囲指定もできますが、意図しない更新を避けるため固定値で書くのが安全です。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: sealed-secrets
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://bitnami-labs.github.io/sealed-secrets
    chart: sealed-secrets
    targetRevision: 1.16.1
    helm:
      releaseName: sealed-secrets
      valuesObject:
        resources:
          requests:
            cpu: 50m
            memory: 64Mi
  destination:
    server: https://kubernetes.default.svc
    namespace: kubeseal
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

releaseName を省くとApplication名がリリース名になります。後から変えると、app.kubernetes.io/instance ラベルをセレクタに使うchartでは既存リソースと一致しなくなるおそれがあると、公式ガイドが警告しています。最初に決めた値を変えない運用にしてください。

valueFiles・valuesObject・parametersの優先順位と使い分け

values の渡し方は4通りあり、公式ガイドが示す優先順位は高い順に次のとおりです。

順位	フィールド	向く用途
1	parameters	個別キーの一時上書き
2	valuesObject	YAMLのまま書く値
3	values	文字列で書く値
4	valueFiles	環境別ファイル
5	chartのvalues.yaml	chart既定値

基本はvalueFilesで環境ごとのファイルを指定し、Application側には環境を問わない少数の値だけを valuesObject で書く形です。values は文字列なのでインデントの崩れに気づきにくく、新しく書くなら valuesObject を選びます。parameters は最優先で効くぶん、どこで値が決まったかを追いにくくなります。障害対応の一時的な上書きに限るのが無難です。

valueFiles は複数書くと後のファイルが勝ち、存在しないファイルを指すとエラーになります。valueFiles のパスや parameters の値には $ARGOCD_APP_NAME などのビルド環境変数も使えます。

プライベートのHelmリポジトリとOCIレジストリを登録するSecret

認証が要るリポジトリは、Declarative Setupの書式でSecretとして登録します。ラベル argocd.argoproj.io/secret-type: repository を付け、リポジトリの種類として type: helm を指定してください。OCIレジストリの場合は enableOCI: "true" を足します。

apiVersion: v1
kind: Secret
metadata:
  name: private-helm
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  name: private-helm
  url: https://charts.example.com
  type: helm
  username: deploy-bot
  password: "(パスワードやトークンは外部のSecret管理から注入する)"
---
apiVersion: v1
kind: Secret
metadata:
  name: oci-helm
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  name: oci-helm
  url: registry.example.com/charts
  type: helm
  enableOCI: "true"

OCIのchartをApplicationで指定するときは、repoURL に oci:// を付けずに書きます。chartとvaluesを別ドメインから取る構成で認証情報を送る必要があるなら、helm.passCredentials: true を指定します。

values.yamlを別のGitリポジトリに置くマルチソース構成の手順

公開chartを使いながら、valuesだけは自社のGitで管理したい。この要望に応えるのが、v2.6で入ったMultiple Sourcesです。source の代わりに sources を配列で書きます。

sourcesとref: valuesで環境別のvaluesファイルを参照する例

1つ目のソースでHelmリポジトリのchartを取り、2つ目のソースにvalues用のGitリポジトリを ref: values という名前で置きます。chart側からは $values でそのリポジトリのルートを指せます。

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: prometheus-prod
  namespace: argocd
spec:
  project: default
  sources:
    - repoURL: https://prometheus-community.github.io/helm-charts
      chart: prometheus
      targetRevision: 15.7.1
      helm:
        valueFiles:
          - $values/charts/prometheus/values-common.yaml
          - $values/charts/prometheus/values-prod.yaml
        ignoreMissingValueFiles: true
    - repoURL: https://git.example.com/org/helm-values.git
      targetRevision: main
      ref: values
  destination:
    server: https://kubernetes.default.svc
    namespace: monitoring

この形にすると、chartのバージョンを上げる変更と、環境ごとの値を変える変更が別々のコミットになります。レビューの単位が分かれるので、どちらの変更が差分の原因かを追いやすい構成です。Gitを正とする運用の全体像はGitOpsとは：4原則とPush型との違い、Argo CD・Fluxの最小構成YAMLで扱っています。

ignoreMissingValueFilesの欠落許容設定と$valuesの制約

公式ドキュメントが挙げている制約は次の4点です。

ref を持つソースに chart は書けない
$values はvaluesファイルのパスの先頭でしか使えない
パスは ref を持つソースのルートが基準で、path を指定していても変わらない
別のHelm chartをvaluesの取得元にはできない

先の例で付けた ignoreMissingValueFiles: true は、存在しないファイルをHelmに渡さず読み飛ばす設定です。共通ファイルと、環境によっては無い上書きファイルを並べる場合に使います。ただし、パスの書き間違いも黙って通るため、必須のファイルが読まれているかは argocd app manifests の出力で一度確かめてください。

Helm hookとランダム値がArgo CDの同期で起こす差分への対処

Helmでは問題なく入るchartが、Argo CDでは毎回差分を出したり、hookの順序が変わったりすることがあります。原因の多くはこの2つです。

Helm hookをPreSync・PostSyncへ読み替える同期時の対応表

Argo CDはinstallとupgradeを区別せず、どちらも同期として扱います。そのためHelm hookは、公式ガイドの対応表に沿ってArgo CDのhookへ読み替えられます。表に示すのは、pre-installやpost-upgradeと同期フェーズとの対応関係です。表中のrollbackの前後とは、pre-rollbackとpost-rollbackのことです。

Helm hook	Argo CDでの扱い
pre-install・pre-upgrade	PreSync
post-install・post-upgrade	PostSync
pre-delete	PreDelete
post-delete	PostDelete
hook-weight	sync-waveと同等
rollbackの前後	無視
test-success・test-failure	無視

pre-installとpre-upgradeが同じPreSyncになるため、「初回だけ流したいDBの初期化Job」は毎回の同期で走ります。公式ガイドは、install系のhookに hook-weight: "-1"、upgrade系に hook-delete-policy: before-hook-creation を付けることを勧めています。

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    helm.sh/hook: pre-install,pre-upgrade
    helm.sh/hook-weight: "-1"
    helm.sh/hook-delete-policy: before-hook-creation
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: registry.example.com/app-migrate:1.4.2
          args: ["migrate", "up"]

Jobの中身は、何度実行しても結果が同じになるよう冪等に作ります。なお、chart内に1つでもArgo CDのhook注釈を書くと、Helm hookはすべて無視されます。自作chartで両方の注釈を混ぜないよう注意してください。

randAlphaNumで常にOutOfSyncになるchartを固定値で止める

chartのテンプレートが randAlphaNum でパスワードなどを生成していると、Argo CDが比較のたびに描画し直すので値が毎回変わり、アプリはずっとOutOfSyncのままになります。対策は、生成される値をvaluesで固定値として渡すことです。公式ガイドでは、argocd app set redis -p password=abc123 のようにパラメータで上書きする例が示されています。

ただし、パスワードをApplicationやGitに平文で書くのは避けるべきです。chartが既存Secretを参照する設定（existingSecret などの名前で用意されていることが多い）を持っているなら、Secretは外部のSecret管理から作り、chartにはその名前だけを渡す形にします。

Argo CD本体をargo-helmのargo-cd chartで入れる手順

次は逆方向で、Argo CDそのものをHelm chartで入れる手順です。公式マニフェストを kubectl apply で入れる方法は親記事で扱いました。argo-helmのargo-cd chartを使うと、レプリカ数やIngressといった設定をvaluesファイル1つで管理できます。

v3.5.5同梱のchart 10.10系をHelmでインストールする手順

READMEの前提は、Kubernetes 1.25以上とHelm v3.0.0以上です。2026年10月時点のChart.yamlは、chartバージョン10.10.5、同梱するArgo CDはv3.5.5でした。argo-helmのリリース一覧では、10.10.3でArgo CDがv3.5.5へ更新されています。chartのバージョンを固定して入れます。

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
helm search repo argo/argo-cd --versions | head -n 5

helm install argocd argo/argo-cd \
  --namespace argocd --create-namespace \
  --version 10.10.5 \
  -f values-argocd.yaml

kubectl -n argocd get pods

3.5系では2026年10月にCriticalの脆弱性が複数公表されており、修正版は3.5.4以降です。経緯と影響範囲はArgo CDの脆弱性一覧と対処：2026年10月のCritical4件と修正版にまとめました。chartで入れる場合も、同梱されるArgo CDの版を確かめてから固定してください。

HA構成のvaluesとCRDをchartに管理させるかの判断

このchartは既定で非HA構成を入れます。本番向けにHAへ切り替えるvaluesは、READMEの例をもとにすると次の形です。Redis HAはPodを別々のノードに置くため、ワーカーノードが3台以上必要です。

global:
  domain: argocd.example.com

redis-ha:
  enabled: true

controller:
  replicas: 1

server:
  autoscaling:
    enabled: true
    minReplicas: 2

repoServer:
  autoscaling:
    enabled: true
    minReplicas: 2

applicationSet:
  replicas: 2

configs:
  params:
    server.insecure: true

server.insecure: true は、TLSをIngressコントローラー側で終端する構成のときだけ使う設定です。Argo CDのサーバーへ直接TLSで届く構成なら外してください。

CRDは、crds.install（既定 true）でchartが入れて更新し、crds.keep（既定 true）でアンインストール時に残します。Helmは crds/ フォルダのCRDを更新できないため、このchartは5.2.0以降CRDをテンプレート側へ移し、server-side applyを使って適用する仕組みです。CRDをchartの外で管理したい場合は crds.install=false にし、手で入れるときもserver-side applyを有効にします。

adminパスワードを固定したい場合、configs.secret.argocdServerAdminPassword にbcryptのハッシュを渡します。Argo CDのApplicationからこのchartを管理するなら、ハッシュは parameters でなく values 側に書きます。parameters では $ がArgo CDの変数置換に食われ、ハッシュが壊れるためです。

Argo CDでHelmを扱う構成の判断基準と見送るべき場面

最後に、chartの置き場所と周辺ツールの選び方について、受託でGitOps基盤を組むときの判断を言い切ります。

Helmリポジトリ直参照とGit管理のchartのどちらを選ぶか

外部の公開chartをそのまま使うなら、Helmリポジトリを直接参照し、valuesだけをマルチソースで自社Gitに置く構成を選びます。chartの更新は targetRevision の書き換え1行で済み、valuesのレビューと分けられるからです。

自社で書いたchartは、アプリのコードと同じGitリポジトリか、chart専用のGitリポジトリに置き、path で参照します。chartをHelmリポジトリやOCIへ公開する作業を挟むのは、複数のチームや顧客に同じchartを配る場合だけで十分です。社内の1サービスのためにchartの公開手順まで作るのは、管理する成果物が増えるだけになります。

KustomizeやHelm Secretsプラグインが必要な構成で迷ったとき

値の差し替えが数か所で、テンプレートの分岐まで要らないなら、Helm chartを書かずにKustomizeのoverlaysで足ります。Helmを選ぶのは、配布されているchartを使うときと、条件分岐や繰り返しを含むテンプレートが必要なときです。

見送るべきなのは、helm-secretsのようなHelmプラグインに依存した手順を、そのままArgo CDへ持ち込む構成です。Argo CDはHelmを描画にしか使わないため、プラグインを動かすにはrepo-serverのイメージやサイドカーを自前で作り込む必要があり、3.5系のHelm v4化のような更新のたびに検証の手間がかかります。秘密情報はchartの外でSecretとして作り、chartには参照名だけを渡す設計に寄せるほうが、Argo CDの更新に追従しやすくなります。

既存のHelm運用をArgo CDによるGitOpsへ移す場合や、valuesの分け方と環境構成から設計し直したい場合は、DevOps・CI/CD導入支援で設計から運用の引き継ぎまで相談を受けています。

よくある質問

Argo CDでHelm chartを扱う際によく出る疑問に、公式ドキュメントの記述をもとに答えます。

Argo CDで入れたアプリがhelm lsに表示されないのはなぜですか？

Argo CDはHelmをテンプレートの描画にだけ使い、helm install を実行しないためです。Helmのリリース情報が作られないので、helm ls や helm rollback では確認も操作もできません。状態の確認と切り戻しは、Argo CDのUIやCLI、またはGitのコミット履歴から行います。

valueFilesに書いたファイルが反映されないときは何を確認しますか？

まず優先順位を確認します。parameters・valuesObject・values のどれかに同じキーがあると、valueFilesの値より優先されます。次に確認するのは、パスがchartのディレクトリ基準、マルチソースなら ref を持つリポジトリのルート基準になっているかという点です。ignoreMissingValueFiles: true を付けている場合は、パスの誤りでもエラーにならない点に注意が要ります。

Argo CD 3.5に上げるとHelm chartの描画は変わりますか？

3.5からchartの描画に使うHelmはv4だけになりました。helm.version: v3 の指定は無視されますが、書いたままでもエラーにはなりません。影響が出やすいのは平文HTTPのOCIレジストリで、リポジトリ設定に insecureOCIForceHttp を足す必要があります。描画結果の差は、更新前後で argocd app manifests の出力を比べて確かめると確実です。

Argo CD本体はkubectl applyとHelm chartのどちらで入れるべきですか？

検証環境で動作を確かめるだけなら、公式マニフェストを kubectl apply で入れるほうが手早く済みます。本番でHA構成やIngress、SSOの設定を継続して管理するなら、argo-helmの argo-cd chartとvaluesファイルで入れる方法を選びます。どちらの場合も、同梱されるArgo CDの版を確かめて固定してください。

Helm hookのpre-installが毎回の同期で実行されるのはなぜですか？

Argo CDはinstallとupgradeを区別できず、pre-installもpre-upgradeもPreSyncとして同期のたびに実行するからです。初回だけ流したい処理は、何度実行しても結果が変わらない冪等な作りにし、hook-delete-policy: before-hook-creation を付けて前回のJobを消してから作り直す形にします。