ConnectorClass

Содержание

Overview

ConnectorClass — это ресурс на уровне кластера, который определяет режимы доступа и спецификации поведения для конкретных типов инструментов. Он описывает:

Формат адреса доступа к инструменту
Поддерживаемые методы аутентификации
Метод проверки доступности инструмента
Метод проверки валидности аутентификации
API-адрес инструмента

Например, следующее определение описывает коннектор типа Git, который поддерживает базовую аутентификацию:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
spec:
  address:
    type: string  #  Адрес в формате строки
  auth:
    types:
      - name: basicAuth
        secretType: kubernetes.io/basic-auth  #  Используется Basic Auth для аутентификации

Address Information

Информация об адресе определяет формат доступа к инструменту. В настоящее время поддерживаются конфигурации адреса типа string. Эта информация об адресе ограничивает тип поля, которому должен соответствовать текущий тип инструмента.

spec:
  address:
    type: string  # В настоящее время поддерживается только тип string

Это означает, что информация об адресе для подключения инструмента к платформе должна быть типа string.

Authentication Information

Authentication Type

Тип аутентификации определяет тип учетных данных, используемых для аутентификации инструмента. Инструмент может поддерживать несколько типов аутентификации, позволяя пользователям выбирать один из них при использовании инструмента.

Пользователи могут уникально именовать текущий тип аутентификации через

spec.auth.types[].name, который должен быть уникальным и не повторяться.
spec.auth.types[].secretType, который указывает тип Secret, необходимого для аутентификации, соответствующий kubernetes secret type.

Пример:

spec:
  auth:
    types:
      - name: basicAuth  # Имя типа аутентификации
        secretType: kubernetes.io/basic-auth  # Соответствующий тип Secret
      - name: sshAuth
        secretType: kubernetes.io/ssh-auth

Authentication Parameters

Параметры, необходимые для учетных данных при аутентификации, определяются в spec.auth.types[].params.

Для стандартных типов Kubernetes secret с четко определёнными полями данных параметры можно опустить. Например:

kubernetes.io/basic-auth: аутентификация по имени пользователя и паролю
kubernetes.io/ssh-auth: аутентификация по SSH-ключу

Для пользовательских типов аутентификации можно определить необходимые параметры аутентификации, при этом secretType указывается как kubernetes.io/opaque.

Например, для аутентификации GitLab с использованием Personal Access Token (PAT):

spec:
  auth:
    types:
      - name: privateToken
        secretType: kubernetes.io/opaque
        params:
          - name: username
            type: string
          - name: private-token
            type: string

В этом случае потребуется, чтобы учетные данные, используемые в коннекторе инструмента, содержали информацию username и private-token.

Optional Authentication

Некоторые инструменты поддерживают доступ без аутентификации, что отмечается полем optional, указывающим, является ли аутентификация необязательной:

Например, следующий пример указывает, что учетные данные для basicAuth являются необязательными, а для sshAuth — обязательными.

spec:
  auth:
    types:
      - name: basicAuth
        optional: true  # Отметка аутентификации как необязательной
        secretType: kubernetes.io/basic-auth
      - name: sshAuth
        secretType: kubernetes.io/basic-auth

В этом случае при подключении данного типа инструмента к платформе аутентификация типа basicAuth может быть пропущена.

Accessibility Check

Проверка доступности используется для подтверждения того, что к инструменту можно получить доступ нормально. Конфигурация способа проведения этой проверки задаётся через поле livenessProbe.

Например, следующий фрагмент указывает, что проверка выполняется с помощью HTTP-запросов.

spec:
  livenessProbe:
    http:
      path: /

Если инструмент возвращает статус 200, считается, что он доступен.

Authentication Checking

Проверка аутентификации используется для подтверждения того, как проверяется валидность аутентификационной информации для инструментов данного типа.

Например, следующий YAML указывает, что при проверке аутентификации инструмента будет выполнен http GET запрос с добавленным заголовком Authorization: abc.

