> ## 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.

# Onboarding padrão

> Implante o ClickHouse na sua própria infraestrutura de nuvem

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">
  ## O que é o onboarding padrão?
</div>

**Onboarding padrão** é o fluxo guiado padrão para implantar o ClickHouse na sua própria conta de nuvem usando BYOC. Nessa abordagem, o ClickHouse Cloud provisiona todos os principais recursos de nuvem necessários para a implantação — como VPC/VNet, sub-redes, grupos de segurança, cluster do Kubernetes (EKS/GKE/AKS) e funções do IAM/contas de serviço/principais de serviço de suporte — na sua conta da AWS, projeto do GCP ou assinatura do Azure. Isso garante uma configuração consistente e segura, além de minimizar as etapas manuais necessárias da sua equipe.

Com o onboarding padrão, basta fornecer uma conta dedicada da AWS, um projeto do GCP ou uma assinatura do Azure e executar uma stack inicial (via CloudFormation ou Terraform) para criar as permissões mínimas e a relação de confiança necessárias para que o ClickHouse Cloud orquestre o restante da configuração. Todas as etapas subsequentes — incluindo o provisionamento da infraestrutura e o lançamento do serviço — são gerenciadas pelo console web do ClickHouse Cloud.

É altamente recomendável que os clientes preparem uma conta da AWS, um projeto do GCP ou uma assinatura do Azure **dedicados** para hospedar a implantação BYOC do ClickHouse, a fim de garantir melhor isolamento em termos de permissões e recursos. O ClickHouse implantará um conjunto dedicado de recursos de nuvem (VPC/VNet, cluster do Kubernetes, funções do IAM/contas de serviço/principais de serviço, buckets de armazenamento de objetos etc.) na sua conta.

Se você precisar de uma configuração mais personalizada (por exemplo, implantar em uma VPC existente), consulte a documentação de [Customized Onboarding](/pt-BR/products/bring-your-own-cloud/onboarding/customization-aws).

<Note>
  Um onboarding BYOC padrão leva aproximadamente de 45 a 90 minutos de ponta a ponta, medidos desde o momento em que as etapas do CloudFormation ou do Terraform são iniciadas até o momento em que o primeiro serviço do ClickHouse fica acessível.
</Note>

<div id="request-access">
  ## Solicitar acesso
</div>

