Стадия жизненного цикла модуля: General Availability
У модуля есть требования для установки

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

Как мы обеспечиваем безопасную коммуникацию между компонентами?

Мы используем шифрование TLS для всех внутренних коммуникаций между сервисами GitLab внутри кластера Kubernetes. Мы также гарантируем, чтобы любой внешний доступ был защищен с помощью HTTPS или другого безопасного протокола.

Как мы обеспечиваем безопасный сбор метрик?

Мы защищаем сбор метрик, используя контейнер sidecar kube-rbac-proxy вместе с RBAC Kubernetes. Kube-rbac-proxy действует как слой аутентификации и авторизации, обеспечивая доступ к конечным точкам метрик только для запросов с действующими правами.

Как разрешить доступ к мониторингу извне кластера

По умолчанию эндпоинт метрик Code (/metrics) доступен только с адресов 127.0.0.0/8 и подсети подов кластера. Запросы с любых других адресов отклоняются самим Code.

Чтобы разрешить доступ внешней системе мониторинга (например, Prometheus, работающему вне кластера), добавьте её IP-адреса или CIDR-подсети в spec.monitoring.ipWhitelist:

spec:
  monitoring:
    ipWhitelist:
      - 10.0.0.0/24    # подсеть внешнего Prometheus
      - 192.168.1.100  # конкретный хост мониторинга

Указанные адреса добавляются к списку по умолчанию — стандартные значения (127.0.0.0/8 и pod CIDR) сохраняются.

Примечание: принимаются только IPv4- и IPv6-адреса и CIDR-подсети в стандартной записи. Одиночные адреса хостов без длины префикса (например, 192.168.1.100) также допустимы.

Какое шифрование TLS поддерживается?

  • Для всех входящих и исходящих TLS-соединений требуется TLS 1.2 или выше.
  • TLS-сертификаты должны иметь не менее 112 бит. Ключи RSA, DSA и DH короче 2048 бит, а
    также ключи ECC короче 224 бит не безопасны и запрещены.

Как указать секрет для поля в CodeInstance?

Некоторые поля поддерживают следующий шаблон для чтения чувствительных данных: secret/<secret-name>/<key-name> . Оператор сам проверит и извлечет данные из Secret ресурса расположенного в NS d8-code.

Вопросы связанные с Gitaly серверами

Почему сервис имеет расширенные права?

Gitaly использует механизм cgroup для управления потреблением ресурсов во время операций над Git репозиториями. Чтобы работать в среде Kubernetes, мы должны разрешить pod в его собственную cgroup по пути /sys/fs/cgroup на ноде.

Capabilities:

  • SETUID , SETGID, CHOWN - Используются init контейнером, чтобы задать пользователя git:git в cgroup пода
  • FOWNER - для обхода проверки если директория с Git данными имеет другого владельца
  • SYS_ADMIN - обязательно для монтирования cgroupfs и работы cgroup иерархией
  • SYS_RESOURCE - обязательно для работы с лимитами ресурсов в cgroup (CPU, Memory, IO)
  • SYS_PTRACE - для выполнения системных вызовов вида process_vm_readv / process_vm_writev
  • KILL - обязательно для завершения или передачи сигнала процессам в управляемых cgroups

Как обновить одну из Gitaly реплик

Кейсы:

  • Перезалить данные на ноду Gitaly после пересоздания PV
  • Ручное обновление ноды когда данные устарели

Для обновления определенной ноды Gitaly выполните:

kubectl exec -i -t -n d8-code praefect-0 -c praefect -- praefect -config /etc/gitaly/config.toml verify --virtual-storage <virtual_storage> --storage <gitaly_pod_name>

Данные всех репозиториев на <gitaly_pod_name> будут помечены как устаревшие для приоритизации перепроверки. Перепроверка будет работать асинхронно в фоновом режиме.

Репозиторий существует, но его файлы не найдены

Если репозиторий отображается в интерфейсе Code, но при попытке работы с ним возникают ошибки доступа к файлам, следуйте инструкции ниже для диагностики.

  1. Убедитесь, что поды praefect и gitaly запущены и находятся в состоянии Ready:

    kubectl -n d8-code get pods -l app.kubernetes.io/component=praefect
kubectl -n d8-code get pods -l app.kubernetes.io/component=gitaly

  2. Проверьте состояние базы Praefect и доступность узлов Gitaly:

    kubectl -n d8-code exec -it sts/praefect -- praefect --config /etc/gitaly/config.toml check

    В выводе не должно быть ошибок. Если ошибки присутствуют — обратитесь в поддержку.

  3. Проверьте наличие метаданных о репозитории в базе Praefect. ID проекта можно найти в интерфейсе Code в разделе Settings > General:

    kubectl -n d8-code exec -it sts/praefect -- praefect --config /etc/gitaly/config.toml metadata --repository-id <project-id>

    Пример успешного вывода:

    Repository ID: 2238
