# Міграція з OBI Config v1 на Config v2 > Дізнайтеся, як безпечно перенести файл конфігурації OBI Config v1 на Config v2. --- LLMS index: [llms.txt](/llms.txt) --- OBI v0.11.0 та новіші включають команди для міграції та валідації конфігурації. Мігруйте одне розгортання за раз, перевірте згенерований файл Config v2 і протестуйте його перед продовженням розгортання. Цей посібник пояснює, як мігрувати конфігурації автономного OBI та приймача OBI Колектора. Щодо структури Config v2 та підтримуваних полів див. [Довідка Config v2](../config-v2/). ## Перед міграцією {#before-you-migrate} Підготуйте план відкату перед міграцією: 1. Збережіть поточний файл Config v1. Зафіксуйте точну версію бінарного файлу OBI, тег образу або дайджест образу, що використовує розгортання. 2. Перелічіть будь-які налаштування, передані через змінні середовища, прапорці командного рядка, Helm-значення, Kubernetes-маніфести або інʼєкцію секретів. Команда міграції читає лише файл, який ви надаєте. 3. Встановіть бінарний файл OBI v0.12.1 або новішої цільової версії. 4. Оберіть один репрезентативний екземпляр або робоче навантаження для канаркового розгортання. Команда міграції **розвʼязує** вирази підстановки у вихідному файлі. Тому згенерований файл може містити секретні значення. Записуйте вивід у приватну тимчасову теку, ретельно переглядайте його і не зберігайте секрети в репо чи код. ## Міграція автономної конфігурації {#migrate-a-standalone-configuration} Команда `obi config migrate` приймає один файл Config v1. Вона записує згенерований Config v2 YAML у стандартний вивід, а звіт про міграцію — у стандартний потік помилок. ```sh umask 077 migration_dir="$(mktemp -d)" obi config migrate ./obi-v1.yaml \ > "${migration_dir}/obi-v2.yaml" \ 2> "${migration_dir}/migration-report.txt" ``` Перевірте код виходу перед використанням згенерованого файлу. Код виходу 0 означає успіх. Успішний звіт починається з `migrated v1 config to OBI config v2`. Помилка починається з `migration failed:`. Потім перевірте згенерований файл: ```sh obi config validate "${migration_dir}/obi-v2.yaml" ``` Команди міграції та валідації використовують такі коди виходу: | Статус | Значення | | ------ | ----------------------------------------- | | `0` | Команда виконана успішно. | | `1` | Помилка парсингу, валідації або міграції. | | `2` | Невірний синтаксис або аргументи команди. | ## Розуміння згенерованої структури {#understand-the-generated-structure} Команда міграції переміщує налаштування Config v1 до таких розділів Config v2: | Налаштування Config v1 | Розташування в Config v2 | | --------------------------------------------------------------------- | ----------------------------------------------------------------- | | Селектори виявлення | `extensions.obi.capture.policy` та `extensions.obi.capture.rules` | | Протоколи застосунків | `extensions.obi.capture.instrumentation` | | Інструментування середовищ виконання | `extensions.obi.capture.runtimes` | | Захоплення мережі та статистика | `extensions.obi.capture.network` | | Керування eBPF та пакетною обробкою | `extensions.obi.capture.engine` | | Kubernetes та збагачення імен сервісів | `extensions.obi.enrich` | | Кореляція trace-log | `extensions.obi.correlation` | | Логування процесу, профілювання, завершення роботи, внутрішні метрики | `extensions.obi.daemon` | | Вибірка та експорт трейсів | Кореневий `tracer_provider` | | Експорт метрик | Кореневий `meter_provider` | | Атрибути ресурсів | Кореневий `resource` | Згенерований файл включає явні стандартні значення, коли вони необхідні для збереження поведінки Config v1. Не змінюйте ці значення, доки ви не протестуєте конфігурацію в канарковому розгортанні. ## Перегляд змін поведінки {#review-behavior-changes} ### Стандарти захоплення та порядок правил {#capture-defaults-and-rule-order} Файл Config v1 без полів вибору вимикає захоплення застосунків. На відміну від цього, файл Config v2 стандартно включає робочі навантаження. Щоб зберегти поведінку Config v1, команда міграції встановлює `default_action` на `exclude`, коли вихідний файл не вибирає робоче навантаження. Команда міграції також записує вбудовані виключення і може змінити порядок селекторів включення Config v1. Згенерований порядок зберігає пріоритетність Config v1 у моделі правил Config v2. Не перевпорядковуйте правила, доки ви не протестуєте які накладаються правила та робочі навантаження, що відповідають лише одному правилу. Якщо ви явно встановите `rules: []`, OBI видаляє вбудовані виключення. ### Фільтри {#filters} Config v1 надає по одному фільтру для телеметрії застосунків, мережевої телеметрії та TCP-статистики. Команда міграції копіює кожен фільтр Config v1 у кожне відповідне поле Config v2, щоб згенерована конфігурація зберегла оригінальну поведінку. Після того як ви встановите базову лінію, Config v2 дозволяє налаштовувати фільтри застосунків незалежно для кожного протоколу та сигналу. Наприклад, фільтр HTTP трейсів більше не має відповідати фільтру HTTP метрик або SQL фільтру. Вносьте ці зміни в канарковому розгортанні і порівнюйте обсяг телеметрії та кардинальність перед масовим розгортанням. Фільтри мережевих потоків та TCP-статистики залишаються спільними для трейсів та метрик у v0.12.1. Тримайте дві мапи ідентичними в межах кожної групи. Валідація повідомляє про помилку, коли вони відрізняються. ### HTTP-маршрути {#http-routes} Глобальні налаштування маршрутів Config v1 застосовуються до вхідного та вихідного трафіку. Команда міграції копіює їх до обох напрямків під `capture.instrumentation.http.routes`. Налаштування маршрутів на рівні сервісу переміщуються до `rules[].refine.http.routes`. Для заданого напрямку явний список на рівні сервісу замінює глобальний список, а порожній список його очищає. Міграція зазнає невдачі, коли комбінація глобальних та на рівні сервісу патернів не може зберегти поведінку наслідування Config v1. ### Уточнення робочих навантажень {#workload-refinements} Селектори Config v1 можуть включати уточнення експорту та маршрутів. У Config v2 правило включення не успадковує опущене уточнення з попереднього відповідного правила. Коли ця різниця змінить поведінку, міграція не вдається для списків селекторів, що змішують явні та опущені поля `exports` або `routes`. Для міграції таких селекторів зробіть кожне уточнення явним на кожному застосованому селекторі. Перебудуйте селектори, що залежать від умовного успадкування, таким чином, щоб кожне правило Config v2 було самостійним, а потім перевірте всі правила, що перекриваються. ## Налаштування експортерів {#configure-exporters} Config v2 визначає конвеєри телеметрії в розділах OpenTelemetry верхнього рівня. Команда міграції може генерувати OTLP/gRPC експортери. Міграція не вдається, якщо команда не може визначити точку доступу або протокол без зміни його значення. Використовуйте наступну конфігурацію для OTLP/gRPC експортера трейсів: ```yaml tracer_provider: processors: - batch: exporter: otlp_grpc: endpoint: http://collector:4317 tls: insecure: true ``` Використовуйте наступну конфігурацію для OTLP/gRPC експортера метрик: ```yaml meter_provider: readers: - periodic: exporter: otlp_grpc: endpoint: http://collector:4317 tls: insecure: true interval: 60000 ``` Якщо файл Config v1 використовує OTLP через HTTP, спочатку мігруйте інші налаштування. Потім додайте HTTP-експортери вручну: ```yaml tracer_provider: processors: - batch: exporter: otlp_http: endpoint: http://collector:4318/v1/traces encoding: protobuf meter_provider: readers: - periodic: exporter: otlp_http: endpoint: http://collector:4318/v1/metrics encoding: protobuf ``` Для OTLP через HTTP ви також можете встановити `encoding` на `json`. Config v2 також підтримує декларативні заголовки експортера. Змінні середовища для автентифікації експортера залишаються вхідними даними під час виконання; команда міграції не копіює їхні значення у згенерований файл. ## Обробка налаштувань, що вимагають ручних змін {#handle-settings-that-need-manual-changes} Якщо команда міграції не може зберегти налаштування, вона не вдається і ідентифікує поле Config v1 у повідомленні про помилку. Замініть або видаліть непідтримувану поведінку перед повторним запуском команди. Наступні налаштування часто вимагають ручних змін: | Налаштування Config v1 | Що робити | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `service_name`, `service_namespace` | Для автономного OBI встановіть `service.name` або `service.namespace` як атрибути ресурсу верхнього рівня. Для приймача OBI Колектора використовуйте процесор ресурсів Колектора. | | `prometheus_export.path` | Використовуйте шлях, підтримуваний вибраним Колектором або Prometheus-експортером. Config v2 не має переносного поля для цього. | | Користувацькі або порожні `discovery.excluded_linux_system_paths` | Замініть виключення на основі шляхів на виключення робочих навантажень у `capture.rules`. Видаліть налаштування, якщо відповідне виключення робочого навантаження не потрібне. | | `health_check.*` | Використовуйте перевірки стану розгортання або засоби перевірки стану Колектора. | | `jvm_runtime_metrics.sampling_interval` | Видаліть користувацький інтервал і протестуйте поведінку вибірки JVM Config v2. | | `attributes.instance_id.dns` | Встановіть `service.instance.id` як атрибут ресурсу верхнього рівня або перенесіть збагачення ідентичності екземпляра в процесор Колектора. | | `ebpf.stats_wakeup_data_bytes` | Видаліть користувацький поріг пробудження і протестуйте продуктивність з Config v2 стандартними значеннями. | | Селектор `name`, `namespace`, метрики на рівні селектора, або селектор вибірки | Перепроєктуйте селектор з підтримуваними полями `match` та `refine`. Розділіть його на явні правила, коли уточнення відрізняються. | | Селектор `exports.logs` | Видаліть уточнення експорту логів на рівні селектора. Використовуйте правила захоплення для вибору робочих навантажень, придатних для кореляції логів. | | `ebpf.log_enricher.services` | Замініть окремий селектор анотації логів правилами захоплення, що вибирають придатні робочі навантаження. | | `sensitive_query_params` | Перепроєктуйте політику приватності перед міграцією. Config v2 не має еквівалентного поля. | | Debug-експортер або непідтримуваний семплер | Налаштуйте підтримуваний OTLP-експортер або семплер. | | Різні активні списки інструментування OTLP та Prometheus | Зробіть увімкнення метрик протоколів послідовним перед міграцією. | Команда також повідомляє про інші непідтримувані функції метрик та гістограму, експортер або Prometheus налаштування окремо. Перегляньте та вирішіть кожне повідомлене поле перед повторним запуском міграції. Коли поле не має прямого еквіваленту, оберіть підтримувану поведінку Config v2 або Колектора і перевірте зміну в канарковому розгортанні. Команда також відхиляє невідомі поля Config v1, файли, які вже використовують Config v2, та файли, що містять кілька YAML-документів. Наприклад, привʼяжіть спеціально створену ідентифікацію автономної служби до атрибутів ресурсу: ```yaml resource: attributes: - name: service.name value: checkout - name: service.namespace value: shop ``` Додайте цей фрагмент лише в корінь автономної конфігурації. Для приймача OBI Колектора використовуйте процесор ресурсів Колектора. ## Міграція перевизначень середовищем {#migrate-environment-overrides} Команда міграції читає вихідний файл, але не застосовує перевизначення середовищем OBI часу виконання. OBI також автоматично не зіставляє імена змінних середовища Config v1 з полями Config v2. Наприклад, якщо ваше розгортання встановлює `OTEL_EBPF_BPF_WAKEUP_LEN=999`, додайте явний вираз підстановки у відповідне поле Config v2: ```yaml extensions: obi: version: '2.0' capture: engine: batching: wakeup_len: ${OTEL_EBPF_BPF_WAKEUP_LEN:-500} ``` Ви можете використовувати `${VAR}`, `${env:VAR}` або їхні форми `:-fallback` у файлі конфігурації. Ви також можете використовувати еквівалентні форми `$()`. Щоб зберегти вираз як літеральний текст, додайте перед ним додатковий `$`. Перегляньте перевизначення командного рядка та рівня розгортання так само. Перенесіть кожне значення у відповідне поле Config v2 або налаштування конвеєра Колектора. ## Міграція приймача Колектора {#migrate-a-collector-receiver} Передайте тіло компонента приймача OBI команді міграції, а не повну конфігурацію Колектора: ```sh obi config migrate --mode=receiver ./obi-receiver-v1.yaml \ > ./obi-receiver-v2.yaml \ 2> ./migration-report.txt obi config validate --mode=receiver ./obi-receiver-v2.yaml ``` Команда генерує тіло компонента приймача Config v2. У цьому форматі поля захоплення зʼявляються поруч з `version` без рівня `capture`: ```yaml version: '2.0' policy: default_action: exclude rules: - action: include match: process: open_ports: '8080' ``` Після успішної валідації скопіюйте тіло компонента з `receivers.obi` у конфігурації Колектора. Міграція приймача не приймає автономні експортери, збагачення, кореляцію, daemon або поля внутрішньої телеметрії. Налаштуйте еквівалентну поведінку з експортерами Колектора, процесорами, розширеннями та сервісною телеметрією. Див. [Запуск OBI як приймача Колектора](../collector-receiver/) для повного прикладу конвеєра. ## Валідація та тестування міграції {#validate-and-test-the-migration} `obi config validate` перевіряє структуру YAML і контролює, чи підтримує OBI вказані поля Config v2. Команда не запускає OBI, не звертається до експортерів, не приєднує eBPF-програми і не перевіряє можливості ядра. Після успішної валідації розгорніть Config v2 на одному екземплярі і порівняйте його з розгортанням Config v1: - Підтвердіть, що ті самі робочі навантаження включені та виключені. - Підтвердіть трейси, метрики, маршрути, атрибути та поведінку вибірки. - Підтвердіть зʼєднання експортера та автентифікацію. - Порівняйте обсяг телеметрії та кардинальність. - Перевірте логи OBI та внутрішні метрики на наявність помилок або зворотного тиску. - Запустіть робочі навантаження, що відповідають правилам вибору. Зберігайте файл Config v1 та попередній бінарний файл OBI або образ доступними під час канаркового тесту. Якщо поведінка відрізняється, відкотіть конфігурацію та версію OBI. Вирішіть невідповідність перед продовженням розгортання.