> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Balanceadores de carga > Balanceadores de carga gerenciados: ouvintes, regras de roteamento, grupos-alvo, verificações de integridade e as réplicas que atendem ao seu tráfego. Os exemplos de cliente usam CLI v0.24.0 e Go SDK v0.28.0. Veja [Configuração da CLI](/pt/cli) e [Configuração do Go](/pt/reference-resolution#released-go-sdk). Os snippets Go assumem um `cfg` configurado, um `ctx` de `context.Background()`, e importações para `log`, `basaltic` (`github.com/basaltic-sh/sdk-go`) e `loadbalancer` (`github.com/basaltic-sh/sdk-go/loadbalancer`). `LOAD_BALANCER_ID`, `LISTENER_ID` e `TARGET_GROUP_ID` (e seus equivalentes em Go) são UUIDs retornados. Veja [Resource references](/pt/reference-resolution) para tipos de referência aceitos, escopo de pesquisa, identidades canônicas e filtros de lista exata. Veja [Resource faults](/pt/resource-faults) para o array `faults` ativo. Um balanceador de carga aceita conexões em um ou mais ouvintes e encaminha-os para um grupo-alvo. Ele é executado em instâncias de computação que a plataforma opera para você — as **réplicas** — dentro de sua própria sub-rede VPC, para que ele chegue aos seus backends por meio de endereços privados. Um IP flutuante público fornece seu endereço voltado para a Internet. Os endereços IPv6 nativos de réplica não podem aceitar novas conexões de fora da VPC; use os endereços de balanceamento de carga regidos por [exposição](#exposure). O serviço é **regional**: `https://loadbalancer.sa-saopaulo-1.basaltic.sh`. Camada 7. Aceita conexões em listeners `http` e `https`, roteia por host, caminho, cabeçalho, parâmetros de consulta e método, e faz a terminação TLS. Camada 4. Aceita conexões em listeners `tcp` e `udp` e encaminha os fluxos para um único grupo de destinos. `type` é definido na criação e não pode ser alterado. Não há nenhum patch que converta um no outro — crie um segundo balanceador de carga e mova o endereço. A sub-rede, a família de tipos de instância e os grupos de segurança necessários para criar o balanceador. O IP virtual privado, o IP flutuante escolhido na criação e o hostname usado nos registros DNS. Protocolos, exposição, certificados e como uma solicitação escolhe um grupo-alvo. Destinos, verificações de integridade, persistência de sessão e protocolo PROXY. Escalabilidade, o primeiro rolo de tipo de instância e como assisti-lo. Ativo mas inalcançável, alvos presos no `initial`, um redimensionamento que para. ## Criando um balanceador de carga Vá para **Compute → Load Balancers** e escolha **Create Load Balancer**. Em **Load balancer details**, dê um **Name** e escolha o **Type**: **Application** para a camada 7, **Network** para a camada 4. **Placement** toma o **VPC**, a **Subnet** de que o IP virtual é reservado e os **Security groups** que cada réplica herda. Em **IP addresses**, escolha o IP flutuante público privado e opcional para cada família ativada. Os endereços privados são definidos como padrão para **Automatic — allocate from this subnet**; os endereços públicos são definidos como padrão para **None**. Escolha um **Flavor** — a lista já está filtrada para a família de balanceador de carga — e defina **Minimum count**, **Maximum count** e **Desired count** em **Scale**. Ative **Automatic scaling** para configurar metas de métrica. Um load balancer sem um IP flutuante público permanece interno — veja a seção sobre o IP flutuante público. [como ele obtém seu endereço](#how-a-load-balancer-gets-its-address). Cada lista flutuante de IP oferece apenas endereços elegíveis que não estão ligados a nada. Aloque um em **Networking → Floating IPs** primeiro se ele estiver vazio. ```bash theme={null} POST https://loadbalancer.sa-saopaulo-1.basaltic.sh/v1/load-balancers { "name": "web-lb", "type": "application", "vpc": "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9", "subnet": "d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0", "flavor": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1", "security_groups": ["d1b6f3a8-4c2e-4a9d-8f7b-1e5c3a2d9b4f"], "min_count": 2, "max_count": 4, "desired_count": 2 } ``` ```bash theme={null} basaltic loadbalancer load-balancer create --name web-lb --type application \ --vpc c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9 --subnet d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0 \ --flavor e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1 \ --security-groups d1b6f3a8-4c2e-4a9d-8f7b-1e5c3a2d9b4f --replica-count 2 ``` ```go theme={null} _, err := loadbalancer.New(cfg).CreateLoadBalancer(ctx, &loadbalancer.CreateLoadBalancerRequest{ Name: "web-lb", Type: "application", VPC: "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9", Subnet: "d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0", Flavor: "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1", SecurityGroups: []string{"d1b6f3a8-4c2e-4a9d-8f7b-1e5c3a2d9b4f"}, ReplicaCount: basaltic.Int(2), }) if err != nil { log.Fatal(err) } ``` As entradas de relacionamento aceitam UUIDs, CRNs ou nomes exatos imutáveis. A VPC abrange nomes de sub-rede; os recursos referenciados devem pertencer à sua conta na mesma região. Os tipos de instância vêm do catálogo regional. IPs flutuantes aceitam apenas UUIDs ou CRNs. Os pontos finais de lista aceitam filtros exatos `name` e `crn`; um filtro vazio não seleciona linhas, e CRNs malformados retornam um erro de validação. As réplicas herdam estas em cada NIC, e uma NIC em nenhum grupo de segurança aceita nada. Um balanceador de carga sem um ainda provisionaria, ainda receberia um IP flutuante e ainda reportaria `active` — enquanto não respondesse a ninguém. A criação é recusada em vez disso. **A porta de ouvinte tem de ser aberta por um grupo de segurança listado aqui**, ou o balanceador de carga é inacessível nela. As réplicas são operadas pela plataforma e têm preços correspondentes, portanto, um flavor geral ou de banco de dados é rejeitado com a família do flavor nomeada no erro. As réplicas obtêm NICs aqui e o IP virtual é reservado fora do intervalo desta sub-rede. Use `1 ≤ min_count ≤ desired_count ≤ max_count ≤ 10`. Desired é padrão para 1; limites omitidos são padrão para desired. Escolha um mínimo de pelo menos 2 para HA. Deixe espaço abaixo do máximo para uma substituição de tipo de instância. Veja [scaling](#scaling). `replica_count` continua sendo um alias obsoleto de `desired_count`. Se ambos forem enviados, os valores devem ser iguais. A CLI e o SDK Go aceitam limites independentes e políticas de escalonamento automático. Mantenha o máximo acima da quantidade desejada para permitir substituições durante uma troca de tipo de instância. A resposta é **`201`** com o balanceador de carga em `provisioning`. Ele muda para `active` na primeira réplica cujo proxy relata pronto — as réplicas inicializam, instalam seu software e puxam sua configuração, então espere alguns minutos. As réplicas executam o próprio software proxy da plataforma. Você alcança um balanceador de carga por meio de seu endereço; não há acesso SSH de locatário às suas réplicas. ### Leitura de colocação de volta Uma resposta de balanceador de carga incorpora toda a sua `subnet`, no lugar dos antigos campos `subnet_id` e `vpc_id`. O embed carrega a VPC pai e o resumo da tabela de rotas nuláveis descrito em [subnet placement](/pt/networking/subnets#reading-placement): ```json theme={null} { "load_balancer": { "subnet": { "id": "d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0", "crn": "crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/public", "name": "public", "cidr": "10.0.0.0/24", "vpc": { "id": "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9", "name": "production" }, "route_table": { "id": "…", "crn": "…", "name": "public-routes" } } } } ``` Não há nenhum campo `vpc` separado: a VPC é `subnet.vpc`, então `subnet.name` e `subnet.vpc.name` são ambos legíveis fora do balanceador de carga sem uma segunda leitura. É isso que a visão geral do console vincula. No Go SDK estes são `lb.Subnet` e `lb.Subnet.VPC`. `subnet` é **null** quando a sub-rede referenciada não é mais resolvida. Trate isso como um posicionamento indisponível e atualize em vez de um balanceador de carga não posicionado — as réplicas e o IP virtual ainda estão onde estavam. Em Go, verifique `lb.Subnet != nil` antes de ler `lb.Subnet.VPC`. Create ainda leva `vpc` e `subnet` como referências **string**, e `PATCH /v1/load-balancers/{id}` não leva nenhuma delas — a colocação é imutável. Quando você copiar o posicionamento de uma resposta para outra requisição (criando um segundo balanceador de carga ou um cluster na mesma sub-rede, por exemplo), passe o `id` ou `crn` da sub-rede embutida, nunca o objeto. ## Como um balanceador de carga obtém seu endereço Um balanceador de carga usa IPs flutuantes para endereços privados e públicos. Na criação, `floating_ips` pode selecionar um endereço por família e visibilidade: IPv4 privado, IPv4 público, IPv6 privado e IPv6 público. Os endereços privados selecionados devem pertencer à sub-rede do balanceador de carga. Qualquer família privada ausente é alocada automaticamente quando essa família é ativada na sub-rede. Os endereços públicos são opcionais e devem ser selecionados explicitamente. ```json theme={null} { "floating_ips": [ "f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2", "e2c19b77-7374-4793-a8ab-23e1b9cc0001" ] } ``` Use IPs flutuantes existentes e gratuitos na mesma conta e região. O array `floating_ips` da resposta inclui suas identidades, famílias, visibilidade e endereços. `internal_ipv4`, `internal_ipv6`, e `public_ipv6` resumem os endereços correspondentes quando presentes. Esses IPs flutuantes encaminham o tráfego de ouvinte para réplicas saudáveis; eles não são endereços extras configurados dentro dos convidados. No console, use o cartão **IP addresses** em **Create Load Balancer**. Cada seleção privada é padrão para **Automatic — allocate from this subnet** e cada seleção pública é padrão para **None**. As opções disponíveis seguem as famílias e rotas habilitadas da sub-rede. Os IPs flutuantes privados atribuídos automaticamente pertencem ao balanceador de carga, são cobertos por sua cota e são liberados quando ele é excluído. Os endereços existentes que você forneceu são separados e retidos quando ele é excluído. Nenhum dos dois tipos pode ser desligado de forma independente enquanto o balanceador de carga o possui. A seleção de endereço é fixa na criação. `PATCH /v1/load-balancers/{id}` não o altera. Para adicionar exposição pública ou substituir um endereço, crie um novo balanceador de carga com os IPs flutuantes necessários e mova o tráfego para ele. O IPv4 público requer `0.0.0.0/0` através de um gateway de Internet na tabela de rotas da sub-rede; o IPv6 público requer `::/0` através de um gateway de Internet e uma sub-rede habilitada para IPv6. Os gateways NAT e somente de saída não fornecem exposição de ouvinte público. Uma sub-rede ULA privada pode usar um IP flutuante IPv6 público: o NAT66 o traduz para os endereços de réplica. O campo `floating_ip` create permanece uma abreviatura IPv4 pública. Não pode ser combinado com `floating_ips`, e não aloca um endereço IPv6 público. ### Apontando um nome para ele A resposta carrega `dns_name`, um nome de host publicado para você em uma zona regional compartilhada, na forma de `{name}.{account}.lb..`. Ele resolve para o IP flutuante em um balanceador de carga voltado para a Internet e para o VIP privado de outra forma. Leia `dns_name` da resposta em vez de montá-lo. Ele está vazio em uma região onde a zona de conveniência não está configurada — o VIP e o IP flutuante permanecem autoritativos de qualquer maneira. O nome do balanceador de carga é fixo após a criação, portanto, as atualizações mantêm seu nome de host. Para o seu próprio domínio, publique um `CNAME` para `dns_name` — ou um registro `A` para o IP flutuante se você precisar de um apex — com [DNS](/pt/dns). ## Listeners Um ouvinte vincula um protocolo e uma porta no balanceador de carga. O par tem que ser único — um segundo ouvinte no mesmo protocolo e porta é recusado — então um balanceador de carga de rede pode servir `tcp` e `udp` no mesmo número de porta, mas nunca dois ouvintes `tcp` em um. Abra o balanceador de carga e escolha **Add Listener**. O cartão **Listener** recebe o **Protocol**, o **Port** e o **Exposure**; escolher HTTP ou HTTPS move a porta para 80 ou 443 para você. **Routing** define o **Default target group**. Um ouvinte HTTPS cria um cartão de **TLS certificates**. Escolha um ou mais em **Certificates** — o console observa que o primeiro que você selecionar se torna o padrão e o resto são opções de SNI. A lista **Protocol** sempre oferece apenas o que esse tipo de balanceador de carga aceita, portanto, a incompatibilidade descrita abaixo não pode ser feita aqui. ```bash theme={null} POST /v1/load-balancers/{id}/listeners { "protocol": "https", "port": 443, "certificates": [{ "certificate": "crn:certificate::my-account:certificate/prod-web" }], "default_target_group": "b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4" } ``` ```bash theme={null} basaltic loadbalancer listener create "$LOAD_BALANCER_ID" --protocol https --port 443 \ --certificates '[{"certificate":"crn:certificate::my-account:certificate/prod-web"}]' \ --default-target-group b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4 ``` ```go theme={null} _, err := loadbalancer.New(cfg).CreateListener(ctx, loadBalancerID, &loadbalancer.CreateListenerRequest{ Protocol: "https", Port: 443, Certificates: []*loadbalancer.CreateListenerCertificate{{ Certificate: "crn:certificate::my-account:certificate/prod-web", }}, DefaultTargetGroup: basaltic.String("b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4"), }) if err != nil { log.Fatal(err) } ``` | Balanceador de carga `type` | Aceito `protocol` | | - | - | | `application` | `http`, `https` | | `network` | `tcp`, `udp` | Misturá-los é rejeitado na criação com o motivo nomeado. Os valores do protocolo são em minúsculas, que é a convenção da plataforma para enums que definimos; valores que vêm de um padrão mantêm a própria caixa desse padrão — um método HTTP em uma condição de regra é `GET`, não `get`. ### Exposição `exposure` seleciona qual dos endereços IP flutuantes do balanceador de carga encaminha o tráfego para o ouvinte. A seleção aplica-se ao IPv4 e ao IPv6. Encaminhado através dos endereços privados do balanceador de carga somente. Encaminhado através dos endereços públicos do balanceador de carga somente. Encaminhada através dos endereços privados e públicos. Os grupos de segurança também devem permitir a porta de ouvinte. Permitir uma porta em um grupo de segurança não a torna disponível através de um endereço LB excluído por `exposure`. Em sub-redes com GUA IPv6 roteado, réplicas gerenciadas também têm endereços de NIC nativos. Novas conexões de fora da VPC para esses endereços nativos são bloqueadas, inclusive quando um grupo de segurança permite a porta. Os clientes públicos devem usar um endereço de balanceador de carga público. As conexões iniciadas pela réplica e suas respostas ainda funcionam, assim como o tráfego dentro da VPC. Esta política aplica-se a balanceadores de carga públicos e internos; as placas de rede de instância ordinárias mantêm a acessibilidade IPv6 nativa. O console escreve as mesmas três opções **Private only (VPC-internal VIP)**, **Public + private** e **Public only (floating IP)** no campo **Exposure** de **Add Listener**. O padrão se adapta ao balanceador de carga: `both` quando ele carrega um IP flutuante público, `private_only` quando não. Pedir por `public_only` ou `both` em um balanceador de carga sem IP flutuante público é rejeitado. O console desabilita ambas as opções públicas nesse caso e diz **Exposição pública indisponível**. Um listener `public_only` pára de ser servido completamente se o IP flutuante desaparecer — ele não tem mais endereço para vincular. Um ouvinte `both` continua servindo em particular. Patch `exposure` para `private_only` se você quisesse mantê-lo interno. ### Certificados em um ouvinte HTTPS Um ouvinte HTTPS precisa de pelo menos um certificado, nomeado **por CRN**. Nenhum material de chave é enviado para essa API: o ouvinte armazena uma referência e as réplicas obtêm o material do [serviço de certificado](/pt/certificates) sob sua própria identidade. Um ouvinte pode manter vários certificados e escolhe um por conexão, combinando o SNI do cliente com as SANs de cada certificado. O sinalizado `is_default` é o fallback para um cliente cujo SNI não corresponde a nada, ou que não envia nada. ```bash theme={null} POST /v1/load-balancers/{id}/listeners/{listener_id}/certificates { "certificate": "crn:certificate::my-account:certificate/prod-web", "is_default": true } ``` Definir um novo padrão degrada o anterior na mesma transação, então um ouvinte sempre tem exatamente um. Anexando e desligando em um ouvinte *ativo* é *apenas API*. O console escolhe os certificados uma vez, enquanto você está adicionando o ouvinte; depois a página do ouvinte mostra-os somente leitura, marcando o padrão com um emblema `default`. Alterar o conjunto — ou promover um padrão diferente — passa por essas duas chamadas. O desvinculamento é recusado em dois casos: remover o **último** certificado de um ouvinte HTTPS e remover o **padrão atual** enquanto outros certificados ainda estão anexados. Promova uma substituição primeiro, depois desligue. Um CRN de certificado termina em `certificate/`, então a barra deve ser codificada em porcentagem como `%2F` quando o CRN estiver em um segmento de caminho. Enviado em bruto, ele endereça uma rota diferente que não existe. ```bash theme={null} DELETE /v1/load-balancers/{id}/listeners/{listener_id}/certificates/crn:certificate::my-account:certificate%2Fprod-web ``` Os certificados que a plataforma renova são pegos por conta própria — uma reemissão altera a impressão digital que as réplicas rastreiam e elas recuperam novamente. Para forçar uma nova verificação de um certificado já anexado, corrija o ouvinte com seu CRN. Anexar e desconectar também re-escopo o acesso das réplicas para que ele cubra exatamente os certificados atualmente anexados, e nada mais. ### Grupo-alvo padrão `default_target_group` é onde uma solicitação vai quando nenhuma regra corresponde. Em um listener `tcp` ou `udp` é o **único** destino — regras não se aplicam na camada 4 — então um listener L4 sem um não tem para onde enviar tráfego. Um ouvinte HTTP ou HTTPS sem padrão e sem regra de correspondência responde **`503`** com o corpo `no default target group`. Defina-o, ou limpe-o deliberadamente com `clear_default_target_group: true` uma vez que suas regras abranjam tudo o que você serve. ## Regras de roteamento As regras existem apenas em ouvintes `http` e `https`; a criação de uma em um ouvinte L4 é recusada. Cada regra tem uma prioridade, uma lista de condições e um grupo-alvo. Abra o listener e escolha **Add Rule**. **Evaluation order** assume a **Priority**, **Conditions** cria a correspondência e **Forward to** escolhe o **Target group**. ```bash theme={null} POST /v1/load-balancers/{id}/listeners/{listener_id}/rules { "priority": 100, "conditions": [ { "field": "host", "op": "exact", "values": ["api.example.com"] }, { "field": "path", "op": "prefix", "values": ["/v1"] } ], "target_group": "b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4" } ``` ```bash theme={null} basaltic loadbalancer rule create "$LOAD_BALANCER_ID" "$LISTENER_ID" --priority 100 \ --conditions '[{"field":"host","op":"exact","values":["api.example.com"]},{"field":"path","op":"prefix","values":["/v1"]}]' \ --target-group b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4 ``` ```go theme={null} _, err := loadbalancer.New(cfg).CreateRule(ctx, loadBalancerID, listenerID, &loadbalancer.CreateRuleRequest{ Priority: 100, Conditions: []*loadbalancer.RuleCondition{ {Field: "host", Op: "exact", Values: []string{"api.example.com"}}, {Field: "path", Op: "prefix", Values: []string{"/v1"}}, }, TargetGroup: "b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4", }) if err != nil { log.Fatal(err) } ``` As regras são avaliadas em ordem crescente de prioridade e a **primeira correspondência vence**; `priority` é `1..50000` e único por ouvinte. Todas as condições de uma regra devem corresponder — a lista é um AND. | `field` | Jogos de cartas | No console | | - | - | - | | `host` | A autoridade da solicitação (seu `Host`) | **Cabeçalho do host** | | `path` | O caminho da solicitação | **Caminho** | | `header` | O cabeçalho nomeado em `name` | **Cabeçalho HTTP** | | `query` | A chave de query-string nomeada em `name` | **Query param** | | `method` | O método HTTP, escrito como HTTP o escreve — `GET` | **Método HTTP** | | `op` | Comportamento | | - | - | | `exact` | Igualdade de valor total | | `prefix` | O valor começa com | | `glob` | Apenas `*` é um curinga; todos os outros metacaracteres são literais | | `regex` | RE2 sintaxe | O console lista os operadores como **equals**, **prefix**, **glob** e **regex** — apenas `exact` lê diferente lá. Dê a cada condição um **valor único**. `values` é um array, mas o plano de dados corresponde à primeira entrada e ignora o resto. Expresse alternativas com `glob` ou `regex`, ou escreva uma regra por valor. Uma condição `header` ou `query` sem `name` é rejeitada, e assim é um valor `regex` que não compila como RE2. Esse rigor é deliberado: a configuração de um balanceador de carga é construída em uma única passagem, então uma única condição não traduzível interromperia **todas as** réplicas carregando qualquer configuração — incluindo substituições que um redimensionamento está esperando. Recusar a gravação custa um erro em vez de uma interrupção. Atualizar uma regra é uma substituição completa: envie `priority`, `conditions` e `target_group` juntos, a mesma forma que criar. O console faz a mesma coisa atrás de **Edit Rule**, intitulado com a prioridade da regra — o formulário aparece preenchido e **Save Rule** escreve a regra inteira de volta. Exclua uma regra através de seu listener — `DELETE /v1/load-balancers/{id}/listeners/{listener_id}/rules/{rule_id}`. O formulário sem ouvinte ainda funciona para clientes que já estão nele, mas ele tem que verificar os ouvintes do balanceador de carga para provar que a regra pertence a ele. ## Grupos de destinos Um grupo de destino é o conjunto nomeado de backends para os quais um ouvinte ou regra encaminha. É um recurso de escopo de conta próprio, não um filho de um balanceador de carga, então um grupo pode apoiar vários ouvintes — o que torna uma troca azul/verde uma questão de reposicionar uma regra. Vá para **Compute → Target Groups** e escolha **Create Target Group**. Os arquivos do console direcionam grupos em **Compute**, mesmo que pertençam à API de balanceamento de carga. **Target group** recebe o **Name**, o **Protocol** e o **Port**. **Backends** escolhe o **Backend mode** — **Static targets** para um conjunto que você mesmo anexar, **Instance pool** para rastrear um pool — e, para um grupo estático, o **Target type**: **IP address** ou **Instance**. ```bash theme={null} POST /v1/target-groups { "name": "web-targets", "protocol": "http", "target_type": "instance", "port": 8080 } ``` ```bash theme={null} basaltic loadbalancer target-group create --name web-targets --protocol http --target-type instance --port 8080 ``` ```go theme={null} _, err := loadbalancer.New(cfg).CreateTargetGroup(ctx, &loadbalancer.CreateTargetGroupRequest{ Name: "web-targets", Protocol: "http", Port: 8080, TargetType: basaltic.String("instance"), }) if err != nil { log.Fatal(err) } ``` Deve corresponder ao protocolo do ouvinte que aponta para ele. O que `target` significa em cada alvo anexado. `static` usa os alvos que você anexar. `pool` obtém seus backends de um pool de instâncias de computação chamado `instance_pool`, então escalar o pool move o conjunto de backends com ele — e anexar um alvo manualmente é recusado com um `409`, porque uma linha para a qual nada seria roteado é pior do que um erro. Um grupo de modo de pool é forçado a `target_type: instance`. A porta padrão para destinos no grupo. Um alvo pode substituí-lo. Excluir um grupo enquanto um padrão de ouvinte ou uma regra ainda o refere é um **`409`** — reposicione ou exclua a referência primeiro. No console que é **Excluir grupo de destino**, na guia **Settings** do grupo. O número de ouvintes por balanceador de carga, grupos de destino por balanceador de carga e destinos por grupo são cotas de conta; exceder um é recusado na gravação. `target_type: function` é aceito em um grupo, mas anexar um alvo a ele é recusado: o tempo de execução da função ainda não está disponível, então o grupo não tem como resolver um backend. ### Anexando alvos Abra o grupo de destino e escolha **Attach Target**. O primeiro campo segue o tipo de destino do grupo — **IP address** ou **Instances** — e **Port** é o padrão para a porta do grupo de destino. Um grupo de modo de pool não tem nenhum botão **Attach Target**: a associação rastreia o pool de instâncias, então não há nada para anexar manualmente. ```bash theme={null} POST /v1/target-groups/{id}/targets { "target": "web-01", "port": 8080 } ``` ```bash theme={null} basaltic loadbalancer target-group attach-target "$TARGET_GROUP_ID" --target web-01 --port 8080 ``` ```go theme={null} _, err := loadbalancer.New(cfg).AttachTarget(ctx, targetGroupID, &loadbalancer.AttachTargetRequest{Target: "web-01", Port: basaltic.Int(8080)}) if err != nil { log.Fatal(err) } ``` `target` é um endereço IP literal em um grupo `ip` e um UUID, CRN ou nome de instância de computação em um grupo `instance`. Uma referência de instância permanece não resolvida na linha e se torna um endereço no momento da configuração, portanto, uma instância cujo endereço de NIC seja alterado não precisa ser atualizada aqui. A instância tem que existir em sua conta — veja [compute](/pt/compute). Os endereços são armazenados de forma canônica, portanto, a ortografia que você lê pode ser diferente daquela que você enviou, e duas ortografias do mesmo endpoint são reconhecidas como duplicatas. Um alvo `ip` tem que ser um **endereço unicast roteável**. Endereços de loopback, link-local, multicast e não especificados são rejeitados. Esse é um limite de segurança, não de limpeza: link-local carrega o ponto de extremidade de metadados da instância e loopback é o próprio soquete administrativo da réplica. Ambos são acessíveis a partir de uma réplica, então sem a verificação um ouvinte os enviaria diretamente para a internet. O formulário IPv6 mapeado para IPv4 também é rejeitado — envie o formulário IPv4 pontilhado. Separando um alvo remove-o imediatamente — **Detach** na linha do alvo no console, confirmado como **Detach target**. ### Check-ups de saúde O plano de dados sonda cada alvo e relata o que vê. Defina os botões por grupo, na criação ou com um patch: **Create Target Group** expõe exatamente um desses, como **Health check path** em **Health & connection**. O campo só aparece para um grupo HTTP ou HTTPS. O intervalo, tempo limite e limiares são *API somente*. A aba **Health check** de um grupo alvo exibe o que quer que eles estejam definidos, mas nada no console os grava — envie o bloco abaixo para alterar um. ```bash theme={null} PATCH /v1/target-groups/{id} { "health_check": { "protocol": "http", "path": "/healthz", "interval_sec": 30, "timeout_sec": 5, "healthy_threshold": 3, "unhealthy_threshold": 3 } } ``` ```bash theme={null} basaltic loadbalancer target-group update "$TARGET_GROUP_ID" \ --health-check '{"protocol":"http","path":"/healthz","interval_sec":30,"timeout_sec":5,"healthy_threshold":3,"unhealthy_threshold":3}' ``` ```go theme={null} _, err := loadbalancer.New(cfg).UpdateTargetGroup(ctx, targetGroupID, &loadbalancer.UpdateTargetGroupRequest{ HealthCheck: &loadbalancer.HealthCheck{ Protocol: "http", Path: "/healthz", IntervalSec: 30, TimeoutSec: 5, HealthyThreshold: 3, UnhealthyThreshold: 3, }, }) if err != nil { log.Fatal(err) } ``` `protocol` padrões para o próprio grupo. Sondagem sobre HTTP em um grupo `tcp` é suportada e comum — um backend que fala um protocolo binário ainda pode servir uma página de saúde. `path` padrões para `/` para `http` e `https`; `tcp` e `udp` verificações são apenas de conexão e ignorá-lo. Os limiares são resultados consecutivos: três fracassos seguidos para ficar doente, três sucessos para voltar. `health_check.matcher` e `health_check.port` são aceitos e armazenados, mas **não são aplicados à sonda** hoje. Uma sonda atinge a própria porta do alvo. Deixe-os sem configuração em vez de esperar que eles mudem qualquer coisa. Leia o resultado em cada alvo: | `health` | Significado da palavra | | - | - | | `initial` | Nenhuma sonda bem sucedida ainda. Um alvo que nunca sai desse estado não está sendo alcançado. | | `healthy` | Passagem e recebimento de tráfego. | | `unhealthy` | Falhando, e tirado de rotação. | ### Afinidade da sessão Por padrão, cada solicitação é balanceada de forma independente. Ativar a stickiness por grupo-alvo: No console, esse é o campo **Stickiness** — em **Create Target Group** e na guia **Settings** de um grupo existente. Ele oferece **None**, **Cookie** e **IP de origem**, com **Nome do cookie** e **Duração (segundos)** aparecendo em **Cookie**. **Cookie** só está listado para um grupo HTTP ou HTTPS, pelo motivo abaixo. ```json theme={null} { "session_affinity": { "type": "cookie", "cookie_name": "BASALTICLB", "duration_sec": 86400 } } ``` O balanceador de carga define um cookie opaco na primeira resposta e envia cada solicitação posterior levando-o para o mesmo backend. Apenas os grupos `http` e `https` — não há cookie em um fluxo bruto. `cookie_name` é padrão para `BASALTICLB` e `duration_sec` para um dia, até um limite de sete dias (`604800`). O cookie é um valor aleatório que não significa nada fora deste balanceador de carga. Ele não codifica qual backend foi escolhido, então um cliente não pode ler seus endereços internos dele. ```json theme={null} { "session_affinity": { "type": "source_ip" } } ``` Hashes o endereço do cliente. Funciona em todos os protocolos e é a única opção para `tcp` e `udp`. Esteja ciente de que um gateway NAT na frente de seus clientes faz com que cada cliente atrás dele seja uma chave, o que os concentra em um backend. ```json theme={null} { "session_affinity": { "type": "none" } } ``` O padrão. Desabilitar a stickiness **off** em um grupo existente precisa desse corpo explícito — omitir `session_affinity` de um patch deixa a configuração atual sozinha. Ambos os modos fazem hash consistentemente, então adicionar ou perder um backend move apenas os clientes que o backend estava servindo, em vez de reorganizar todos. ### Ver o cliente real Um grupo alvo `http` ou `https` já obtém o endereço do cliente em `X-Forwarded-For`, e qualquer `X-Forwarded-For` que o cliente enviar não é confiável — o balanceador de carga é a borda, então nada acima dele conta. Para grupos `tcp` e `udp`, ou backends que preferem um envelope enquadrado, defina `proxy_protocol: true` e as conexões upstream são envolvidas em um cabeçalho PROXY v2 que carrega o endereço e a porta do cliente original. A opção do console é **PROXY protocol (v2)**, em **Health & connection**. ## Réplicas `desired_count` é o número de réplicas desejado. `min_count` e `max_count` vinculados tanto ao dimensionamento manual quanto automático. Uma réplica é suficiente para funcionar; duas ou mais podem continuar servindo se uma for perdida. ```bash theme={null} GET /v1/load-balancers/{id}/replicas ``` As réplicas são instâncias gerenciadas, então `GET /v1/instances` não as retorna por design. Esse endpoint é a única janela para eles. Cada entrada carrega `instance_id`, `replica_index`, o `flavor_id` que ele realmente inicializou, e uma visão de liveness atualizada em cada relatório de saúde: | `status` | Significado da palavra | | - | - | | `initializing` | A réplica nunca relatou — boot ainda em andamento. `last_seen` está ausente. | | `healthy` | Relatório, e seu proxy está servindo. | | `unhealthy` | Relatório, mas seu proxy está em baixo. É retirado do caminho de tráfego até que se recupere. | | `draining` | Aposentadoria após a retirada de novo tráfego. As conexões existentes têm um período de carência limitado. | O próprio balanceador de carga fica `active` na primeira réplica a reportar saúde, e cai para `error` somente quando **todas** as réplicas ficaram silenciosas após a janela de obsolescência — um relatório perdido não é suficiente. Ele retorna para `active` assim que qualquer réplica recomeça. ### Escala **Scale** no balanceador de carga abre **Scale load balancer**. Ele mostra o **Current size** e leva **Minimum count**, **Maximum count** e **Desired count**. Ative **Automatic scaling** para configurar metas de CPU ou métricas personalizadas e escolha **Scale** para salvar. A guia **Scaling** mostra a política e as decisões recentes. ```bash theme={null} PATCH /v1/load-balancers/{id} { "min_count": 2, "max_count": 6, "desired_count": 4 } ``` ```bash theme={null} basaltic loadbalancer load-balancer update "$LOAD_BALANCER_ID" --min-count 2 --max-count 6 --desired-count 4 ``` ```go theme={null} _, err := loadbalancer.New(cfg).UpdateLoadBalancer(ctx, loadBalancerID, &loadbalancer.UpdateLoadBalancerRequest{MinCount: basaltic.Int(2), MaxCount: basaltic.Int(6), DesiredCount: basaltic.Int(4)}) if err != nil { log.Fatal(err) } ``` As chamadas CLI e Go acima definem os limites e a quantidade desejada juntas. O máximo de seis permite substituir réplicas sem reduzir as quatro desejadas. Uma atualização apenas dos limites ajusta a quantidade desejada ao novo intervalo; uma quantidade desejada explícita fora dele é rejeitada. As provisões de escalabilidade horizontal fornecem réplicas do pool de instâncias gerenciadas do balanceador de carga. O dimensionamento interno retira as réplicas de retirada do novo tráfego, aguarda que o proxy reconheça a drenagem e, em seguida, permite o período de carência configurado antes da exclusão. O período de carência padrão é de 120 segundos. Sessões TCP, UDP e WebSocket de longa duração podem terminar quando uma réplica é removida; planeje reconexões. As alterações à associação de encaminhamento IP flutuante também podem alterar o posicionamento da conexão durante a retirada. O campo `autoscaling` aceita as mesmas [políticas de CPU e métricas personalizadas](/pt/compute/instance-pools#automatic-scaling) que os pools de instâncias. Por exemplo, o rastreamento de meta de CPU em 60% ajusta a capacidade desejada entre o mínimo e o máximo. As métricas personalizadas podem usar a profundidade da fila, as taxas de solicitação ou outra demanda publicada na Telemetria. Os balanceadores de carga sempre retêm pelo menos uma réplica. Amostras ausentes ou obsoletas impedem a escala. Configure a política do balanceador de carga através de sua própria API. Seu pool gerenciado não pode ser redimensionado de forma independente. Os pools de instâncias de back-end têm seus próprios limites e políticas: a alteração da capacidade do proxy não redimensiona os aplicativos de trabalho. A telemetria do balanceador de carga inclui `instance_id` em cada série de réplicas. Para contadores, calcule as taxas por série antes de somar entre réplicas para que uma reinicialização ou substituição não possa mascarar o tráfego de outra réplica. Soma o último medidor de conexão ativa de cada réplica para obter um total. Os medidores de integridade de destino descrevem a exibição de cada réplica dos mesmos backends, portanto, mantenha essas exibições separadas ou use um mínimo ou máximo; somá-las conta backends repetidamente. Para histogramas de latência, calcule taxas de contador por série e combine limites de intervalo correspondentes em réplicas antes de calcular um percentil. ### Mudando o tipo de instância Uma instância em execução não pode mudar de tamanho no local, portanto, um redimensionamento registra o novo tamanho e retorna — as réplicas já instaladas são substituídas uma por vez em segundo plano, nos minutos seguintes. **Resize** no balanceador de carga abre **Resize load balancer**. Escolha o novo **Flavor** e confirme com **Resize**. O botão está desabilitado enquanto um redimensionamento já está em execução — o console não irá empilhar dois rolos. ```bash theme={null} PATCH /v1/load-balancers/{id} { "flavor": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1" } ``` ```bash theme={null} basaltic loadbalancer load-balancer update "$LOAD_BALANCER_ID" --flavor e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1 ``` ```go theme={null} _, err := loadbalancer.New(cfg).UpdateLoadBalancer(ctx, loadBalancerID, &loadbalancer.UpdateLoadBalancerRequest{ Flavor: basaltic.String("e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1"), }) if err != nil { log.Fatal(err) } ``` **O pool cresce antes de encolher.** Uma réplica extra aparece no novo tipo de instância e começa a servir *antes* de qualquer réplica no antigo ser aposentada, então o rolo aguarda a capacidade de substituição antes de aposentar a capacidade antiga. A réplica extra deve caber dentro de `max_count`. Desired e minimum permanecem inalterados; `rollout_surge` indica o membro extra temporário. Quando a última réplica antiga for removida, o pool retornará à capacidade desejada. Assista-o em `GET /v1/load-balancers/{id}/replicas`. Uma réplica foi substituída quando seu `instance_id` muda, e o redimensionamento é feito quando cada `flavor_id` lá corresponde ao do balanceador de carga. Ver mais uma réplica listada do que `desired_count` a meio do caminho é o aumento mantendo sua capacidade, não uma réplica vazando — ela desaparece quando a última antiga desaparece. O console lê a mesma coisa para você: a guia **Replicas** marca uma réplica que o rolo ainda não atingiu, e a página do balanceador de carga conta quantos estão no novo tamanho. Duas coisas que vale a pena saber: * **Nada é aposentado até que tudo esteja em ordem.** O rolo aguarda que o pool esteja completo com cada relatório de réplica e seu proxy ativo. Uma substituição que nunca chega saudável interrompe o redimensionamento com o balanceador de carga inteiro, em vez de executá-lo uma réplica por passagem. * **Um balanceador de carga em seu máximo não tem capacidade livre para substituições.** Aumentar `max_count` Uma alteração de tipo de instância é recusada quando não há espaço para uma substituição. Um rolo já em andamento aguarda se uma alteração de limites posterior remover esse espaço. O dimensionamento automático pausa durante o rolo. Um redimensionamento é rejeitado antecipadamente se sua conta não tiver a cota de computação para a réplica de substituição, para que não seja possível aplicar metade e deixar o balanceador de carga com pouco espaço. ## A apagar Na guia **Settings** do balanceador de carga, **Delete load balancer**. Você é solicitado a digitar o nome do balanceador de carga para confirmar. Um listener é excluído da guia **Listeners** e leva suas regras com ele. Os grupos de destino sobrevivem a ambos — são recursos com escopo de conta, não filhos do balanceador de carga. ```bash theme={null} DELETE /v1/load-balancers/{id} ``` ```bash theme={null} basaltic loadbalancer load-balancer delete "$LOAD_BALANCER_ID" ``` ```go theme={null} err := loadbalancer.New(cfg).DeleteLoadBalancer(ctx, loadBalancerID) if err != nil { log.Fatal(err) } ``` Respostas **`202`**. O balanceador de carga passa para `deleting` e permanece legível enquanto sua reserva de endereço, réplicas e estado interno são liberados, com o registro removido por último. Sondagem até que ele responda `404` em vez de tratar o `202` como prova de que ele se foi. Repetir a exclusão é seguro. ## Status ```mermaid theme={null} stateDiagram-v2 [*] --> provisioning: create provisioning --> active: a replica reports its proxy healthy provisioning --> error: an active error fault active --> error: an active error fault error --> active: every error fault resolved active --> deleting: delete error --> deleting: delete deleting --> [*]: teardown converges ``` | Status do produto | Significado da palavra | | - | - | | `provisioning` | Nenhuma réplica começou a atender tráfego. As réplicas estão inicializando e instalando seu software. Nesse estado, ainda não se registram falhas de atividade das réplicas. | | `active` | Pelo menos uma réplica está servindo e nenhuma falha de erro ativa permanece. Um aviso `REPLICAS_DEGRADED` deixa esse status no lugar. | | `error` | Um erro de falha ativo permanece — leia cada entrada em `faults`. Isso inclui uma interrupção completa da réplica (`REPLICAS_UNAVAILABLE`) e qualquer falha de provisionamento ou configuração. | | `deleting` | Desmontagem em andamento. Ainda legível até que o registro seja removido. | Um novo sinal de atividade resolve apenas os códigos relacionados à atividade das réplicas (`REPLICAS_DEGRADED`, `REPLICAS_UNAVAILABLE`). Falhas de provisionamento ou de geração da configuração permanecem ativas. | Código | Significado e recuperação | | - | - | | `PROVISIONING_FAILED` | Réplicas ou seu software não apareceu. O balanceador de carga permanece em `error` até que o trabalho seja bem sucedido. | | `CONFIG_RENDER_FAILED` | A configuração do proxy não pôde ser renderizada. | | `CONFIG_PUBLISH_FAILED` | Uma configuração renderizada não pôde ser publicada para as réplicas. | | `CONFIG_GENERATION_FAILED` | Uma nova geração de configuração não pôde ser produzida. | | `OVN_RECONCILE_FAILED` | O programa de plano de dados não convergiu. | | `REPLICA_ROLL_FAILED` | Uma substituição de réplica não foi concluída. | | `TEARDOWN_FAILED` | Levantado somente quando o teardown para de fazer progresso — réplicas que desligam durante uma exclusão normal não levantam nenhuma falha. Limpa quando a retentação converge. | | `LEGACY_OPERATION_FAILED` | Uma falha migrada da cadeia de erros anterior. Limpado pela operação que agora o possui. | | `REPLICAS_DEGRADED` | Algumas réplicas estão fora de serviço e outras ainda estão em serviço. Registrado somente após a primeira observação de serviço. Este é um `warning`; `status` permanece `active`. | | `REPLICAS_UNAVAILABLE` | Nenhuma réplica está servindo. Registrado somente após a primeira observação de serviço — um conjunto de réplicas que nunca foi servido é provisionamento, não uma interrupção. Isto é um `error`. | ## Limites e nomenclatura Começa com uma letra, depois letras, dígitos, `.`, `_` ou `-`, até 127 caracteres. Ele aparece no CRN, então ele tem que ser seguro para URLs. Os nomes de balanceador de carga e grupo de destino são fixos após a criação porque as políticas do IAM abordam seus CRNs. Atualizações contendo `name` retornam um erro de validação, incluindo valores inalterados, vazios ou `null`. Os recursos existentes mantêm seus nomes atuais. Excluir um recurso e reutilizar seu nome cria um recurso diferente, mesmo que seu CRN seja o mesmo. Os ouvintes e as regras não têm nomes separados. Seus CRNs usam componentes UUID sob o nome imutável do balanceador de carga: `load-balancer//listener/` e `load-balancer//listener//rule/`. Passe um UUID ou CRN codificado em URL em seus parâmetros de caminho; os nomes de ouvintes e regras não são aceitos. O CRN de um balanceador de carga termina em `load-balancer/` e o de um grupo alvo em `target-group/`. Como o CRN carrega o nome, uma [política do IAM](/pt/iam/policies) pode usar um curinga para uma convenção de nomenclatura em vez de listar ids. Pegue a string exata do campo `crn` do recurso ao invés de montá-la. Tanto na criação como em um patch. Único por ouvinte. Ouvintes por balanceador de carga, grupos-alvo por balanceador de carga e alvos por grupo-alvo são cotas de contas, e não números fixos. Lista de operações de página com `limit` e `marker`; página até `meta.has_more` é falso em vez de até que uma página parece curta. Cria aceitar um cabeçalho `Idempotency-Key`, que faz com que uma nova tentativa retorne o resultado original em vez de uma duplicata. ## Solução de problemas A causa mais comum é que nenhum grupo de segurança nas réplicas abre a porta de ouvinte. `security_groups` é definido na criação e não pode ser corrigido no balanceador de carga — altere as regras dentro dos grupos de segurança que você já anexou, ou recrie com o conjunto correto. Veja [networking](/pt/networking). A segunda causa é um ouvinte cuja `exposure` é `private_only` quando você esperava public, ou `public_only` em um balanceador de carga cujo IP flutuante foi perdido — um ouvinte `public_only` sem endereço público não é servido de forma alguma. A sub-rede que você escolheu não tem nenhuma rota `0.0.0.0/0` para um gateway de internet. O tráfego de resposta sai dessa tabela de rota, então o endereço seria inacessível, e toda a criação falha em vez de deixar você com um balanceador de carga sem o endereço que você pediu. Anexe um gateway de internet à VPC e adicione a rota padrão, depois crie-a novamente — `floating_ip` é um campo de tempo de criação somente, então não há segunda chance depois. `initial` significa que nenhuma sonda ainda foi bem sucedida. Verifique, em ordem: o backend está escutando na `port` do grupo (ou na substituição do alvo); o próprio grupo de segurança do backend permite a sub-rede das réplicas; e, para uma verificação HTTP, esse `path` retorna um status de sucesso. Lembre-se que a sonda atinge a própria porta do alvo - `health_check.port` não é aplicado hoje. Três coisas a verificar. Regras em ordem crescente `priority` e a primeira correspondência ganha, então uma regra ampla com número baixo sombreia as regras específicas abaixo dela. Cada condição em uma regra deve corresponder — a lista é um AND, não um OR. **primeiro** entrada de dados `values`; entradas extras são ignoradas, portanto expresse alternativas com `glob` ou `regex`. Sem nenhuma correspondência de regra, a solicitação vai para o `default_target_group` do ouvinte, ou recebe um `503` lendo `no default target group` se não houver nenhum. Duas remoções são recusadas: o último certificado em um ouvinte HTTPS e o certificado atualmente sinalizado como `is_default`, enquanto outros permanecem. Anexar ou promover uma substituição como padrão primeiro — que rebaixa a antiga na mesma transação — e depois desconectar. Se a solicitação 404s ou erros no caminho em si, a barra do CRN foi enviado bruto. Codifica-o como `%2F`. O rolo avança por uma réplica de cada vez e não irá retirar nada enquanto qualquer réplica estiver doente ou ainda em ascensão. Então, um redimensionamento parado geralmente significa uma substituição que nunca saiu saudável — verifique `GET /v1/load-balancers/{id}/replicas` para um que esteja em `initializing` ou `unhealthy`. O balanceador de carga continua servindo nas réplicas que ele tem enquanto isso for verdade, que é o ponto. É esperado ver uma réplica mais do que `replica_count` no meio do rolo. O `default_target_group` de um ouvinte ou o `target_group` de uma regra ainda aponta para ele. Reposicione ou exclua a referência e, em seguida, exclua o grupo.