spec:
  authProbes:
    - authName: basicAuth  # Соответствующий тип аутентификации
      probe:
        http:
          httpHeaders:
            Authorization: abc
          path: /
          method: GET # По умолчанию GET, поддерживаются методы POST и GET
          disableRedirect: false # По умолчанию false, разрешая автоматическую переадресацию

authName указывает используемый тип аутентификации, должен совпадать с spec.auth.types[].name.
При проверке аутентификации будет напрямую использоваться информация об адресе коннектора инструмента.
spec.authProbes[].probe.http.method задаёт HTTP-метод для аутентификации, поддерживает GET и POST. По умолчанию GET.
spec.authProbes[].probe.http.disableRedirect указывает, отключать ли переадресацию при аутентификации. По умолчанию разрешена автоматическая переадресация.

Custom Authentication Check Parameters

Некоторые проверки аутентификации могут требовать дополнительных параметров, например, указания имени репозитория при проверке доступа к Git-репозиторию. Они могут быть заданы через spec.authProbes[].params.

spec:
  authProbes:
    - authName: basicAuth  # Соответствующий тип аутентификации
      params:
        - name: repository
          type: string

Authentication Check Expressions

При настройке authProbes можно использовать выражения для динамического получения информации об учетных данных или информации о Connector.

Например,

spec:
  authProbes:
    - authName: basicAuth  # Соответствующий тип аутентификации
      probe:
        http:
          httpHeaders:
            Authorization: {{ .Secret.StringData.token }}
          path: /
      params:
        - name: repository
          type: string

Выражения можно использовать в полях httpHeaders и path.
Формат выражений — go template
Поддерживаемые верхнеуровневые поля:
- .Connector: информация самого Connector
- .Secret: информация Secret, используемого для данных Connector.
Методы, доступные в выражениях, можно посмотреть в документации sprig
- Например: b64enc: Base64-кодирование строк, trimPrefix для удаления префиксов строк

Example

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

spec:
  authProbes:
    - authName: basicAuth
      params:
        - name: repository
          type: string
      probe:
        http:
          path: /{{- range .Connector.Spec.Auth.Params }}{{- if eq .Name "repository" }}{{ .Value.StringVal }}{{ end }}{{- end }}/info/refs?service=git-upload-pack
          httpHeaders:
          - name: Authorization
            value: >-
              {{- if .Secret }}Basic {{ printf "%s:%s" .Secret.StringData.username .Secret.StringData.password | b64enc }} {{- end }}

Коннектор будет выполнять проверку валидности на основе информации в ConnectorClass.

Приведённый выше yaml указывает проверку аутентификации для basic auth:

path: использует значение repository, заданное в auth.params внутри информации Connector, объединённое как /<repository>/info/refs?service=git-upload-pack
Authorization: если в Connector настроен Secret, возвращаются поля username и password из Secret в base64.

ConnectorClass API {connectorclass_api}

ConnectorClass может предоставлять RESTful API для текущего ConnectorClass, что облегчает клиентам доступ к ресурсам внутри инструментов при использовании Connectors.

API ConnectorClass нужно настроить в поле spec.api, например:

spec:
  api:
    ref:
      kind: Service
      name: git
      namespace: default

Можно указать информацию о Service API через spec.api.ref. Если у API ConnectorClass есть фиксированный префикс адреса, его можно указать через spec.api.uri. Например:

spec:
  api:
    ref:
      kind: Service
      name: git
      namespace: default
    uri: /api

Или можно указать абсолютный путь API через spec.api.uri. Например:

spec:
  api:
    uri: https://git.example.com/api

Вне зависимости от формы, итоговый разрешённый API-адрес будет храниться в status.api.address.url. Например:

Для указания API connector class через сервис

spec:
  api:
    ref:
      kind: Service
      name: git
      namespace: default
status:
  api:
    address:
      url: https://git.default.svc

Для указания API connector class через URI

spec:
  api:
    uri: https://git.default.svc/api
status:
  api:
    address:
      url: https://git.default.svc/api

