2026.03.10

MicroK8s 環境で ArgoCD と Keycloak を OIDC 連携する手順【完全ガイド】

keycloak Kubernetes t-inagaki アジャイル＆DevOps クラウドネイティブ

はじめに

KubernetesのGitOpsツールとして有名な ArgoCD ですが、本番環境では SSO（OIDC認証） によるログイン管理を行うことが多いです。

今回は MicroK8s 上の ArgoCD と Keycloak をOIDC連携する手順を解説します。

また、実際に構築してハマったポイントも紹介します。

構成

全体アーキテクチャと構成要素は以下の通りです。

全体アーキテクチャ

構成要素

MicroK8s
ArgoCD
Keycloak
Ingress

OIDCシーケンス図

OIDCでは Authorization Code Flow を使用します。

microk8sのインストール

Homebrewを使用してmicrok8sをインストールします。以下のコマンドを実行してください。

brew install microk8s

VMの作成とmicrok8s環境構築

microk8sの仮想マシンを作成し、Kubernetesクラスタを構築します。

このコマンドはインタラクティブに実行され、マルチパスの仮想マシンがセットアップされます。

microk8s install

アドオンの有効化

microk8sで必要なアドオンを有効化します。

DNSアドオンはコンテナ間の名前解決を、Ingressアドオンはクラスタへの外部トラフィックルーティングを提供します。

microk8s enable dns
microk8s enable ingress

Node IPの確認

Multipassで作成された仮想マシンの一覧と、各マシンのIPアドレスを確認します。

このIPアドレスは後でhostsファイルやDNS設定で使用します。

multipass list

hostsの設定

ローカルマシンの/etc/hostsファイルに、microk8sの仮想マシンのIPアドレスとドメイン名のマッピングを追加します。

これにより、ブラウザからドメイン名でアクセスできるようになります。

sudo vim /etc/hosts

以下の行を追加してください（IPアドレスはmicrok8sの環境に合わせて調整）：

192.168.2.10 argocd.example.com
192.168.2.10 keycloak.example.com

mkcertのインストール

ローカルマシンで自己署名証明書を生成するために、mkcertをインストールします。

brew install mkcert nss
mkcert -install

証明書の作成

mkcertを使用して、ArgoCDとKeycloak用の自己署名証明書を生成します。

このコマンドは指定したドメイン名に対応した証明書ファイル（.pemと-key.pem）を作成し、ローカル開発環境でHTTPS通信を実現します。

mkcert argocd.example.com
mkcert keycloak.example.com

CoreDNS設定

microk8sクラスタ内のDNS解決を設定するため、CoreDNSのConfigMapを編集します。

以下のコマンドでConfigMapを開き、ローカルドメイン名とIPアドレスのマッピングを追加します。

kubectl -n kube-system edit configmap coredns

ConfigMapのdataセクションに以下のhostsプラグイン設定を追加してください：

hosts {
  192.168.2.10 argocd.example.com
  192.168.2.10 keycloak.example.com
  fallthrough
}

この設定により、クラスタ内のPodからドメイン名でArgoCDとKeycloakに接続できるようになります。

ArgoCDインストール

ArgoCDをhelmでインストールしたい場合は、拙著のhttps://www.creationline.com/tech-blog/cloudnative/kubernetes/79136を参照ください。

ArgoCDネームスペースの作成

ArgoCDをインストールするための専用ネームスペースを作成します。

kubectl create namespace argocd

ArgoCDマニフェストのインストール

ArgoCDの公式リポジトリから安定版のマニフェストをダウンロードし、argocdネームスペースに適用します。

これにより、ArgoCDサーバー、APIサーバー、リポジトリサーバーなど、必要なコンポーネントがKubernetesクラスタにデプロイされます。

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

ArgoCDの TLS シークレット作成

ArgoCDサーバーで HTTPS 通信を実現するために、mkcert で生成した証明書をKubernetesのシークレットとして登録します。

このシークレットは後の Ingress 設定で参照されます。

kubectl -n argocd create secret tls argocd-tls \
  --cert=argocd.example.com.pem \
  --key=argocd.example.com-key.pem

ArgoCD Ingress設定ファイルの作成

ArgoCDサーバーへのHTTPS通信を実現するために、Ingressリソースを定義します。

以下のコマンドでIngress設定ファイルを生成し、先ほど作成したTLSシークレット（argocd-tls）を使用してHTTPS通信を有効化します。

