> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Стандартный онбординг

> Развертывание ClickHouse в собственной облачной инфраструктуре

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

<div id="what-is-standard-onboarding">
  ## Что такое стандартный онбординг?
</div>

**Стандартный онбординг** — это управляемый процесс развертывания ClickHouse в вашем собственном облачном аккаунте по модели BYOC. В этом случае ClickHouse Cloud создает в вашем аккаунте AWS, проекте GCP или подписке Azure все основные облачные ресурсы, необходимые для развертывания, — такие как VPC/VNet, подсети, группы безопасности, кластер Kubernetes (EKS/GKE/AKS) и вспомогательные роли IAM/сервисные учетные записи/сервисные субъекты. Это обеспечивает единообразную и безопасную конфигурацию, а также сводит к минимуму объем ручных действий со стороны вашей команды.

При стандартном онбординге вам нужно только предоставить выделенный аккаунт AWS, проект GCP или подписку Azure и запустить начальный стек (через CloudFormation или Terraform), чтобы создать минимально необходимые разрешения и доверительные отношения, которые нужны ClickHouse Cloud для оркестрации дальнейшей настройки. Все последующие шаги, включая подготовку инфраструктуры и запуск сервиса, выполняются через веб-консоль ClickHouse Cloud.

Клиентам настоятельно рекомендуется подготовить **выделенный** аккаунт AWS, проект GCP или подписку Azure для размещения развертывания ClickHouse BYOC, чтобы обеспечить лучшую изоляцию разрешений и ресурсов. ClickHouse развернет в вашем аккаунте выделенный набор облачных ресурсов (VPC/VNet, кластер Kubernetes, роли IAM/сервисные учетные записи/сервисные субъекты, бакеты объектного хранилища и т. д.).

Если вам требуется более гибкая настройка (например, развертывание в существующей VPC), обратитесь к документации [Customized Onboarding](/ru/products/bring-your-own-cloud/onboarding/customization-aws).

<Note>
  Стандартный BYOC-онбординг занимает примерно 45–90 минут от начала до конца — с момента запуска шагов CloudFormation или Terraform до момента, когда становится доступен первый сервис ClickHouse.
</Note>

<div id="request-access">
  ## Запросите доступ
</div>

