Index

Документация по установке и использованию GitLab Runner Operator через OLM (Operator Lifecycle Manager) в рамках платформы AIOps.

Описание

GitLab Runner Operator — официальный Kubernetes-оператор от GitLab для управления GitLab Runner инстансами через CRD Runner.

В данном проекте оператор устанавливается строго через OLM, что гарантирует:

корректную установку CRD (полная схема)
управляемые обновления оператора
отсутствие «урезанных» CRD и рассинхронизации схем

Архитектура

┌──────────────────────────────────────────┐
│ OLM (Operator Lifecycle Manager)         │
│ namespace: olm                           │
│                                          │
│ ├─ olm-operator                          │
│ ├─ catalog-operator                     │
│ └─ operatorhubio-catalog                │
└──────────────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────┐
│ GitLab Runner Operator                   │
│ namespace: tech-gitlab-runner-operator   │
│                                          │
│ ├─ Controller Manager                    │
│ │   └─ CRD: runners.apps.gitlab.com      │
│ │      (полная схема через OLM)          │
│ └─ kube-rbac-proxy (/metrics)            │
└──────────────────────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────┐
│ GitLab Runner Instances                  │
│ namespace: tech-gitlab-runner-instances  │
│                                          │
│ ├─ Runner (CR)                           │
│ │   └─ gitlab-runner-tech                │
│ ├─ Runner Pod                            │
│ └─ CI Build Pods (Kubernetes executor)   │
└──────────────────────────────────────────┘

Namespaces

Компонент	Namespace
OLM	`olm`, `operators`
GitLab Runner Operator	`tech-gitlab-runner-operator`
GitLab Runner instances	`tech-gitlab-runner-instances`
Monitoring (Prometheus)	`tech-monitoring`

Быстрый старт (OLM)

1. Установка OLM

1	`make olm-install`

Что делает команда:

устанавливает CRD OLM
разворачивает olm-operator и catalog-operator
создаёт namespaces olm и operators

Проверка:

kubectl get pods -n olm
kubectl get pods -n operators

2. Установка GitLab Runner Operator через OLM

1	`make gitlab-runner-olm-install`

В процессе:

создаётся Subscription из OperatorHub (channel stable)
OLM устанавливает полную CRD Runner
оператор управляется через ClusterServiceVersion (CSV)

Проверка:

kubectl get subscription -n operators
kubectl get csv -n operators
kubectl get crd runners.apps.gitlab.com

3. Создание секрета с токеном GitLab

Получите токен в GitLab:

1	`Settings → CI/CD → Runners`

Создание секрета:

1	`make gitlab-runner-create-secret`

Параметры секрета:

name: gitlab-runner-token
namespace: tech-gitlab-runner-instances
key: runner-registration-token

4. Создание Runner instance

1	`make gitlab-runner-create-instance`

После этого оператор создаст Runner Pod и зарегистрирует его в GitLab.

5. Проверка статуса

1	`make gitlab-runner-status`

Также можно проверить вручную:

kubectl -n tech-gitlab-runner-operator get pods
kubectl -n tech-gitlab-runner-instances get pods

Команды Makefile

OLM

make olm-install
make olm-uninstall

GitLab Runner Operator

make gitlab-runner-olm-install
make gitlab-runner-status
make gitlab-runner-uninstall

Runner instances

make gitlab-runner-create-secret
make gitlab-runner-create-instance
make gitlab-runner-update-instance

RBAC для PostgreSQL

make gitlab-runner-apply-rbac     # Применить RBAC для доступа к секретам PostgreSQL
make gitlab-runner-check-rbac     # Проверить текущие права доступа

Конфигурация Runner

Пример Runner Custom Resource:

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: gitlab-runner-tech
  namespace: tech-gitlab-runner-instances
spec:
  gitlabUrl: https://gitlab.com/
  token: gitlab-runner-token

  tags: "kubernetes,ci"
  runUntagged: true
  locked: false

  concurrent: 10
  interval: 30
  logFormat: json

  namespace: tech-gitlab-runner-instances
  buildImage: alpine:latest

Основные параметры:

tags — используются в .gitlab-ci.yml
concurrent — максимальное число параллельных jobs
namespace — где создаются build pods
buildImage — образ по умолчанию

Метрики и мониторинг

Метрики оператора

Источник:

Service: gitlab-runner-controller-manager-metrics-service
Namespace: tech-gitlab-runner-operator
Port: 8443
Protocol: HTTPS (через kube-rbac-proxy)

Используется отдельный ServiceMonitor с:

scheme: https
bearerTokenFile
insecureSkipVerify: true

Метрики GitLab Runner

По умолчанию отключены.

Для включения требуется:

установка оператора через OLM
расширенная CRD
включение через listenAddr или spec.config

После включения:

port: 9242
path: /metrics
Service: gitlab-runner-tech

