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

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

В этом руководстве рассматриваются следующие темы:

• Включение feature flag для пользовательских CA-сертификатов
• Настройка глобальных CA-сертификатов, применяемых ко всем connectors
• Настройка CA-сертификатов для отдельного connector
• Проверка конфигурации через условие CACertReady

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

• Развернутый Connectors deployment (controller, proxy и необязательные расширения).
• Доступ администратора к cluster в системном namespace, где работают компоненты Connectors (обычно connectors-system).
• Один или несколько CA-сертификатов в формате PEM, которыми подписаны серверные сертификаты ваших инструментов.

#Шаг 1: Включите feature flag

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

Отредактируйте ConfigMap connectors-config в системном namespace и установите для флага значение true:

apiVersion: v1
kind: ConfigMap
metadata:
  name: connectors-config
  namespace: connectors-system
  labels:
    group: connectors.alauda.io
data:
  enable-custom-ca-certs: "true"

Примените изменения с помощью:

kubectl -n connectors-system patch configmap connectors-config \
  --type merge -p '{"data":{"enable-custom-ca-certs":"true"}}'

Изменение feature flag вступает в силу немедленно — настройка проверяется в момент обработки запроса. Когда флаг имеет значение false, условие CACertReady не добавляется к статусу Connector, а компоненты сохраняют прежнее поведение TLS для обратной совместимости.

#Шаг 2: Настройте глобальные CA-сертификаты

Глобальные CA-сертификаты применяются ко всем connectors в cluster. Они автоматически обнаруживаются по меткам на Secrets в системном namespace.

Создайте Secret в системном namespace с меткой connectors.cpaas.io/ca-cert: "true" и одним или несколькими сертификатами в формате PEM в ключах data. Загружаются только ключи, оканчивающиеся на .crt или .pem, либо значения, содержащие PEM-заголовок, — остальные ключи игнорируются.

apiVersion: v1
kind: Secret
metadata:
  name: my-internal-ca
  namespace: connectors-system
  labels:
    connectors.cpaas.io/ca-cert: "true"
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDazCCAlOgAwIBAgIUF+...
    -----END CERTIFICATE-----

Примените изменения с помощью:

kubectl apply -f my-internal-ca.yaml

Примечание: После обновления global Secret с нужной меткой reverse proxy может понадобиться до 5 минут, чтобы подхватить новый CA pool — транспорты connector reverse-proxy кэшируются для каждого connector с TTL 5 минут. Чтобы принудительно обновить их сразу, перезапустите Deployment connectors-proxy.

Вы можете создать несколько Secret с нужными метками — все их сертификаты будут объединены в глобальный CA pool. Добавление или удаление Secret с метками приводит к автоматическому повторному согласованию затронутых connectors.

#Шаг 3: Настройте CA-сертификаты для отдельного connector (необязательно)

Для инструментов, которым нужен определенный CA, не общий с другими connectors, вы можете указать CA Secret непосредственно в ресурсе Connector. Secret должен находиться в том же namespace, что и Connector (ссылки между namespace не поддерживаются).

Сначала создайте CA Secret в namespace connector:

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

Затем укажите его в Connector:

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

CA для отдельного connector является добавочным — он добавляется к глобальному CA pool (системные CAs + глобальные Secrets с метками + Secret для конкретного connector).

#Шаг 4: Проверьте конфигурацию

Проверьте условие CACertReady в статусе Connector:

kubectl -n my-namespace get connector my-tool-connector \
  -o jsonpath='{.status.conditions[?(@.type=="CACertReady")]}'

Ожидаемый результат для корректной конфигурации:

{
  "type": "CACertReady",
  "status": "True",
  "reason": "Valid",
  "message": "CA certificate loaded from secret \"my-tool-ca\"",
  "severity": "Info"
}

Условие CACertReady носит информационный характер — его статус не влияет на верхнеуровневое условие Ready. Это означает, что некорректно настроенный CA Secret будет отображаться как предупреждение, но не будет блокировать согласование connector. Полный справочник по статусам см. в разделе CA-сертификаты статуса на странице концепций Connector.

Если CA Secret отсутствует или содержит некорректные PEM-данные, controller создаст объект Warning Event в Kubernetes для объекта Connector. Просмотреть события можно так:

kubectl -n my-namespace describe connector my-tool-connector

#Распространенные проблемы

#В статусе Connector указано CACertReady=False, reason=SecretNotFound

Secret, указанный в spec.caCertSecretRef.name, не существует в namespace connector. Проверьте имя Secret и namespace:

kubectl -n my-namespace get secret my-tool-ca

#В статусе Connector указано CACertReady=False, reason=InvalidPEM

Secret существует, но его данные не содержат корректных сертификатов в формате PEM. Проверьте содержимое Secret:

kubectl -n my-namespace get secret my-tool-ca -o jsonpath='{.data.ca\.crt}' | base64 -d

Вывод должен начинаться с -----BEGIN CERTIFICATE----- и заканчиваться -----END CERTIFICATE-----.

#После включения флага условие CACertReady не появляется

Убедитесь, что после переключения флага вы перезапустили controller, proxy и API deployment. CA pool загружается при запуске компонентов.

kubectl -n connectors-system rollout restart deployment connectors-proxy connectors-controller-manager connectors-api

#Инструмент по-прежнему отклоняет подключения после настройки CA

CA pool формируется по добавочным уровням: системные CAs + глобальные Secrets с метками + Secret для отдельного connector. Убедитесь, что CA, подписавший серверный сертификат вашего инструмента, присутствует хотя бы в одном из этих уровней. Проверить, что глобальный pool заполнен, можно, перечислив Secrets с метками:

kubectl -n connectors-system get secret -l connectors.cpaas.io/ca-cert=true

#Соединение по-прежнему не работает сразу после изменения CA Secret

Reverse proxy кэширует CA pool с TTL 5 минут. Если вы только что обновили global Secret с меткой или Secret для отдельного connector, подождите истечения TTL либо перезапустите connectors-proxy, чтобы новый pool был подхвачен немедленно:

kubectl -n connectors-system rollout restart deployment connectors-proxy

#Дополнительно

• Концепции Connector: CA-сертификаты
• Справочник условий статуса Connector