#Управление компонентом PAC

В этом руководстве объясняется, как развертывать, обновлять и удалять компонент Pipelines-as-Code (PAC) на платформах Kubernetes.

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

Перед управлением PAC убедитесь, что у вас есть:

• Кластер Kubernetes (версия 1.24 или выше)
• Установленный и запущенный Tekton Operator
• Права администратора кластера
• Установленный и настроенный kubectl для доступа к вашему кластеру

#Развертывание компонента PAC

PAC развертывается путем создания CR OpenShiftPipelinesAsCode. Operator обнаруживает его и подготавливает все необходимые ресурсы.

Примеры в этом документе используют пространство имен PAC по умолчанию tekton-pipelines. Если вы задаете другое значение targetNamespace, замените tekton-pipelines в командах и манифестах.

#Шаг 1. Создайте CR OpenShiftPipelinesAsCode

Создайте YAML-файл с именем pac.yaml:

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
    remote-tasks: "true"
    secret-auto-create: "true"
  targetNamespace: tekton-pipelines  # Default namespace, you can customize this

Создайте namespace, если он еще не существует:

kubectl create namespace tekton-pipelines  # Or your custom namespace name

#Шаг 2. Примените конфигурацию

Примените CR к вашему кластеру:

kubectl apply -f pac.yaml

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

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

#Шаг 3. Проверьте развертывание

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

kubectl get openshiftpipelinesascodes.operator.tekton.dev

В выводе должен отображаться CR со статусом Ready:

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

Проверьте статус TektonInstallerSet:

kubectl get tektoninstallersets -n tekton-pipelines | grep pipelinesascode

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

NAME                              READY   REASON
pipelinesascode-installer-set     True    Ready

Проверьте, что pod'ы PAC запущены:

kubectl get pods -n tekton-pipelines | grep pipelines-as-code

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

NAME                                      READY   STATUS    RESTARTS   AGE
pipelines-as-code-controller-xxxxx        1/1     Running   0          5m
pipelines-as-code-watcher-xxxxx           1/1     Running   0          5m
pipelines-as-code-webhook-xxxxx           1/1     Running   0          5m

Три pod'а (controller, watcher, webhook) должны иметь статус Running.

#Настройка доступа

Контроллер PAC должен быть доступен из Git-провайдеров, которые будут отправлять ему webhook-события. Перед настройкой любого repository опубликуйте его одним из способов ниже.

#Использование Gateway API

Используйте этот способ, чтобы опубликовать контроллер PAC с доменным именем через ACP Gateway API.

Git provider -> PAC domain -> Envoy Gateway Service -> Gateway/HTTPRoute -> pipelines-as-code-controller

В этом примере используются:

• Namespace PAC по умолчанию: tekton-pipelines
• GatewayClass: envoy-gateway-operator-cpaas-default
• Домен: pac.example.com

Шаг 1. Подготовьте Envoy Gateway. Установите Alauda build of Envoy Gateway и убедитесь, что GatewayClass по умолчанию принят. Ссылка: Operator Envoy Gateway.

kubectl get gatewayclass envoy-gateway-operator-cpaas-default

NAME                                   ACCEPTED
envoy-gateway-operator-cpaas-default   True

Шаг 2. Подготовьте адреса LoadBalancer. Сервис Envoy Gateway будет создан с типом LoadBalancer, поэтому сервисы LoadBalancer должны иметь возможность получить внешний IP. На bare-metal-кластерах ACP установите и настройте Alauda Container Platform Load Balancer for MetalLB. Ссылка: Настройка MetalLB.

kubectl get ipaddresspool,l2advertisement -A

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

NAMESPACE        NAME                                    ADDRESSES
metallb-system   ipaddresspool.metallb.io/default-pool   ["192.168.1.100-192.168.1.110"]

