Okoscope Cloud — Быстрый старт

Подключите приложение в своём Kubernetes-кластере к Okoscope Cloud. Вы устанавливаете агента в кластере; сервер, веб-интерфейс и базу данных обслуживаем мы.

Перед началом

Это инструкция для Okoscope Cloud. Для установки собственного сервера используйте руководство «Self-hosted — Самостоятельное развёртывание».

Перед установкой агента подготовьте следующее:

• Kubernetes-кластер, соответствующий требованиям из раздела «Совместимость и ограничения», и работающий Deployment, за которым вы хотите наблюдать.
• kubectl и Helm, доступ к нужному кластеру и права на установку ресурсов чарта. Проверьте текущий контекст командой ниже.
• Возможность исходящего TLS-соединения от агента к https://grpc.okoscope.com:443.
• Ознакомьтесь с разделом «Данные и безопасность»: агенту eBPF нужны права уровня узла и доступ к ресурсам хоста. Его права на обращение к Kubernetes API ограничены чтением.

kubectl config current-context

1. Доступ и приложение
2. Нагрузка Kubernetes
3. Secret с токеном
4. Установка агента
5. Проверка запуска
6. Первое наблюдение

Получите доступ и создайте приложение

Откройте https://okoscope.com и войдите в учётную запись или зарегистрируйтесь. После регистрации придёт приветственное письмо: сеанс появится только после явного подтверждения ссылки и последующего входа.

При регистрации создаётся ваша организация, а вы становитесь её владельцем. Внутри неё создаются проекты и приложения:

Организация → Проект → Приложение

Проект группирует связанные приложения.

К приложению в Okoscope будут привязаны наблюдения выбранной Kubernetes-нагрузки.

Если у вас уже есть доступ к организации, используйте её. Если доступ или создание ресурсов недоступны, обратитесь к владельцу организации.

1. Откройте «Подключение агента» в основном меню или перейдите на https://okoscope.com/onboarding.
2. Выберите существующий проект или создайте его прямо в мастере, например Production.
3. Выберите существующее приложение или создайте его, например payment-api. На следующем экране вы настроите его подключение к Kubernetes-нагрузке.

Другой способ открыть мастер

Если у приложения ещё нет наблюдений рабочих узлов, в разделе «Рабочие узлы» доступна кнопка «Подключить агента». Она открывает тот же мастер с выбором проекта и приложения.

Укажите Kubernetes-нагрузку

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

1. «Название кластера» — понятное вам имя, например production. Оно сохраняется в установке и передаётся агенту как identity.clusterName.
2. «Namespace нагрузки» — пространство имён, в котором находится Deployment, например production. Оно может отличаться от пространства имён, где будут установлены агент и его Secret.
3. «Имя Deployment» или «Селектор меток» — введите точное имя Deployment, например payment-api, либо метки вида app=payment-api,environment=production. Метки должны выбирать ровно один Deployment в указанном пространстве имён.
4. Прочитайте «Расширенные настройки наблюдения». Это описание настроек чарта по умолчанию, без редактируемых полей: включены жизненный цикл процессов и основная сетевая активность; наблюдение файлов и экспериментальные функции выключены.
5. Нажмите «Создать установку». Мастер покажет одноразово отображаемый токен приложения и команды для создания Secret и установки агента.

Создайте Secret с токеном

Токен приложения нужен агенту для аутентификации. Скопируйте его из мастера до закрытия или перезагрузки страницы: повторно показать исходный токен нельзя.

Чарт читает токен из уже существующего Kubernetes Secret. Используйте команду создания Secret из мастера: в ней указаны нужные пространство имён, имя Secret и ключ.

Не помещайте токен в Helm values, ConfigMap, Git, скриншоты или журналы.

1. Выполните команду из мастера в Bash или zsh, предварительно выбрав нужный контекст Kubernetes.
2. При появлении приглашения вставьте токен и нажмите Enter. Ввод не отображается. Команда создаст или обновит Secret, а затем очистит переменную оболочки.
3. Убедитесь, что команда завершилась успешно, прежде чем переходить к Helm. В примере ниже пространство имён агента — okoscope-system, а ключ Secret — payment-api; используйте значения из своего мастера.

Если вы перезагрузили страницу

Выберите те же проект и приложение, чтобы вернуться к сохранённой установке. Если токен потерян, воспользуйтесь кнопкой «Заменить потерянный credential». Это отзывает прежний токен: обновите Kubernetes Secret новым токеном перед продолжением.

kubectl create namespace okoscope-system --dry-run=client -o yaml | kubectl apply -f -
printf "Okoscope Application token: " >&2
IFS= read -rs OKOSCOPE_TOKEN
printf '\n' >&2
kubectl -n okoscope-system create secret generic okoscope-application-credentials \
  --from-literal=payment-api="$OKOSCOPE_TOKEN" \
  --dry-run=client -o yaml | kubectl apply -f -
unset OKOSCOPE_TOKEN

Установите агента

После создания Secret выполните команду Helm из мастера. Она содержит совместимую версию чарта, адрес Cloud, параметры выбора нагрузки и ссылку на ваш Secret.

Чарт okoscope-agent создаёт конфигурацию агента, DaemonSet, ServiceAccount и права чтения Kubernetes API (RBAC).

Okoscope Cloud использует публично доверенный TLS-сертификат: оставьте системное доверие и параметр server.developmentPlaintext выключенным. Secret с частным CA не требуется.

Команда ниже показывает пример установки для Deployment payment-api в пространстве имён production. Имя Secret и ключ в команде Helm должны совпадать со значениями из команды создания Secret.