Prometheus

Метрики собираются через ServiceMonitor в namespace tech-monitoring:

отдельный monitor для оператора
отдельный monitor для runner

Подключение к GitLab

Проверка регистрации Runner

В GitLab:

1	`Settings → CI/CD → Runners`

Runner должен появиться со статусом online и тегами:

1	`kubernetes, ci`

Использование в `.gitlab-ci.yml`

job:
  tags:
    - kubernetes
  script:
    - echo "Running on GitLab Runner (Kubernetes)"

RBAC для доступа к секретам PostgreSQL

GitLab Runner автоматически читает credentials для миграций из Kubernetes секретов, если они не указаны явно в GitLab CI/CD Variables.

Установка RBAC

1	`make gitlab-runner-apply-rbac`

Команда применяет манифест gitlab-runner-rbac.yaml, который создаёт: * Role gitlab-runner-postgres-secrets-reader в namespace tech-postgres-databases * RoleBinding для ServiceAccount gitlab-runner-app-sa

Проверка прав

1	`make gitlab-runner-check-rbac`

Команда проверяет: * Существование ServiceAccount * Права на чтение секретов в namespace tech-postgres-databases * Наличие RoleBinding

Ожидаемый результат:

Checking permissions to read secrets in tech-postgres-databases:
yes

Как это работает

Если в CI указана переменная MIGRATION_ENV_VARS_* (например, MIGRATION_ENV_VARS_STAGE), используется она
Если переменная не указана, система автоматически:
Определяет окружение из CI_ENVIRONMENT_NAME (stage/pre/production)
Читает секрет pg-user-{SERVICE}-{ENV} из namespace tech-postgres-databases
Извлекает credentials и создаёт .env.migration для docker

Обратная совместимость

Старый способ через GitLab CI/CD Variables продолжает работать. Автоматическое чтение K8s секретов включается только если MIGRATION_ENV_VARS_* не указана.

Требования

Секрет должен существовать: make postgres-init-service-db SERVICE=your-service
RBAC должен быть применён: make gitlab-runner-apply-rbac
KUBECONFIG должен быть настроен в CI jobs (уже есть через KUBECONFIG_STAGE/PRE/PROD)

Безопасность

RBAC ограничивает права GitLab Runner: * Только чтение (get) секретов * Только в namespace tech-postgres-databases * Только секреты с префиксом pg-user-*

Troubleshooting

Operator не запускается

kubectl -n operators get csv
kubectl -n tech-gitlab-runner-operator logs deploy/gitlab-runner-gitlab-runnercontroller-manager -c manager

ImagePullBackOff: `ose-kube-rbac-proxy`

В gitlab-runner-operator.yaml у Subscription задано RELATED_IMAGE_KUBE_RBAC_PROXY → публичный kube-rbac-proxy (quay.io/brancz/...), чтобы при установке с нуля OLM мог подставить override (как задумано в Operator SDK для related images).

Если в конкретной версии CSV sidecar всё ещё тянет битый digest из манифеста bundle — это уже разовая операция в кластере (например kubectl set image … kube-rbac-proxy=…), а не часть репозитория.

CRD не принимает новые поля

Причины:

оператор установлен не через OLM
CRD применена вручную
конфликт версий

Проверка схемы:

1	`kubectl explain runner.spec`

Runner не регистрируется в GitLab

kubectl -n tech-gitlab-runner-instances get secret gitlab-runner-token
kubectl -n tech-gitlab-runner-instances logs -l app=gitlab-runner

Build pods не создаются

kubectl top nodes
kubectl -n tech-gitlab-runner-instances get events --sort-by='.lastTimestamp'

Ссылки

GitLab Runner Operator (OperatorHub) https://operatorhub.io/operator/gitlab-runner-operator
GitLab Runner Operator Docs https://docs.gitlab.com/runner/install/operator/
Operator Lifecycle Manager https://olm.operatorframework.io/
GitLab Runner https://docs.gitlab.com/runner/

На странице

Оглавление Описание Архитектура Namespaces Быстрый старт (OLM) 1. Установка OLM 2. Установка GitLab Runner Operator через OLM 3. Создание секрета с токеном GitLab 4. Создание Runner instance 5. Проверка статуса Команды Makefile OLM GitLab Runner Operator Runner instances RBAC для PostgreSQL Конфигурация Runner Метрики и мониторинг Метрики оператора Метрики GitLab Runner Prometheus Подключение к GitLab Проверка регистрации Runner Использование в .gitlab-ci.yml RBAC для доступа к секретам PostgreSQL Установка RBAC Проверка прав Как это работает Обратная совместимость Требования Безопасность Troubleshooting Operator не запускается ImagePullBackOff: ose-kube-rbac-proxy CRD не принимает новые поля Runner не регистрируется в GitLab Build pods не создаются Ссылки