Шаг 3. Создайте ресурсы Gateway API. Создайте gateway-api.yaml. При необходимости замените tekton-pipelines, envoy-gateway-operator-cpaas-default и pac.example.com. Ссылки: Настройка GatewayAPI Gateway и Настройка GatewayAPI Route.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: pipelines-as-code
  gatewayClassName: envoy-gateway-operator-cpaas-default
  listeners:
    - name: http
      port: 80
      hostname: pac.example.com
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  provider:
    kubernetes:
      envoyService:
        type: LoadBalancer
      envoyDeployment:
        replicas: 1
        container:
          imageRepository: registry.alauda.cn:60080/acp/envoyproxy/envoy
          resources:
            limits:
              cpu: "1"
              memory: 1Gi
            requests:
              cpu: 100m
              memory: 256Mi
    type: Kubernetes
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  hostnames:
    - pac.example.com
  parentRefs:
    - name: pipelines-as-code
      sectionName: http
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: pipelines-as-code-controller
          port: 8080

Примените файл:

kubectl apply -f gateway-api.yaml

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

gateway.gateway.networking.k8s.io/pipelines-as-code created
envoyproxy.gateway.envoyproxy.io/pipelines-as-code created
httproute.gateway.networking.k8s.io/pipelines-as-code created

Шаг 4. Получите внешний адрес. Проверьте созданный сервис Envoy:

kubectl get svc -A \
  -l gateway.envoyproxy.io/owning-gateway-name=pipelines-as-code,gateway.envoyproxy.io/owning-gateway-namespace=tekton-pipelines

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

NAMESPACE                  NAME                                                 TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)
envoy-gateway-operator    envoy-tekton-pipelines-pipelines-as-code-3f8c88ad    LoadBalancer   10.96.10.20     192.168.1.100   80:32176/TCP

Шаг 5. Проверьте и получите URL webhook. Убедитесь, что Git-провайдер может разрешить и открыть домен PAC. Обычный способ — создать DNS A-запись. Например, если EXTERNAL-IP сервиса — 192.168.1.100, создайте:

Type: A
Name: pac.example.com
Value: 192.168.1.100

Если DNS еще не готов или вы хотите протестировать маршрут только со своей текущей машины, используйте curl --resolve:

EXTERNAL_IP=$(kubectl get svc -A \
  -l gateway.envoyproxy.io/owning-gateway-name=pipelines-as-code,gateway.envoyproxy.io/owning-gateway-namespace=tekton-pipelines \
  -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}')

kubectl get gateway pipelines-as-code -n tekton-pipelines
kubectl get httproute pipelines-as-code -n tekton-pipelines -o yaml
curl -i --resolve "pac.example.com:80:${EXTERNAL_IP}" http://pac.example.com/

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

• Сервис имеет EXTERNAL-IP.
• Для Gateway указано PROGRAMMED=True.
• HTTPRoute принят.
• curl возвращает ответ контроллера PAC.

После того как домен станет доступен из сети Git-провайдера, выведите URL:

WEBHOOK_URL=http://pac.example.com

WEBHOOK_URL — это URL webhook PAC. Зарегистрируйте это значение в Git-провайдере или введите его, когда tkn pac create repo запросит URL webhook.

Если вместо этого вы публикуете PAC через ACP ALB или другой Ingress Controller, используйте Использование Ingress.

Примечания:

• HTTPRoute перенаправляет трафик на существующий сервис pipelines-as-code-controller на порту 8080; не указывайте его на admission webhook Service с именем pipelines-as-code-webhook.
• Если созданный сервис Envoy остается в состоянии EXTERNAL-IP=<pending>, проверьте провайдера LoadBalancer кластера. Для MetalLB см. Настройка MetalLB.
• Сведения о параметрах Gateway API, таких как зарезервированный VIP, маршруты без host или HTTPS-listener'ы, см. в Настройка GatewayAPI Gateway и Настройка GatewayAPI Route.

#Использование Ingress

Используйте этот способ, если в кластере уже есть Ingress Controller и вы хотите опубликовать контроллер PAC через домен Ingress.

В этом примере используются:

• Namespace PAC по умолчанию: tekton-pipelines
• Домен: pac.example.com