このIngressにより、argocd.example.comドメインでArgoCDサーバーにアクセスできるようになります。

cat <<EOF > argocd-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
spec:
  ingressClassName: public
  tls:
  - hosts:
    - argocd.example.com
    secretName: argocd-tls
  rules:
  - host: argocd.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 80
EOF

ArgoCD Ingress設定の適用

作成したIngress設定ファイルをKubernetesクラスタに適用します。

このコマンドにより、ArgoCDサーバーへのHTTPS通信ルーティングが有効化され、argocd.example.comドメインでアクセスできるようになります。

kubectl -n argocd apply -f argocd-ingress.yaml

ArgoCDサーバーのInsecureモード設定

ArgoCDサーバーをInsecureモードで実行するよう設定します。

このモードにより、ArgoCDサーバーがHTTP通信を受け入れるようになり、Ingressを経由したHTTPS通信が正しくルーティングされます。

以下のコマンドでArgoCDサーバーのデプロイメントを編集します。

kubectl -n argocd edit deploy argocd-server

spec.template.spec.containers[0].argsセクションに--insecureフラグを追加してください：

spec:
  template:
    spec:
      containers:
      - args:
        - /usr/local/bin/argocd-server
        - --insecure  # <-- ここを追加

ファイルを保存すると、設定が自動的に反映されます。

ArgoCDの初期管理者パスワード取得

ArgoCDサーバーのデプロイ時に自動生成される初期管理者パスワードを取得します。

このパスワードはKubernetesのシークレットに保存されており、以下のコマンドで復号化して表示できます。

取得したパスワードはArgoCDログイン時に使用します。

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

ArgoCDへのログイン確認

ブラウザを起動し、https://argocd.example.comを入力して、ユーザー名:admin、パスワードは先ほど取得した初期パスワードでログインできることを確認します。

Keycloakインストール

Keycloakネームスペースの作成

Keycloakをインストールするための専用ネームスペースを作成します。

kubectl create namespace keycloak

Keycloakマニフェストのインストール

Keycloakの公式リポジトリから、Kubernetes環境用のマニフェストをダウンロードし、keycloakネームスペースに適用します。

このコマンドにより、KeycloakサーバーとPostgreSQLデータベースなど、必要なコンポーネントがKubernetesクラスタにデプロイされます。

kubectl -n keycloak create -f \
  https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/main/kubernetes/keycloak.yaml

Keycloak TLS シークレット作成

Keycloakサーバーで HTTPS 通信を実現するために、mkcert で生成した証明書をKubernetesのシークレットとして登録します。

このシークレットは後の Ingress 設定で参照されます。

kubectl -n keycloak create secret tls keycloak-tls \
  --cert=keycloak.example.com.pem \
  --key=keycloak.example.com-key.pem

Keycloak Ingress設定ファイルの作成

KeycloakサーバーへのHTTPS通信を実現するために、Ingressリソースを定義します。

以下のコマンドでIngress設定ファイルを生成し、先ほど作成したTLSシークレット（keycloak-tls）を使用してHTTPS通信を有効化します。

このIngressにより、keycloak.example.comドメインでKeycloakサーバーにアクセスできるようになります。

cat <<EOF > keycloak-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: keycloak-ingress
  namespace: keycloak
spec:
  ingressClassName: public
  tls:
  - hosts:
    - keycloak.example.com
    secretName: keycloak-tls
  rules:
  - host: keycloak.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: keycloak
            port:
              number: 8080
EOF

Keycloak Ingress設定の適用

作成したIngress設定ファイルをKubernetesクラスタに適用します。

このコマンドにより、Keycloakサーバーへの HTTPS 通信ルーティングが有効化され、keycloak.example.comドメインでアクセスできるようになります。

kubectl -n keycloak apply -f keycloak-ingress.yaml

cat <<EOF > keycloak-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: keycloak-ingress
  namespace: keycloak
spec:
  ingressClassName: public
  tls:
  - hosts:
    - keycloak.example.com
    secretName: keycloak-tls
  rules:
  - host: keycloak.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: keycloak
            port:
              number: 8080
EOF

kubectl -n keycloak apply -f keycloak-ingress.yaml

Keycloakへのログイン確認

ブラウザを起動し、https://keycloak.example.comを入力して、ユーザー名:admin、パスワード:adminでログインできることを確認します。

