Привет всем! В данной статье мы осветим наш опыт внедрения в платформу Gitorion собственного приватного реестра Docker-образов на базе CNCF Distribution Registry. Рассмотрим настройку аутентификации Docker-registry в Keycloak и подключение Web-интерфейса к Docker-registry.

Назначение и основные функции приватного реестра Docker-образов

Приватный реестр Docker-образов является подсистемой непрерывной доставки Continuous Delivery платформы Gitorion.

Пайплайны Jenkins билдят Docker-образы микросервисов и push-ат их в приватный реестр Docker-registry. Ниже для наглядности приведем команду сборки микросервиса backend:

docker buildx build --push -t registry.gitorion.ru/owneruser/backend/main:5c83f123556419654beb22eda68d1478c7d13825 --cache-to 'type=registry,ref=registry.gitorion.ru/owneruser/backend/main:latest,mode=min' --cache-from 'type=registry,ref=registry.gitorion.ru/owneruser/backend/main:latest' --cache-from 'type=registry,ref=registry.gitorion.ru/php:8.3.1-fpm-alpine3.19' .

после сборки, Docker-образ микросервиса бэкенда:

registry.gitorion.ru/owneruser/backend/main:5c83f123556419654beb22eda68d1478c7d13825

push-ится в частный приватный реестр Docker-образов https://registry.gitorion.ru

Чтобы ускорить процесс сборки, в качестве Docker-кэша используются Docker-образы, которые так же pull-ятся из частного приватного репозитория Docker-образов:

--cache-from 'type=registry,ref=registry.gitorion.ru/owneruser/backend/main:latest'
--cache-from 'type=registry,ref=registry.gitorion.ru/php:8.3.1-fpm-alpine3.19'

На этапе деплоя Kubernetes pull-ит Docker-образы микросервисов из приватного реестра Docker-образов и использует для запуска контейнеров микросервисов в кластере Kubernetes:

apiVersion: v1
items:
- apiVersion: apps/v1
  kind: Deployment
  metadata:
    annotations:
      meta.helm.sh/release-name: staging-owneruser-backend
      meta.helm.sh/release-namespace: staging
    labels:
      app: staging-owneruser-backend
      app.kubernetes.io/managed-by: Helm
    name: staging-owneruser-backend
    namespace: staging
  spec:
    replicas: 1
    selector:
      matchLabels:
        app: staging-owneruser-backend
    strategy:
      rollingUpdate:
        maxSurge: 25%
        maxUnavailable: 25%
      type: RollingUpdate
    template:
      metadata:
          labels:
          app: staging-owneruser-backend
      spec:
        containers:
        - image: registry.gitorion.ru/owneruser/backend/main:5c83f123556419654beb22eda68d1478c7d13825
          imagePullPolicy: IfNotPresent
          name: backend

Также собственный приватный реестр Docker-образов позволяет обойти проблему с лимитом на количество скачиваний Docker-образов из публичного реестра. Публичные реестры имеют лимит на количество скачиваний с одного IP. При интенсивной работе большой команды программистов, часто запускающих пайплайны, скачивающие базовые образы из публичного реестра, можно вскоре получить ошибку, которая остановит всю работу:

ERROR: failed to solve: alpine:3.19.1: failed to resolve source metadata for docker.io/library/alpine:3.19.1: failed to copy: httpReadSeeker: failed open: unexpected status code https://registry-1.docker.io/v2/library/alpine/manifests/sha256:c5b1261d6d3e43071626931fc004f70149baeba2c8ec672bd4f27761f8e1ad6b: 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

Поэтому, мы скачиваем один раз базовые образы микросервисов из публичного реестра и помещаем их в собственный приватный реестр Docker-образов:

docker login registry.gitorion.ru
docker pull php:8.3.1-fpm-alpine3.19
docker tag php:8.3.1-fpm-alpine3.19 registry.gitorion.ru/php:8.3.1-fpm-alpine3.19
docker push registry.gitorion.ru/php:8.3.1-fpm-alpine3.19

И в дальнейшем пайплайны сборки Docker-образов используют базовые образы из частного приватного реестра Docker-образов. Пример базового слоя в Dockerfile микросервиса бэкенда:

FROM registry.gitorion.ru/php:8.3.1-fpm-alpine3.19