Шаг 1. Подготовьте Ingress Controller. Убедитесь, что Ingress Controller установлен и готов к работе. Ссылка: Настройка Ingress.

Шаг 2. Создайте ресурс Ingress. Создайте ingress.yaml. При необходимости замените tekton-pipelines и pac.example.com.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  rules:
  - host: pac.example.com
    http:
      paths:
      - backend:
          service:
            name: pipelines-as-code-controller
            port:
              number: 8080
        path: /
        pathType: Prefix

Примените файл:

kubectl apply -f ingress.yaml

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

ingress.networking.k8s.io/pipelines-as-code created

Шаг 3. Проверьте адрес Ingress. Убедитесь, что Ingress имеет адрес:

kubectl get ingress pipelines-as-code -n tekton-pipelines

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

NAME                CLASS   HOSTS             ADDRESS         PORTS
pipelines-as-code   nginx   pac.example.com   192.168.1.100   80

Шаг 4. Получите URL webhook. Убедитесь, что Git-провайдер может разрешить и открыть pac.example.com через адрес Ingress. Затем выведите URL:

HOST=$(kubectl get ingress pipelines-as-code -n tekton-pipelines \
  -o jsonpath='{.spec.rules[0].host}')

echo "WEBHOOK_URL=http://${HOST}"

WEBHOOK_URL — это URL webhook PAC. Зарегистрируйте это значение в Git-провайдере или введите его, когда tkn pac create repo запросит URL webhook.

Если у вас нет DNS-имени, удалите поле host и используйте вместо него доступный URL IP Ingress.

Необязательно: включите HTTPS. Создайте TLS Secret в tekton-pipelines и добавьте раздел tls в тот же Ingress. Сертификат должен соответствовать pac.example.com.

kubectl create secret tls pipelines-as-code-tls \
  -n tekton-pipelines \
  --cert=tls.crt \
  --key=tls.key

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  rules:
  - host: pac.example.com
    http:
      paths:
      - backend:
          service:
            name: pipelines-as-code-controller
            port:
              number: 8080
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - pac.example.com
    secretName: pipelines-as-code-tls

Когда TLS настроен, используйте HTTPS URL webhook:

echo "WEBHOOK_URL=https://${HOST}"

#Использование NodePort

Создайте Service типа NodePort:

apiVersion: v1
kind: Service
metadata:
  name: pipelines-as-code-controller-nodeport
  namespace: tekton-pipelines
spec:
  ports:
    - name: http-listener
      port: 8080
      protocol: TCP
      targetPort: 8082  # PAC controller listens on port 8082
      nodePort: 30080  # Optional: specify a fixed NodePort
  selector:
    app.kubernetes.io/part-of: pipelines-as-code
    app.kubernetes.io/component: controller
  type: NodePort

Важно:

• targetPort должен быть 8082, это порт, на котором pod контроллера PAC принимает webhook-события
• port (8080) — это порт Service (используется для внутренней связи внутри кластера)
• nodePort (30080) — это внешний порт, доступный извне кластера
• Для Ingress порт Service — 8080, он внутренне маршрутизируется на порт контроллера 8082

Выведите URL на основе доступного IP узла и сгенерированного NodePort:

NODEPORT=$(kubectl get service pipelines-as-code-controller-nodeport -n tekton-pipelines \
  -o jsonpath='{.spec.ports[?(@.name=="http-listener")].nodePort}')

