Перейти к основному содержанию
Запускайте ваше приложение и collector AgentEye в одном поде Kubernetes, чтобы телеметрия никогда не пересекала границу сети при сборе. SDK вашего приложения и collector совместно используют единую очередь событий в поде, что означает низколатентную передачу телеметрии внутри процесса без открытого порта localhost, без сетевого взаимодействия и с жизненным циклом collector’а, привязанным непосредственно к рабочей нагрузке, которую он наблюдает. Сертификат клиента mTLS, который представляет collector, доставляется прямо в ваш под из AWS Secrets Manager, поэтому ротация учетных данных не требует ручного перемещения файлов с вашей стороны. Модель sidecar + shared-spool, описанная здесь, независима от облачной платформы; два контейнера, совместно использующих очередь событий emptyDir, работают на любом дистрибутиве Kubernetes. Только путь доставки сертификата в этом руководстве (AWS Secrets Manager + Secrets Store CSI Driver + IRSA) специфичен для AWS/EKS. Если вы работаете в другом месте, сохраняйте компоновку pod’а и очереди и замените механизм монтирования секретов вашей платформы на этапы 2 и 3.
Когда использовать этот паттерн. Выбирайте single-pod, когда ваше приложение не должно обращаться через границу сети к collector’у (низколатентный in-pod IPC, тесная связь жизненных циклов, изоляция pod’а по тенантам). Для многоприложных флотов, совместно использующих один collector на узел или на кластер, см. вместо этого enterprise-docs/kubernetes-deployment.md.

На первый взгляд

Два потока данных, два тома:
  • События (in-pod): SDK вашего приложения записывает файлы .jsonl в общий emptyDir в $AGENTEYE_HOME/events/; sweeper collector’а их читает и загружает. Без порта localhost, без loopback, чистая передача через общую файловую систему.
  • Сертификат mTLS (pod ← cloud): Secrets Store CSI Driver монтирует пакет сертификата из Secrets Manager в том только для чтения в /etc/agenteye/tls/, ограниченный контейнером collector’а.
Две независимые стороны:
СторонаОтветственность
ExosphereВыдает сертификат клиента mTLS и доставляет пакет в ваш AWS аккаунт в Secrets Manager под стабильным именем. Переиздает обновленный пакет в тот же секрет перед истечением срока действия.
ВыУстановите Secrets Store CSI Driver, предоставьте ServiceAccount pod’а доступ к чтению секрета через IRSA и примените манифест Pod. Вот и все.

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

В вашем AWS аккаунте/кластере EKS

  • Кластер EKS с связанным поставщиком OIDC. Подтвердите с помощью:
    Если команда возвращает URL https://oidc.eks.…, то OIDC включен. Если нет, свяжите его:
  • Secrets Store CSI Driver и AWS provider, установленные в кластере (см. § Этап 2).
  • AWS CLI v2 и kubectl на вашей рабочей станции.

Координация с Exosphere

Перед развертыванием Exosphere доставляет пакет клиента mTLS в Secrets Manager вашего AWS аккаунта и предоставляет:
  • Имя секрета (соглашение: agenteye/mtls-client/<your-cluster>)
  • Регион AWS, где находится секрет
  • URL backend’а AgentEye для конфигурации collector’а
  • Ваш API ключ collector’а (см. enterprise-docs/api-keys.md)

Этап 1: Что доставляет Exosphere

Вы не генерируете сертификат клиента mTLS самостоятельно. Exosphere выдает его и доставляет пакет непосредственно в Secrets Manager вашего AWS аккаунта, поэтому единственный материал учетных данных, который попадает в вашу среду, — это готовый к монтированию секрет. Что прибывает в ваш аккаунт:
СвойствоЗначение
Имя секретаagenteye/mtls-client/<cluster-name> (стабильно при обновлениях)
РегионРегион AWS, который вы номинировали для вашего кластера EKS
PayloadЕдинственный JSON-секрет с тремя ключами (client.crt, client.key и ca.crt), каждый содержит PEM-кодированный материал
ТегAgentEyeCluster=<cluster-name>
При обновлении один и тот же секрет обновляется на месте с новой версией, поэтому ARN и имя никогда не меняются; ваш SecretProviderClass и политика IAM продолжают работать без изменений. Для жизненного цикла сертификата (валидность, кадрия обновления, оповещения об истечении) см. enterprise-docs/kubernetes-deployment.md.

Этап 2: Установка Secrets Store CSI Driver + AWS provider

Пропустите этот шаг, если вы уже запускаете другую рабочую нагрузку, которая монтирует AWS секреты через CSI.
Проверка:
Ожидается: Running для каждого pod’а.
Почему rotationPollInterval=1h? Когда Exosphere публикует обновленный сертификат, Secrets Manager обновляется на месте. CSI Driver перечитывает секрет в этом интервале и переписывает смонтированные файлы. Collector читает файлы сертификата один раз при запуске, поэтому он начинает представлять обновленный сертификат только после перезагрузки процесса; см. § Ротация сертификата о том, как запустить перезагрузку.