Кроме того, Docker-образы из приватного репозитория используются как Docker-кэш для ускорения сборки в команде билдинга Docker-образа docker buildx build

--cache-from 'type=registry,ref=registry.gitorion.ru/php:8.3.1-fpm-alpine3.19'

Агент Jenkins при запуске каждого пайплайна скачивает Docker-образ buildkit, что тоже может привести к блокировке из-за лимита на скачивание из публичного репозитория. Поэтому мы скачали Docker-образ buildkit из публичного реестра, поместили его в приватный реестр платформы, и пайплайны используют Docker-образ buildkit из приватного реестра:

docker buildx create --name container '--driver=docker-container' --config /etс/buildkitd.toml --driver-opt 'image=registry.gitorion.ru/buildkit:buildx-stable-1' --use container

Указанный выше подход позволяет вести разработку на платформе автономно без регулярного скачивания Docker-образов из публичного реестра при запуске каждого пайплайна.

Установка и настройка Docker-registry

Ниже мы приведем спецификацию контейнера в yaml манифесте и поясним ключевые настройки аутентификации Docker-registry в Keycloak. Как получить значения параметров из Keycloak мы поясним в следующем пункте чуть ниже.

          containers:
            - image: registry:2
              name: docker-registry
              env:
              - name: REGISTRY_AUTH
                value: "token"
              - name: REGISTRY_AUTH_TOKEN_REALM
                value: "https://auth.gitorion.ru/realms/gitorion/protocol/docker-v2/auth"
              - name: REGISTRY_AUTH_TOKEN_SERVICE
                value: "docker-registry"
              - name: REGISTRY_AUTH_TOKEN_ISSUER
                value: "https://auth.gitorion.ru/realms/gitorion"
              - name: REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE
                value: "/opt/certs/localhost_trust_chain.pem"
              - name: REGISTRY_HTTP_HEADERS_Access-Control-Allow-Origin
                value: "[https://registry.gitorion.ru]"
              - name: REGISTRY_HTTP_HEADERS_Access-Control-Allow-Methods
                value: "[HEAD,GET,OPTIONS,DELETE]"
              - name: REGISTRY_HTTP_HEADERS_Access-Control-Allow-Credentials
                value: "[true]"
              - name: REGISTRY_HTTP_HEADERS_Access-Control-Allow-Headers
                value: "[Authorization,Accept,Cache-Control]"
              - name: REGISTRY_HTTP_HEADERS_Access-Control-Expose-Headers
                value: "[Docker-Content-Digest]"
              - name: REGISTRY_STORAGE_DELETE_ENABLED
                value: "true"

https://auth.gitorion.ru - URL, по которому доступен Keycloak в платформе;

image: registry:2 - используйте официальный образ Docker-registry;

REGISTRY_AUTH - выберите тип аутентификации в Docker-registry по токену из Keycloak;

REGISTRY_AUTH_TOKEN_REALM - задайте путь к области Keycloak, в которой находится Client для Docker-registry;

REGISTRY_AUTH_TOKEN_SERVICE - задайте имя клиента Docker-registry;

REGISTRY_AUTH_TOKEN_ISSUER - задайте источник, выдающий токены;

REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE - подключите SSL-сертификат доступа к области Keycloak, в которой находится Client для Docker-registry. Как получить сертификат области из Keycloak объяснено в следующем пункте ниже;

REGISTRY_HTTP_HEADERS_Access-Control-Allow-Origin — при подключении аутентификации типа token, Docker-registry активирует механизм безопасности единого источника CORS и разрешает доступ к частному реестру только из своего же домена.

Настройка аутентификации Docker-registry в Keycloak

Чтобы не дублироваться, мы не будем в данной статье останавливаться на создании пользователей, групп и ролей, которые освещены в статье о внедрении в платформу Gitorion единой системы аутентификации SSO на базе Keycloak. Здесь мы рассмотрим только нюансы подключения Docker-registry к Keycloak.

По умолчанию Keycloak запускается без поддержки "docker-v2", и ее нужно включить, передав параметр KC_FEATURES в команде запуска Keycloak, либо через переменную окружения:

containers:
- env:
  - name: KC_FEATURES
    value: docker
  image: docker.io/bitnami/keycloak:24.0.4-debian-12-r2
  imagePullPolicy: IfNotPresent

