---
title: KeycloakをHelmでインストールするメモ
tags: ["Keycloak", "Kubernetes", "Helm", "PostgreSQL"]
categories: ["Middleware", "IdentityProvider", "Keycloak"]
date: 2025-10-03T06:15:29Z
updated: 2025-10-03T06:15:29Z
---

https://github.com/codecentric/helm-charts/tree/master/charts/keycloakx のHelm Chartを使ってKeycloakをKubernetesにインストールするメモ。

まずはKeycloak用のNamespaceを作成する。

```bash
kubectl create namespace keycloak
```

PostgreSQLをインストールする。ここでは動作検証用のシンプルなStatefulSetを作成する。実際にはManaged PostgreSQLサービスなどを利用することを推奨。

```yaml
cat <<EOF > postgres.yaml
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: keycloak-db
spec:
  serviceName: keycloak-db-headless
  selector:
    matchLabels:
      app: keycloak-db
  replicas: 1
  template:
    metadata:
      labels:
        app: keycloak-db
    spec:
      containers:
      - name: keycloak-db
        image: postgres:17
        volumeMounts:
        - mountPath: /data
          name: cache-volume
        env:
        - name: POSTGRES_USER
          valueFrom:
            secretKeyRef:
              name: keycloak-db
              key: username
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: keycloak-db
              key: password
        - name: PGDATA
          value: /data/pgdata
        - name: POSTGRES_DB
          value: keycloak
      volumes:
      - name: cache-volume
        emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: keycloak-db-headless
spec:
  clusterIP: None
  selector:
    app: keycloak-db
  ports:
  - port: 5432
    targetPort: 5432
    protocol: TCP
    name: postgres
---
EOF
```

PostgreSQLのユーザー名とパスワードをKubernetes Secretとして作成し、PostgreSQLをデプロイする。

```bash
kubectl create secret generic keycloak-db \
  --from-literal=username=testuser \
  --from-literal=password=testpassword \
  -n keycloak

kubectl apply -f postgres.yaml -n keycloak
```

PostgreSQLが起動したら、KeycloakをHelmでインストールする。次のようなvaluesファイルを作成する。


```yaml
cat <<EOF > keycloak-values.yaml
---
args: [ "start" ]
extraEnv: |
  - name: KC_BOOTSTRAP_ADMIN_USERNAME
    value: admin
  - name: KC_BOOTSTRAP_ADMIN_PASSWORD
    value: admin
  - name: KC_DB_URL
    value: jdbc:postgresql://keycloak-db-headless:5432/keycloak
  - name: KC_DB_USERNAME
    valueFrom:
      secretKeyRef: 
        name: keycloak-db
        key: username
  - name: KC_DB_PASSWORD
    valueFrom:
      secretKeyRef: 
        name: keycloak-db
        key: password
  - name: KC_HOSTNAME_STRICT
    value: "false"
  - name: KC_LOG_CONSOLE_OUTPUT
    value: json
  - name: KC_LOG_CONSOLE_JSON_FORMAT
    value: ecs
  - name: JAVA_OPTS_APPEND
    value: >-
      -Djgroups.dns.query={{ include "keycloak.fullname" . }}-headless
database:
  vendor: postgres
cache:
  stack: jdbc-ping
proxy:
  mode: xforwarded
ingress:
  enabled: true
  annotations:
    projectcontour.io/tls-cert-namespace: projectcontour
  rules:
  - host: keycloak.lan.ik.am
    paths:
    - path: /
      pathType: Prefix
  tls:
  - hosts:
    - keycloak.lan.ik.am
    secretName: default-tls
---
EOF
```

次のコマンドでHelm Chartのテンプレートを確認できる。

```bash
helm template -n keycloak keycloakx oci://ghcr.io/codecentric/helm-charts/keycloakx --version 7.1.3 -f keycloak-values.yaml
```

次のコマンドでKeycloakをインストールする。

```bash
helm upgrade --install -n keycloak keycloakx oci://ghcr.io/codecentric/helm-charts/keycloakx --version 7.1.3 -f keycloak-values.yaml --create-namespace --wait
```

次のコマンドでKeycloakのPod、StatefulSet、Ingressを確認できる。

```bash
$ kubectl get pod,sts,ing -n keycloak -owide
NAME                READY   STATUS    RESTARTS   AGE   IP             NODE     NOMINATED NODE   READINESS GATES
pod/keycloak-db-0   1/1     Running   0          56m   10.1.173.137   cherry   <none>           <none>
pod/keycloakx-0     1/1     Running   0          55m   10.1.173.187   cherry   <none>           <none>

NAME                           READY   AGE   CONTAINERS    IMAGES
statefulset.apps/keycloak-db   1/1     56m   keycloak-db   postgres:17
statefulset.apps/keycloakx     1/1     55m   keycloak      quay.io/keycloak/keycloak:26.3.3

NAME                                  CLASS     HOSTS                ADDRESS          PORTS     AGE
ingress.networking.k8s.io/keycloakx   contour   keycloak.lan.ik.am   192.168.11.240   80, 443   55m
```

IngressのアドレスにブラウザでアクセスするとKeycloakのログイン画面が表示される。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1852/a1cd32ed-3d54-4929-bec5-79e2692e6e48.png)