NODE_IP=$(kubectl get nodes \
  -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')

echo "WEBHOOK_URL=http://${NODE_IP}:${NODEPORT}"

WEBHOOK_URL — это URL webhook PAC. Зарегистрируйте это значение в Git-провайдере или введите его, когда tkn pac create repo запросит URL webhook.

#Параметры конфигурации

Вы можете настраивать поведение PAC через поле settings в CR OpenShiftPipelinesAsCode:

hub-url указывает на Tekton Hub, который контроллер PAC запрашивает при разрешении remote tasks. URL внутри кластера по умолчанию — http://tekton-hub-api.tekton-pipelines:8000/v1; для Hub в другом namespace используйте тот же формат service DNS с нужным namespace.

Параметры custom-console-* переписывают ссылки на стороне кластера, которые PAC отправляет обратно в Git-провайдер, чтобы они вели на console платформы, а не на OpenShift Console. Пошаговое описание приведено в разделе Настройка пользовательских ссылок на console.

#Обновление компонента PAC

#Обновление конфигурации

1. Отредактируйте CR OpenShiftPipelinesAsCode:

   kubectl edit openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

2. При необходимости обновите поле settings:

   spec:
     settings:
       application-name: "My Custom PAC"
       hub-url: http://tekton-hub-api.tekton-pipelines:8000/v1
       remote-tasks: "true"
       error-detection-from-container-logs: "true"

3. Сохраните изменения и выйдите. Operator автоматически обновит TektonInstallerSet и применит изменения.

#Распространенные обновления конфигурации

Примеры в этом разделе обновляют поле spec.settings CR OpenShiftPipelinesAsCode с именем pipelines-as-code.

kubectl edit openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

#Настройка пользовательских ссылок на console

Параметры custom-console-* переписывают ссылки на стороне кластера, которые PAC отправляет обратно в Git-провайдер, чтобы они указывали на console платформы. Замените console.example.com и my-cluster на адрес вашей console и имя кластера:

spec:
  targetNamespace: tekton-pipelines
  settings:
    custom-console-name: "My Console"
    custom-console-url: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns/"
    custom-console-url-pr-details: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}"
    custom-console-url-pr-tasklog: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}?tab=task_overview&id={{ task }}"
    custom-console-url-namespace: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns"
  options:
    configMaps:
      pipelines-as-code:
        data:
          replace-empty-template-vars-with-empty: "true"

Эффект: ссылки на статусы в Git-провайдере открывают страницы PipelineRun и task в console платформы вместо стандартных URL-заглушек в стиле OpenShift.

PAC подставляет эти переменные, когда публикует ссылки на статусы:

Для PipelineRun с именем my-app-build-abc123 в namespace my-app PAC формирует ссылки вроде:

https://console.example.com/console-acp/workspace/my-app~my-cluster~my-app/pipeline/pipelineRuns/detail/my-app-build-abc123
https://console.example.com/console-acp/workspace/my-app~my-cluster~my-app/pipeline/pipelineRuns/detail/my-app-build-abc123?tab=task_overview&id=build-task
https://console.example.com/console-acp/workspace/my-app~my-cluster~my-app/pipeline/pipelineRuns

Эти URL отображаются в статусах commit, панелях GitHub Checks и комментариях merge request.

#Изменение имени приложения

Используйте этот параметр, чтобы изменить отображаемое имя, которое PAC использует в сообщениях статуса Git-провайдера:

spec:
  settings:
    application-name: "New Application Name"

Эффект: checks, статусы и комментарии Git-провайдера показывают новое имя приложения. Это не меняет имя ресурса OpenShiftPipelinesAsCode.

#Включение обнаружения ошибок

spec:
  settings:
    error-detection-from-container-logs: "true"
    error-detection-max-number-of-lines: "100"

Эффект: PAC анализирует логи неудачных task и добавляет краткий фрагмент ошибки в feedback Git-провайдера.

#Обновление URL Hub

Если ваш Tekton Hub развернут в другом namespace или вы хотите использовать внешний Hub:

spec:
  settings:
    # For a cluster-internal Hub in another namespace
    hub-url: "http://tekton-hub-api.devops-system:8000/v1"

    # Or for external/public Hub
    hub-url: "https://api.hub.tekton.dev/v1"

Эффект: PAC разрешает remote tasks из указанного Tekton Hub API вместо Hub внутри кластера по умолчанию.

Чтобы найти свой service Tekton Hub:

kubectl get svc -A | grep tekton-hub-api

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

tekton-pipelines   tekton-hub-api   ClusterIP   10.96.123.45   <none>   8000/TCP   10m

