#Быстрый старт

Этот документ поможет вам быстро понять, как создать OCI Connector и использовать его для безопасного доступа к реестрам контейнеров без прямой работы с учетными данными.

#Введение

#Применимые сценарии

OCI (Open Container Initiative) Connector предоставляет безопасный способ:

• Доступа к реестрам контейнеров (Docker Hub, Harbor и др.) без встраивания учетных данных в рабочие нагрузки
• Централизованного управления информацией для аутентификации в реестрах
• Использования прокси-механизма для безопасной отправки и получения образов контейнеров
• Настройки контейнерных инструментов для работы с прокси реестра

Этот подход особенно полезен для:

• CI/CD конвейеров, которым необходимо отправлять образы в приватные реестры
• Многочисленных команд, которым нужно безопасно совместно использовать учетные данные реестра
• Процессов сборки контейнеров внутри Kubernetes

#Оценочное время чтения

15 минут

#Примечания

• OCI connector использует интеграцию с CSI драйвером для безопасной инъекции учетных данных реестра.
• Разным контейнерным инструментам (Buildah и др.) может потребоваться специфическая конфигурация для доступа к небезопасным реестрам.
• Файлы конфигурации, сгенерированные коннектором, действительны в течение 30 минут.

#Предварительные требования

• Kubernetes кластер с установленной системой Connectors (Operator, Core и компоненты OCI). Подробнее об установке смотрите в Installation Guide.
• kubectl, настроенный для работы с вашим кластером
• Учетные данные для доступа к реестру контейнеров (Docker Hub, Harbor и др.)
• Базовые знания ресурсов Kubernetes

#Обзор процесса

#Шаги выполнения

#Шаг 1: Создать Namespace

Создайте выделенный namespace для демонстрации:

kubectl create ns oci-connector-demo

#Шаг 2: Создать учетные данные реестра и OCI Connector

Создайте Secret с учетными данными реестра и ресурс OCI Connector. Более подробную информацию о создании и настройке коннекторов смотрите в Connectors Quick Start Guide.

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: registry-auth
  namespace: oci-connector-demo
type: cpaas.io/distribution-registry-token
stringData:
  username: your-username  # Замените на имя пользователя вашего реестра
  password: your-token     # Замените на пароль/токен вашего реестра
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: oci-connector
  namespace: oci-connector-demo
spec:
  connectorClassName: oci
  address: "https://index.docker.io"  # Замените на адрес вашего реестра
  auth:
    name: tokenAuth
    secretRef:
      name: registry-auth
EOF

Проверьте, что коннектор находится в статусе "Ready":

kubectl get connector oci-connector -n oci-connector-demo

Вывод должен быть следующим:

NAME           CLASS   ADDRESS               READY   AGE
oci-connector  oci     https://index.docker.io True    1m

#Шаг 3: Создать задачу сборки/отправки контейнера

Создайте ConfigMap с примером Dockerfile:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: dockerfile
  namespace: oci-connector-demo
data:
  Dockerfile: |
    FROM scratch
    LABEL maintainer="example@example.com"
    WORKDIR /app
    ENV APP_VERSION="1.0.0"
EOF

Создайте задачу, которая использует коннектор для сборки и отправки образа контейнера:

cat <<EOF | kubectl apply -f -
apiVersion: batch/v1
kind: Job
metadata:
  name: image-build
  namespace: oci-connector-demo
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: buildkit
        image: moby/buildkit:v0.11.0
        securityContext:
          privileged: true
        env:
        - name: BUILDKITD_FLAGS
          value: "--config /etc/buildkit/buildkitd.toml"
        command:
        - /bin/sh
        - -c
        args:
        - |
          set -ex
          buildctl-daemonless.sh \
          build \
          --progress=plain \
          --frontend=dockerfile.v0 \
          --local context=/workspace \
          --local dockerfile=/workspace \
          --output type=image,name=c-oci-connector.oci-connector-demo.svc.cluster.local/namespaces/oci-connector-demo/connectors/oci-connector/your-username/test-image:v1,push=true
        volumeMounts:
        - name: dockerfile
          mountPath: /workspace
        - name: docker-config
          mountPath: /root/.docker
        - name: buildkitd-config
          mountPath: /etc/buildkit
      volumes:
      - name: dockerfile
        configMap:
          name: dockerfile
      - name: docker-config
        csi:
          readOnly: true
          driver: connectors-csi
          volumeAttributes:
            connector.name: "oci-connector"
            configuration.names: "docker-config"
      - name: buildkitd-config
        csi:
          readOnly: true
          driver: connectors-csi
          volumeAttributes:
            connector.name: "oci-connector"
            configuration.names: "buildkitd"
