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> |
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:GetSecretValue | arn: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:
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 работает следующим образом:-
Версия
AWSCURRENTсекрета Secrets Manager обновляется. ARN и имя не изменяются. -
В течение
rotationPollInterval(по умолчанию 1 час; см. § Этап 2) CSI Driver читает новую версию и переписывает файлы в/etc/agenteye/tls/. -
Collector загружает файлы сертификата один раз при запуске, поэтому он продолжает представлять предыдущий сертификат до перезагрузки процесса. Для переключения на обновленный материал перезагрузите collector’а; rolling restart достаточно:
Чтобы это было автоматическим, добавьте sidecar, который отслеживает
/etc/agenteye/tls/(например, сinotifywait) и запускает rollout при изменении файлов.
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.crt | PEM-кодированный сертификат клиента | AGENTEYE_TLS_CERT |
client.key | PEM-кодированный приватный ключ | AGENTEYE_TLS_KEY |
ca.crt | PEM-кодированный сертификат CA | AGENTEYE_TLS_CA (опционально, только когда сертификат сервера AgentEye не подписан публично доверенным центром) |
Очередь событий: $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 контейнер не требуется.
Связанные документы
- enterprise-docs/collector-installation.md: опции бинарного файла collector, справочник конфигурации mTLS, режимы демона.
- enterprise-docs/kubernetes-deployment.md: развертывание на несколько pod’ов, внутренние процессы выдачи сертификата, оповещения о жизненном цикле и истечении.
- enterprise-docs/api-keys.md: подготовка API ключа collector’а, потребляемого pod’ом.
- enterprise-docs/troubleshooting.md: индекс troubleshooting’а на уровне кластера.

