> For the complete documentation index, see [llms.txt](https://utm-1.gitbook.io/utm-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://utm-1.gitbook.io/utm-docs/dokumentaciya/utm-it/resheniya/organizaciya-dostupov/spravochnaya-informaciya/keycloak/instrukcii-po-razvertyvaniyu/razvyortyvanie-keycloak-v-k8s-alisa-ai.md).

# Развёртывание Keycloak в K8S (Алиса AI)

### Развёртывание KeycloakX в Kubernetes (Инструкция от Алиса AI)

#### 1. Подготовка сервера для генерации keystore (192.168.4.31, Ubuntu)

<details>

<summary>Нужно только при включении HTTPS</summary>

**1.1. Установка Java JDK**

```bash
ssh user@192.168.4.31
sudo apt update
sudo apt install openjdk-17-jdk -y

# Проверка установки
java -version
keytool -help
```

**1.2. Генерация keystore.jks**

```bash
# Переходим в рабочую директорию
cd ~/keycloak-certs

# Генерируем keystore
keytool -genkeypair \
  -alias keycloak \
  -keyalg RSA \
  -keysize 2048 \
  -keystore keystore.jks \
  -validity 365 \
  -storepass your_strong_password \
  -keypass your_strong_password \
  -dname "CN=keycloak.utmsoft.ru, OU=IT, O=Company, L=City, ST=Region, C=RU"
```

**Параметры:**

* `your_strong_password` — замените на надёжный пароль (16+ символов, буквы, цифры, спецсимволы);
* `-dname` — укажите актуальные данные вашей организации.

**1.3. Проверка созданного хранилища**

```bash
keytool -list -v -keystore keystore.jks -storepass your_strong_password
```

</details>

#### 2. Кодирование keystore.jks в base64

<details>

<summary>Нужно только при включении HTTPS</summary>

**2.1. Кодирование в base64 (однострочный вариант)**

```bash
base64 ~/keycloak-certs/keystore.jks
```

**2.2. Кодирование с сохранением в файл**

```bash
base64 ~/keycloak-certs/keystore.jks > keystore-base64.txt
```

**2.3. Проверка декодирования (опционально)**

```bash
base64 -d keystore-base64.txt > decoded-keystore.jks
diff ~/keycloak-certs/keystore.jks decoded-keystore.jks
```

Если файлов нет различий — кодирование выполнено верно.

</details>

#### 3. Подготовка манифестов Kubernetes Secrets

**3.1. Манифест для секрета базы данных (keycloak-db-secret.yaml)**

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-secret
  namespace: keycloak
type: Opaque
data:
  username: a2V5Y2xva2s=  # base64("keycloak")
  password: eW91cl9wYXNz  # base64(ваш пароль БД)
```

**3.2. Манифест для секрета администратора (keycloak-admin-secret.yaml)**

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: keycloak-admin-secret
  namespace: keycloak
type: Opaque
data:
  username: YWRtaW4=  # base64("admin")
  password: YWRtaW4xMjM=  # base64(ваш админ-пароль)
```

**3.3. Манифест для keystore (keycloak-keystore-secret.yaml)**

<details>

<summary>Нужно только при включении HTTPS</summary>

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: keycloak-keystore-secret
  namespace: keycloak
type: Opaque
data:
  keystore.jks: |
    # base64-содержимое файла keystore.jks
    # (вставьте строку из keystore-base64.txt)
```

</details>

**3.4. Манифест для пароля keystore (keycloak-keystore-password.yaml)**

<details>

<summary>Нужно только при включении HTTPS</summary>

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: keycloak-keystore-password
  namespace: keycloak
type: Opaque
data:
  password: eW91cl9zdHJvbmdfcGFzc3dvcmQ=  # base64(ваш пароль keystore)
```

</details>

#### 4. Применение манифестов Secrets

```bash
kubectl apply -f keycloak-db-secret.yaml
kubectl apply -f keycloak-admin-secret.yaml
```

<details>

<summary>Нужно только при включении HTTPS</summary>

```bash
kubectl apply -f keycloak-keystore-secret.yaml
kubectl apply -f keycloak-keystore-password.yaml
```

</details>

#### 5. Настройка PostgreSQL

**5.1. Создание базы данных и пользователя**

Подключитесь к PostgreSQL (`192.168.4.9`) как суперпользователь:

```sql
CREATE USER keycloak WITH PASSWORD 'your_secure_db_password';
CREATE DATABASE keycloak;
GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak;
ALTER USER keycloak CREATEDB;
```

**5.2. Проверка подключения**

```bash
psql -h 192.168.4.9 -U keycloak -d keycloak
```

#### 6. Установка и настройка cert-manager

<details>

<summary>Нужно только при включении HTTPS</summary>

**6.1. Добавление репозитория Helm**

```bash
helm repo add jetstack https://charts.jetstack.io
helm repo update
```

**6.2. Установка cert-manager**

```bash
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.15.0
```

**6.3. Проверка установки**

```bash
kubectl get pods -n cert-manager
# Все поды должны быть в статусе Running
```

**6.4. Создание ClusterIssuer для Let’s Encrypt**

Создайте файл `letsencrypt-prod.yaml`:

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    email: your-email@example.com  # Укажите свой email
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - http01:
          ingress:
            class: nginx
```

Примените манифест:

```bash
kubectl apply -f letsencrypt-prod.yaml
```

**6.5. Проверка ClusterIssuer**

```bash
kubectl get clusterissuer -n cert-manager
# Статус должен быть Ready=True
```

</details>

#### 7. Настройка Helm‑чарта KeycloakX

**7.1. Добавление репозитория Codecentric**

```bash
helm repo add codecentric https://codecentric.github.io/helm-charts
helm repo update
```

**7.2. Файл values.yaml (с чтением пароля из Secret)**

На основе файла [values.yaml](https://github.com/codecentric/helm-charts/blob/master/charts/keycloakx/values.yaml)

<details>

<summary>Работа c keycloak по HTTPS</summary>

```yaml
# Количество реплик
replicas: 2

# Образ контейнера
image:
  repository: quay.io/keycloak/keycloak
  tag: 25.0.4
  pullPolicy: IfNotPresent

# Конфигурация БД
database:
  vendor: postgres
  host: 192.168.4.9
  port: 5432
  database: keycloak
  username:
    valueFrom:
      secretKeyRef:
        name: keycloak-db-secret
        key: username
  password:
    valueFrom:
      secretKeyRef:
        name: keycloak-db-secret
        key: password
  schema: public
  jdbcParams: sslmode=require

# Ресурсы
resources:
  requests:
    memory: "1024Mi"
    cpu: "500m"
  limits:
    memory: "2048Mi"
    cpu: "1000m"

# Переменные окружения
extraEnv:
  # Аутентификация Keycloak
  - name: KEYCLOAK_USER
    valueFrom:
      secretKeyRef:
        name: keycloak-admin-secret
        key: username
  - name: KEYCLOAK_PASSWORD
    valueFrom:
      secretKeyRef:
        name: keycloak-admin-secret
        key: password

  # Настройки HTTPS
  - name: KC_HTTPS_KEYSTORE_FILE
    value: "/opt/keycloak/conf/keystore.jks"
  - name: KC_HTTPS_KEYSTORE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: keycloak-keystore-password
        key: password
  - name: KC_HTTPS_PROTOCOL
    value: "TLS"
  - name: KC_HOSTNAME_STRICT
    value: "false"
  - name: KC_HTTP_ENABLED
    value: "false"  # отключаем HTTP

# Mount keystore из Secret
extraVolumeMounts:
  - name: keystore-volume
    mountPath: /opt/keycloak/conf/keystore.jks
    subPath: keystore.jks

extraVolumes:
  - name: keystore-volume
    secret:
      secretName: keycloak-keystore-secret

# Сервис
service:
  type: ClusterIP
  port: 8443  # HTTPS-порт
  annotations: {}

# Ingress
ingress:
  enabled: true
  hostname: keycloak.utmsoft.ru
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
  tls:
    - secretName: keycloak-tls
      hosts:
        - keycloak.utmsoft.ru

```

</details>

Работа c keycloak по HTTP

```yaml
# Количество реплик
replicas: 2


# Образ контейнера
image:
  repository: quay.io/keycloak/keycloak
  tag: 26.4.55.0.4
  pullPolicy: IfNotPresent

# Проверка готовности БД
dbchecker:
  enabled: true
  
# Конфигурация БД
database:
  vendor: postgres
  host: 192.168.4.9
  port: 5432
  database: keycloak
  username:
    valueFrom:
      secretKeyRef:
        name: keycloak-db-secret
        key: username
  password:
    valueFrom:
      secretKeyRef:
        name: keycloak-db-secret
        key: password

# Ресурсы
resources:
  requests:
    memory: "1024Mi"
    cpu: "500m"
  limits:
    memory: "2048Mi"
    cpu: "1000m"


# Переменные окружения
extraEnv:
  # Аутентификация Keycloak
  - name: KEYCLOAK_USER
    valueFrom:
      secretKeyRef:
        name: keycloak-admin-secret
        key: username
  - name: KEYCLOAK_PASSWORD
    valueFrom:
      secretKeyRef:
        name: keycloak-admin-secret
        key: password

  # Настройка HTTP и прокси
  - name: KC_HTTP_ENABLED
    value: "true"
  - name: KC_PROXY_ADDRESS_FORWARDING
    value: "true"
  - name: KC_HOSTNAME
    value: "keycloak.utmsoft.ru"
#  # Для HTTP этот параметр не используется
#  - name: KC_HTTPS_PORT
#    value: "8443"


# Сервис (ClusterIP, только HTTP на 8080)
service:
  type: ClusterIP
  httpPort: 8080
  # httpsPort не указываем — HTTPS отключён
  annotations: {}


# Ingress (без TLS, только HTTP)
ingress:
  enabled: true
  className: nginx  # или другой класс вашего Ingress-контроллера
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
    # Nginx уже завершил HTTPS, поэтому редирект не нужен
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
  hosts:
    - host: keycloak.utmsoft.ru
      paths:
        - path: /
          pathType: Prefix
```

**Важные параметры:**

* `ingress.enabled: true` — включаем Ingress для внешнего доступа;
* `cert-manager.io/cluster-issuer` — указывает cert‑manager, какой ClusterIssuer использовать;
* `secretName: keycloak-tls` — cert‑manager сохранит сертификат в этот Secret.

***

#### 8. Развёртывание через Argo CD

**8.1. Манифест приложения (`keycloak-app.yaml`)**

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: keycloak
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/keycloak-deploy.git
    path: .
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: keycloak
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
```

**8.2. Применение конфигурации**

```bash
kubectl apply -f keycloak-app.yaml -n argocd
```

**8.3. Мониторинг развёртывания**

```bash
argocd app get keycloak
argocd app sync keycloak
```

***

#### 9. Настройка обратного прокси Nginx

Конфигурация Nginx (`/etc/nginx/sites-available/proxy`):

```nginx
server {
  listen 80;
  server_name keycloak.utmsoft.ru;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl;
  server_name keycloak.utmsoft.ru;

  ssl_certificate /etc/letsencrypt/live/utmsoft.ru/fullchain.pem;
  ssl_trusted_certificate /etc/letsencrypt/live/utmsoft.ru/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/utmsoft.ru/privkey.pem;

  location / {
        proxy_pass http://192.168.1.100:31080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;  # Важно!
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-Host $host;       
  }
}
```

**Важные заголовки:**

* `X-Forwarded-Proto: https` — сообщает Keycloak, что клиент использовал HTTPS;
* `X-Real-IP` — передаёт реальный IP клиента;
* `Host` — сохраняет оригинальный хост.

#### 10. Проверка развёртывания

**9.1. Статус подов**

```bash
kubectl get pods -n keycloak
```

Все поды должны быть в статусе `Running`.

**9.2. Статус сервиса и Ingress**

```bash
kubectl get service -n keycloak
kubectl get ingress -n keycloak
```

Убедитесь, что Ingress создан и имеет внешний IP/хост.

**9.3. Статус сертификата**

<details>

<summary>Нужно только при включении HTTPS</summary>

```bash
kubectl get certificate -n keycloak
```

</details>

Статус должен быть `Ready=True`.

**9.4. Статус Secret с сертификатом**

<details>

<summary>Нужно только при включении HTTPS</summary>

```bash
kubectl get secret keycloak-tls -n keycloak
```

</details>

Secret должен существовать и содержать сертификат.

**9.5. Доступ к интерфейсу Keycloak**

Откройте в браузере: `https://keycloak.utmsoft.ru`