Этап 3: Предоставьте pod’у доступ к чтению секрета (IRSA)

3.1 Создание политики IAM

Сохраните как agenteye-mtls-reader-policy.json:
Замените <region>, <account-id> и <cluster-name>. Завершающий -* соответствует шестизначному случайному суффиксу, который AWS добавляет к каждому ARN секрета. Создайте политику:

3.2 Создание роли IAM и привязка к ServiceAccount pod’а

Это создает ServiceAccount с именем agenteye-pod с аннотацией eks.amazonaws.com/role-arn, указывающей на новую роль.

3.3 Требуемые разрешения IAM: итоговая таблица

РазрешениеОбластьПочему
secretsmanager:GetSecretValuearn:aws:secretsmanager:<region>:<acct>:secret:agenteye/mtls-client/<cluster>-*CSI Driver читает пакет сертификата при каждом монтировании и тике ротации.
secretsmanager:DescribeSecretто жеCSI Driver вызывает DescribeSecret для обнаружения изменений версии между опросами.
НЕ предоставляйте secretsmanager:PutSecretValue, secretsmanager:UpdateSecret или secretsmanager:DeleteSecret pod’у. Pod только читает секрет; запись новых версий обрабатывается Exosphere при выдаче или обновлении сертификата. Если секрет зашифрован с использованием управляемого пользователем ключа KMS (не ключа aws/secretsmanager по умолчанию), также предоставьте:

Этап 4: Развертывание Pod’а

4.1 SecretProviderClass

agenteye-mtls-spc.yaml:
Блок jmesPath сообщает AWS provider’у разбить JSON-секрет на три отдельных файла на диске. Кавычки в '"client.crt"' необходимы, потому что JMESPath рассматривает . как оператор подвыражения.

4.2 Манифест Pod / Deployment

Как два контейнера взаимодействуют друг с другом. SDK AgentEye и collector не взаимодействуют через сокет сети; нет локального HTTP-порта. SDK записывает пакеты событий как файлы .jsonl в $AGENTEYE_HOME/events/, и collector непрерывно отслеживает этот каталог и загружает каждый файл. Для pod’а sidecar это означает:
  • Оба контейнера монтируют один и тот же том emptyDir в один и тот же путь.
  • Оба контейнера устанавливают AGENTEYE_HOME на этот путь.
  • Ваш образ приложения должен иметь установленный и настроенный SDK AgentEye (см. enterprise-docs/python-sdk.md).
Когда AGENTEYE_HOME не установлен, как SDK, так и collector по умолчанию используют ~/.agenteye, и два контейнера имеют разные домашние каталоги, поэтому они приземлились бы на две отдельные очереди и передача была бы молчаливо потеряна. Установите AGENTEYE_HOME на одинаковый явный путь на обоих контейнерах. Проверка в §4.3 и соответствующая строка Troubleshooting перехватывают это, если это пропущено.
agenteye-pod.yaml (Deployment с одной копией, масштабируйте по мере необходимости):
Секрет agenteye-collector-api-key содержит API ключ collector’а (см. enterprise-docs/api-keys.md для подготовки). Применить:

4.3 Проверка

Ожидается: client.crt, client.key, ca.crt все присутствуют и только для чтения, принадлежащие пользователю контейнера. Подтвердите, что общая очередь событий видна обоим контейнерам:
Если два списка различаются, том не смонтирован в оба контейнера (или AGENTEYE_HOME отличается); см. § Troubleshooting. Тест дыма end-to-end:
Ожидается: collector загружает все находящиеся в очереди события и печатает сводку Done: N/N uploaded, 0 failed.. Если очередь пуста, она печатает No pending files. и выходит без проверки чего-либо — поэтому запустите это только после того, как ваше приложение выгрузит хотя бы одно событие. Обратите внимание, что flush выходит с ненулевым кодом только для локальных ошибок установки: отсутствует конфигурация (нет разрешенного URL/ключа) или нечитаемый/непарсируемый сертификат TLS (проверьте § Troubleshooting). Неправильный API ключ не меняет код выхода — загрузка получает 401, файл перемещается в failed/, и команда все еще печатает [FAILED] … на файл плюс Done: 0/N uploaded, N failed. и выходит 0. Для обнаружения плохого ключа или отклоненной загрузки читайте выход Done:/[FAILED] или проверяйте файлы, попадающие в $AGENTEYE_HOME/failed/, не код выхода.

Ротация сертификата

Сертификат клиента действителен в течение 90 дней и автоматически обновляется примерно за 15 дней до истечения; затем Exosphere публикует обновленный пакет в тот же секрет Secrets Manager. Оттуда поток in-pod работает следующим образом:
  1. Версия AWSCURRENT секрета Secrets Manager обновляется. ARN и имя не изменяются.
  2. В течение rotationPollInterval (по умолчанию 1 час; см. § Этап 2) CSI Driver читает новую версию и переписывает файлы в /etc/agenteye/tls/.
  3. Collector загружает файлы сертификата один раз при запуске, поэтому он продолжает представлять предыдущий сертификат до перезагрузки процесса. Для переключения на обновленный материал перезагрузите collector’а; rolling restart достаточно:
    Чтобы это было автоматическим, добавьте sidecar, который отслеживает /etc/agenteye/tls/ (например, с inotifywait) и запускает rollout при изменении файлов.
