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

    • Коннектор

    Содержание

    ОбзорАдрес коннектораБазовый формат URLURL с префиксом путиРасширения адреса коннектораПараметры коннектораИнформация об аутентификацииНастройка информации об аутентификацииНеобязательная аутентификацияПроверка аутентификацииПользовательские CA-сертификатыСсылка на CA-сертификат для конкретного ConnectorГлобальные CA-сертификатыАдрес proxyИнформация о статусеПримерыКоннектор Git с базовой аутентификациейКоннектор Git без аутентификации

    Обзор

    Connector — ресурс уровня namespace, используемый для определения конфигурации подключения между инструментами и платформами. Он включает:

    • Адрес доступа к инструменту
    • Информацию аутентификации инструмента
    • Информацию о состоянии инструмента

    Например, следующее определение иллюстрирует коннектор типа Git:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
  namespace: default
spec:
  connectorClassName: git  ##  Specify the connector type as git, this ConnectorClass must exist
  address: "https://github.com"  ##  Access address of the tool
  auth:
    name: basicAuth
    secretRef:  ##  Reference to authentication information
      name: github-secret

    Адрес коннектора

    Поле address задает URL endpoint целевого инструмента, с которым Connector будет интегрироваться. Оно принимает как корневые URL, так и URL с префиксом пути.

    Базовый формат URL

    Для инструментов, доступных в корневом домене:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
spec:
  connectorClassName: git
  address: "https://github.com"
  # ...

    URL с префиксом пути

    Для инструментов, развернутых за reverse proxy или доступных по определенным путям:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-gitlab
spec:
  connectorClassName: git
  address: "https://internal-tool.com/gitlab"
  # ...

    Примечание

    Проверки аутентификации и liveness probe на основе http не будут выполняться по префиксу пути. Если вы хотите выполнять проверку по префиксу пути, можно использовать выражения проверки аутентификации и выражения проверки liveness.

    Подробнее см. liveness probe и authentication probe.

    Расширения адреса коннектора

    spec.addressExtensions определяет дополнительные именованные адреса в экземпляре Connector. Доступные имена берутся из расширений адреса ConnectorClass.

    • spec.addressExtensions[].name: Имя расширения. Должно быть уникальным в пределах одного Connector.
    • spec.addressExtensions[].value: Значение расширения. Должно быть непустым URL с http/https.

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

    1. Должны быть указаны расширения, требуемые ConnectorClass (без default).
    2. Connector не может указывать имена расширений, которые не объявлены в ConnectorClass.
    3. Имена расширений должны быть уникальными в Connector.
    4. Значения расширений не должны дублировать spec.address.

    Поведение во время выполнения:

    • Connectors API может выбирать backend-адрес по имени расширения или по прямому URL через x-openapi-address.
    • Connectors Proxy может рассматривать spec.address и spec.addressExtensions[*].value как адреса назначения для внедрения учетных данных.

    Пример

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
spec:
  connectorClassName: github
  address: "https://github.com"
  addressExtensions:
    - name: api
      value: "https://api.github.com"

    Параметры коннектора

    Параметры коннектора позволяют передавать в экземпляр Connector дополнительную информацию о конфигурации. Эти параметры сначала определяются в спецификации ConnectorClass, а затем настраиваются при создании отдельных ресурсов Connector.

    Значения параметров можно задавать в Connector с помощью поля spec.params.

    • spec.params[].name: Имя параметра, которое должно совпадать с именем параметра, определенным в соответствующем ConnectorClass.
    • spec.params[].value: Значение параметра. Тип значения должен соответствовать типу параметра, определенному в ConnectorClass. В настоящее время поддерживается только тип string.

    Если для параметра в ConnectorClass задано значение по умолчанию, вы можете не указывать этот параметр при создании Connector, и будет использовано значение по умолчанию.

    Подробнее о задании параметров в ConnectorClass см. Параметры ConnectorClass.

    Пример

    Следующий пример демонстрирует Connector, настроенный с параметром sslVerify:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-gitlab
