Skip to main content

​
O que é o onboarding padrão?

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

​
Solicitar acesso

Para iniciar o processo de onboarding, entre em contato conosco. 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.

​
Onboarding

​
Prepare uma conta da AWS/projeto do GCP/assinatura do Azure

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

Escolha um provedor de Cloud

2

Configuração da conta, do projeto ou da assinatura

A configuração inicial do BYOC pode ser realizada usando um template do CloudFormation (AWS), um módulo do Terraform (GCP) ou um módulo do Terraform (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.
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.
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.

​
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:
Substitua <version> pela tag mais recente na página de lançamentos 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).
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.

​
ID externo da AWS

Na AWS, a função do IAM criada durante o setup confia no ClickHouse Cloud usando um ID externo (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.
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.
3

Configure a infraestrutura de BYOC

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 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 para mais detalhes.

​
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: 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.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.

​
Crie seu primeiro serviço BYOC do ClickHouse

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. 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.
Última modificação em 26 de agosto de 2026