Para iniciar o processo de onboarding, [entre em contato conosco](https://clickhouse.com/cloud/bring-your-own-cloud). Nossa equipe orientará você quanto aos requisitos do BYOC, ajudará a selecionar as opções de implantação mais adequadas e adicionará sua conta à lista de permissões.

<div id="onboarding-process">
  ## Onboarding
</div>

<div id="prepare-an-aws-account">
  ### Prepare uma conta da AWS/projeto do GCP/assinatura do Azure
</div>

Prepare uma nova conta da AWS, um projeto do GCP ou uma assinatura do Azure na sua organização.

<Steps>
  <Step title="Escolha um provedor de Cloud" 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="BYOC: escolher CSP" background="black" width="1182" height="944" data-path="images/cloud/reference/byoc-onboarding-1.webp" />
  </Step>

  <Step title="Configuração da conta, do projeto ou da assinatura" id="account-setup">
    A configuração inicial do BYOC pode ser realizada usando um [template do CloudFormation (AWS)](https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/cf-templates/byoc_v2.yaml), um [módulo do Terraform (GCP)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/gcp) ou um [módulo do Terraform (Azure)](https://github.com/ClickHouse/terraform-byoc-onboarding/tree/main/modules/azure). Ela cria uma identidade com privilégios elevados (IAM role/service account/principal de serviço), permitindo que os controllers do BYOC no ClickHouse Cloud gerenciem sua infraestrutura.

    <Warning>
      **Aplique os artefatos de onboarding exatamente como fornecidos.** Não altere nada no template do CloudFormation ou no módulo do Terraform — incluindo renomear recursos ou adicionar parâmetros como `PermissionsBoundary` — sem a aprovação explícita do ClickHouse. A automação do ClickHouse depende dos recursos exatos criados por esses artefatos; as personalizações compatíveis são expostas como parâmetros. Em particular, na AWS, a IAM role deve manter o nome padrão `ClickHouseManagementRole` — sem prefixo ou sufixo —, a menos que o ClickHouse tenha concordado explicitamente com outro nome de antemão. Tecnicamente, o módulo do Terraform expõe uma entrada `role_name`, mas a automação do ClickHouse precisa ser configurada para corresponder a ela. Portanto, alterá-la sem coordenação — ou renomear a role no template do CloudFormation, que não tem esse parâmetro — resulta em uma stack aplicada com êxito, mas com falha no provisionamento da infraestrutura, pois o ClickHouse não consegue assumir a role esperada.
    </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="Inicializar conta BYOC" background="black" width="1182" height="316" data-path="images/cloud/reference/byoc-onboarding-2.webp" />

    <Note>
      Os buckets de armazenamento, a VPC/VNet, o cluster do Kubernetes e os recursos de compute necessários para executar o ClickHouse não estão incluídos nesta configuração inicial. Eles serão provisionados no próximo passo.
    </Note>

    #### Módulo do Terraform para AWS

    Se preferir usar o Terraform em vez do CloudFormation para implantações na AWS, use o módulo [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>"
    }
    ```

    Substitua `<version>` pela tag mais recente na [página de lançamentos](https://github.com/ClickHouse/terraform-byoc-onboarding/releases) do módulo — use sempre o lançamento mais recente.

    O módulo retorna `clickhouse_management_role_arn`. No fluxo padrão, não é necessário fazer nada com ele — o onboarding continua no console do ClickHouse Cloud —, mas mantenha esse valor à mão: o ClickHouse o solicitará se sua configuração diferir dos padrões (por exemplo, devido a um nome de função personalizada coordenada).

    <Note>
      O módulo era distribuído anteriormente como um tarball em `https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz`. Essa URL continua disponível, mas foi descontinuada — use o módulo do GitHub acima.
    </Note>

    #### ID externo da AWS

    Na AWS, a função do IAM criada durante o setup confia no ClickHouse Cloud usando um [ID externo](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) (`sts:ExternalId`) para proteção contra ataques de representante confuso. O console do ClickHouse Cloud gera um ID externo para sua conta AWS quando você inicia o onboarding e o preenche automaticamente no link do CloudFormation; se usar o Terraform, passe o mesmo valor como `external_id`. Todas as infraestruturas BYOC na mesma conta AWS compartilham o mesmo ID externo.

    <Note>
      As infraestruturas BYOC integradas antes da introdução dos IDs externos usam o valor de placeholder `emptyid` para compatibilidade retroativa. O console mostra esse valor quando você adiciona infraestrutura a uma conta AWS com uma implantação legacy existente, para que todas as infraestruturas da conta mantenham uma configuração de confiança consistente. Se quiser mudar para um ID externo único, entre em contato com o suporte do ClickHouse.
    </Note>
  </Step>

  <Step title="Configure a infraestrutura de BYOC" id="setup-byoc-infrastructure">
    Você deverá configurar a infraestrutura, incluindo buckets de armazenamento de objetos, VPC/VNet e o cluster do Kubernetes, no console do ClickHouse Cloud. Algumas configurações devem ser definidas nesta etapa, pois não poderão ser alteradas posteriormente. Especificamente:

    * **Região**: Todas as **regiões públicas** listadas em nossa documentação sobre [regiões compatíveis](/pt-BR/products/cloud/reference/supported-regions) estão disponíveis para implantações BYOC. Atualmente, regiões privadas não são compatíveis.

    * **Intervalo CIDR da VPC/VNet**: Por padrão, usamos `10.0.0.0/16` como intervalo CIDR para a VPC BYOC (AWS/GCP) ou VNet (Azure). Se você planeja usar peering de VPC/VNet com outra conta, certifique-se de que os intervalos CIDR não se sobreponham. O tamanho mínimo varia conforme a Cloud:

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

      Esses são limites mínimos, não recomendações: cada réplica consome endereços IP; portanto, implantações maiores precisam de um intervalo maior.

    * **Zonas de disponibilidade**: Se você planeja usar peering de VPC, alinhar as zonas de disponibilidade entre as contas de origem e BYOC pode ajudar a reduzir os custos de tráfego entre AZs. Por exemplo, na AWS, os sufixos de zona de disponibilidade (`a`, `b`, `c`) podem representar IDs de zonas físicas diferentes entre contas. Consulte o [guia da AWS](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/use-consistent-availability-zones-in-vpcs-across-different-aws-accounts.html) para mais detalhes.

    <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="Configuração da infraestrutura BYOC" background="black" width="1182" height="1406" data-path="images/cloud/reference/byoc-onboarding-3.webp" />

    #### Validação prévia

    Ao clicar em **Set up Infrastructure**, o ClickHouse Cloud executa um conjunto de verificações prévias **read-only** na sua conta antes de criar qualquer recurso. Se tudo for aprovado, o provisionamento continua. Se alguma verificação falhar, a configuração é pausada e o console mostra exatamente qual é o problema, para que você possa corrigi-lo antes que qualquer recurso seja criado.

    As verificações confirmam que:

    * **Permissões** — a identidade de gerenciamento (IAM role / service account / principal de serviço) tem as permissões necessárias para que o ClickHouse Cloud provisione e opere sua implantação.
    * **Serviços habilitados** *(GCP)* — as APIs necessárias do Google Cloud (Compute Engine, Kubernetes Engine, Cloud Storage, Network Connectivity, IAM) estão habilitadas no seu projeto.
    * **Rede** *(AWS com sua própria VPC)* — sua VPC e sub-redes atendem aos [requisitos de rede](/pt-BR/products/bring-your-own-cloud/onboarding/customization-aws#configure-existing-vpc): tamanhos das sub-redes, tags obrigatórias, distribuição entre zonas de disponibilidade, conectividade de saída e endereços IP disponíveis.
    * **Cotas e proteções** *(AWS)* — sua conta tem cotas de serviço suficientes (VPCs, NAT gateways, Elastic IPs, EKS clusters, vCPUs) e nenhuma política da organização (SCP) bloqueia uma ação necessária.

    Quando as verificações falham, cada uma é listada com a ação correspondente e o motivo da falha (por exemplo, `iam:CreateRole · explicitDeny`). Expanda **Show passed checks** para revisar tudo o que foi bem-sucedido.

    <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="Validação prévia do BYOC reportando falhas nas verificações de configuração da Cloud" background="black" width="1358" height="1724" data-path="images/cloud/reference/byoc-onboarding-preflight-failed.png" />

    Para resolver as falhas, execute novamente a stack mais recente do CloudFormation ou do Terraform do ClickHouse — ou conceda as actions reportadas à identidade de gerenciamento (IAM role / service account / principal de serviço) — e então escolha uma destas opções:

    * **Verificar novamente** — executa novamente as verificações de pré-requisitos. Use esta opção depois de corrigir os problemas relatados para confirmar que sua configuração está pronta antes do provisionamento.
    * **Prosseguir mesmo assim** — continua o provisionamento apesar das verificações que falharam. Use esta opção somente se tiver certeza de que uma falha relatada é um falso positivo; caso contrário, o provisionamento provavelmente falhará no meio do processo.

    Use a tabela abaixo para resolver falhas comuns.

    | Erro de validação                                                                                                                                                                                   | Causa provável                                                                                                                                               | Como resolver                                                                                                                                                                          |
    | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Não é possível assumir a role de gerenciamento** *(AWS)*                                                                                                                                          | A stack de onboarding não foi concluída ou a role ou o ID externo não correspondem                                                                           | Execute novamente a stack de onboarding mais recente e confirme que o [ID externo](#aws-external-id) exibido no console corresponde ao da sua política de confiança                    |
    | **Não é possível assumir a identidade da conta de serviço de gerenciamento** *(GCP)*                                                                                                                | O Terraform de onboarding não foi concluído, a service account `clickhouse-management` está ausente ou não concede ao ClickHouse permissão para impersoná-la | Execute novamente o Terraform de onboarding mais recente e confirme que a service account `clickhouse-management` existe e concede ao ClickHouse permissão para impersoná-la           |
    | **Permissão ausente** (por exemplo, criar VPC, criar IAM role, criar cluster do Kubernetes)                                                                                                         | A identidade de gerenciamento não tem a permissão necessária — geralmente devido a uma stack personalizada ou desatualizada                                  | Execute novamente a stack de onboarding mais recente, que concede o conjunto completo de permissões; se você restringir as permissões intencionalmente, adicione a permissão informada |
    | **API obrigatória não ativada** *(GCP)*                                                                                                                                                             | Uma API de serviço obrigatória do Google Cloud está desabilitada no projeto                                                                                  | Ative-a, por exemplo, com `gcloud services enable compute.googleapis.com --project <your-project>`                                                                                     |
    | **Problema de configuração da sub-rede ou VPC** *(AWS com VPC própria)* — CIDR muito pequeno, tag ausente, poucas zonas de disponibilidade, sem saída para a Internet ou poucos endereços IP livres | A VPC fornecida não atende aos requisitos de rede do BYOC                                                                                                    | Ajuste a VPC para atender aos [requisitos de rede](/pt-BR/products/bring-your-own-cloud/onboarding/customization-aws#configure-existing-vpc)                                           |
    | **QUOTA de service insuficiente** *(AWS)*                                                                                                                                                           | A cota da sua conta para um recurso necessário é muito baixa                                                                                                 | Solicite um aumento da cota ao seu provedor de Cloud; consulte os [limites de serviço da AWS](/pt-BR/products/bring-your-own-cloud/reference/aws-service-limits)                       |
    | **Bloqueado por política da organização / SCP** *(AWS)*                                                                                                                                             | Uma proteção organizacional impede uma ação necessária para a conta                                                                                          | Trabalhe com o administrador da sua Cloud para permitir a ação na conta BYOC                                                                                                           |
  </Step>
</Steps>

<div id="create-clickhouse-service">
  ### Crie seu primeiro serviço BYOC do ClickHouse
</div>

Depois que sua infraestrutura BYOC for provisionada, você poderá lançar seu primeiro serviço do ClickHouse. Abra o console do ClickHouse Cloud, selecione seu ambiente BYOC e siga as instruções para criar um novo serviço.

<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 criar um novo serviço" width="732" height="881" data-path="images/cloud/reference/byoc-new-service-1.webp" />

Durante a criação do serviço, você configurará as seguintes opções:

* **Nome do serviço**: Insira um nome claro e descritivo para seu serviço do ClickHouse.
* **Infraestrutura BYOC**: Selecione o ambiente BYOC, incluindo a conta de nuvem e a região, em que seu serviço será executado.
* **Configuração de recursos**: Escolha a quantidade de CPU e memória alocada às réplicas do ClickHouse.
* **Número de réplicas**: Defina o número de réplicas para aumentar a alta disponibilidade.