spec:
  connectorClassName: git-example
  address: "https://private-gitlab.example.com"
  params:
    - name: sslVerify
      value: "false"
---
apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git-example
spec:
  # ...
  params:
    - name: sslVerify
      type: string
      default: "true"

    Информация об аутентификации

    Информация аутентификации задает учетные данные для доступа к инструменту. В зависимости от типа инструмента можно настроить разные методы аутентификации. Этот метод аутентификации определяется в ConnectorClass. Подробнее см. описание информации аутентификации в ConnectorClass.

    Настройка информации об аутентификации

    Информация аутентификации настраивается следующим образом:

    1. Укажите имя типа аутентификации, используемого согласно определению ConnectorClass.
    2. Создайте Secret, содержащий учетные данные.
    3. Ссылайтесь на Secret в Connector через spec.auth.secretRef.
    4. Укажите информацию о параметрах, требуемых при проверке аутентификации.

    Например, чтобы настроить базовую аутентификацию:

    ##  Create a Secret containing username and password
apiVersion: v1
kind: Secret
metadata:
  name: github-secret
  namespace: default
type: kubernetes.io/basic-auth
data:
  username: dXNlcm5hbWU=  ##  Base64 encoded username
  password: cGFzc3dvcmQ=  ##  Base64 encoded password
---
##  Reference the Secret in the Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: github-secret
      namespace: default

    Необязательная аутентификация

    Некоторые инструменты поддерживают доступ без аутентификации. В этом случае spec.auth.secretRef можно опустить.

    Например, доступ к публичному Git-репозиторию:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-public
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth ##  Authentication for git connectorclass basic-auth is optional

    Проверка аутентификации

    Connector поддерживает проверку корректности информации аутентификации. Конфигурация проверки задается через spec.auth.params, который включает параметры, необходимые для проверки аутентификации.

    Например, чтобы проверить права доступа к Git-репозиторию:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: github-secret
      namespace: default
    params:
    - name: repository  ##  Specify the repository to be checked
      value: "org/repo.git"

    Обратите внимание, что если ConnectorClass задает параметры обнаружения аутентификации, параметры в connector должны быть указаны обязательно. Даже если Connector создается без указания сведений Secret, spec.auth.params должен быть передан.

    Пользовательские CA-сертификаты

    Когда TLS-сертификат инструмента подписан внутренним или закрытым центром сертификации (CA), платформу Connector можно настроить на доверие этим CA без отключения проверки сертификата.

    Поддержка пользовательских CA-сертификатов доступна только при включенном feature flag enable-custom-ca-certs, который по умолчанию отключен для сохранения обратной совместимости с существующими развертываниями.

    Когда флаг включен, платформа формирует пул CA, состоящий из трех дополняющих слоев:

    1. Системный пул CA по умолчанию — хранилище доверенных сертификатов на уровне ОС, встроенное в образ контейнера.
    2. Глобальные пользовательские CA-сертификаты — Secret в namespace connectors-system с меткой connectors.cpaas.io/ca-cert: "true". Несколько Secret агрегируются.
    3. CA-сертификаты для конкретного Connector — необязательный Secret, на который ссылается spec.caCertSecretRef.name в Connector. Secret ДОЛЖЕН находиться в том же namespace, что и Connector.

    Сформированный пул CA используется для:

    • проверок liveness и аутентификации, выполняемых контроллером по отношению к инструменту
    • proxy-доступа к инструменту из proxy-компонентов
    • проверок доступности ConnectorClass со стороны контроллера
    • proxy-расширений (OCI, Harbor, Git HTTPS и т. д.), где это применимо

    Ссылка на CA-сертификат для конкретного Connector

    Чтобы доверять определенному CA только для одного Connector, задайте spec.caCertSecretRef.name:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: internal-tool
  namespace: my-namespace
