> ## 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. # Pools de instâncias > Mantenha um conjunto de instâncias idênticas em uma contagem de destino, coloque-as em um novo modelo de lançamento e faça o front-end delas com um endereço público compartilhado. Um pool de instâncias é um modelo de lançamento mais uma contagem de destino. A plataforma mantém essas instâncias em execução a partir desse modelo, substitui as que falham e as espalha entre os hosts. É um primitivo para máquinas idênticas e intercambiáveis. Tudo o que ele faz segue disso: réplicas não podem ter endereços fixos, uma mudança de modelo não toca o que já está em execução, e um pool é o que torna um endereço público responsável por várias instâncias ao mesmo tempo. O modelo de lançamento, os limites de dimensionamento e como as réplicas são nomeadas. O que o pool converge, o que ele substitui e o contador para alertar. Por que editar o modelo não muda nada ainda, e o que uma atualização faz. Anycast entre as réplicas — e as maneiras que não é um balanceador de carga. ## Criando uma pool Vá para **Compute → Instance pools** e escolha **Create instance pool**. Após **Details**, vem um cartão **Scaling** com **Min**, **Desired** e **Max**; o restante do formulário é o modelo de lançamento, cartão por cartão, o mesmo que criar uma instância — **Flavor**, **Image**, **Boot volume**, **Data volumes**, **Networking**, **IAM role**, **User data**. **Min** é o piso e **Max** é o teto. Você pode alterar ambos mais tarde com **Scale**. Os dois mapas de tags abaixo são nomeados pela diferença entre eles: **Instance tags** são *estampados em cada réplica que o pool lança*, enquanto **Pool tags** *rotulam o próprio pool e não atingem nenhuma de suas instâncias*. ```bash theme={null} POST https://compute.sa-saopaulo-1.basaltic.sh/v1/instance-pools { "name": "web-asg", "desired_count": 3, "min_count": 2, "max_count": 6, "tags": { "team": "backend" }, "template": { "flavor": "550e8400-e29b-41d4-a716-446655440000", "image": "app-base:20260807", "networks": [ { "subnet": "9b2e4f1a-3c5d-4e6f-8a90-1b2c3d4e5f60", "security_groups": ["c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"] } ], "user_data": "I2Nsb3VkLWNvbmZpZwo...", "tags": { "role": "web" } } } ``` ```bash theme={null} basaltic compute instance-pool create --name web-asg \ --desired-count 3 --min-count 2 --max-count 6 --from-file pool.json ``` Salve a solicitação de API acima como `pool.json`. Os sinalizadores substituem os valores nesse arquivo; o arquivo fornece o modelo de lançamento aninhado. ```go theme={null} pool, err := compute.New(cfg).CreateInstancePool(ctx, &compute.InstancePoolCreateRequest{ Name: "web-asg", DesiredCount: basaltic.Int(3), MinCount: basaltic.Int(2), MaxCount: basaltic.Int(6), Template: &compute.InstancePoolTemplateRequest{ Flavor: "550e8400-e29b-41d4-a716-446655440000", Image: basaltic.String("app-base:20260807"), Networks: []*compute.NetworkConfig{ {Subnet: "9b2e4f1a-3c5d-4e6f-8a90-1b2c3d4e5f60"}, }, }, }) ``` Em pedidos de criação e substituição, `template` é a configuração de lançamento, na mesma forma que um [standalone instance create](/pt/compute/instances) toma — mesmos nomes de campo, mesmos tipos, mesmos significados. Não há um recurso de modelo de lançamento separado para criar, fazer versão ou compartilhar; o modelo pertence ao pool. Um flavor e uma sub-rede primária são necessários: `template.flavor` e `template.networks[0].subnet`. O índice 0 é a NIC primária; o resto são extras. **Um template não pode carregar um endereço fixo dentro de `addresses` ou um `mac` fixo.** Cada réplica é iniciada a partir do mesmo template, então um endereço fixo faria com que a segunda réplica pedisse um que a primeira já possui. Ambos são rejeitados com um `400` em vez de ser abandonado em silêncio. ### Referências e respostas de função do IAM As solicitações de criação e substituição aceitam `template.iam_role` como um UUID, CRN ou cadeia de nome exata para uma função em sua conta. Anexando a função requer `iam:PassRole` e autorização de confiança de instância; consulte [Funções e identidade de instância](/pt/iam/roles). Respostas de pool retornam um resumo de função opcional dentro de `template`, em vez de `iam_role_id`. Este excerto de resposta mostra a identidade do anexo: ```json theme={null} { "template": { "iam_role": { "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1", "crn": "crn:iam::my-account:role/deploy", "name": "deploy" } } } ``` O resumo contém apenas `id`, `crn` e `name` e é visível com acesso de leitura de pool, sem `iam:GetRole`. Exclui campos de função confidenciais, como políticas. `template.iam_role` é omitido quando nenhuma função está anexada, a função foi excluída ou pertence a outra conta. Abrir os detalhes do IAM da função ainda requer `iam:GetRole`. ### Referências e respostas de sub-rede As solicitações de criação e substituição levam `template.networks[].subnet` como uma cadeia de caracteres: um UUID ou um CRN completo de VPC/sub-rede. Um nome de sub-rede simples não é suficiente, porque os nomes de sub-rede são exclusivos apenas dentro de sua VPC. As respostas de pool incorporam toda a sub-rede em cada NIC de modelo, no lugar do antigo `subnet_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} { "template": { "networks": [ { "subnet": { "id": "9b2e4f1a-3c5d-4e6f-8a90-1b2c3d4e5f60", "crn": "crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/private", "name": "private", "cidr": "10.0.1.0/24", "vpc": { "id": "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9", "name": "production" }, "route_table": { "id": "…", "crn": "…", "name": "private-routes" } }, "floating_ip_assignment": "none" } ] } } ``` Assim, `subnet.name` e `subnet.vpc.name` são legíveis diretamente do pool — nenhuma leitura separada de sub-rede ou VPC é necessária apenas para mostrar onde as réplicas aterrissam. No Go SDK estes são `nic.Subnet` e `nic.Subnet.VPC`. `subnet` é **null** quando a sub-rede referenciada não é mais resolvida, como uma sub-rede excluída depois que o modelo foi armazenado. Trate isso como um posicionamento indisponível em vez de "sem sub-rede": mostre-o como indisponível e atualize antes de agir sobre ele. O modelo ainda nomeia uma sub-rede na qual o pool não pode ser lançado, e é por isso que a próxima substituição que ele lança falha. **Nunca envie o objeto embutido de volta.** As solicitações levam uma string, então uma substituição construída a partir de uma resposta tem que converter a `subnet` de cada NIC para seu `id` ou `crn` — veja [Changing the template](#changing-the-template). Uma `subnet` nulo não tem referência para copiar: forneça uma válida antes do `PATCH`, ou o local de armazenamento de substituição que o pool não pode usar. ### A imagem é resolvida uma vez `template.image` toma as mesmas três formas que instance create faz — um id, `name:version`, ou um `name` simples. Ao contrário da criação de instância, **a referência é resolvida uma vez, quando o pool é criado (ou quando o modelo é substituído), e o id de imagem resultante é o que todas as réplicas inicializam** — incluindo substituições geradas meses depois. Isso é deliberado. Uma tag re-resolvida por réplica permitiria que um membro curado inicializasse uma compilação mais recente do que seus irmãos, e um pool cujos membros não são idênticos é a premissa da quebra primitiva silenciosa. Para mover um pool para uma nova compilação, altere o modelo e atualize. ### Como são chamadas as réplicas Cada réplica recebe um **número de sequência**, estável enquanto tiver o slot, e é nomeada `-` — `web-asg-0`, `web-asg-1`, e assim por diante. Um substituto assume o número liberado. `GET /v1/instance-pools/{pool_id}/instances` retorna todos os objetos `Instance` em `instances`, mais a paginação `meta`, assim como a lista de instâncias de nível superior. Cada objeto inclui seu estado, endereços, tipo de instância, imagem e função; você não precisa de uma solicitação de instância separada para cada membro. Leia a sequência de réplica de `metadata["basalt:pool:sequence_num"]`. Seu valor é uma string, incluindo `"0"` para o primeiro slot. Filtrar esta lista com `name`, `crn`, `current_state`, `flavor` ou `image`. Ele também aceita `limit` e `marker`. Enquanto `meta.has_more` for true, solicite a próxima página usando `meta.marker` como `marker`, mantendo os mesmos filtros e limites. Colete `instances` de cada página para listar todos os membros correspondentes. Os nomes das instâncias são únicos por conta, então um pool chamado `web` não pode coexistir com uma instância que você já nomeou como `web-0`. Os próprios nomes de pool são de 1 a 127 caracteres de letras, dígitos, ponto, traço e sublinhado, exclusivos por conta. ### Discos e endereços por réplica `template.volumes` cria um disco com cada réplica e o recupera com essa réplica. `delete_on_termination` padrão para `true`; defina-o como `false` e uma réplica escalada, substituída ou desmontada com o pool **libera** seu volume de volta para `available` em vez de destruí-lo. `template.networks[0].floating_ip_assignment` dá a **cada réplica seu próprio** IP flutuante em sua NIC primária, alocado conforme o pool escala para fora e liberado conforme ele escala para dentro. Uma NIC em `template.networks[]` carrega sua própria bandeira, então uma interface secundária pode ser a pública. Cada endereço conta contra sua cota `floating_ips`. Isso é diferente do endereço compartilhado do pool — [veja abaixo](#one-address-for-the-whole-pool). ## Dimensionamento e convergência Todos os três campos de dimensionamento são inteiros mutáveis. Os valores resultantes devem satisfazer `0 ≤ min_count ≤ desired_count ≤ max_count ≤ 100`. Em criar apenas, limites omitidos padrão para `desired_count`. Em `PATCH`, os limites omitidos mantêm seus valores armazenados. Se você omitir `desired_count`, o alvo atual é fixado nos novos limites: elevar o mínimo acima dele eleva o alvo; diminuir o máximo abaixo dele diminui o alvo. Um alvo já dentro dos limites permanece inalterado. Se você enviar explicitamente `desired_count`, ele deve se encaixar nos limites resultantes. O dimensionamento inválido retorna `400` sem aplicar qualquer parte da atualização, incluindo tags ou um modelo enviado com ela. Zero é válido, incluindo ambos os limites em zero. O dimensionamento não substitui o modelo de lançamento nem solicita uma atualização. Esses controles se aplicam a pools gerenciados pelo cliente. Os pools de propriedade de um serviço gerenciado não podem ser redimensionados por meio da API de pool de instâncias; use os controles desse serviço. ### Escala automática Uma política de `autoscaling` ajusta `desired_count` dentro dos limites configurados. A mesma política está disponível em [load balancers](/pt/load-balancers#scaling). Criar ou atualizar uma política não altera o modelo de inicialização. O rastreamento de alvo da CPU requer `min_count` de pelo menos 1. Abra o pool e escolha **Scale**. Defina **Minimum count**, **Maximum count** e **Desired count** e, em seguida, ative **Automatic scaling**. Escolha uma **Metric source** e defina seu alvo; para CPU, use **Target CPU (%)**. Escolha **Scale** para salvar. A guia **Scaling** mostra a política e as decisões recentes de escala. ```http theme={null} PATCH /v1/instance-pools/{pool_id} ``` ```json theme={null} { "min_count": 1, "max_count": 10, "autoscaling": { "enabled": true, "metrics": [ { "source": "cpu", "target_type": "utilization", "target_value": 60 } ] } } ``` ```bash theme={null} basaltic compute instance-pool update "$POOL_ID" \ --min-count 1 --max-count 10 \ --autoscaling '{"enabled":true,"metrics":[{"source":"cpu","target_type":"utilization","target_value":60}]}' ``` ```go theme={null} _, err := compute.New(cfg).UpdateInstancePool(ctx, poolID, &compute.InstancePoolUpdateRequest{ MinCount: basaltic.Int(1), MaxCount: basaltic.Int(10), Autoscaling: &compute.AutoscalingPolicy{ Enabled: true, Metrics: []*compute.ScalingMetric{{ Source: "cpu", TargetType: "utilization", TargetValue: 60, }}, }, }) if err != nil { log.Fatal(err) } ``` O alvo é a utilização da CPU como uma porcentagem das vCPUs alocadas dos membros. Os membros devem estar em execução e passar o período de aquecimento antes que a demanda seja avaliada. O dimensionamento aguarda enquanto a capacidade está convergindo, os membros estão se aposentando ou uma atualização está em andamento. Você também pode escalar a partir de uma métrica que publica para [Telemetria](/pt/telemetry), como a profundidade da fila. O proprietário da política precisa de `telemetry:ReadMetrics`; essa permissão é verificada novamente enquanto a política é executada. Somente as métricas da conta e da região do pool são elegíveis. ```json theme={null} { "min_count": 0, "max_count": 10, "autoscaling": { "enabled": true, "metrics": [{ "source": "telemetry", "name": "queue_depth", "labels": { "queue": "jobs" }, "sample_aggregation": "last", "series_aggregation": "sum", "expected_series": 1, "window_seconds": 120, "max_age_seconds": 90, "target_type": "average_value", "target_value": 100 }] } } ``` Uma profundidade de fila de 750 com uma meta de 100 trabalhos por instância recomenda oito instâncias, antes que limites e limites de etapa sejam aplicados. As amostras são agregadas dentro de cada série primeiro, depois entre séries. `expected_series` deve corresponder ao número de séries selecionadas; uma série ausente impede o dimensionamento. As métricas de contador podem usar `sample_aggregation: "rate"` para contabilizar redefinições antes que as taxas sejam combinadas em todas as séries. Publique um novo zero quando a fila estiver vazia. Dados ausentes, obsoletos ou incompletos nunca significam zero e não podem remover a capacidade. As métricas de demanda personalizadas podem aumentar um pool a partir do zero; as políticas de CPU não podem. Com várias métricas, a maior recomendação de capacidade válida vence. Dados ausentes ainda permitem uma recomendação de escala válida de outra métrica. O aquecimento padrão é de 180 segundos, o tempo de recarga é de 60 segundos e a estabilização de redução é de 300 segundos. Cada decisão adiciona no máximo quatro instâncias ou remove no máximo uma. Estes limites e `drain_seconds` (padrão 120) são configuráveis. O tempo de espera e a estabilização permanecem em vigor durante as reinicializações do serviço. Leia `autoscaling_status.reason` e `autoscaling_status.history` para a condição de espera atual e as mudanças recentes de capacidade. Você ainda pode alterar o tamanho manualmente. A avaliação automática recomeça após o tempo de recarga. Para parar as alterações automáticas, envie a política com `enabled: false`; sua configuração de métrica é mantida quando você a envia de volta. As políticas são substituídas como um todo, portanto, inclua a configuração da métrica ao desabilitar uma. O dimensionamento inicial marca primeiro um membro como aposentado e o retira dos conjuntos de back-end do balanceador de carga e dos IPs flutuantes compartilhados. A exclusão aguarda o reconhecimento da retirada e o período de carência de drenagem. Isso não invoca um gancho de desligamento de aplicativo; trabalhos de longa execução devem tolerar o término da instância. Sessões TCP, UDP e WebSocket de longa duração podem terminar no prazo de drenagem. As alterações à associação de encaminhamento de IP flutuante compartilhado também podem alterar o posicionamento da conexão durante a retirada. ### Ajustando os limites A sequência a seguir começa com um mínimo de 2, desejado 3 e máximo 6. Ele aumenta o alvo para 4, diminui para 2 e, em seguida, escala para zero. Escalar para zero aposenta todos os membros; seus discos seguem `delete_on_termination`. Abra o pool e escolha **Scale** para abrir o **Scale instance pool**. Defina **Minimum count** para 4, mantenha **Maximum count** em 6 e deixe **Desired count** inalterada. Escolha **Scale**; o alvo se torna 4. Reabra **Scale**, defina **Minimum count** para 2 e **Maximum count** para 2, e deixe **Desired count** inalterado; o alvo se torna 2. Para escalar para zero, reabra a caixa de diálogo e defina ambos os limites para 0, novamente deixando **Desired count** inalterada. O console omite um valor desejado inalterado para que a API possa ajustá-lo automaticamente. ```bash theme={null} PATCH /v1/instance-pools/{pool_id} { "min_count": 4 } PATCH /v1/instance-pools/{pool_id} { "min_count": 2, "max_count": 2 } PATCH /v1/instance-pools/{pool_id} { "min_count": 0, "max_count": 0 } ``` ```bash theme={null} basaltic compute instance-pool update --min-count 4 basaltic compute instance-pool update --min-count 2 --max-count 2 basaltic compute instance-pool update --min-count 0 --max-count 0 ``` ```go theme={null} c := compute.New(cfg) pool, err := c.UpdateInstancePool(ctx, poolID, &compute.InstancePoolUpdateRequest{MinCount: basaltic.Int(4)}) if err != nil { return err } pool, err = c.UpdateInstancePool(ctx, poolID, &compute.InstancePoolUpdateRequest{ MinCount: basaltic.Int(2), MaxCount: basaltic.Int(2), }) if err != nil { return err } pool, err = c.UpdateInstancePool(ctx, poolID, &compute.InstancePoolUpdateRequest{ MinCount: basaltic.Int(0), MaxCount: basaltic.Int(0), }) if err != nil { return err } ``` Um ponteiro nil omite um campo; `basaltic.Int(0)` envia um zero explícito. Criar o pool retorna `201` imediatamente. As instâncias são geradas por um reconciliador de fundo, que também é o que converge o pool para `desired_count` sempre que você o altera, então observe o pool ao invés de esperar membros na resposta de criação. Quatro contadores dizem onde está uma pool, e confundir dois deles é a fonte usual de um falso alarme: | Campo de jogo | Pergunta que responde | | - | - | | `desired_count` | Quantos você pediu. | | `member_count` | Quantos a pool tem, em execução ou não. Isto é o que o `status` reflete. | | `live_count` | Quantos são **up** — membros em `current_state: running`. **Este é o número para alertar ou escalar.** | | `stale_instance_count` | Quantos estão em um modelo diferente do atual. | `status: "active"` significa `member_count == desired_count` — o pool contém os membros que foram solicitados. **Não é uma afirmação de que todos eles estão ativos.** Um pool pode estar `active` com `live_count` abaixo de `desired_count` quando os membros pararam. Leia `live_count` para liveness. `scaling` significa que ele não mantém seu alvo e está convergindo: após uma criação, após uma alteração de `desired_count`, e para a duração de uma atualização. `error` significa uma falha de erro ativa — leia cada entrada em `faults` — e ainda está reconciliada: o pool continua sendo re-tentado. `deleting` é um teardown em andamento. Códigos de escala (`POOL_LAUNCH_FAILED`, `POOL_SCALE_OUT_FAILED`, `POOL_SCALE_IN_FAILED`) limpar quando o pool atinge seu alvo. Um redimensionamento posterior não os limpa primeiro: um pool que falhou em gerar e está sendo redimensionado novamente ainda não provou que a falha está por trás dele. | Código | Significado e recuperação | | - | - | | `POOL_LAUNCH_FAILED` | Os membros iniciais não foram lançados. Limpa quando o pool atinge seu alvo. | | `POOL_SCALE_OUT_FAILED` | Scale-out não alcançou `desired_count`. Limpa quando o pool atinge seu alvo. | | `POOL_SCALE_IN_FAILED` | Scale-in não alcançou `desired_count`. Limpa quando o pool atinge seu alvo. | | `POOL_REFRESH_FAILED` | Uma atualização contínua não foi concluída. Tente atualizar novamente. | | `POOL_DELETE_FAILED` | O desmantelamento da pool falhou. Tente novamente a exclusão. | ### O que é substituído e o que não é A cada passagem, o pool substitui qualquer membro cujo `current_state` é `error` ou `deleted`, e qualquer binding cuja instância foi excluída a partir dele. A substituição pega o número de sequência liberado e é lançada a partir do modelo atual do pool. **O pool não verifica a integridade de nada dentro do convidado e não substitui um membro que você parou.** Uma réplica que é `stopped`, ou em execução, mas servindo erros, permanece um membro: `live_count` cai para um parado, e nada muda para uma aplicação encurvada. A substituição é impulsionada pela falha da instância, não pela falha da carga de trabalho. Se você precisar de verificação de integridade no nível do aplicativo, coloque um balanceador de carga na frente. Escalar remove os **números de sequência mais altos primeiro**, então uma escala de 5 a 3 retira `-4` e `-3`. Cada desativação executa a exclusão da instância completa, portanto, sua cota, seus volumes e seus endereços são manipulados exatamente como para uma instância autônoma. As réplicas são distribuídas entre os hosts — melhor esforço. Cada nova réplica evita os hosts que seus irmãos já ocupam, mas quando a frota não tem espaço, o spread é descartado em vez de o lançamento falhar, então as réplicas podem acabar compartilhando um host. ## Alterar o modelo `PATCH /v1/instance-pools/{pool_id}` altera `desired_count`, `min_count`, `max_count`, `autoscaling`, as `tags` do pool, o `template`, ou qualquer combinação. Cada campo é opcional; enviar nenhum deles é um `400` ao invés de um no-op silencioso. A guia **Settings** do pool edita três partes dele: **Tags** no pool e **Instance tags** e **Instance metadata** no modelo de lançamento. **Minimum count**, **Maximum count** e **Desired count** estão em **Scale** no cabeçalho. O resto do modelo é apenas API. Não há controle de console para o tipo de instância do modelo, imagem, volume de inicialização, rede, chaves SSH, função IAM ou dados do usuário - a página do pool mostra esses como detalhes somente leitura, e mudar qualquer um deles é um `PATCH`. Como o `PATCH` substitui o template por completo, salvar qualquer uma das duas placas de template reenvia toda a configuração armazenada: o console converte a sub-rede embutida de cada NIC de volta para seu ID para que nenhuma interface seja descartada. Se a sub-rede de qualquer NIC não for resolvida, ela relata a interface e não envia nada, ao invés de salvar um modelo curto de uma NIC. ```bash theme={null} PATCH /v1/instance-pools/{pool_id} { "desired_count": 4, "template": { "...": "the whole launch config" } } ``` ```bash theme={null} basaltic compute instance-pool update --desired-count 4 ``` ```go theme={null} pool, err := compute.New(cfg).UpdateInstancePool(ctx, poolID, &compute.InstancePoolUpdateRequest{DesiredCount: basaltic.Int(4)}) ``` **Um novo `template` substitui o armazenado em massa.** Qualquer coisa que você deixar de fora é apagada, não mantida — substituição ao invés de uma mesclagem profunda, então um array `networks` ou `volumes` mais curto não pode ser lido como um truncamento e silenciosamente soltar uma interface ou um disco. Envie toda a configuração que você quiser. Ao construir uma substituição a partir de uma resposta de pool, converta o resumo da função em uma referência de cadeia de caracteres: por exemplo, defina `template.iam_role` para o resumo `id` ou `crn`. Não envie o objeto de resumo de volta. Omitir `iam_role` de uma substituição limpa o anexo para lançamentos futuros. Da mesma forma, converta a `subnet` embutida de cada NIC de resposta para sua string `id` ou `crn` na solicitação de substituição — veja [referências e respostas de subnet](#subnet-references-and-responses). Uma sub-rede nula precisa de uma referência de substituição válida; não copie objetos de resposta diretamente para a solicitação. Faça isso para **todas** as entradas de `networks`, não apenas a primária: uma NIC extra descartada porque sua sub-rede não pôde ser convertida é uma interface sem a qual a próxima réplica é iniciada. Uma alteração de modelo decide o que o pool lança **a seguir**. As instâncias já em execução mantêm o que inicializaram, porque uma VM ativa não pode alterar o tipo de instância, a camada, a sub-rede ou suas tags no local. Então, entre a edição e um roll, o pool legitimamente mantém membros de dois modelos diferentes. `stale_instance_count` é quantos estão no mais antigo, e um valor diferente de zero é o sinal de que uma alteração de modelo ainda não foi implementada. Esta é a mesma divisão entre "editar o modelo" e "substituir as instâncias" que um `PATCH` silenciosamente substituindo cada membro em execução apagaria - uma operação destrutiva usando a forma de uma edição. ### Rolando a pool 1. Abra **Instance pools** e selecione seu pool. 2. Escolha **Roll instances** ao lado de **Scale**. 3. Confirme a substituição de cada membro em execução em um modelo mais antigo ou desconhecido. Os membros no modelo atual são mantidos. Sem espaço de aumento, o rolo espera; use **Scale** para aumentar **Maximum count** acima de **Desired count** (até 100). 4. Assista **Roll in progress** e **Stale instances**. Uma contagem de zero não significa que o rolo terminou enquanto o **Roll in progress** permanece. **Refresh** recarrega os dados da página. Ele não rola instâncias. ```bash theme={null} POST /v1/instance-pools/{pool_id}/refresh ``` ```bash theme={null} basaltic compute instance-pool refresh ``` ```go theme={null} pool, err := compute.New(cfg).RefreshInstancePool(ctx, poolID) ``` Ele responde `202` com o pool como ele está, e substitui todos os membros não lançados a partir do modelo atual — incluindo qualquer um que precede o rastreamento de modelo. Assincronizado, e deliberadamente: cada substituição é uma inicialização de VM, e uma solicitação que esperava expiraria muito antes que um pool de qualquer tamanho terminasse. O conciliador aposenta um membro obsoleto de cada vez, o mais antigo primeiro, para que o rolo passe pelo pool em uma ordem previsível. A próxima aposentadoria aguarda até que o pool esteja acima do tamanho desejado com todos os membros em execução. Um template que não inicializa, portanto, **paraliza o roll com o pool intacto**, em vez de executá-lo uma instância de cada vez. Com headroom, o pool lança uma instância sobre seu alvo, então uma substituição já está sendo usada antes que qualquer coisa seja aposentada. `desired_count` não é tocado — o surto é derivado, não escrito no que você pediu. Quando `max_count == desired_count`, uma atualização aguarda em vez de aposentar um membro obsoleto abaixo da capacidade desejada. Isso também se aplica se uma atualização de limites remover espaço durante um lançamento. O dimensionamento e a recuperação normais continuam; a redução desejada ainda pode aposentar membros como parte do dimensionamento. Aumentar `max_count` acima `desired_count` Por exemplo, com desejado 3 e máximo 3, atualize máximo para 4 e deixe desejado inalterado usando o comando: [os controles de dimensionamento](#adjusting-the-bounds)No limite máximo da plataforma de 100, a adição de espaço livre requer a redução do desejado primeiro, o que reduz a capacidade solicitada. Observe `refresh_in_progress` e `stale_instance_count` para o progresso do rolo, e `member_count` e `live_count` para a capacidade. Uma contagem zero significa apenas que nenhum membro usa um modelo antigo. Depois que o sinalizador de atualização for limpo, o pool ainda poderá precisar remover seu membro de pico e convergir para o desejado. Espere até que o flag seja false, `status: "active"`, e ambas as contagens sejam iguais antes de tratar a capacidade como resolvida. Perguntar novamente enquanto um rolo está em execução é aceito e não o reinicia. ### Dois conjuntos de tags Um pool carrega dois mapas de tags e eles respondem a perguntas diferentes. Rótulos do **recurso de pool**. Lido pelas condições do IAM como `basalt:ResourceTag/` e usado para atribuição de custo. Tem efeito imediatamente, não toca em nenhuma instância e substitui todo o conjunto — um objeto vazio os limpa, um campo omitido os deixa sozinhos. Carimbado em **cada réplica que a pool lança**. Parte da configuração de lançamento, então alterá-lo afeta apenas lançamentos futuros e precisa de uma atualização para alcançar o que já está em execução. Editar `template.tags` sozinho é a maneira mais fácil de acabar com um pool cujos membros carregam dois conjuntos de tags diferentes — o que importa se uma política do IAM ou um relatório de custos tiverem chaves neles. `stale_instance_count` é quantos ainda estão no conjunto antigo. ## Um endereço para toda a pool `POST /v1/instance-pools/{pool_id}/floating-ips` vincula um IP flutuante que você já alocou ao pool. Um IP público, respondido por cada réplica — um endereço anycast — ao contrário de `template.networks[0].floating_ip_assignment`, que dá a cada réplica o seu próprio. A guia **Floating IPs** do pool lista seus endereços compartilhados e oferece **Attach floating IP**, que seleciona entre os endereços que você mantém que não estão anexados a nada. **One address, every replica** explica a adesão e a prontidão. As colunas **Members**, **Healthy**, **Unhealthy** e **Unknown health** distinguem a associação da elegibilidade de tráfego. Um pool vazio mantém a propriedade de seus endereços compartilhados. ```bash theme={null} POST /v1/instance-pools/{pool_id}/floating-ips { "floating_ip": "3f9a1c7e-5b2d-4e8a-9c1f-6d3b7a2e5c9f" } ``` ```bash theme={null} basaltic compute instance-pool attach-floating-ip --floating-ip basaltic compute instance-pool detach-floating-ip ``` ```go theme={null} c := compute.New(cfg) fip, err := c.AttachInstancePoolFloatingIP(ctx, poolID, &compute.InstancePoolFloatingIPAttachRequest{FloatingIP: floatingIPID}) err = c.DetachInstancePoolFloatingIP(ctx, poolID, floatingIPID) ``` O IP flutuante `attached_to` nomeia o CRN canônico do pool, mesmo quando `members` está vazio. Todas as réplicas ativas podem se tornar membros, incluindo réplicas no mesmo host. Leia a interface embutida e os resumos de instância em `members` para identificá-los; veja [Reading the bindings](/pt/networking/floating-ips#reading-the-bindings). A associação é mantida para você: um membro de escala de saída se junta, um membro de escala de entrada sai, um membro substituído é trocado. Não há nenhuma conexão por réplica a ser feita, e as próprias conexões e desconexões do serviço de rede são recusadas no endereço de um pool. ### Não é um balanceador de carga Com mais de um membro, a borda da região escolhe **um membro por conexão**, fazendo hash dos endereços e portas do fluxo, e cada pacote dessa conexão vai para o mesmo. Isso espalha conexões entre instâncias independentes e sobrevive à perda de um host. Sem `health_check` configurado no IP flutuante, a saúde indica se o sistema da instância está ativo, não a prontidão da aplicação. Os membros que ainda estão inicializando permanecem na lista sem integridade e não recebem tráfego até serem admitidos; as imagens que nunca entram em contato com o serviço de metadados da instância são admitidas após alguns minutos. Configure uma verificação de prontidão se o tráfego precisar esperar pelo seu aplicativo. Membros não saudáveis não recebem tráfego, e se todos falharem o endereço deixa de encaminhar tráfego. As conexões em andamento para um membro que se afasta terminam. Não há terminação TLS, roteamento de solicitação ou maneira de ponderar membros. ### Requisitos e remoção O IP flutuante deve ser **unattached** (`attached_to: null`) e seu, e a sub-rede do pool já deve rotear `0.0.0.0/0` para um gateway de internet. A anexação é idempotente: re-anexar o mesmo endereço ao mesmo pool retorna-o inalterado. Um `409` significa que o endereço já está ligado a algo, ou já pertence a outro pool. `DELETE /v1/instance-pools/{pool_id}/floating-ips/{floating_ip_id}` interrompe o roteamento do endereço para o pool. No console, é a ação de linha na guia **Floating IPs**, confirmada como **Detach floating IP**. **O endereço não é liberado.** Você alocou-o, ele permanece seu e não anexado, para reutilizar ou liberar com `DELETE /v1/floating-ips/{floating_ip_id}`. Separando um o pool não contém respostas `204`. `GET /v1/instance-pools/{pool_id}/floating-ips` lista os endereços compartilhados com seus membros atuais em `floating_ips`, mais paginação `meta`, usando a mesma forma de resposta que a lista de IP flutuante de nível superior. Ele aceita `name`, `crn`, `limit` e `marker`. IPs flutuantes não têm nome, então fornecer `name` retorna uma lista vazia. Enquanto `meta.has_more` for true, passe `meta.marker` como `marker` na próxima solicitação, preservando os filtros e limites, e colete `floating_ips` de cada página. Os endereços por réplica não estão aqui — eles pertencem à réplica e são lidos da [lista de NICs](/pt/compute/attachments#network-interfaces) da instância. ## Excluir um pool **Delete pool** está na guia **Settings** do pool, na zona de perigo. A confirmação reafirma o custo — *termina todas as VMs no pool* — e precisa que o nome do pool seja digitado novamente. ```bash theme={null} DELETE /v1/instance-pools/{pool_id} ``` ```bash theme={null} basaltic compute instance-pool delete ``` ```go theme={null} err := compute.New(cfg).DeleteInstancePool(ctx, poolID) ``` Ele derruba todas as instâncias que o pool possui e deixa o pool cair. É idempotente, e responde `204`. Excluir o pool é a única maneira de remover seus membros: excluir uma réplica diretamente apenas libera seu número de sequência e o pool gera uma substituição para ela na próxima passagem. ## Permissões Toda operação de pool autoriza contra `crn:compute:::instance-pool/` — esse é o valor que uma declaração de política do IAM deve nomear para escopo de uma permissão para um pool. Uma atualização autoriza como **`compute:UpdateInstancePool`**, a mesma ação que um `PATCH`, não como uma ação própria. Conceder a alguém a capacidade de editar um pool, portanto, também lhe concede a capacidade de rolá-lo, o que substitui todos os membros em execução. As réplicas são iniciadas como o principal que criou o pool, de modo que a permissão `compute:CreateInstance` do principal — e sua `iam:PassRole` em `template.iam_role`, se o template tiver uma — é a que cada recuperação e escalabilidade posterior é executada. Veja [policies](/pt/iam/policies) e [roles](/pt/iam/roles). ## Solução de problemas `active` significa `member_count == desired_count`, não que os membros estão ativos. Leia o `live_count`. Uma lacuna entre eles são membros que existem e não estão em execução — parados, ainda em inicialização ou em cunho — e o pool não substitui um membro parado. Primeiro compare `max_count` com `desired_count`. Se não houver capacidade livre para novas réplicas, aumente o máximo acima do desejado (até 100). A atualização permanece solicitada e retoma sem outra chamada de atualização. As alterações de limites durante uma atualização podem colocá-lo nesse estado de espera; o dimensionamento normal continua. Com espaço, o rolo espera por uma substituição acima do desejado com **cada** membro em execução antes de aposentar o próximo. Se o novo modelo não inicializar, o roll para lá por design ao invés de esvaziar o pool — verifique as `faults` da réplica mais recente e sua [saída do console](/pt/compute/console). `stale_instance_count` pára de cair assim que isso acontece, e `refresh_in_progress` permanece verdadeiro. Esperado. Ao construir uma substituição a partir de uma resposta de pool, converta o resumo da função em uma referência de cadeia de caracteres: por exemplo, defina `template.iam_role` para o resumo `id` ou `crn`. Não envie o objeto de resumo de volta. Omitir `iam_role` de uma substituição limpa o anexo para lançamentos futuros. Uma alteração de modelo decide o que o pool iniciará em seguida; as instâncias já em execução mantêm o que inicializaram. `stale_instance_count` conta-os, e `POST /v1/instance-pools/{pool_id}/refresh` os atualiza. `template` em um `PATCH` Leia o pool de volta e crie a solicitação de substituição completa, convertendo o resumo da função em uma referência de string, como descrito em [Alterar o modelo](#changing-the-template). Compare as réplicas ativas do pool com os resumos de membros incorporados do endereço. A associação converge à medida que as réplicas são colocadas e removidas; os membros podem compartilhar um host. Verifique a `health` e a `reason` de cada membro separadamente: os membros que estão inicializando ou falhando permanecem listados, mas não recebem tráfego. Uma lista de membros vazia não limpa a propriedade `attached_to` do pool. Três causas, e a mensagem diz qual: o id está ausente ou mal formado; a sub-rede do pool não tem rota padrão para um gateway de internet; ou a região não tem endereços de pool compartilhados ativados. Um `409` é diferente — que é um endereço já anexado a outra coisa, ou já detido por outro pool. O pool converge para `desired_count`, então a exclusão de um membro é lida como deriva e reabastecida no número de sequência liberado. Diminua o `desired_count`, ou exclua o pool. Use números inteiros com `0 ≤ min_count ≤ max_count ≤ 100`. Um `desired_count` explícito deve estar dentro desses limites. Na criação, os limites omitidos são padrão para o desejado; na atualização, eles preservam os limites armazenados. Omita o desejado na atualização para fixá-lo automaticamente. O dimensionamento inválido não aplica nenhuma atualização. Para crescer além do máximo original, aumente `max_count` antes ou junto com desired.