Кэш на собственном сервере
Узлы кэша на собственном сервере позволяют хранить артефакты сборки и метаданные кэша рядом с машинами, которые создают и потребляют результаты сборки. Используйте их, когда важна задержка кэша в CI, офисах разработчиков, на удалённых рабочих станциях или в региональных вычислительных кластерах.
Цель — обеспечить кэширование с низкой задержкой повсюду, а не только в той среде, где центральный кэш случайно оказался поблизости. Каждый узел кэша обслуживает чтение и запись с локального диска, а сеть реплицирует артефакты и метаданные между узлами, чтобы другие локации со временем могли использовать тот же кэш.
Узлы собственного кэша Tuist работают на базе Kura — децентрализованной сети кэша Tuist. Kura является плоскостью данных для узлов кэша: она обслуживает операции чтения и записи кэша, хранит локальное состояние на диске и реплицирует артефакты и метаданные на соседние узлы.
Как собственный кэш интегрируется с Tuist#
Управляемый кэш Tuist использует https://<account>.cache.tuist.dev. При использовании собственного сервера Tuist CLI получает URL кэша из настройки сервера TUIST_CACHE_ENDPOINTS. Укажите URL вашего основного сервера кэша или балансировщика нагрузки. Если указано несколько URL, используется первый.
Для частных или пользовательских узлов кэша, подключённых к размещённому серверу Tuist, явно задайте конечную точку в оболочках разработчиков и в CI:
export TUIST_CACHE_ENDPOINT=https://cache.example.com
Это переопределение имеет приоритет на обоих типах серверов и является необязательным для собственных серверов Tuist. Для демона кэша Xcode после установки повторно выполните tuist setup cache, чтобы LaunchAgent получил обновлённое окружение.
Собственный сервер Tuist берёт конечные точки из статической конфигурации. На размещённом сервере Tuist узлы проходят аутентификацию по учётным данным и регистрируются. Сначала разверните узел, следуя одному из двух разделов ниже, затем см. Подключение узлов к Tuist.
Развёртывание в Kubernetes#
Kura распространяется как Helm-чарт через GitHub Container Registry. Он разворачивает Kura как StatefulSet с постоянными томами, headless-сервисом для обнаружения узлов и обычным сервисом для HTTP- и gRPC-трафика.
helm upgrade --install kura oci://ghcr.io/tuist/charts/kura \
--namespace kura \
--create-namespace \
--version <version> \
--set image.tag=<tag> \
--set config.region=local
Для собственного сервера Tuist в том же кластере настройте его основную конечную точку кэша:
server:
cacheEndpointUrl: "http://kura.kura.svc.cluster.local:4000"
Это устанавливает TUIST_CACHE_ENDPOINTS в поде сервера. Используйте адрес, доступный машинам разработчиков и CI; приведённое выше имя сервиса внутри кластера подходит для клиентов, работающих внутри кластера.
Каждый узел Kura должен владеть своим собственным KURA_DATA_DIR. Kura устанавливает блокировку уровня приложения на запись в каталог данных и ожидает, что им будет владеть ровно один процесс. В Kubernetes используйте по одному постоянному тому на под. Вне Kubernetes не направляйте несколько процессов в один и тот же смонтированный каталог.
Развёртывание без Kubernetes#
Kura также может работать как обычный контейнер на виртуальных машинах или bare-metal-хостах. В этом режиме вы отвечаете за мониторинг процессов, постоянное хранилище, маршрутизацию и обнаружение узлов.
Как минимум каждому узлу нужны постоянный каталог данных, временный каталог, публичный порт кэша (один слушатель обслуживает и HTTP API кэша, и REAPI gRPC), внутренний URL узла, а также либо статический список узлов, либо механизм обнаружения:
docker run -d --name kura \
-p 4000:4000 \
-p 7443:7443 \
-v /var/lib/kura:/var/cache/kura \
-e KURA_PORT=4000 \
-e KURA_INTERNAL_PORT=7443 \
-e KURA_TENANT_ID=default \
-e KURA_REGION=local \
-e KURA_TMP_DIR=/var/cache/kura/tmp \
-e KURA_DATA_DIR=/var/cache/kura \
-e KURA_NODE_URL=http://kura-1.internal:7443 \
-e KURA_PEERS=http://kura-1.internal:7443,http://kura-2.internal:7443 \
ghcr.io/tuist/kura:<tag>
На собственном сервере Tuist настройте основной URL кэша, доступный машинам разработчиков и CI:
TUIST_CACHE_ENDPOINTS=https://cache.example.com
Размещение узлов за балансировщиком нагрузки#
Клиенты используют каждый URL конечной точки кэша как для HTTP, так и для gRPC: HTTP для проверок работоспособности и HTTP API кэша, gRPC для кэша модулей и удалённого кэша Bazel. Любой ingress, балансировщик нагрузки или CDN между клиентами и Kura должен перенаправлять оба протокола на одном хосте и порту. Это относится ко всем конечным точкам, которые получают клиенты, потому что CLI выбирает ту, которая отвечает быстрее всего. Если gRPC не достигает Kura, CLI предупреждает, что удалённое кэширование модулей недоступно, и использует только локальный кэш модулей.
Маршрутизируйте эти префиксы путей в Kura как gRPC поверх HTTP/2, а всё остальное — как HTTP:
| Префикс пути | Используется |
|---|---|
/build.bazel.remote.execution.v2. |
Кэш модулей, Bazel |
/google.bytestream. |
Кэш модулей, Bazel |
/build.bazel.remote.asset.v1. |
Bazel |
/google.devtools.build.v1. |
События сборки Bazel |
Kura принимает незашифрованный HTTP/2 (h2c) на KURA_PORT и HTTP/2 поверх TLS на KURA_HTTPS_PORT, если заданы KURA_PUBLIC_TLS_CERT_PATH и KURA_PUBLIC_TLS_KEY_PATH. Если ваш прокси повторно использует исходящие соединения между запросами, как это делает ingress-nginx, установите KURA_GATEWAY_GRPC_PORT и направляйте gRPC-трафик на этот порт. Он обслуживает только gRPC, поэтому запросы HTTP/1.1 и gRPC никогда не используют одно соединение.
Настройте маршруты gRPC следующим образом:
- Без ограничения размера тела запроса. Загрузка отправляет один файл в одном запросе, до 2 ГиБ.
- Буферизация запросов и ответов отключена.
- Таймауты чтения, отправки и простоя не менее 300 секунд.
Kura не предоставляет службу проверки работоспособности gRPC. Проверяйте работоспособность узлов по HTTP на /ready. Если ваш балансировщик нагрузки требует проверку работоспособности gRPC, вызовите /build.bazel.remote.execution.v2.Capabilities/GetCapabilities и принимайте коды состояния gRPC 0 и 16. Узел с включённой авторизацией отвечает на запрос без токена кодом 16 (UNAUTHENTICATED).
ingress-nginx#
При использовании Helm-чарта оставьте HTTP-ingress на / и добавьте gRPC-ingress для того же хоста. TLS объявляется только в HTTP-ingress:
service:
gatewayGrpcPort: 4001
ingress:
enabled: true
className: nginx
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: "0"
nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
hosts:
- host: kura.example.com
paths:
- path: /
pathType: Prefix
tls:
- hosts:
- kura.example.com
secretName: kura-tls
grpcIngress:
enabled: true
className: nginx
annotations:
nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
nginx.ingress.kubernetes.io/use-regex: "true"
nginx.ingress.kubernetes.io/proxy-body-size: "0"
nginx.ingress.kubernetes.io/proxy-buffering: "off"
nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
hosts:
- host: kura.example.com
paths:
- path: /build\.bazel\.remote\.execution\.v2\.
pathType: ImplementationSpecific
- path: /google\.bytestream\.
pathType: ImplementationSpecific
- path: /build\.bazel\.remote\.asset\.v1\.
pathType: ImplementationSpecific
- path: /google\.devtools\.build\.v1\.
pathType: ImplementationSpecific
AWS Application Load Balancer#
Группам целей gRPC нужен HTTPS-слушатель. На этом слушателе:
- Перенаправьте правило по умолчанию в группу целей с версией протокола
HTTP1наKURA_PORT, проверяя работоспособность по HTTP на/ready. - Создайте вторую группу целей с версией протокола
gRPC, используя протоколHTTPнаKURA_GATEWAY_GRPC_PORT(илиKURA_PORT), либо протоколHTTPSнаKURA_HTTPS_PORT. Настройте её проверку работоспособности, как описано выше. - Добавьте правило, которое перенаправляет шаблоны путей
/build.bazel.remote.execution.v2.*,/google.bytestream.*,/build.bazel.remote.asset.v1.*и/google.devtools.build.v1.*во вторую группу целей. - Увеличьте таймаут простоя балансировщика нагрузки до не менее 300 секунд.
CDN#
CDN перед узлом должен поддерживать gRPC и не блокировать пути gRPC в своих правилах межсетевого экрана. Клиенты загружают большие артефакты частями размером не более 2 МиБ, а узел собирает их, поэтому ни один запрос не требует большого тела или длительной загрузки. Кэш модулей и кэш компиляции Xcode работают так же, как и Bazel при сборке с флагом --experimental_remote_cache_chunking (Bazel 8.7 и 9.1 или новее). Без этого флага Bazel загружает каждый вывод в одном запросе, поэтому CDN также должен разрешать большие тела запросов и загрузки, которые занимают столько времени, сколько требуется для ваших самых больших выводов на самом медленном канале связи. Если ваш CDN не может соответствовать этим требованиям, предоставьте клиентам имя хоста, которое обходит его, например запись только с DNS.
Cloudflare#
Кэширование модулей работает через проксируемое имя хоста Cloudflare на любом тарифном плане. В зоне:
- В разделе Network включите gRPC.
- В разделе SSL/TLS установите режим шифрования Full или Full (strict). Cloudflare подключается к источнику через порт 443, поэтому источник должен обслуживать TLS на этом порту и поддерживать HTTP/2 через ALPN.
- Убедитесь, что никакое пользовательское или управляемое правило WAF не блокирует перечисленные выше пути gRPC.
Cloudflare завершает запрос, если источник не начал отвечать примерно через две минуты. Загрузка Bazel без --experimental_remote_cache_chunking получает ответ только после прибытия последнего байта, поэтому в Cloudflare такие загрузки завершаются ошибкой, если они занимают больше времени.
Подключение узлов к Tuist#
Настройте маршрутизацию клиентов и зарегистрируйте свои узлы в Tuist, чтобы их адреса, готовность и использование отображались в панели управления.
На самостоятельно размещённом сервере Tuist вы statically объявляете конечные точки с помощью TUIST_CACHE_ENDPOINTS, как показано в разделах развёртывания выше. CLI использует первый настроенный URL. TUIST_CACHE_ENDPOINT переопределяет этот URL для отдельного клиента.
На сервере, размещённом Tuist, установите TUIST_CACHE_ENDPOINT в оболочках разработчиков и CI, чтобы направлять запросы к кэшу на ваши узлы. Каждый узел проходит аутентификацию с учётными данными, которые вы генерируете, затем регистрирует свой адрес и сообщает о своей готовности панели управления. В этом разделе описана регистрация узлов.
Самостоятельно размещённые узлы кэша доступны на тарифе Enterprise. Раздел Self-hosted servers, описанный ниже, отображается только для аккаунтов на этом тарифе.
Генерация учётных данных узла#
В панели управления Tuist откройте свой аккаунт, перейдите в раздел Cache и найдите Self-hosted servers. Выберите Generate credential, чтобы создать клиентский ID и секрет.
Учётные данные авторизуют трафик только для аккаунта, который их создал.
Секрет отображается один раз и не может быть восстановлен после закрытия диалогового окна, поэтому сразу скопируйте его в хранилище секретов, из которого читают ваши узлы. Отзыв учётных данных немедленно прекращает аутентификацию всех использующих их узлов, поэтому перед отзывом действующих учётных данных создайте замену.
Регистрация узла при запуске#
Регистрация — рекомендуемый способ запуска узла. Установите KURA_ENROLL_ON_BOOT и укажите узлу его учётные данные и собственный peer-URL:
KURA_ENROLL_ON_BOOT=true
KURA_CONTROL_PLANE_URL=https://tuist.dev
KURA_CONTROL_PLANE_CLIENT_ID=<client ID>
KURA_CONTROL_PLANE_CLIENT_SECRET=<client secret>
KURA_NODE_URL=https://kura-1.internal:7443
Узел локально генерирует свою пару ключей, поэтому закрытый ключ никогда не покидает его, и получает подписанный peer-сертификат, CA аккаунта, идентификатор арендатора и список peers. Это всё, что иначе пришлось бы настраивать вручную: зарегистрированному узлу не нужны KURA_TENANT_ID, KURA_PEERS и настройка peer-TLS.
Оставьте KURA_INTERNAL_TLS_* неустановленным: при регистрации материалы сертификата записываются в каталог tls внутри KURA_DATA_DIR. Указывайте эти пути самостоятельно только если вы предоставляете сертификаты вместо регистрации, как описано в разделе Построение сетки кэша.
Узел, впервые присоединяющийся к сетке аккаунта, загружает существующий кэш аккаунта перед тем, как стать обслуживающим участником кольца. Выделите место на диске под весь кэш и учитывайте, что первое присоединение через канал связи широкой зоны может занять некоторое время. Узел сообщает статус joining, пока не синхронизируется, а затем serving.
Объявление конечной точки#
Регистрация добавляет узел в сетку. Регистрация сообщает клиентский адрес узла и его готовность в Tuist. Установите переменные регистрации:
KURA_REGISTRATION_URL=https://tuist.dev/_internal/kura/mesh/registrations
KURA_ADVERTISED_HTTP_URL=https://kura-1.example.com:4443
Узел отправляет heartbeat каждые 60 секунд в рамках аренды на 180 секунд. Tuist считает регистрацию недоступной, когда срок аренды истекает. Tuist никогда не вызывает узел, поэтому он должен быть доступен только вашим клиентам, а не из интернета.
Проверка работы узла#
Вернувшись в раздел Cache панели управления, вы увидите узел в списке Registered nodes с его конечной точкой, регионом, статусом и временем последнего heartbeat. Узел, который никогда не появляется, не достигает конечной точки регистрации или не проходит авторизацию. Узел, который появляется, а затем исчезает, перестал отправлять heartbeat или сообщать о своей готовности.
Использование постоянного идентификатора арендатора аккаунта#
KURA_TENANT_ID — это постоянный идентификатор кэша аккаунта. Для аккаунта, который никогда не переименовывался, он совпадает с handle аккаунта. После переименования сохраняйте исходное значение на каждом узле, включая заменяющие: изменение этого значения выбирает другое пространство хранения, а переименование аккаунта не переносит сохранённые артефакты. Используйте идентификатор арендатора от существующего узла или tenant_id, возвращённый при регистрации, вместо того чтобы определять его по текущему URL аккаунта.
Плоскость управления сравнивает арендатора из heartbeat с аккаунтом, разрешённым из учётных данных, и отклоняет несоответствие кодом 409 tenant_mismatch, поэтому узел с неправильным значением успешно проходит аутентификацию, но так и не регистрируется.
И Helm-чарт, и пример контейнера ранее в этом руководстве по умолчанию устанавливают это значение в default. Замените его на идентификатор арендатора аккаунта перед регистрацией узла. Регистрация узла полностью избегает этого вопроса, так как плоскость управления предоставляет значение.
Неустановленный KURA_TENANT_ID не пропускает проверку. Он полностью отключает регистрацию: узел продолжает обслуживать трафик кэша, в панели управления ничего не появляется, и ошибки не сообщаются. Если узел исправен, но отсутствует в списке Registered nodes, сначала проверьте эту переменную.
Выбор объявленного URL, доступного вашим клиентам#
Используйте адрес, доступный клиентам, для KURA_ADVERTISED_HTTP_URL и для URL кэша, настроенного на сервере Tuist или в CLI.
Имя хоста, доступное только во внутренней сети, подходит, если каждый клиент, настроенный на его использование, может разрешить это имя и подключиться к нему. Для клиентов в разных сетях используйте общий доступный адрес или настройте доступный узел кэша для каждой среды.
Создание сетки кэша#
Сетка кэша позволяет размещать ёмкость кэша рядом с вычислительными ресурсами, которым она нужна. Компания может запустить один узел рядом со своими основными CI-раннерами, другой — близко к разработчикам в Европе, а третий — рядом с офисом в США или региональным кластером сборок. Каждое местоположение читает и записывает данные через ближайший узел, а Kura фоновой репликацией распространяет артефакты и метаданные, чтобы последующие сборки в других локациях могли повторно использовать те же результаты.
Сетка работает только тогда, когда узлы могут достигать друг друга по внутреннему порту пиров Kura. Эта плоскость пиров отделена от публичных конечных точек кэша, которые используют клиенты Tuist. Kura использует её для проверки членства, заполнения данных на новых узлах и репликации артефактов после принятия локальных записей.
Мы настоятельно рекомендуем защищать плоскость пиров с помощью mTLS, когда узлы общаются через регионы, облака, VPC, офисы или любую сеть, которая не является полностью приватной для развёртывания кэша. При включённом mTLS Kura обслуживает внутренние конечные точки репликации только для пиров, предъявляющих сертификат, подписанный настроенным центром сертификации (CA). Сертификаты пиров должны покрывать DNS-имена, которые узлы используют для вызова друг друга, а URL-адреса пиров должны использовать https:// на внутреннем порту.
Узлы, регистрирующиеся в плоскости управления, размещённой Tuist, получают свой сертификат пира и CA аккаунта во время регистрации, поэтому ручные шаги ниже применимы к сеткам, которые не проходят регистрацию.
Например, эта команда генерирует частный CA и один сертификат пира, который можно подключить к каждому узлу в небольшой сетке. Замените DNS-имена на внутренние имена, которые ваши узлы используют в KURA_NODE_URL и KURA_PEERS.
mkdir -p kura-peer-tls
cd kura-peer-tls
openssl ecparam -genkey -name prime256v1 -noout -out ca.key
openssl req -x509 -new -key ca.key -sha256 -days 3650 \
-subj "/CN=kura-peer-ca" \
-out ca.pem
openssl ecparam -genkey -name prime256v1 -noout -out tls.key
openssl req -new -key tls.key \
-subj "/CN=kura-peer" \
-out peer.csr
cat > peer.ext <<'EOF'
subjectAltName = DNS:kura-0.kura-headless.kura.svc.cluster.local,DNS:kura-1.kura-headless.kura.svc.cluster.local,DNS:kura-2.kura-headless.kura.svc.cluster.local,DNS:kura-1.internal,DNS:kura-2.internal
extendedKeyUsage = serverAuth,clientAuth
keyUsage = digitalSignature,keyEncipherment
EOF
openssl x509 -req -in peer.csr \
-CA ca.pem \
-CAkey ca.key \
-CAcreateserial \
-out tls.crt \
-days 730 \
-sha256 \
-extfile peer.ext
Синхронизация между узлами#
Узел, который присоединяется или повторно присоединяется к сетке, выполняет заполнение: он проходит по записям каждого пира от самых новых к старым и загружает недостающие данные, в то время как живая репликация обрабатывает записи, сделанные пока пир был виден. Проход заполнения идёт от самой новой записи пира до более старой из двух границ: горизонта кольца сегментов узла и его последнего завершённого прохода, поэтому узлу гарантировано наличие недавних данных, но не обязательно всех. KURA_BACKFILL_MARGIN_PERCENT определяет, насколько далеко назад отстоит горизонт.
Перед запуском сетки стоит знать о двух последствиях:
- Узел сообщает о готовности
/ready, как только его кольцо сегментов заполнено наKURA_BACKFILL_READY_RING_PERCENTили завершается первый цикл заполнения, и после этого готовность сохраняется до конца времени жизни процесса. Последующие кратковременные недоступности пира никогда не выводят обслуживающий узел из ротации. - Цикл также завершается, если пир остаётся недоступным достаточно долго. Поэтому узел, у которого единственный пир не работает, переходит в состояние Ready, имея мало данных или не имея их вовсе. Он обслуживает промахи кэша вместо ошибок.
/status/rolloutсообщаетbackfill_initial_cycle(pending,completeилиdegraded), если вы хотите ограничить развёртывание в зависимости от этого различия.
Обновление сетки при изменении механизма заполнения. Релизы Kura до появления заполнения синхронизировались через другой, ныне удалённый протокол пиров. Переведите каждый узел на релиз, поддерживающий заполнение, до перехода на релиз, который работает только с заполнением. Узлы на двух разных протоколах не могут синхронизироваться друг с другом: «тёплый» узел продолжает обслуживать данные со своего тома, но перестаёт сокращать разрыв, а узел, запускающийся на пустом томе в этот период, никогда не переходит в состояние Ready. Чарт устанавливает KURA_BACKFILL_ENABLED=true за вас, поэтому обновление сначала через чарт покрывает этот случай. Единое helm upgrade, которое одновременно обновляет чарт и образ, этого не делает.
Используйте ограничения на сетевом уровне в дополнение к mTLS. В Kubernetes запускайте Kura как StatefulSet с одним постоянным томом на под и headless-сервисом для обнаружения пиров, затем разрешайте внутренний порт пиров только между подами, принадлежащими одному развёртыванию кэша, например, с помощью NetworkPolicy. Вне Kubernetes присвойте каждому узлу стабильное DNS-имя или IP-адрес, заполните сетку внутренними URL других узлов и используйте правила межсетевого экрана или группы безопасности, чтобы только узлы кэша могли обращаться к порту пиров. Публичный трафик кэша должен поступать через публичные HTTP- или gRPC-конечные точки, а не через внутреннюю плоскость пиров.
Конфигурация#
Helm-чарт формирует общие настройки времени выполнения из values.yaml. Если вы запускаете Kura без Kubernetes, установите те же переменные непосредственно в процессе. Переменные, которые чарт не отображает напрямую, можно внедрить через extraEnv или extraEnvFrom.
| Переменная окружения | Описание | Обязательно | По умолчанию | Значение Helm |
|---|---|---|---|---|
KURA_PORT |
Публичный порт кэша. Один слушатель обслуживает HTTP API кэша, конечные точки проверки состояния и gRPC (h2c) для Bazel/Buck2 REAPI. | Да | Нет значения по умолчанию | service.httpPort |
KURA_INTERNAL_PORT |
Внутренний HTTP- или mTLS-порт, используемый пирами Kura. | Да | Нет значения по умолчанию | peerTls.internalPort |
KURA_TENANT_ID |
Идентификатор арендатора по умолчанию для узла. | Да | Нет значения по умолчанию | config.tenantId |
KURA_REGION |
Метка региона, используемая в метриках и состоянии репликации. | Да | Нет значения по умолчанию | config.region |
KURA_TMP_DIR |
Временная директория для промежуточных тел запросов и сборки multipart. | Да | Нет значения по умолчанию | Фиксировано как /var/cache/kura/tmp |
KURA_TMP_DIR_MAX_BYTES |
Максимальный объём промежуточных байтов, допускаемых в KURA_TMP_DIR до применения обратного давления на запросы. |
Нет | 8589934592 |
config.tmpDirMaxBytes |
KURA_DATA_DIR |
Постоянная директория для состояния метаданных и файлов сегментов. | Да | Нет значения по умолчанию | Фиксировано как /var/cache/kura |
KURA_NODE_URL |
Канонический внутренний URL, который другие пиры используют для доступа к этому узлу. | Да | Нет значения по умолчанию | Выводится из DNS-имени пода и peerTls.internalPort |
KURA_PEERS |
Список начальных пиров, используемый до завершения обнаружения. | Нет | KURA_NODE_URL |
Выводится из реплик StatefulSet |
KURA_DISCOVERY_DNS_NAME |
DNS-имя, используемое для автоматического обнаружения пиров. | Нет | Отключено | Включается через config.discovery.enabled |
KURA_INTERNAL_TLS_CA_CERT_PATH |
CA-сертификат, используемый для проверки mTLS пиров. | Нет | Отключено или выводится в KURA_DATA_DIR при регистрации узла |
peerTls.enabled и peerTls.caCertFileName |
KURA_INTERNAL_TLS_CERT_PATH |
Сертификат, используемый внутренним слушателем mTLS пиров. | Нет | Отключено или выводится в KURA_DATA_DIR при регистрации узла |
peerTls.enabled и peerTls.certFileName |
KURA_INTERNAL_TLS_KEY_PATH |
Закрытый ключ, используемый внутренним слушателем mTLS пиров. | Нет | Отключено или выводится в KURA_DATA_DIR при регистрации узла |
peerTls.enabled и peerTls.keyFileName |
KURA_PUBLIC_TLS_CERT_PATH |
Сертификат, используемый для завершения TLS на совместно размещённом HTTPS-слушателе (KURA_HTTPS_PORT). |
Нет | Отключено | extraEnv |
KURA_PUBLIC_TLS_KEY_PATH |
Закрытый ключ, соответствующий KURA_PUBLIC_TLS_CERT_PATH. |
Нет | Отключено | extraEnv |
KURA_HTTPS_PORT |
TLS-порт, обслуживающий ту же совместно размещённую поверхность HTTP + gRPC (согласованную через ALPN). Привязывается только при настройке путей публичного TLS. | Нет | 4443 |
extraEnv |
KURA_GATEWAY_GRPC_PORT |
Порт HTTP/2 без шифрования, обслуживающий только gRPC API, для прокси, которые повторно используют восходящие соединения. См. Разместите узлы за балансировщиком нагрузки. | Нет | Отключено | service.gatewayGrpcPort |
KURA_FILE_DESCRIPTOR_POOL_SIZE |
Бюджет файловых дескрипторов для запросов и фонового ввода-вывода. | Нет | Выводится автоматически | config.fileDescriptors.poolSize |
KURA_FILE_DESCRIPTOR_ACQUIRE_TIMEOUT_MS |
Сколько времени запрос ожидает, прежде чем обратное давление файловых дескрипторов приведёт к ошибке выделения. | Нет | 5000 |
config.fileDescriptors.acquireTimeoutMs |
KURA_SEGMENT_HANDLE_CACHE_SIZE |
Максимальное количество закреплённых хендлов чтения сегментов. | Нет | Выводится автоматически | config.fileDescriptors.segmentHandleCacheSize |
KURA_DRAIN_COMPLETION_TIMEOUT_MS |
Окно завершения для выполняемых HTTP- и gRPC-запросов во время остановки. | Нет | 240000 |
config.shutdown.drainCompletionTimeoutMs |
KURA_MEMORY_SOFT_LIMIT_BYTES |
Мягкий порог памяти, при достижении которого Kura начинает снижать использование опциональной памяти. | Нет | Выводится автоматически | config.memory.softLimitBytes |
KURA_MEMORY_HARD_LIMIT_BYTES |
Жёсткий порог памяти, при достижении которого Kura приостанавливает репликацию и очищает горячие кэши. | Нет | Выводится автоматически | config.memory.hardLimitBytes |
KURA_MANIFEST_CACHE_MAX_BYTES |
Максимальный размер кэша манифестов в памяти. | Нет | Выводится автоматически | config.memory.manifestCacheMaxBytes |
KURA_MAX_KEYVALUE_BYTES |
Максимальный размер полезной нагрузки keyvalue на один запрос. | Нет | 1048576 |
config.memory.maxKeyvalueBytes |
KURA_METADATA_STORE_MAX_OPEN_FILES |
Бюджет файловых дескрипторов, зарезервированный для хранилища метаданных. | Нет | Выводится автоматически | config.metadataStore.maxOpenFiles |
KURA_METADATA_STORE_MAX_BACKGROUND_JOBS |
Параллелизм фоновой записи и компактизации для хранилища метаданных. | Нет | Выводится автоматически | config.metadataStore.maxBackgroundJobs |
KURA_METADATA_STORE_READ_CACHE_BYTES |
Ёмкость кэша чтения хранилища метаданных. | Нет | Выводится автоматически | extraEnv |
KURA_METADATA_STORE_WRITE_BUFFER_POOL_BYTES |
Общий бюджет памяти, зарезервированный для буферизации записи метаданных. | Нет | Выводится автоматически | extraEnv |
KURA_METADATA_STORE_WRITE_BUFFER_BYTES |
Размер каждого буфера записи метаданных перед сбросом. | Нет | Выводится автоматически | extraEnv |
KURA_METADATA_STORE_MAX_WRITE_BUFFERS |
Максимальное количество буферов записи метаданных, хранимых в памяти. | Нет | Выводится автоматически | extraEnv |
KURA_MULTIPART_UPLOAD_TTL_MS |
Сколько времени может храниться незавершённая многокомпонентная загрузка до истечения срока действия. | Нет | 86400000 |
extraEnv |
KURA_MULTIPART_JANITOR_INTERVAL_MS |
Как часто Kura сканирует устаревшие многокомпонентные загрузки. | Нет | 600000 |
extraEnv |
KURA_BACKFILL_MARGIN_PERCENT |
Доля кольца сегментов, упорядоченных по возрасту (отсчитывается от самых новых), которая ограничивает глубину прохода дозаполнения. | Нет | 40 |
config.backfill.marginPercent |
KURA_BACKFILL_READY_RING_PERCENT |
Заполненность кольца сегментов, при которой узел, всё ещё выполняющий первый цикл дозаполнения, сообщает о своей готовности. | Нет | Половина от KURA_BACKFILL_MARGIN_PERCENT |
config.backfill.readyRingPercent |
KURA_BACKFILL_BATCH_BYTES |
Байтовый порог, по которому формируется одна пакетная загрузка тел для дозаполнения, а также размер, выше которого запись загружается отдельно. | Нет | 33554432 |
config.backfill.batchBytes |
KURA_TOKIO_WORKER_THREADS |
Количество рабочих потоков Tokio. | Нет | Выводится автоматически | extraEnv |
KURA_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT |
Конечная точка трассировки OTLP. Оставьте пустой, чтобы отключить трассировку. | Нет | Отключено | config.telemetry.otlpTracesEndpoint |
KURA_OTEL_SERVICE_NAME |
Имя сервиса OpenTelemetry. | Да | Значение по умолчанию отсутствует | Имя пода в Helm |
KURA_OTEL_DEPLOYMENT_ENVIRONMENT |
Среда развёртывания OpenTelemetry. | Да | Значение по умолчанию отсутствует | config.telemetry.deploymentEnvironment |
KURA_SENTRY_DSN |
DSN Sentry для отчётов о паниках и ошибках. | Нет | Отключено | extraEnv или extraEnvFrom |
KURA_NODE_COUNTRY |
Страна дата-центра, в котором работает узел, в формате ISO 3166-1 alpha-2; добавляется в экспортируемые трассировки как geo.country.iso_code. |
Нет | Выводится из KURA_REGION, если его префикс является кодом страны |
extraEnv |
KURA_NODE_SUBDIVISION |
Подразделение дата-центра по стандарту ISO 3166-2 (например, US-CA), добавляется как geo.region.iso_code. |
Нет | Не задано | extraEnv |
KURA_AUTH_ENABLED |
Требует от вызывающих сторон предоставления действительного токена Tuist. Установка KURA_AUTH_TUIST_URL самостоятельно включает авторизацию, а установка этого параметра в false не отключает её — чтобы запустить узел без авторизации, уберите URL. |
Нет | Отключено | auth.enabled |
KURA_AUTH_TUIST_URL |
Сервер Tuist, против которого узел выполняет авторизацию. Включает авторизацию самостоятельно. | Обязательно, если авторизация включена | Значение по умолчанию отсутствует | auth.tuistUrl |
KURA_AUTH_TUIST_CONNECT_TIMEOUT_MS |
Таймаут подключения для вызовов к этому серверу. | Нет | 500 |
extraEnv |
KURA_AUTH_TUIST_REQUEST_TIMEOUT_MS |
Таймаут запроса для вызовов к этому серверу. | Нет | 1500 |
extraEnv |
KURA_AUTH_JWT_SECRET |
Общий секрет для токенов, которые узел может читать самостоятельно, минуя лишний сетевой обмен. Он и подписывает, и проверяет токены, поэтому используйте его только там, где узел и сервер находятся в одной границе доверия. На самостоятельно размещённых узлах этот параметр обычно не задают. | Нет | Отключено | extraEnv или extraEnvFrom |
KURA_AUTH_JWT_PUBLIC_KEY |
Открытая часть пары ключей, которой сервер подписывает токены кэша, в виде одного или нескольких сцепленных блоков PEM. Позволяет читать такие токены без возможности их выпускать — именно это должен иметь узел, доступный из интернета. Взаимоисключающе с KURA_AUTH_JWT_SECRET. |
Нет | Отключено | extraEnvFrom |
KURA_AUTH_JWT_ALGORITHM |
Алгоритм для этого ключа: HS256, HS384 или HS512 с секретом, ES256 с открытым ключом. |
Нет | HS256 с секретом, ES256 с открытым ключом |
extraEnv |
KURA_AUTH_JWT_ISSUER |
Издатель, который должен быть указан в токенах. | Нет | Не проверяется | extraEnv |
KURA_AUTH_JWT_AUDIENCES |
Разделённый запятыми список аудиторий, которые должны быть указаны в токенах. | Нет | Не проверяется | extraEnv |
KURA_AUTH_CACHE_MAX_ENTRIES |
Максимальное количество записей, хранимых в каждом из кэшей аутентификации и авторизации. | Нет | 100000 |
extraEnv |
KURA_ENROLL_ON_BOOT |
Регистрирует узел в плоскости управления при каждой загрузке, предоставляя его сертификат пира и передавая KURA_TENANT_ID и KURA_PEERS. |
Нет | Отключено | extraEnv |
KURA_CONTROL_PLANE_URL |
Сервер Tuist, против которого узел проходит регистрацию. | Обязательно при регистрации | Значение по умолчанию отсутствует | extraEnv |
KURA_CONTROL_PLANE_CLIENT_ID |
Идентификатор клиента учётных данных узла, созданных в панели управления. | Обязательно при регистрации или подключении | Значение по умолчанию отсутствует | extraEnv |
KURA_CONTROL_PLANE_CLIENT_SECRET |
Секрет клиента, связанный с KURA_CONTROL_PLANE_CLIENT_ID. |
Обязательно при регистрации или подключении | Значение по умолчанию отсутствует | extraEnv |
KURA_REGISTRATION_URL |
Абсолютный URL, на который узел отправляет сигналы регистрации, объявляя свой клиентский конечный пункт. | Обязательно при регистрации | Значение по умолчанию отсутствует | extraEnv |
KURA_ADVERTISED_HTTP_URL |
Клиентский URL кэша, который плоскость управления передаёт клиентам. Должен быть доступен каждому клиенту в аккаунте. | Обязательно при регистрации | Значение по умолчанию отсутствует | extraEnv |
KURA_REGISTRATION_INTERVAL_MS |
Частота сигналов регистрации. Аренда охватывает несколько пропущенных сигналов, поэтому один потерянный сигнал не приводит к удалению конечного пункта. | Нет | 60000 |
extraEnv |
Если вы включаете внутренний mTLS между пирами, установите вместе KURA_INTERNAL_TLS_CA_CERT_PATH, KURA_INTERNAL_TLS_CERT_PATH и KURA_INTERNAL_TLS_KEY_PATH. KURA_NODE_URL и каждое значение в KURA_PEERS должны затем использовать https:// с внутренним портом пира.