--- title: "ArgoCDでHelm chartを使う方法：valueFiles・マルチソースの設定とargo-cd chartでのインストール【3.5系】" url: "https://www.issoh.co.jp/tech/details/18562/" published: 2026-10-19 updated: 2026-10-19 categories: ["インフラ・クラウド"] publisher: "株式会社一創" --- # 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設定をコード付きで解説](https://www.issoh.co.jp/tech/details/15438/)、Helmのチャート・リポジトリ・リリースの概念は[Helmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説](https://www.issoh.co.jp/tech/details/7694/)で整理しています。 ### helm installを使わないためhelm lsにリリースが出ない理由 公式の[FAQ](https://argo-cd.readthedocs.io/en/stable/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へのアップグレードガイド](https://argo-cd.readthedocs.io/en/stable/operator-manual/upgrading/3.4-3.5/)によると、3.5でArgo CDに同梱されるHelmは4.2系に上がりました。[Helmのユーザーガイド](https://argo-cd.readthedocs.io/en/stable/user-guide/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](https://argo-cd.readthedocs.io/en/stable/operator-manual/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](https://argo-cd.readthedocs.io/en/stable/user-guide/multiple%5Fsources/)です。`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](https://www.issoh.co.jp/tech/details/18553/)で扱っています。 ### 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](https://github.com/argoproj/argo-helm/tree/main/charts/argo-cd)を使うと、レプリカ数や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のリリース一覧](https://github.com/argoproj/argo-helm/releases)では、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件と修正版](https://www.issoh.co.jp/tech/details/18560/)にまとめました。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](https://www.issoh.co.jp/tech/details/15572/)の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導入支援](https://www.issoh.co.jp/service/system/devops/)で設計から運用の引き継ぎまで相談を受けています。 ## よくある質問 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を消してから作り直す形にします。 ## 関連記事 - [ArgoCDとは？GitOpsの仕組みとインストール・Sync設定をコード付きで解説](https://www.issoh.co.jp/tech/details/15438/)：Argo CDの仕組みと公式マニフェストでのインストール手順 - [Helmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説](https://www.issoh.co.jp/tech/details/7694/)：chart・リポジトリ・リリースの基本とhelmコマンド - [GitOpsとは：4原則とPush型との違い、Argo CD・Fluxの最小構成YAML](https://www.issoh.co.jp/tech/details/18553/)：valuesをGitで管理する前提の運用モデル - [Kustomizeとは？base・overlaysの仕組みとHelmとの違い・導入判断を実装者目線で解説](https://www.issoh.co.jp/tech/details/15572/)：Helmを使わずに環境差分を扱う選択肢 - [Argo CDの脆弱性一覧と対処：2026年10月のCritical4件と修正版3.5.4・3.4.10・3.3.15への更新手順](https://www.issoh.co.jp/tech/details/18560/)：chartで入れる版を決める前に確認する脆弱性情報 - [Argo Workflowsとは？DAG・WorkflowTemplate・CronWorkflowのYAML実装とArgo CDとの役割分担](https://www.issoh.co.jp/tech/details/18558/)：同じArgoプロジェクトでジョブ実行を担う製品 - [ArgoCD ApplicationSetの使い方：List・Cluster・Git・Matrixジェネレーターで複数クラスタへ展開するYAML【3.5系】](https://www.issoh.co.jp/tech/details/18565/)：Helm chartを複数クラスタ・複数環境へ展開するApplicationSetの書き方 --- 出典: [ArgoCDでHelm chartを使う方法：valueFiles・マルチソースの設定とargo-cd chartでのインストール【3.5系】]()（株式会社一創）