Чтобы начать процесс онбординга, [свяжитесь с нами](https://clickhouse.com/cloud/bring-your-own-cloud). Наша команда поможет вам разобраться с требованиями BYOC, выбрать наиболее подходящие варианты развертывания и добавить вашу учетную запись в список разрешенных.

<div id="onboarding-process">
  ## Онбординг
</div>

<div id="prepare-an-aws-account">
  ### Подготовьте аккаунт AWS/проект GCP/подписку Azure
</div>

Подготовьте новый аккаунт AWS, проект GCP или подписку Azure в своей организации.

<Steps>
  <Step title="Выберите облачного провайдера" id="choose-cloud-provider">
    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/wrAOYL3DquclMwbQ/images/cloud/reference/byoc-onboarding-1.webp?fit=max&auto=format&n=wrAOYL3DquclMwbQ&q=85&s=a6b94d9f4e2e84782e2ce1cad935b24d" size="lg" alt="Выбор CSP для BYOC" background="black" width="1182" height="944" data-path="images/cloud/reference/byoc-onboarding-1.webp" />
  </Step>

  <Step title="Настройка аккаунта/проекта/подписки" id="account-setup">
    Первоначальную настройку BYOC можно выполнить с помощью [шаблона CloudFormation (AWS)](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/cf-templates/byoc_v2.yaml), [модуля Terraform (GCP)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/gcp) или [модуля Terraform (Azure)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/azure). При этом создается высокопривилегированное удостоверение (роль IAM/сервисный аккаунт/сервисный субъект), которое позволяет контроллерам BYOC из ClickHouse Cloud управлять вашей инфраструктурой.

    <Warning>
      **Применяйте артефакты онбординга строго в предоставленном виде.** Не изменяйте ничего в шаблоне CloudFormation или модуле Terraform — включая переименование ресурсов или добавление таких параметров, как `PermissionsBoundary`, — без явного одобрения ClickHouse. Автоматизация ClickHouse зависит от точного набора ресурсов, создаваемых этими артефактами; поддерживаемые настройки доступны в виде параметров. В частности, в AWS роль IAM должна сохранять имя по умолчанию `ClickHouseManagementRole` — без префикса или суффикса, — если ClickHouse заранее явно не согласовал другое имя. Технически модуль Terraform предоставляет входной параметр `role_name`, однако для этого необходимо соответствующим образом настроить автоматизацию ClickHouse. Поэтому его изменение без согласования (или переименование роли в шаблоне CloudFormation, где такого параметра нет) приводит к успешному применению стека, но сбою при подготовке инфраструктуры, поскольку ClickHouse не может принять ожидаемую роль.
    </Warning>

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/wrAOYL3DquclMwbQ/images/cloud/reference/byoc-onboarding-2.webp?fit=max&auto=format&n=wrAOYL3DquclMwbQ&q=85&s=4517b457d58fa14a822a5f4608cc1a7e" size="lg" alt="Инициализация аккаунта BYOC" background="black" width="1182" height="316" data-path="images/cloud/reference/byoc-onboarding-2.webp" />

    <Note>
      Бакеты хранилища, VPC/VNet, кластер Kubernetes и вычислительные ресурсы, необходимые для запуска ClickHouse, не входят в первоначальную настройку. Они будут подготовлены на следующем шаге.
    </Note>

    #### Модуль Terraform для AWS

    Если для развертываний в AWS вы предпочитаете Terraform вместо CloudFormation, используйте модуль [terraform-byoc-onboarding](https://github.com/ClickHouse/terraform-byoc-onboarding):

    ```hcl theme={null}
    module "clickhouse_onboarding" {
      source      = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws?ref=<version>"
      external_id = "<external-id-provided-by-clickhouse>"
    }
    ```

    Замените `<version>` на последний тег со [страницы релизов](https://github.com/ClickHouse/terraform-byoc-onboarding/releases) модуля — всегда используйте самый свежий релиз.

    Модуль выводит `clickhouse_management_role_arn`. В стандартном сценарии никаких действий с ним не требуется: онбординг продолжается в консоли ClickHouse Cloud. Однако сохраните его: ClickHouse запросит его, если ваша конфигурация отличается от стандартной (например, если требуется согласовать пользовательское имя роли).

    <Note>
      Ранее модуль распространялся в виде архива tarball по адресу `https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz`. Этот URL по-прежнему доступен, но устарел — используйте указанный выше модуль на GitHub.
    </Note>

    #### Внешний ID AWS

    В AWS роль IAM, созданная при настройке, доверяет ClickHouse Cloud, используя [внешний ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) (`sts:ExternalId`) для защиты от атак типа «confused deputy». При запуске онбординга консоль ClickHouse Cloud генерирует внешний ID для вашего аккаунта AWS и предварительно заполняет его в ссылке CloudFormation. Если вы используете Terraform, передайте то же значение в параметре `external_id`. Все инфраструктуры BYOC в рамках одного аккаунта AWS используют один и тот же внешний ID.

    <Note>
      Для обратной совместимости инфраструктуры BYOC, прошедшие онбординг до появления внешних ID, используют значение-заполнитель `emptyid`. Консоль показывает это значение при добавлении инфраструктуры в аккаунт AWS с существующим legacy-развертыванием, чтобы все инфраструктуры в аккаунте сохраняли согласованную конфигурацию доверия. Если вы хотите перейти на уникальный внешний ID, обратитесь в ClickHouse Support.
    </Note>
  </Step>

  <Step title="Настройте инфраструктуру BYOC" id="setup-byoc-infrastructure">
    В консоли ClickHouse Cloud вам будет предложено настроить инфраструктуру, включая бакеты объектного хранилища, VPC/VNet и кластер Kubernetes. На этом этапе необходимо выбрать некоторые параметры, так как позже их изменить нельзя. В частности:

    * **Регион**: Для развертываний BYOC доступны все **публичные регионы**, перечисленные в нашей документации по [поддерживаемым регионам](/ru/products/cloud/reference/supported-regions). Частные регионы в настоящее время не поддерживаются.

    * **Диапазон CIDR VPC/VNet**: По умолчанию для диапазона CIDR VPC BYOC (AWS/GCP) или VNet (Azure) используется `10.0.0.0/16`. Если вы планируете настроить пиринг VPC/VNet с другим аккаунтом, убедитесь, что диапазоны CIDR не пересекаются. Минимальный размер зависит от облачного провайдера:

      * **AWS**: `/23`
      * **Azure**: `/23`
      * **GCP**: `/20`

      Это минимальные требования, а не рекомендации: каждая реплика использует IP-адреса, поэтому для крупных развертываний требуется больший диапазон.

    * **Зоны доступности**: Если вы планируете использовать пиринг VPC, согласование зон доступности между исходным аккаунтом и аккаунтом BYOC может помочь снизить затраты на межзональный трафик. Например, в AWS суффиксы зон доступности (`a`, `b`, `c`) могут соответствовать разным идентификаторам физических зон в разных аккаунтах. Подробнее см. в [руководстве AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/use-consistent-availability-zones-in-vpcs-across-different-aws-accounts.html).

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/wrAOYL3DquclMwbQ/images/cloud/reference/byoc-onboarding-3.webp?fit=max&auto=format&n=wrAOYL3DquclMwbQ&q=85&s=ae5d4ae59e0dddcb873a0d05879c8c59" size="lg" alt="Настройте инфраструктуру BYOC" background="black" width="1182" height="1406" data-path="images/cloud/reference/byoc-onboarding-3.webp" />

    #### Предварительная проверка

    Когда вы нажимаете **Set up Infrastructure**, ClickHouse Cloud выполняет в вашем аккаунте набор предварительных проверок **только для чтения**, прежде чем создавать какие-либо ресурсы. Если все проверки пройдены, подготовка инфраструктуры продолжается. Если проверка не пройдена, настройка приостанавливается, и консоль показывает, в чём именно проблема, чтобы вы могли устранить её до создания каких-либо ресурсов.

    Проверки подтверждают, что:

    * **Разрешения** — удостоверение для управления (роль IAM / сервисный аккаунт / сервисный субъект) обладает разрешениями, необходимыми ClickHouse Cloud для подготовки инфраструктуры и работы вашего развертывания.
    * **Включенные сервисы** *(GCP)* — в вашем проекте включены необходимые API Google Cloud (Compute Engine, Kubernetes Engine, Cloud Storage, Network Connectivity, IAM).
    * **Сеть** *(AWS с собственной VPC)* — ваша VPC и подсети соответствуют [сетевым требованиям](/ru/products/bring-your-own-cloud/onboarding/customization-aws#configure-existing-vpc): размер подсетей, необходимые теги, распределение по зонам доступности, исходящее подключение и доступные IP-адреса.
    * **Квоты и ограничения** *(AWS)* — в вашем аккаунте достаточно квот сервисов (VPC, шлюзы NAT, Elastic IP, кластеры EKS, vCPU), и ни одна политика организации (SCP) не блокирует необходимые действия.

    Если проверки не пройдены, для каждой из них указывается соответствующее действие и причина сбоя (например, `iam:CreateRole · explicitDeny`). Разверните **Show passed checks**, чтобы просмотреть все успешно пройденные проверки.

    <Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/HVVNl4vu1ZT30V-H/images/cloud/reference/byoc-onboarding-preflight-failed.png?fit=max&auto=format&n=HVVNl4vu1ZT30V-H&q=85&s=de520286d9727431016ba1f722e8178b" size="lg" alt="Предварительная проверка BYOC сообщает о неудачных проверках настройки Cloud" background="black" width="1358" height="1724" data-path="images/cloud/reference/byoc-onboarding-preflight-failed.png" />

    Чтобы устранить сбои, повторно примените последнюю версию стека ClickHouse CloudFormation или Terraform — либо выдайте указанные действия управляющему удостоверению (роль IAM / сервисный аккаунт / сервисный субъект) — а затем выберите один из вариантов:

    * **Повторно проверить** — повторно запускает предварительные проверки. Используйте эту функцию после устранения указанных проблем, чтобы убедиться, что перед подготовкой ресурсов все готово.
    * **Всё равно продолжить** — продолжает подготовку ресурсов, несмотря на неуспешные проверки. Используйте этот вариант только если вы уверены, что указанная ошибка — ложное срабатывание; иначе подготовка ресурсов, скорее всего, завершится сбоем.

    Используйте приведённую ниже таблицу для устранения типичных сбоев.

    | Ошибка валидации                                                                                                                                                                                              | Вероятная причина                                                                                                                                                   | Способ устранения                                                                                                                                                                |
    | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Не удается принять управляющую роль** *(AWS)*                                                                                                                                                               | Стек онбординга не был полностью развернут либо роль или внешний ID не совпадают                                                                                    | Повторно примените последний стек онбординга и убедитесь, что [внешний ID](#aws-external-id), отображаемый в консоли, совпадает с указанным в вашей политике доверия             |
    | **Не удается имперсонировать сервисный аккаунт управления** *(GCP)*                                                                                                                                           | Terraform для онбординга не был применен, либо сервисный аккаунт `clickhouse-management` отсутствует или не предоставляет ClickHouse разрешение на его имперсонацию | Повторно примените актуальную версию Terraform для онбординга и убедитесь, что сервисный аккаунт `clickhouse-management` существует и разрешает ClickHouse выдавать себя за него |
    | **Недостаточно разрешений** (например, на создание VPC, роли IAM или кластера Kubernetes)                                                                                                                     | Управляющему удостоверению не хватает необходимого разрешения — часто из-за измененного или устаревшего стека                                                       | Повторно запустите последнюю версию стека онбординга, предоставляющего полный набор разрешений; если вы намеренно ограничиваете разрешения, добавьте указанное разрешение        |
    | **Не включён обязательный API** *(GCP)*                                                                                                                                                                       | Необходимый API сервиса Google Cloud отключён для проекта                                                                                                           | Включите его, например: `gcloud services enable compute.googleapis.com --project <your-project>`                                                                                 |
    | **Проблема с конфигурацией подсети или VPC** *(AWS bring-your-own-VPC)* — слишком маленький CIDR, отсутствует тег, слишком мало зон доступности, нет исходящего трафика или слишком мало свободных IP-адресов | Указанная VPC не соответствует сетевым требованиям BYOC                                                                                                             | Настройте VPC в соответствии с [требованиями к сети](/ru/products/bring-your-own-cloud/onboarding/customization-aws#configure-existing-vpc)                                      |
    | **Недостаточная QUOTA сервиса** *(AWS)*                                                                                                                                                                       | Квота аккаунта для необходимого ресурса слишком мала                                                                                                                | Запросите увеличение квоты у своего облачного провайдера; см. [лимиты сервисов AWS](/ru/products/bring-your-own-cloud/reference/aws-service-limits)                              |
    | **Заблокировано политикой организации / SCP** *(AWS)*                                                                                                                                                         | Ограничение, заданное на уровне организации, запрещает необходимое действие для аккаунта                                                                            | Обратитесь к администратору облака, чтобы разрешить это действие для аккаунта BYOC                                                                                               |
  </Step>
</Steps>

<div id="create-clickhouse-service">
  ### Создайте свой первый BYOC-сервис ClickHouse
</div>

После того как ваша BYOC-инфраструктура будет подготовлена, можно запускать первый сервис ClickHouse. Откройте консоль ClickHouse Cloud, выберите свою BYOC-среду и следуйте подсказкам, чтобы создать новый сервис.

<Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/wrAOYL3DquclMwbQ/images/cloud/reference/byoc-new-service-1.webp?fit=max&auto=format&n=wrAOYL3DquclMwbQ&q=85&s=e5862ee54425953f7f12af7c1daab7e8" size="md" alt="BYOC создание нового сервиса" width="732" height="881" data-path="images/cloud/reference/byoc-new-service-1.webp" />

При создании сервиса вы настроите следующие параметры:

* **Service name**: Введите понятное и информативное имя для вашего сервиса ClickHouse.
* **BYOC infrastructure**: Выберите BYOC-среду, включая облачную учетную запись и регион, в которых будет работать сервис.
* **Resource configuration**: Выберите объем CPU и памяти, выделяемых для реплик ClickHouse.
* **Replica count**: Укажите количество реплик для повышения отказоустойчивости и Высокой доступности.