RootCA登録

ローカルのルートCA証明書パスを確認

mkcertで生成したローカルのルートCA証明書の保存先パスを確認します。

このパスは次のステップでKubernetesのConfigMapに登録する際に必要になります。

mkcert -CAROOT

このコマンドを実行すると、ルートCA証明書が保存されているディレクトリパス（通常は~/.local/share/mkcert）が表示されます。

表示されたパスのrootCA.pemファイルを、後続のコマンドで使用してください。

ArgoCDへのルートCA証明書登録

ArgoCDがKeycloakの自己署名証明書を信頼するよう、ローカルのルートCA証明書をConfigMapとして登録します。

以下のコマンドでルートCA証明書をArgoCDネームスペースに登録し、その後ArgoCDサーバーを再起動して設定を反映させます。

kubectl -n argocd create configmap argocd-tls-certs-cm \
  --from-file=keycloak.example.com=<rootCA.pemのフルパス> \
  --dry-run=client \
  -o yaml \
  | kubectl apply -f -

ArgoCDサーバーの再起動

ルートCA証明書の登録後、ArgoCDサーバーを再起動して設定を反映させます。

このコマンドにより、ArgoCDサーバーのPodが再作成され、登録したCA証明書が読み込まれるようになります。

kubectl -n argocd rollout restart deployment argocd-server

Keycloak設定

Keycloakレルムの作成

Keycloakにログインした後、新しいレルムを作成します。

管理画面左上から「Create Realm」を選択し、レルム名を「platform」に設定して作成します。このレルムがArgoCDのOIDC統合の基盤となります。

レルム名の入力

「Create Realm」ダイアログで、レルム名として「platform」を入力します。

このレルム名がArgoCDのOIDC統合設定で使用されます。

ArogoCD用のClientの作成

ArgoCD用のクライアントを作成するために「Create Client」をクリックします。

クライアント設定

「Create Client」ダイアログで、以下の設定を行います。

クライアントIDを「argocd」に設定し、クライアント認証を有効化して、ArgoCDがKeycloakと安全に通信できるようにします。

クライアント認証の有効化

「Capability config」で「Client authentication」を有効化します。

ログイン設定

「Root URL」「Home URL」「Valid redirect URLs」「Valid Post logout redirect URLs」「Web origines」を画像の通りに入力してください。

クライアントシークレットの確認

Keycloakクライアント設定ページで、生成されたクライアントシークレットを確認します。

このシークレットはArgoCDのOIDC設定で使用される重要な認証情報です。

後の手順でこの値をコピーして使用してください。

クライアントスコープの作成

「groups」というクライアントスコープを作成します。

マッパーの追加

「groups」というマッパーを追加します。

クライアントスコープの追加

「Add client scope」をクリックします。

Mapperの設定

ArgoCDがKeycloakからグループ情報を取得するために、Mapperを設定します。

クライアントスコープの詳細ページから「Add mapper」を選択し、ユーザーグループ情報をトークンに含めるMapperを作成してください。

これにより、ArgoCDはKeycloakから認証情報とグループメンバーシップを同時に取得できるようになります。

グループの作成

「argocd-admin」というグループを作成します。

ユーザー作成

「admin」ユーザーを作成し、「argocd-admin」グループに所属させます。

初期パスワード設定

「admin」ユーザーの初期パスワードを設定します。

ArgoCD OIDC設定

ArgoCDのシークレットにクライアントシークレットを登録

Keycloakで生成したクライアントシークレットをArgoCDのシークレットに登録します。

このコマンドにより、ArgoCDがKeycloakとの通信時にクライアント認証を行うための認証情報が設定されます。

<REPLACE_WITH_CLIENT_SECRET>部分には、Keycloakで確認したクライアントシークレットの値をそのまま貼り付けてください。

kubectl -n argocd patch secret argocd-secret \
  --patch='{"stringData": {
    "oidc.keycloak.clientSecret": "<REPLACE_WITH_CLIENT_SECRET>"
  }}'

ArgoCDのConfigMapを編集してOIDC設定を追加

ArgoCDサーバーがKeycloakを使用してOIDC認証を行うよう設定します。

以下のコマンドでArgoCDの設定ファイル（ConfigMap）を編集し、Keycloakの接続情報を追加します。

kubectl -n argocd edit configmap argocd-cm

ConfigMapのdataセクションに以下の設定を追加してください。