Virtual Storage: "default"
Relative Path: "@hashed/45/1b/451b...git"
Replica Path: "@cluster/repositories/7a/98/2238"
Primary: "gitaly-default-0"
Generation: 0
Replicas:
- Storage: "gitaly-default-0"
  Assigned: true
  Generation: 0, fully up to date
  Healthy: true
  Valid Primary: true
  Verified At: 2026-03-16 13:43:34 +0000 UTC

    Интерпретация результата:

    • Секция Replicas содержит запись с Healthy: true — метаданные Praefect в порядке. Praefect знает, на каком узле Gitaly хранится репозиторий и считает его живым. В этом случае проблема на стороне Gitaly: файлы репозитория отсутствуют на диске — удалены или потеряны при миграции. Необходимо восстановить репозиторий из бэкапа.

    • Вывод пустой или секция Replicas отсутствует — база Praefect не содержит информации об этом репозитории. Причиной может быть ручное вмешательство в базу, ошибка во время миграции или миграция на непустую базу Praefect (данные уже существовали в базе до начала миграции — это необходимо исключать при подготовке к миграции). Во всех этих случаях необходимо восстановить базу Praefect из бэкапа.

Конфигурация сети

Как использовать ownLoadBalancer с зарезервированным публичным IPv4-адресом в Yandex Cloud

Чтобы назначить вашему ownLoadBalancer зарезервированный публичный IPv4-адрес, достаточно указать специальный label. Пример:

network:
    ownLoadBalancer:
      annotations:
        yandex.cpi.flant.com/listener-address-ipv4: xx.xx.xx.xx
      enabled: true

Важно: Указанный IPv4-адрес должен быть заранее зарезервирован в вашем облаке через Yandex Cloud Console или CLI.

Как задать класс для LoadBalancer сервиса когда используется ownLoadBalancer

Если конфигурация вашего кластера не имеет LoadBalancer класс по-умолчанию, вы можете использовать параметр ownLoadBalancer.loadBalancerClass, чтобы задать необходимый

Пример:

network:
    ownLoadBalancer:
      enabled: true
      loadBalancerClass: my-lb-class

Важно: поле loadBalancerClass нельзя изменить без пересоздания CR

Как настроить web UI с пользовательским сертификатом

Создайте TLS Secret в d8-code и укажите его в spec.network.web.https:

spec:
  network:
    certificates:
      customCAs:
        - secret: code-web-tls
          keys:
            - tls.crt
    web:
      hostname: code.example.com
      https:
        mode: CustomCertificate
        customCertificate:
          secretName: code-web-tls

Подробную пошаговую инструкцию и чеклист проверки смотрите в документации по сети.

Миграция с/на Omnibus

Не могу открыть Gitlab Web IDE

Если вы столкнулись с ошибкой Could not find a callback URL, обновите ее URL в меню Admin > Applications на актуальную

Компоненты

Как включить или выключить toolbox

toolbox — опциональный компонент и включён по умолчанию.

  • Чтобы явно включить toolbox:
spec:
  features:
    toolbox:
      enabled: true # значение по умолчанию
  • Чтобы выключить toolbox:
spec:
  features:
    toolbox:
      enabled: false

Если вы используете процедуры, которым нужен Toolbox Pod (например, Rails-консоль или некоторые сценарии backup/restore), убедитесь, что toolbox включён.

Как отключить Code Operator?

Чтобы приостановить управление ресурсами оператором без полного отключения модуля, установите spec.maintenance в значение NoResourceReconciliation в ModuleConfig:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: code
spec:
  enabled: true
  version: 1
  maintenance: NoResourceReconciliation

После применения остановите под оператора:

kubectl -n d8-code scale --replicas=0 deploy/code-operator

Перед применением убедитесь, что понимаете последствия этой настройки — см. документацию ModuleConfig.

Как восстановить оператор после его отключения?

  1. Удалите spec.maintenance из ModuleConfig:

    apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: code
spec:
  enabled: true
  version: 1

  2. Запустите под оператора:

    kubectl -n d8-code scale --replicas=1 deploy/code-operator

  3. Дождитесь, пока оператор вернётся в состояние Running и возобновит управление ресурсами.

Бэкап бакет S3 быстро увеличивается в размерах

Используйте backup.keepLast для настройки хранения бэкапов. Подробнее.

Миграция на registry с базой данных для метаданных(v2)

Этапы миграции

Удаление модуля

При необходимости Вы можете удалить модуль и полностью очистить кластер от его следов в 2 простых шага:

  • Выключите модуль, следуя обычной процедуре выключения модуля (одинакова для всех модулей кластера DKP)
  • Добавьте в moduleConfig аннотацию modules.deckhouse.io/allow-disable: "true", чтобы предотвратить ошибку удаления от deckhouse-controller
  • Измените enable параметр в moduleConfig со значения true на false
  • Удалите namespace, так как он может содержать некоторые остаточные артефакты в виде configmap или секретов: kubectl delete ns d8-code

Перед удалением секретов не забудьте сохранить secrets/rails-secret иначе Вы потеряете возможность восстановиться из существующиъ бекапов в будущем

Поддерживает ли Code инкрементные бэкапы?

Code не поддерживает полноценные инкрементальные бекапы.