#Отключение remote tasks

Используйте remote-tasks, чтобы управлять тем, будет ли PAC получать и встраивать удаленные ресурсы, на которые ссылаются аннотации PAC.

spec:
  settings:
    remote-tasks: "false"

Эффект: используйте "false", если хотите запретить PAC получать remote Tasks или Pipelines по ссылкам из аннотаций.

#Удаление компонента PAC

#Удалите CR OpenShiftPipelinesAsCode

Удаление CR заставляет operator удалить TektonInstallerSet и все объекты PAC Deployment, Service, ConfigMap и RBAC, которые создал operator.

kubectl delete openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

Убедитесь, что CR, installer set и pod'ы удалены:

kubectl get openshiftpipelinesascodes.operator.tekton.dev
kubectl get tektoninstallersets -n tekton-pipelines | grep pipelinesascode
kubectl get pods -n tekton-pipelines | grep pipelines-as-code

Каждая из этих команд должна вернуть No resources found.

#Очистите ресурсы, которыми operator не владеет

Operator удаляет все, что он создал. Ресурсы, которые вы добавили вручную, остаются и должны быть удалены вручную.

Repository CR в пользовательских namespace:

kubectl get repositories -A
kubectl delete repositories --all -n <namespace>

Secrets для каждого repository в пользовательских namespace. Это токены доступа Git-провайдера (provider.token) и webhook secrets (webhook.secret), создаваемые пользователями при настройке repositories. Cluster secrets, которыми владеет PAC и которые имеют метку app.kubernetes.io/part-of=pipelines-as-code, удаляются operator'ом; эти per-repository secrets — нет. Перед удалением убедитесь, что каждый Secret не используется другим ресурсом:

kubectl delete secret <secret-name> -n <namespace>

Ресурсы Gateway API для контроллера PAC, если вы создали их в разделе Настройка доступа:

kubectl delete httproute pipelines-as-code -n tekton-pipelines
kubectl delete gateway pipelines-as-code -n tekton-pipelines
kubectl delete envoyproxy pipelines-as-code -n tekton-pipelines

Ingress / Service типа NodePort для контроллера PAC, если вы создали их в разделе Настройка доступа:

kubectl delete ingress pipelines-as-code -n tekton-pipelines
kubectl delete service pipelines-as-code-controller-nodeport -n tekton-pipelines

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

#Pod'ы PAC не запускаются

Проверьте логи pod'ов:

kubectl logs -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code

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

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Starting PAC controller"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PAC controller ready"}

#CR OpenShiftPipelinesAsCode не готов

Проверьте статус CR и события:

kubectl describe openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

Пример вывода (сокращенно):

Name:         pipelines-as-code
Namespace:
Status:       Ready
Version:      0.x.x
Events:
  Type    Reason   Age   From              Message
  ----    ------   ----  ----              -------
  Normal  Ready    5m    tekton-operator   PAC component deployed successfully

#Проблемы TektonInstallerSet

Когда TektonInstallerSet не имеет статуса Ready, прочитайте его conditions и представление operator'а о соответствующем CR OpenShiftPipelinesAsCode. Оба варианта — только для чтения; никогда не удаляйте installer set самостоятельно.

kubectl get tektoninstallersets -n tekton-pipelines -o yaml

Если ошибки сохраняются, заново создайте CR OpenShiftPipelinesAsCode — operator перестроит installer set с нуля.

#CR не удаляется

Удаление, которое зависает, обычно удерживается finalizer'ом operator'а. Просмотрите finalizer'ы:

kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o yaml | grep finalizers

Наличие finalizer'а tekton.dev/operator означает, что operator все еще выполняет очистку; подождите и повторите попытку. Пустой вывод означает, что CR можно удалить.

#Ресурсы не удаляются

Когда pod'ы или Service остаются после удаления:

kubectl delete deployment -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code
kubectl delete service -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code

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

• Руководства
• Определение PipelineRun в Git
• Запуск Pipelines