spec:
  connectorClassName: my-tool
  address: https://internal-tool.example.com
  auth:
    name: bearerToken
    secretRef:
      name: my-tool-credentials
  caCertSecretRef:
    name: my-tool-ca       ##  Secret in the same namespace

    Указанный Secret ДОЛЖЕН содержать как минимум один CA-сертификат в PEM-формате. В пул загружаются только ключи, оканчивающиеся на .crt или .pem, либо значения, содержащие PEM-заголовок, — остальные ключи (например, токены или пароли, случайно помещенные в тот же Secret), игнорируются.

    apiVersion: v1
kind: Secret
metadata:
  name: my-tool-ca
  namespace: my-namespace
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDazCCAlOgAwIBAgIUF+...
    -----END CERTIFICATE-----

    Глобальные CA-сертификаты

    Администраторы кластера могут настроить CA-сертификаты, которые применяются ко всем коннекторам, создав Secret в namespace connectors-system с меткой connectors.cpaas.io/ca-cert: "true". Платформа автоматически обнаруживает все подходящие Secret и агрегирует их сертификаты в глобальный пул CA.

    Добавление или удаление помеченных Secret приводит к автоматическому повторному согласованию затронутых Connector — после включения feature flag перезапуск компонентов для изменения глобальных CA не требуется.

    Пошаговые инструкции см. в Как настроить пользовательские CA-сертификаты.

    Адрес proxy

    Если Connector указывает на ConnectorClass, в котором настроена поддержка proxy, система выделит адрес proxy для каждого Connector.

    Клиенты могут использовать этот адрес proxy для доступа к инструменту без секретов.

    Формат адреса proxy по умолчанию — http://c-{connector-name}.{namespace}.svc.cluster.local, его можно получить из status.proxy.

    Например, следующий пример описывает Connector с адресом proxy:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: harbor
  namespace: default
spec:
  address: https://example.com
status:
 proxy:
    httpAddress:
      url: http://c-harbor.default.svc.cluster.local

    Когда в ConnectorClass настроен тип resolver proxy path, формат адреса proxy — http://c-{connector-name}.{namespace}.svc.cluster.local/namespaces/{namespace}/connectors/{connector-name}, где {path} — путь Connector.

    Например, следующий пример описывает Connector с адресом proxy:

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: harbor
  namespace: default
spec:
  address: https://example.com