В списке "Client Type" на вкладке создания клиента наряду с "OpenID Connect" и "SAML" появится "docker-v2".

Cоздайте Client для приватного реестра Docker-registry и задайте "docker-v2" в поле "Client Type". Введите имя клиента Docker-registry в поле "Client ID" такое же, как задали в переменной окружения REGISTRY_AUTH_TOKEN_SERVICE при настройке Docker-registry в предыдущем пункте выше, и нажмите кнопку Next.

В следующем окне вводить ничего не нужно, просто нажмите кнопку Next и затем кнопку Save.

Далее перейдите к настройкам только что созданного клиента docker-registry и в правом верхнем углу получите параметры настройки Docker-registry, нажав кнопку "Action" и выбрав пункт "Download adapter config".

Выберите пункт "Docker Compose YAML" и нажмите кнопку "Download".

В zip архиве в файле docker-compose.yaml вы найдете значения всех переменных окружения, которые нужно задать в предыдущем пункте настройки Docker-registry выше. В этом же архиве располагается файл certs/localhost_trust_chain.pem с SSL-сертификатом области, который нужно подключить к контейнеру docker-registry и задать в переменной окружения REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE.

Теперь можно залогиниться в наш частный репозиторий Docker-registry пользователем из Keycloak:

docker login registry.gitorion.ru
Authenticating with existing credentials...
Username (user): user
Password:
WARNING! Your password will be stored unencrypted in /root/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

Еще в данном пункте хотим рассказать о неочевидной ошибке, сбивающей с толку, на диагностику и устранение которой может уйти много времени и сил. Даже при правильных настройках команда docker login может получить ошибку:

Cookie not found. Please make sure cookies are enabled in your browser.

а в логах Keycloak появится сообщение:

2024-05-18 18:27:25,916 WARN  [org.keycloak.events] (executor-thread-1) type="CUSTOM_REQUIRED_ACTION_ERROR", realmId="1b5c5f6d-630a-4e5f-ad2e-a442eb1ca4d6", clientId="null", userId="null", ipAddress="10.10.7.143", error="cookie_not_found"

Такую ошибку может вызывать окно Keycloak, требующее от пользователя при первом входе сменить логин и пароль. Команда docker login ждет от Keycloak проверки логина и пароля и токен в ответ, чтобы поместить его в cookie. Вместо этого получает в ответ окно с предложением смены пароля и выдает данную ошибку.

Если администратор Keycloak отключит принудительную смену пароля при первом входе, то ошибку все еще может вызвать окно, предлагающее пользователю заполнить его персональные данные в профиле.

Общая рекомендация: перед первой попыткой залогиниться командой docker login, предварительно залогиньтесь в любой другой сервис платформы, имеющий Web-интерфейс, и убедитесь, что пользователь успешно аутентифицируется в Keycloak.

Подключение Web-интерфейса к Docker-registry

Docker-registry в стоке не имеет графического интерфейса пользователя. Можно конечно обращатьca к Docker-registry curl-ом, но это неудобно. Поэтому мы решили подключить Web-интерфейс от Joxit к Docker-registry.

Автор проекта приводит пример подключения своего Web-интерфейса к Docker-registry с аутентификацией по токену из Keycloak. Тестовый пример разработан для Docker-compose, но его можно использовать как отправную точку для подключения Web-интерфейса к Docker-registry в Kubernetes. Позади Ingress-nginx устанавливается промежуточный прокси на базе Nginx, который запрашивает у пользователя логин и пароль при доступе к Web-интерфейсу Docker-registry, передает их в Keycloak, получает токен доступа из Keycloak, и дальше Web-интерфейс использует токен при подключении к Docker-registry.

Пользователь вводит свой логин и пароль из Keycloak и получает доступ к Web-интерфейсу Docker-registry. На стартовой странице появится список всех репозиториев в приватном реестре Docker-образов.

Можно раскрыть один из репозиториев и получить список Tag-ов в нем и дополнительную информацию. Если потребуется, удалить ненужные Docker-образы.

Заключение

В данной статье мы осветили наш опыт внедрения собственного частного реестра Docker-образов на базе Docker-registry c аутентификацией в Keycloak и Web-интерфейсов от Joxit. Будем рады фидбеку, замечаниям и конструктивной критике. Не сочтите за труд и проголосуйте, пожалуйста, ниже. Спасибо за внимание!