Для указания API connector class через сервис с использованием spec.api.uri для указания пути API

spec:
  api:
    ref:
      kind: Service
      name: git
      namespace: default
    uri: /api
status:
  api:
    address:
      url: https://git.default.svc/api

Для подробностей смотрите

Configurations

Вы можете указать конфигурационную информацию через spec.configurations. Например:

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: config
    data:
      .gitconfig: |
        this is git config

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

Для инструментов типа git — предоставить конфигурацию .gitconfig
Для инструментов типа oci registry — предоставить конфигурацию config.json

Эти конфигурационные данные могут быть смонтированы в Pods в виде файлов через connectors-cs-driver.

Содержимое конфигурации поддерживает использование переменных, которые могут динамически рендериться при монтировании. Подробнее смотрите описание "Configuration file rendering" в connectors-cs-driver.

Example

Следующий ConnectorClass предоставляет файл с именем .gitconfig, используемый для игнорирования проверки SSL-сертификата при git clone.

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: config
    data:
      .gitconfig: |
        [http]
          sslVerify = false

Следующий ConnectorClass предоставляет файл с именем .gitconfig, который автоматически внедряет заголовки и заменяет URL Git при git clone.

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: config
    data:
      .gitconfig: |
        [http]
            extraHeader = Authorization: Basic {{ printf ":%s" .context.token | b64enc }}
        [url "{{ .connector.status.proxyAddress }}"]
            insteadOf = {{.connector.spec.address}}

More Information

connectors csi driver

Metadata

ConnectorClass — это стандартный ресурс Kubernetes, который можно помечать пользовательской информацией через labels и annotations.

Например:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
  labels:
    connectors.cpaas.io/git: "true"
  annotations:
    cpaas.io/icon: ""
    cpaas.io/displayName: Git
    cpaas.io/description: "Connect to any Git tool"
    cpaas.io/readme: "this is readme..."

Status Information

Информация о состоянии хранится в status.conditions. Типы включают:

APIReady: статус информации о возможности API
ProxyReady: статус информации о возможности Proxy
Ready: указывает общий статус текущего ConnectorClass

Ready Condition

Ready Condition используется для указания текущего статуса ConnectorClass. Он агрегирует статусы других условий.

Если все остальные условия True, текущее условие True.
Если любое другое условие False, текущее условие False.
Если любое другое условие Unknown, текущее условие Unknown.

APIReady Condition

Указывает статус информации о сервисе API, настроенном для ConnectorClass. Сервис API задаётся через spec.api ConnectorClass.

Status	Reason	Description
True	NonAPI	Проверка возможности API нормальна, но конфигурация сервиса API не обнаружена
True		Возможность API нормальна
False		Возможность API ненормальна или сама проверка некорректна
Unknown		Проверка возможности API в процессе

Примечание:

Проверка API лишь пытается запросить ссылку без проверки HTTP-статуса. Проверка здоровья сервиса API должна опираться на собственный механизм проверки здоровья API.
Поскольку внешние сервисы могут изменяться в любой момент, статус API не может отражать актуальную информацию в реальном времени. Рекомендуется клиентам использовать эту информацию только как подсказку, не блокируя действия клиента.

ProxyReady Condition

Указывает статус информации о сервисе Proxy, настроенном для ConnectorClass. Сервис Proxy задаётся через spec.proxy ConnectorClass.

Status	Reason	Description
True	NonProxy	Проверка возможности Proxy нормальна, но конфигурация сервиса Proxy не обнаружена
True		Возможность Proxy нормальна
False		Возможность Proxy ненормальна или сама проверка некорректна
Unknown		Проверка возможности Proxy в процессе

Compatibility

Обновления ConnectorClass могут повлиять на существующие Connectors. Если в ConnectorClass внесены несовместимые изменения, это может привести к тому, что ранее созданные Connectors станут недействительными. Ниже приведены некоторые изменения, которые могут привести к несовместимости:

Изменения в информации об аутентификации: если ConnectorClass изменяет поддерживаемые типы или методы аутентификации, это может привести к сбоям в работе Connectors, использующих старый метод аутентификации.
Изменения в конфигурационной информации: если изменяется конфигурация ConnectorClass, например, удаляется существующая конфигурация, это может привести к сбоям в работе Kubernetes workloads, зависящих от старой конфигурации.

Рекомендуется оценить область влияния перед обновлением ConnectorClass или при необходимости создать новый ConnectorClass.

More Examples

ConnectorClass, поддерживающий тип аутентификации basic-auth

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
spec:
  address:
    type: string
  auth:
    types:
      - name: basicAuth
        secretType: kubernetes.io/basic-auth

ConnectorClass, одновременно поддерживающий типы аутентификации basic-auth и ssh-auth, при этом для basic-auth аутентификация необязательна.

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
spec:
  address:
    type: string
  auth:
    types:
      - name: basicAuth
        optional: true
        secretType: kubernetes.io/basic-auth
      - name: sshAuth
        secretType: kubernetes.io/ssh-auth

ConnectorClass для пользовательского типа аутентификации

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: sample
spec:
  address:
    type: string
  auth:
    types:
      - name: patAuth
        optional: true
        secretType: kubernetes.io/opaque
        params:
        - name: username
        - name: privateToken

ConnectorClass с настроенной liveness probe

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
spec:
  address:
    type: string
  auth:
    types:
      - name: basicAuth
        optional: true
        secretType: kubernetes.io/basic-auth
  livenessProbe:
    http:
      path: /

ConnectorClass с настроенной auth probe

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
  labels:
    connectors.cpaas.io/git: "true"
spec:
  address:
    type: string
  auth:
    types:
      - name: basicAuth
        secretType: kubernetes.io/basic-auth
        optional: true
  livenessProbe:
    http:
      path: /
  authProbes:
    - authName: basicAuth
      params:
        - name: repository
          type: string
      probe:
        http:
          path: /{{- range .Connector.Spec.Auth.Params }}{{- if eq .Name "repository" }}{{ .Value.StringVal }}{{ end }}{{- end }}/info/refs?service=git-upload-pack
          httpHeaders:
          - name: Authorization
            value: >-
              {{- if .Secret }}Basic {{ printf "%s:%s" .Secret.StringData.username .Secret.StringData.password | b64enc }} {{- end }}

Полный пример конфигурации Git-коннектора:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
spec:
  address:
    name: address
    type: string
  auth:
    types:
      - name: basicAuth
        secretType: kubernetes.io/basic-auth
        optional: true
      - name: sshAuth
        secretType: kubernetes.io/ssh-auth
  livenessProbe:
    http:
      path: /
  authProbes:
    - authName: basicAuth
      params:
        - name: repository
          type: string
      probe:
        http:
          path: /{{- range .Connector.Spec.Auth.Params }}{{- if eq .Name "repository" }}{{ .Value.StringVal }}{{ end }}{{- end }}/info/refs?service=git-upload-pack
          httpHeaders:
          - name: Authorization
            value: >-
              {{- if .Secret }}Basic {{ printf "%s:%s" .Secret.StringData.username .Secret.StringData.password | b64enc }} {{- end }}

Connector User Guide

#ConnectorClass

#Содержание

#Overview

#Address Information

#Authentication Information

#Authentication Type

#Authentication Parameters

#Optional Authentication

#Accessibility Check

#Authentication Checking

#Custom Authentication Check Parameters

#Authentication Check Expressions

#Example

#ConnectorClass API {connectorclass_api}

#Configurations

#Example

#More Information

#Metadata

#Status Information

#Compatibility

#More Examples

#More

ConnectorClass

Содержание

Overview

Address Information

Authentication Information

Authentication Type

Authentication Parameters

Optional Authentication

Accessibility Check

Authentication Checking

Custom Authentication Check Parameters

Authentication Check Expressions

Example

ConnectorClass API {connectorclass_api}

Configurations

Example

More Information

Metadata

Status Information

Compatibility

More Examples

More