status:
 proxy:
    httpAddress:
      url: http://c-harbor.default.svc.cluster.local/namespaces/default/connectors/harbor

    Информация о статусе

    Информация о статусе Connector записывается в поле status и содержит адрес proxy, адрес API и состояния:

    • status.conditions: Состояния Connector.
    • status.proxy: Адрес proxy Connector.
    • status.api: Адрес API Connector.

    Адрес proxy

    Поле proxy содержит адрес proxy Connector.

    • status.proxy.httpAddress.url: HTTP-адрес proxy для текущего Connector.

    Вы можете использовать этот адрес с существующими клиентами инструмента, чтобы получать доступ к инструменту внутри кластера без секретов. Подробнее см. Прокси Connector.

    Если ConnectorClass не имеет возможности proxy, поле status.proxy будет пустым.

    Адрес API

    Поле api содержит адрес API Connector.

    • status.api.path: Относительный путь API для текущего Connector (относительно точки входа доступа через кластерный ingress).

    Вы можете использовать этот путь вне кластера для доступа к исходному API инструмента через текущий Connector. Подробнее см. API Connector.

    Состояния

    Тип conditions включает:

    • ConnectorClassReady: Указывает, корректен ли тип connector.
    • SecretReady: Указывает, корректно ли настроена информация аутентификации.
    • LivenessReady: Указывает, доступен ли инструмент.
    • AuthReady: Указывает, действительна ли информация аутентификации.
    • ProxyServiceReady: Указывает, успешно ли выделен адрес proxy для текущего Connector.
    • CACertReady: Информационное — указывает состояние конфигурации пользовательских CA-сертификатов. Это состояние не влияет на верхнеуровневое состояние Ready.
    • Ready: Указывает общее состояние.

    Состояние SecretReady

    Указывает информацию о состоянии Secret для Connector.

    StatusReasonDescription
    TrueSecretOptionalConnectorClass помечает информацию аутентификации как необязательную, и для текущего Connector информация аутентификации не настроена
    TrueSecret настроен и существует
    FalseSecret настроен, но при проверке существования Secret произошла ошибка
    UnknownВыполняется проверка корректности настроенного Secret

    Состояние AuthReady

    Указывает информацию о состоянии аутентификации для Connector.

    StatusReasonDescription
    TrueNonAuthProbeConnectorClass не задает информацию Auth Probe
    TrueПроверка учетных данных прошла успешно
    FalseПроверка учетных данных не удалась
    UnknownПроверка учетных данных выполняется

    Состояние LivenessReady

    Указывает информацию о состоянии liveness для Connector.

    StatusReasonDescription
    TrueNonLivenessProbeConnectorClass не задает информацию Liveness Probe
    TrueДоступ к инструменту нормальный
    FalseДоступ к инструменту ненормальный
    UnknownВыполняется проверка доступа к инструменту

    Состояние ProxyServiceReady

    Указывает информацию о состоянии службы proxy для Connector.

    StatusReasonDescription
    TrueNonProxyConnectorClass не задает информацию Proxy Service, текущий Connector не поддерживает Proxy
    TrueСлужба proxy Connector успешно создана
    FalseСлужба proxy находится в ненормальном состоянии
    UnknownВыполняется проверка службы proxy

    Состояние CACertReady

    Информационное — указывает состояние конфигурации пользовательских CA-сертификатов. Это состояние не входит в стандартный набор состояний готовности, имеет severity: Info и не влияет на верхнеуровневое состояние Ready. Оно присутствует только тогда, когда включен feature flag enable-custom-ca-certs.

    StatusReasonDescription
    TrueValidcaCertSecretRef задан, и указанный Secret был успешно загружен
    TrueNoCACertcaCertSecretRef не задан; коннектор использует только глобальный пул CA
    FalseSecretNotFoundcaCertSecretRef задан, но указанный Secret не существует в namespace коннектора
    FalseInvalidPEMУказанный Secret существует, но не содержит допустимых данных сертификата в PEM-формате

    Когда состояние равно False, контроллер также создает в объекте Connector событие Kubernetes Warning Event с причиной CACertSecretNotFound или InvalidCACert, которое можно увидеть с помощью kubectl describe connector <name>.

    Когда feature flag отключен, состояние CACertReady вообще отсутствует.

    Например:

    status:
  conditions:
  - type: ConnectorClassReady
    status: "True"
    message: ""
  - type: SecretReady
    status: "True"
    message: ""
  - type: LivenessReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: AuthReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: ProxyServiceReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: CACertReady           ##  Only present when enable-custom-ca-certs feature flag is enabled
    status: "True"
    severity: Info              ##  Informational — does not affect Ready
    reason: Valid
    message: 'CA certificate loaded from secret "my-tool-ca"'
  - type: Ready
    status: "True"
    message: ""

    Примеры

    Коннектор Git с базовой аутентификацией

    ##  Create authentication information
apiVersion: v1
kind: Secret
metadata:
  name: git-auth
  namespace: default
type: kubernetes.io/basic-auth
data:
  username: dXNlcm5hbWU=
  password: cGFzc3dvcmQ=
---
##  Create Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
  namespace: default
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: git-auth
      namespace: default
    params:
    - name: repository
      value: "org/repo.git"

    Коннектор Git без аутентификации

    apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-public
  namespace: default
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
  params:
    - name: repository
      value: "org/repo.git"