ArgoCDでHelmfileを利用する

argocd
helm

2025-07-30

#はじめに

ArgoCDでHelmfileを使ってデプロイできるようにしたいと思います。
ArgoCDとHelmfileの組み合わせの記事はたくさんあるのですが、最新のArgoCDでは、動かなかったりするので、実際に動作するリポジトリを用意しました。

GitHub - cloudandbuild/helmfile-example
Contribute to cloudandbuild/helmfile-example development by creating an account on GitHub.
GitHub - cloudandbuild/helmfile-example favicon github.com
GitHub - cloudandbuild/helmfile-example

#ArgoCDとは

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes.

出典: https://argo-cd.readthedocs.io/en/stable/

ArgoCDは、Kubernetesのための継続的デリバリー(CD)ツールです。GitOpsの原則に基づいており、Gitリポジトリをソースとして、Kubernetesクラスターにアプリケーションをデプロイします。ArgoCDは、アプリケーションの状態をGitリポジトリと同期させることで、インフラストラクチャの管理を簡素化します。

個人的な経験では、k8sを採用している多くの現場でArgoCDが使われている印象があります。

#Helmfileとは

以前の記事をご覧ください。

helmfileの構成と利用について
helmfileの構成と利用について
helmfileの構成と利用について favicon cloudandbuild.jp
helmfileの構成と利用について

ArgoCDでは、KustomizeやHelmなどは、公式でサポートされていますが、Helmfileは公式ではサポートされていません。しかし、Pluginを使うことで、HelmfileをArgoCDで利用することができます。

#リポジトリ

GitHubにサンプルリポジトリを用意しました。

git clone https://github.com/cloudandbuild/helmfile-example.git
cd helmfile-example

このリポジトリには、ArgoCDとHelmfileを使用してKubernetesクラスターにアプリケーションをデプロイするための設定が含まれています。

#ツールのインストール

このリポジトリでは、HelmfileとArgoCDを使用します。以下のコマンドを実行して、必要なツールをインストールします。

# miseがインストールされている前提
mise install
# install helm plugins
helmfile init

#Kubernetesクラスターの準備

Kubernetesクラスターを準備します。以下のコマンドを実行して、Kubernetesクラスターをセットアップします。

# すでにk8sクラスターがある場合は、不要
k3d cluster create

# アクセス確認
kubectl cluster-info

#ArgoCDのインストール

ArgoCDをインストールします。以下のコマンドを実行して、ArgoCDをインストールします。

helmfile -f releases/argocd/helmfile.yaml.gotmpl sync

#ArgoCD Appsのインストール

ArgoCD Appsは、ArgoCDを使用してアプリケーションリソースを管理します。
以下のコマンドを実行して、ArgoCDのAppsを作成します。

helmfile -f releases/argocd-apps/helmfile.yaml.gotmpl sync

#アプリケーションのデプロイ確認

ArgoCDのWeb UIにアクセスして、アプリケーションが正しくデプロイされていることを確認します。
ArgoCDのWeb UIにアクセスするためには、以下のコマンドを実行してポートフォワードを行います。

kubectl port-forward service/argocd-server -n argocd 8080:443

ArgoCDの初期パスワードを取得するために、以下のコマンドを実行します。

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

ArgoCDのWeb UIにアクセスするためには、以下のURLをブラウザで開きます。

open https://localhost:8080/

ログイン画面で、ユーザー名はadmin、パスワードは先ほど取得した初期パスワードを入力します。

#トラブルシューティング

この手順をまとめるまで、下記の問題に直面しました。以下は、よくある問題とその解決策です。

#Helmがファイル書き込み権限エラーを出す

ArgoCDでHelmfileを動かすために、Config Management Pluginを定義しています。
このPluginのなかで、Helmfileのコンテナをサイドカーで実行されるよう定義しています。
このHelmfileのコンテナは、NonRootで実行されるため、Helmfileの実行時にファイル書き込み権限エラーが発生することがあります。

これを回避するために、Helmが書き込みを行うディレクトリを書き込み可能なディレクトリに変更する必要があります。
これはHelmの環境変数を設定することで回避しました。tmpディレクトリは、書き込み可能なボリュームをマウントしておきます。

repoServer:
  extraContainers: 
    - name: helmfile # argocd-cmp-cm ConfigMapのpluginで定義した名前と同じ名前にする
      command:
        - /var/run/argocd/argocd-cmp-server
      image: ghcr.io/helmfile/helmfile:v1.1.3
      env:
+        - name: HELM_CACHE_HOME
+          value: /tmp
+        - name: HELM_CONFIG_HOME
+          value: /tmp

#次のステップ

ArgoCDとHelmfileの簡単な連携だけしましたが、実際の運用では、以下のような機能を利用することを検討すると良いでしょう。

#TLS終端をIngressで行う

ArgoCDのWeb UIにアクセスするために、ポートフォワードを行う代わりに、Ingressを使用してTLS終端を行うことができます。これにより、外部からのアクセスが簡単になります。

#プライベートレポジトリ

repositoriesを定義する際に、Githubであれば、UsernameとPasswordにPAT(Personal Access Token)を設定することで、プライベートリポジトリからHelmチャートを取得できます。

#マルチクラスタ管理

複数のdestinationを指定することでマルチクラスタを単一のArgoCDで管理できるようになります。実際には、ApplicationSetというリソースを使うことで、複数のクラスターに対してアプリケーションをデプロイすることができます。これも別途記事で紹介したいと思います。

#ユーザー管理

Googleアカウントなどで、ArgoCDのユーザーを管理できるようにしたいと思います。ArgoCDは、OAuth2やOIDCをサポートしているので、Googleアカウントでのログインも可能です。これにより、ユーザー管理が簡素化されます。

#複数プロジェクト

ArgoCDでは、複数のプロジェクトを管理することができます。これにより、異なるチームやアプリケーションごとにアクセス制御を行うことができます。プロジェクトごとに異なるリソース制限やアクセス権を設定することが可能です。

#まとめ

今回は、ArgoCDでHelmfileを使ってデプロイできるようにしてみました。
Helmfileを使うことで、複数のHelmチャートを一元管理できるため、Kubernetesクラスターの管理がより効率的になります。また、ArgoCDを使用することで、GitOpsの原則に基づいた継続的デリバリーが実現できます。