clientSecretにはKeycloakで生成したクライアントシークレットを、rootCAにはmkcertで生成したルートCA証明書の内容を貼り付けます：

data:
  url: https://argocd.example.com
  oidc.config: |
    name: Keycloak
    issuer: https://keycloak.example.com/realms/platform
    clientID: argocd
    clientSecret: $oidc.keycloak.clientSecret
    requestedScopes: ["openid", "profile", "email"]
    rootCA: |
      -----BEGIN CERTIFICATE-----
      （ここに rootCA.pem の中身を貼る：行頭はこのまま2スペースインデント）
      -----END CERTIFICATE-----

ArgoCDサーバーの再起動

OIDC設定を反映させるため、ArgoCDサーバーを再起動します。

このコマンドにより、ArgoCDサーバーのPodが再作成され、ConfigMapに追加した新しい設定が読み込まれるようになります。

kubectl -n argocd rollout restart deployment argocd-server

動作確認

https://argocd.example.com

ログイン画面にKeycloakログインボタンが表示されます。

ハマったポイント

① ConfigMap変更だけでは反映されない

OIDC設定を追加してもログイン画面に Keycloakログインボタンが表示されないことがあります。

原因は ArgoCD Server Podの再起動が必要なためです。

ArgoCDは起動時にConfigMapを読み込むため、 ConfigMap変更だけでは設定が反映されません。

kubectl -n argocd rollout restart deployment argocd-server

このコマンドでArgoCD Server Podを再起動すると設定が反映されます。

② issuer設定ミスでOIDC discoveryが失敗

OIDC設定を誤ると以下のエラーが発生します。

failed to query provider "": 
Get "/.well-known/openid-configuration": unsupported protocol scheme ""

私が間違えた誤り

issuer: keycloak.example.com

正しい設定

issuer: https://keycloak.example.com/realms/platform

OIDCでは

<issuer>/.well-known/openid-configuration

にアクセスしてDiscoveryを行うため、realmまで含める必要があります。

③ ArgoCD PodからKeycloakの名前解決ができない

OIDC設定後に以下のエラーが発生することがあります。

failed to query provider "https://keycloak.example.com/realms/platform":
Get "https://keycloak.example.com/realms/platform/.well-known/openid-configuration":
dial tcp: lookup keycloak.example.com on 10.152.183.10:53: no such host

原因は Pod内DNSでKeycloakの名前解決ができないことです。

ローカルPCの /etc/hosts を設定してもPodのDNSには影響しません。

解決方法

CoreDNSにhosts設定を追加します。

kubectl -n kube-system edit configmap coredns

hosts {
  192.168.2.10 argocd.example.com
  192.168.2.10 keycloak.example.com
  fallthrough
}

kubectl -n kube-system rollout restart deployment coredns

④ 自己署名証明書でTLS検証エラー

ArgoCDからKeycloakに接続する際、以下のエラーが出る場合があります。

x509: certificate signed by unknown authority

原因は ArgoCDがmkcertのRootCAを信頼していないためです。

解決方法

RootCAをArgoCDに登録します。

mkcert -CAROOT

kubectl -n argocd create configmap argocd-tls-certs-cm --from-file=keycloak.example.com=<rootCA.pem>

その後ArgoCD Serverを再起動します。

kubectl -n argocd rollout restart deployment argocd-server

まとめ

今回の記事では、MicroK8s環境上でArgoCDとKeycloakをOIDC連携させる手順を紹介しました。

ArgoCDにSSOを導入することで、ユーザー認証をKeycloakに集約でき、より実運用に近い形でGitOps環境を構築することができます。

構築自体は公式ドキュメントを参考にすれば実現できますが、実際に試してみるといくつかのポイントでつまずくことがあります。

特に、issuer URLの指定ミスによるOIDC Discoveryの失敗や、Pod内部からKeycloakの名前解決ができない問題、自己署名証明書の信頼設定などはハマりやすいポイントでした。

また、ArgoCDではConfigMap変更後にPodの再起動が必要になる点も見落としがちなポイントです。

これらの点を押さえておくことで、MicroK8sのローカル環境でもArgoCDとKeycloakを組み合わせたSSO構成を比較的スムーズに構築できます。

本記事が、ArgoCDの認証基盤をOIDCで構築する際の参考になれば幸いです。

参考資料

Author

t-inagaki

t-inagakiの記事一覧