EOF

Ключевые параметры в определении томов:

• connector.name: имя вашего OCI коннектора
• configuration.names: указывает, какую конфигурацию генерировать из OCI ConnectorClass:
  • "docker-config": генерирует конфигурацию аутентификации (config.json), необходимую для любых операций с реестром
  • "buildkitd": генерирует конфигурацию демона BuildKit для доступа к небезопасному реестру
• mountPath: указывает, куда монтировать файл конфигурации в контейнере:
  • "/root/.docker" для конфигурации аутентификации OCI CLI, например buildkit, buildah
  • "/etc/buildkit" для конфигурации BuildKit

#Шаг 4: Проверить выполнение

Проверьте логи задачи, чтобы убедиться, что образ успешно собран и отправлен:

kubectl logs -f job/image-build -n oci-connector-demo

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

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

После успешного выполнения всех шагов вы увидите:

1. OCI коннектор в статусе "Ready":

   NAME           CLASS   ADDRESS               READY   AGE
   oci-connector  oci     https://index.docker.io True    5m

2. Успешную операцию сборки и отправки образа в логах задачи, показывающую, что образ был отправлен в реестр через прокси коннектора.

3. Адрес прокси коннектора в поле статуса:

   status:
     proxy:
       httpAddress:
         url: http://c-oci-connector.oci-connector-demo.svc.cluster.local

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

OCI Connector работает следующим образом:

1. Создает прокси-сервис, который находится между вашими рабочими нагрузками и реестром контейнеров
2. Внедряет информацию для аутентификации при прохождении запросов через прокси
3. Предоставляет файлы конфигурации для контейнерных инструментов для работы с прокси

Коннектор генерирует три типа файлов конфигурации, которые служат разным целям:

1. docker-config: создает файл config.json с необходимой информацией для аутентификации при доступе к прокси-сервису

   {
     "auths": {
       "<proxy-address>": {
         "auth": "<auth-token>"
       }
     }
   }

   Эта конфигурация необходима для аутентификации и требуется для всех операций с контейнерами.

2. buildkitd: создает файл buildkitd.toml, который настраивает BuildKit на доверие к небезопасному прокси реестра

   insecure-entitlements = [ "network.host", "security.insecure" ]
   [registry."<proxy-address>"]
     http = true

   Это нужно только при использовании BuildKit для сборки и отправки образов.

Чтобы просмотреть сгенерированную конфигурацию:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: inspect-config
  namespace: oci-connector-demo
spec:
  containers:
  - name: inspector
    image: busybox
    command: ["sleep", "3600"]
    volumeMounts:
    - name: docker-config
      mountPath: /mnt/docker
  volumes:
  - name: docker-config
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "oci-connector"
        configuration.names: "docker-config"
EOF

Просмотрите сгенерированную конфигурацию:

kubectl exec -it inspect-config -n oci-connector-demo -- cat /mnt/docker/config.json

#Устранение неполадок

Если операция с контейнером не удалась, проверьте следующее:

1. Статус коннектора: убедитесь, что коннектор в состоянии "Ready":

   kubectl describe connector oci-connector -n oci-connector-demo

2. Права RBAC: проверьте правильность настройки RoleBinding.

3. Доступ к реестру: убедитесь, что учетные данные имеют доступ к указанному репозиторию.

4. Монтирование конфигурации: проверьте, что тома с конфигурацией корректно смонтированы в задаче.

5. Адрес прокси: убедитесь, что вы используете правильный адрес прокси из status.proxy.httpAddress.url в ссылках на образы.

#Следующие шаги

После успешной отправки первого образа с помощью OCI Connector вы можете:

• Использовать коннектор в Kubernetes workload для получения приватных образов
• Интегрировать с CI/CD конвейерами для сборки и отправки образов
• Настроить различные контейнерные инструменты для работы с коннектором
• Использовать коннектор с разными сервисами реестров