Alauda DevOps Pipelines Docs
  • Русский

    • Настройка пользовательских сертификатов

    Для администраторов

    Это руководство предназначено для администраторов кластера, которым необходимо настроить PAC для доверия самоподписанным сертификатам или сертификатам пользовательского центра сертификации (CA) для Git-провайдеров.

    Примечание: В этом документе <pac-namespace> или tekton-pipelines обозначают пространство имён, в котором развернут PAC. По умолчанию это tekton-pipelines, но вы можете изменить его через параметр targetNamespace в CR OpenShiftPipelinesAsCode. Замените <pac-namespace> или tekton-pipelines на фактическое имя вашего пространства имён, если оно отличается.

    В этом руководстве объясняется, как настроить PAC для работы с Git-хостингами, использующими самоподписанные сертификаты или сертификаты, подписанные пользовательским CA. Эта настройка применима ко всем Git-провайдерам (GitHub Enterprise, GitLab self-hosted, Bitbucket Server и др.).

    Содержание

    Предварительные требованияОбзорШаг 1: Подготовка сертификата CAШаг 2: Создание ConfigMap с сертификатом CAМетод 1: Из файлаМетод 2: Ручное созданиеШаг 3: Монтирование сертификата в контроллер PACДля CR OpenShiftPipelinesAsCodeДля CR TektonConfigШаг 4: Применение конфигурацииШаг 5: Проверка настройки сертификатаПроверка монтирования сертификатаПроверка логов контроллера PACТест с репозиториемУстранение неполадокПроверка, что сертификат не доверенПроверка срока действия сертификатаНеправильный сертификатПод не перезапускаетсяНесколько сертификатовВариант 1: Объединить сертификаты в одном ConfigMapВариант 2: Использовать отдельные ConfigMapЛучшие практики1. Управление сертификатами2. Безопасность3. Устранение неполадокСледующие шаги

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

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

    • Развернутый компонент PAC
    • Права администратора кластера
    • Доступ к файлу сертификата CA
    • Возможность изменять CR OpenShiftPipelinesAsCode или CR TektonConfig

    Обзор

    Если ваш Git-хостинг использует самоподписанные сертификаты или сертификаты, подписанные пользовательским CA, то поды контроллера PAC должны доверять этим сертификатам для успешного подключения к Git-сервису. Для этого необходимо:

    1. Создать ConfigMap с сертификатом CA
    2. Смонтировать сертификат в поды контроллера PAC
    3. Настроить Git на использование этого сертификата

    Шаг 1: Подготовка сертификата CA

    Получите файл сертификата CA у администратора вашего Git-хостинга или у центра сертификации вашей организации.

    Распространённые места расположения сертификатов CA:

    • Self-hosted GitLab: обычно доступен в установке GitLab или у вашего CA организации
    • GitHub Enterprise: доступен у администратора GitHub Enterprise Server
    • Bitbucket Server: доступен у администратора Bitbucket Server

    Файл сертификата должен быть в формате PEM:

    -----BEGIN CERTIFICATE-----
<certificate-content>
-----END CERTIFICATE-----

    Шаг 2: Создание ConfigMap с сертификатом CA

    Создайте ConfigMap, содержащий сертификат CA, в пространстве имён PAC (по умолчанию: tekton-pipelines, замените на ваше пространство имён, если оно отличается):

    Метод 1: Из файла

    kubectl create configmap git-ca-cert \
  --from-file=ca.crt=/path/to/ca.crt \
  -n <pac-namespace>  # По умолчанию: tekton-pipelines

    Пример вывода:

    configmap/git-ca-cert created

    Метод 2: Ручное создание

    Создайте YAML-файл git-ca-cert-configmap.yaml:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: git-ca-cert
  namespace: <pac-namespace>  # По умолчанию: tekton-pipelines
data:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <your-ca-certificate-content>
    -----END CERTIFICATE-----

    Примените его:

    kubectl apply -f git-ca-cert-configmap.yaml

    Пример вывода:

    configmap/git-ca-cert created

    Примечание: Замените <your-ca-certificate-content> на фактическое содержимое сертификата.

    Шаг 3: Монтирование сертификата в контроллер PAC

    Смонтируйте сертификат в поды контроллера PAC, обновив CR OpenShiftPipelinesAsCode или CR TektonConfig.

    Для CR OpenShiftPipelinesAsCode

    Если вы используете CR OpenShiftPipelinesAsCode:

    apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  settings:
    application-name: Pipelines as Code CI
    hub-url: http://tekton-hub-api.tekton-pipelines:8000/v1
  targetNamespace: tekton-pipelines  # Пространство имён по умолчанию, можно изменить
  options:
    deployments:
      pipelines-as-code-controller:
        spec:
          template:
            spec:
              containers:
              - name: pac-controller
                volumeMounts:
                - name: git-ca-cert
                  mountPath: /etc/ssl/certs/git-ca.crt
                  subPath: ca.crt
                  readOnly: true
                env:
                - name: GIT_SSL_CAINFO
                  value: /etc/ssl/certs/git-ca.crt
                - name: SSL_CERT_FILE
                  value: /etc/ssl/certs/git-ca.crt
              volumes:
              - name: git-ca-cert
                configMap:
                  name: git-ca-cert

    Для CR TektonConfig

    Если вы используете CR TektonConfig (для развертываний OpenShift):

    apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  platforms:
    openshift:
      pipelinesAsCode:
        enable: true
        options:
          deployments:
            pipelines-as-code-controller:
              spec:
                template:
                  spec:
                    containers:
                    - name: pac-controller
                      volumeMounts:
                      - name: git-ca-cert
                        mountPath: /etc/ssl/certs/git-ca.crt
                        subPath: ca.crt
                        readOnly: true
                      env:
                      - name: GIT_SSL_CAINFO
                        value: /etc/ssl/certs/git-ca.crt
                      - name: SSL_CERT_FILE
                        value: /etc/ssl/certs/git-ca.crt
                    volumes:
                    - name: git-ca-cert
                      configMap:
                        name: git-ca-cert

    Важно:

    • Сертификат монтируется в контейнер по пути /etc/ssl/certs/git-ca.crt
    • Переменные окружения GIT_SSL_CAINFO и SSL_CERT_FILE указывают Git использовать этот сертификат
    • После обновления CR оператор автоматически перезапустит поды контроллера PAC

    Шаг 4: Применение конфигурации

    Примените обновлённый CR:

    kubectl apply -f your-cr-file.yaml

    Пример вывода:

    openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code configured

    Дождитесь перезапуска подов контроллера PAC:

    kubectl rollout status deployment/pipelines-as-code-controller -n <pac-namespace>  # Замените <pac-namespace> на ваше фактическое пространство имён (по умолчанию: tekton-pipelines)

    Пример вывода:

    Waiting for deployment "pipelines-as-code-controller" rollout to finish: 0 of 1 updated replicas are available...
deployment "pipelines-as-code-controller" successfully rolled out

    Шаг 5: Проверка настройки сертификата

    Проверка монтирования сертификата

    Убедитесь, что сертификат смонтирован в поде контроллера PAC:

    # Установите ваше пространство имён PAC (по умолчанию: tekton-pipelines)
PAC_NAMESPACE="tekton-pipelines"

kubectl get pod -n ${PAC_NAMESPACE} \
  -l app=pipelines-as-code-controller \
  -o jsonpath='{.items[0].spec.volumes}' | jq

    Пример вывода:

    [
  {
    "name": "tls",
    "secret": {
      "defaultMode": 420,
      "optional": true,
      "secretName": "pipelines-as-code-tls-secret"
    }
  }
]

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

    Проверка логов контроллера PAC

    Проверьте логи контроллера PAC на наличие ошибок, связанных с сертификатами:

    # Установите ваше пространство имён PAC (по умолчанию: tekton-pipelines)
PAC_NAMESPACE="tekton-pipelines"

kubectl logs -n ${PAC_NAMESPACE} \
  -l app=pipelines-as-code-controller \
  --tail=100

    Если настройка выполнена правильно, в логах не должно быть ошибок SSL/TLS сертификатов.

    Тест с репозиторием

    Запустите тестовый pipeline из репозитория, размещённого на вашем Git-сервисе:

    # Сделайте коммит для запуска pipeline
git commit --allow-empty -m "Test certificate configuration"
git push origin main

    Пример вывода:

    [main abc1234] Test certificate configuration
Enumerating objects: 3, done.
Writing objects: 100% (2/2), 240 bytes | 240.00 KiB/s, done.
To https://gitlab.example.com/user/repo
   def5678..abc1234  main -> main

    Проверьте, что PipelineRun создан успешно:

    kubectl get pipelineruns -n <your-namespace>

    Пример вывода:

    NAME                    STARTED        DURATION   STATUS