Поскольку предыдущий сертификат остается действительным примерно 15 дней после обновления, у вас есть широкое окно для выполнения перезагрузки без перерыва в приеме. Exosphere публикует обновленный пакет для вас; единственное рутинное действие с вашей стороны — убедиться, что collector перезагружается в этом окне.

Troubleshooting

СимптомВероятная причинаРешение
Pod’а зависает в ContainerCreating, события показывают MountVolume.SetUp failed for volume "agenteye-mtls"CSI provider не может достичь Secrets ManagerПроверьте, правильно ли привязана IRSA: kubectl describe sa agenteye-pod -n <ns> показывает аннотацию eks.amazonaws.com/role-arn. Проверьте CloudTrail для вызова AssumeRole.
Ошибка: AccessDeniedException: not authorized to perform secretsmanager:GetSecretValueПолитика IAM ограничена неправильным ARNСуффикс секрета ARN случайный; используйте agenteye/mtls-client/<cluster>-* с подстановочным знаком, а не точный ARN.
Ошибка: ParameterNotFound от AWS providerНесоответствие имени секрета между SecretProviderClass.objects[].objectName и секретом, доставленным ExosphereПодтвердите точное имя с помощью aws secretsmanager list-secrets --filters Key=tag-key,Values=AgentEyeCluster.
Ошибка jmesPath, смонтирован только один файлСинтаксис JMESPathТочки в ключах JSON требуют двойного кавычирования: '"client.crt"', а не client.crt.
Collector логирует tls: bad certificate после обновленияCSI Driver еще не опросил новую версию, или collector все еще работает с предыдущим сертификатом, который он загрузил при запускеПодтвердите, что смонтированные файлы обновлены (ls -l /etc/agenteye/tls/), затем перезагрузите collector для их загрузки: kubectl rollout restart deploy/my-app-with-collector -n <ns>. См. § Ротация сертификата.
Контейнер Collector crashloops с no such file or directory: /etc/agenteye/tls/client.crtТом еще не заполнен при первом запуске; probe запуска слишком агрессивенДобавьте небольшую начальную задержку или используйте init контейнер, который ждет, пока файл существует: until [ -f /etc/agenteye/tls/client.crt ]; do sleep 1; done.
CSI Driver pod OOMKilledОграничения памяти по умолчанию слишком низки для кластеров со многими SecretProviderClassesУвеличьте --set linux.resources.limits.memory=200Mi в установке Helm.
Приложение работает чисто, agenteye-collector flush сообщает No pending files., но ваша панель управления AgentEye не показывает событияПриложение и collector не совместно используют очередь событийПроверьте, что (a) оба контейнера монтируют один и тот же agenteye-spool emptyDir по одному пути, и (b) оба устанавливают AGENTEYE_HOME на этот путь. Запустите две проверки ls /var/lib/agenteye/ из § 4.3; списки должны совпадать.
Логи для получения в первую очередь:

Справка: файлы на диске в pod’е

Pod имеет два пути данных на диске:

Пакет сертификата mTLS: /etc/agenteye/tls/ (CSI, только для чтения, только collector)

Смонтирован Secrets Store CSI Driver из AWS Secrets Manager.
ФайлСодержаниеИспользуется collector’ом как
client.crtPEM-кодированный сертификат клиентаAGENTEYE_TLS_CERT
client.keyPEM-кодированный приватный ключAGENTEYE_TLS_KEY
ca.crtPEM-кодированный сертификат CAAGENTEYE_TLS_CA (опционально, только когда сертификат сервера AgentEye не подписан публично доверенным центром)
Все три смонтированы только для чтения и принадлежат пользователю контейнера. Они переписываются CSI Driver при ротации секрета.

Очередь событий: $AGENTEYE_HOME/ (emptyDir, общая чтение-запись между обоими контейнерами)

Совместно используется через том emptyDir с именем agenteye-spool.
ПутьЗаписаноПрочитаноНазначение
$AGENTEYE_HOME/events/*.jsonlПриложение (SDK AgentEye)Sweeper collector’аПакеты событий, которые SDK выгрузил, ожидающие загрузки.
$AGENTEYE_HOME/failed/Collector (при ошибке загрузки)Вы (при отладке)Файлы JSONL, которые collector не смог загрузить после повторных попыток.
$AGENTEYE_HOME/config.jsonВы (опционально)CollectorОпциональный файл конфигурации collector’а (альтернатива переменным окружения).
Оба подкаталога events/ и failed/ автоматически создаются collector’ом при запуске; init контейнер не требуется.

Связанные документы