Для отдельных установок используйте уникальные имена Helm-релизов даже в разных пространствах имён: имена ClusterRole и ClusterRoleBinding по умолчанию зависят от имени релиза и должны быть уникальны во всём кластере. Измените первый аргумент имени релиза (okoscope-agent) и --namespace в команде Helm и создайте Secret с токеном в том же пространстве имён агента. В командах проверки также укажите соответствующие имя релиза и пространство имён.

Замените значения из примера

<OKOSCOPE_VERSION> — заполнитель, а не переменная окружения. Замените его версией из мастера и укажите свои значения кластера и нагрузки. Удобнее скопировать готовую команду целиком. Если конфигурация Cloud недоступна, обратитесь к оператору Okoscope.

helm upgrade --install okoscope-agent \
  oci://ghcr.io/okoscope/charts/okoscope-agent \
  --version <OKOSCOPE_VERSION> \
  --namespace okoscope-system \
  --set server.endpoint=https://grpc.okoscope.com:443 \
  --set identity.clusterName=production \
  --set 'workloads[0].namespace=production' \
  --set 'workloads[0].kind=Deployment' \
  --set 'workloads[0].name=payment-api' \
  --set 'workloads[0].credentialSecret.name=okoscope-application-credentials' \
  --set 'workloads[0].credentialSecret.key=payment-api'

Проверьте запуск агента

Дождитесь завершения развёртывания DaemonSet, затем проверьте журналы агента на ошибки запуска или подключения. Команды используют имя релиза и пространство имён из примера выше.

Вернитесь к блоку «Прогресс подключения» в мастере.

Как только агенты подключатся к серверу, они должны автоматически появиться в разделе приложения «Рабочие узлы».

Работающий Pod подтверждает запуск. Для проверки подключения нужно также дождаться события от выбранной нагрузки на сервере.

kubectl -n okoscope-system rollout status daemonset/okoscope-agent-okoscope-agent --timeout=5m
kubectl -n okoscope-system logs daemonset/okoscope-agent-okoscope-agent --tail=100

Подтвердите первое наблюдение

Когда агент подключился, создайте активность в выбранном Deployment.

Наблюдения создания процессов и выполнения программ задним числом не восстанавливаются. У процесса, который уже работал к началу наблюдения, нет исторического события создания; только последующий наблюдаемый exec создаст событие выполнения программы.

1. Отправьте обычный запрос к приложению или выполните контролируемый тест, который создаёт процесс, выполняет программу либо открывает сетевое соединение.
2. Дождитесь статуса «Получаем runtime-события» в мастере. Если он сообщает, что нагрузка не найдена или нет разрешения, следуйте подсказке рядом со статусом.
3. Нажмите «Открыть приложение», выберите недавний временной интервал и найдите в группах событий или инвентаризации запись с ожидаемой нагрузкой и временем.

Если событий нет

Откройте Устранение проблем и FAQ и проверьте селектор нагрузки, журналы агента и состояние подключения. Переходите к дополнительным возможностям наблюдения после проверки базового сценария.

Дополнительно: несколько приложений и частный реестр

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

• Добавьте по элементу workloads на приложение. Каждый элемент должен выбирать ровно один Deployment по имени или меткам и ссылаться на имя Secret и ключ с токеном соответствующего приложения.
• Для образов из частного реестра укажите существующий Secret для загрузки образов через imagePullSecrets.
• Не записывайте значения токенов в Helm values-файлы. Настройка частного CA для собственного сервера описана в Self-hosted — Самостоятельное развёртывание.

Удаление Okoscope из кластера

Чтобы отменить установку, сначала проверьте текущий контекст Kubernetes и подставьте в команды ниже фактические имя Helm-релиза и пространство имён агента. Удаление общего релиза остановит наблюдение за всеми приложениями, настроенными в нём.

helm uninstall удаляет DaemonSet и поды агента, ConfigMap, ServiceAccount, ClusterRole и ClusterRoleBinding этого релиза. Созданный отдельно Secret с токеном остаётся: удалите его, только если он не нужен другим установкам. Укажите его фактическое имя: мастер использует okoscope-agent-credentials, а пример в этом руководстве — okoscope-application-credentials.

Если сохраняете пространство имён агента, удалите ненужные Secret для реестра или частного CA, созданные только для этой установки. Не удаляйте общие Secret и посторонние ресурсы.

Очистка кластера не отзывает токен приложения и не удаляет данные, уже отправленные в Okoscope Cloud. Отдельно отзовите ненужные учётные данные в Cloud; для удаления сохранённых данных обратитесь к оператору Okoscope.

Агенты в разных пространствах имён

Найдите свои релизы Okoscope командой helm list --all-namespaces и повторите удаление и очистку для каждого релиза в его пространстве имён агента. Удаление одного пространства имён не удаляет установки в других.

kubectl config current-context
helm uninstall okoscope-agent --namespace okoscope-system --wait
kubectl -n okoscope-system delete secret okoscope-application-credentials

Необязательно: удалите пространство имён агента

После удаления Helm-релиза удаляйте его пространство имён, только если вы создали его исключительно для агента и в нём нет нужных ресурсов. Это уничтожит всё его содержимое: сохраните наблюдаемый Deployment и пространство имён нагрузки. Замените пространство имён в примере фактическим пространством имён агента.

kubectl delete namespace okoscope-system

Читайте также

• Совместимость и ограничения
• Self-hosted — Самостоятельное развёртывание
• Устранение проблем и FAQ
• Данные и безопасность