test-pipeline-xxxxx     1 minute ago  25s        Succeeded

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

    Проверка, что сертификат не доверен

    Проблема: PAC по-прежнему не может подключиться к Git-сервису из-за проблем с сертификатом.

    Решения:

    1. Проверьте формат сертификата: Убедитесь, что сертификат в формате PEM с правильными маркерами BEGIN/END
    2. Проверьте путь сертификата: Убедитесь, что сертификат смонтирован по правильному пути
    3. Проверьте переменные окружения: Убедитесь, что GIT_SSL_CAINFO и SSL_CERT_FILE установлены корректно
    4. Проверьте ConfigMap: Убедитесь, что ConfigMap существует и содержит сертификат: 
      kubectl get configmap git-ca-cert -n <pac-namespace> -o yaml  # Замените <pac-namespace> на ваше фактическое пространство имён (по умолчанию: tekton-pipelines)

    Пример вывода:

    apiVersion: v1
data:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDXTCCAkWgAwIBAgIJAK...
    -----END CERTIFICATE-----
kind: ConfigMap
metadata:
  name: git-ca-cert
  namespace: tekton-pipelines

    Проверка срока действия сертификата

    Проблема: Сертификат CA истёк.

    Решения:

    1. Получите новый сертификат CA у вашего центра сертификации

    2. Обновите ConfigMap:

      # Замените <pac-namespace> на ваше фактическое пространство имён (по умолчанию: tekton-pipelines)
kubectl create configmap git-ca-cert \
  --from-file=ca.crt=/path/to/new-ca.crt \
  -n <pac-namespace> \
  --dry-run=client -o yaml | kubectl apply -f -

      Пример вывода:

      configmap/git-ca-cert configured

    3. Перезапустите поды контроллера PAC:

      kubectl rollout restart deployment/pipelines-as-code-controller -n <pac-namespace>  # Замените <pac-namespace> на ваше фактическое пространство имён (по умолчанию: tekton-pipelines)

    Неправильный сертификат

    Проблема: Используется неправильный сертификат CA для вашего Git-сервиса.

    Решения:

    1. Убедитесь, что используете правильный сертификат CA для вашего Git-хостинга
    2. Для self-hosted сервисов получите сертификат непосредственно от сервиса
    3. Для корпоративных сервисов обратитесь к администратору за правильным сертификатом

    Под не перезапускается

    Проблема: Поды контроллера PAC не перезапускаются после обновления CR.

    Решения:

    1. Проверьте статус CR:

      kubectl get openshiftpipelinesascodes

      Пример вывода:

      NAME                  VERSION   READY   REASON
pipelines-as-code    0.x.x     True    Ready

    2. Проверьте логи оператора:

      kubectl logs -n tekton-operator -l app=tekton-operator --tail=100

    Пример вывода (пример записей в логе):

    {"level":"info","ts":"2024-01-01T12:00:00Z","logger":"operator","msg":"Processing OpenShiftPipelinesAsCode CR"}
    1. Перезапустите деплоймент вручную: 
      kubectl rollout restart deployment/pipelines-as-code-controller -n <pac-namespace>  # Замените <pac-namespace> на ваше фактическое пространство имён (по умолчанию: tekton-pipelines)

    Несколько сертификатов

    Если необходимо доверять нескольким сертификатам CA (например, для нескольких Git-хостингов), можно:

    Вариант 1: Объединить сертификаты в одном ConfigMap

    Объедините несколько сертификатов в одном файле:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: git-ca-cert
  namespace: <pac-namespace>  # По умолчанию: tekton-pipelines
data:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    <certificate-1-content>
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    <certificate-2-content>
    -----END CERTIFICATE-----

    Вариант 2: Использовать отдельные ConfigMap

    Используйте отдельные ConfigMap и монтируйте их в разные места, затем настройте Git на использование бандла сертификатов:

    env:
- name: GIT_SSL_CAINFO
  value: /etc/ssl/certs/ca-bundle.crt
- name: SSL_CERT_FILE
  value: /etc/ssl/certs/ca-bundle.crt

    Создайте бандл сертификатов, объединив все сертификаты в один файл.

    Лучшие практики

    1. Управление сертификатами

    • Храните безопасно: Храните сертификаты CA в защищённом хранилище
    • Контроль версий: Отслеживайте изменения сертификатов в системе контроля версий (если это не чувствительная информация)
    • Документирование: Документируйте используемые сертификаты и их источники
    • Отслеживание срока действия: Следите за сроками действия сертификатов

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

    • Минимальные права: Предоставляйте доступ только к необходимым сертификатам
    • Ротация: Регулярно обновляйте сертификаты
    • Проверка: Проверяйте сертификаты перед развертыванием

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

    • Тестируйте сначала: Проверяйте настройку сертификатов на тестовом репозитории перед применением в продакшене
    • Мониторинг логов: Регулярно проверяйте логи контроллера PAC на ошибки сертификатов
    • Резервное копирование: Храните резервные копии рабочих конфигураций сертификатов

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