> ## 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.
# Criar um balanceador de carga
Requer a ação do IAM **`loadbalancer:CreateLoadBalancer`**. Consulte [permissões de balanceadores de carga](/loadbalancer/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política.
## OpenAPI
````yaml /pt/api-reference/specs/loadbalancer.yaml post /v1/load-balancers
openapi: 3.0.3
info:
title: API do Basaltic Load Balancer
version: 1.0.0
description: >
Relações de solicitação aceitam referências classificadas por sintaxe
resolvidas dentro da conta e região do chamador. Referências IP flutuantes
aceitam somente UUID ou CRN; os alvos IP permanecem literais. Balanceadores
de carga gerenciados: ouvintes, pools de destino, verificações de
integridade e os certificados TLS que um ouvinte encerra.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://loadbalancer.{region}.basaltic.sh
description: Endpoint de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de região
security:
- BearerAuth: []
paths:
/v1/load-balancers:
post:
tags:
- Load Balancers
summary: Criar um balanceador de carga
operationId: createLoadBalancer
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLoadBalancerRequest'
responses:
'201':
description: Criado
content:
application/json:
schema:
$ref: '#/components/schemas/LoadBalancerResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
description: >-
Chave opcional gerada pelo cliente que torna uma criação segura para
reprodução. A reintentar uma solicitação com a mesma chave retorna o
resultado original literalmente em vez de criar um recurso duplicado. A
reutilização de uma chave com um corpo de solicitação diferente é
rejeitada (422); uma solicitação cuja chave ainda está sendo processada
retorna 409. Os registros são honrados por 24 horas. Use um UUID ou
token exclusivo semelhante.
required: false
schema:
type: string
maxLength: 255
example: 550e8400-e29b-41d4-a716-446655440000
schemas:
CreateLoadBalancerRequest:
additionalProperties: false
description: >-
Relações aceitam um UUID, CRN ou nome imutável exato, classificado por
sintaxe. Os grupos de VPC, sub-rede e segurança devem pertencer à conta
do chamador nesta região. Os nomes de sub-rede são escopo pelo vpc.
Flavor é uma referência de catálogo regional. Referências IP flutuantes
aceitam somente UUID ou CRN. Todas as referências são resolvidas antes
de gravar. Os endereços são fixos na criação; atualizações não podem
substituí-los.
type: object
required:
- name
- type
- vpc
- subnet
- flavor
- security_groups
properties:
desired_count:
type: integer
minimum: 1
maximum: 10
description: Alvo estável dentro de min_count e max_count.
example: 2
min_count:
type: integer
minimum: 1
maximum: 10
description: Capacidade mais baixa vinculada.
example: 1
max_count:
type: integer
minimum: 1
maximum: 10
description: Capacidade superior limitada, incluindo aumento de lançamento.
example: 5
autoscaling:
$ref: '#/components/schemas/AutoscalingPolicy'
name:
type: string
description: >-
1..127 caracteres de [A-Za-z0-9._-] Os nomes de recursos não devem
começar com o prefixo literal crn: ou ser UUIDs (formas canônicas,
compactas, entre colchetes ou urn:uuid:, em qualquer caso).
example: web-lb
type:
type: string
enum:
- application
- network
example: application
vpc:
type: string
description: VPC o LB vai viver. Deve corresponder à VPC da sub-rede.
example: c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9
subnet:
type: string
description: >-
Sub-rede às quais as instâncias de LB se conectam. O IP virtual é
alocado a partir desta sub-rede.
example: d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0
flavor:
type: string
description: Calcule o tipo de instância para cada instância de LB.
example: e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1
replica_count:
deprecated: true
type: integer
minimum: 1
maximum: 10
default: 1
description: >-
Alias de entrada obsoleto de desired_count; envie apenas um. O
padrão desejado é 1. Os limites omitidos são padrão para o desejado.
example: 2
floating_ip:
type: string
deprecated: true
description: >-
Public IPv4 abreviatura. Não pode ser combinado com floating_ips.
Não aloca IPv6 público.
example: f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2
floating_ips:
type: array
maxItems: 4
uniqueItems: true
description: >-
IPs flutuantes livres existentes desta conta e região, no máximo um
por família e visibilidade (privado/público, IPv4/IPv6). Os
endereços privados devem pertencer à sub-rede selecionada. As
famílias privadas ausentes são alocadas automaticamente para cada
família ativada nessa sub-rede. Os endereços públicos são opcionais
e exigem uma rota padrão de família correspondente para um gateway
da Internet; gateways NAT e somente de saída não se qualificam. O
IPv6 requer uma sub-rede habilitada para IPv6. Endereços de
propriedade ou anexados ao pool não estão disponíveis. Na exclusão,
os endereços fornecidos são separados e retidos; as alocações
privadas automáticas são liberadas. Não pode ser combinado com
floating_ip.
items:
type: string
example:
- f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2
security_groups:
type: array
description: >-
Grupos de segurança anexados a cada NIC de réplica (forma ALB da
AWS). Uma placa de rede VPC sem grupo de segurança nega todo o
tráfego de dados, portanto, as portas de ouvinte devem ser abertas
por um grupo de segurança listado aqui. Reaplicado a réplicas de
substituição. O caminho do plano de controle do LB (configuração do
agente + heartbeat através do ponto de extremidade de metadados) é
sempre permitido e não precisa de nenhum.
items:
type: string
example:
- d1b6f3a8-4c2e-4a9d-8f7b-1e5c3a2d9b4f
tags:
$ref: '#/components/schemas/Tags'
LoadBalancerResponse:
type: object
properties:
load_balancer:
$ref: '#/components/schemas/LoadBalancer'
AutoscalingPolicy:
type: object
additionalProperties: false
required:
- enabled
- metrics
description: >
Rastreamento de destino compartilhado por pools de instâncias e
balanceadores de carga. As atualizações substituem a política. Defina
enabled=false para manter as configurações e usar o dimensionamento
manual. Cada métrica recomenda uma contagem desejada; a maior
recomendação vence. Observações ausentes, obsoletas ou incompletas
impedem o dimensionamento, mas não bloqueiam o dimensionamento
recomendado por outra métrica válida. As decisões obedecem aos recursos
min_count/max_count, warmup, cooldown, estabilização, limites de passo e
cotas. O estado sobrevive às reinicializações do controlador. As
políticas ativas possuem desired_count; as alterações manuais são
aceitas e a avaliação automática é retomada após o tempo de espera. A
telemetria personalizada requer telemetria:ReadMetrics na mesma conta.
properties:
enabled:
type: boolean
example: true
metrics:
type: array
minItems: 1
maxItems: 5
items:
$ref: '#/components/schemas/ScalingMetric'
warmup_seconds:
type: integer
minimum: 30
maximum: 3600
default: 180
cooldown_seconds:
type: integer
minimum: 30
maximum: 3600
default: 60
scale_down_stabilization_seconds:
type: integer
minimum: 60
maximum: 3600
default: 300
max_scale_out_step:
type: integer
minimum: 1
maximum: 100
default: 4
max_scale_in_step:
type: integer
minimum: 1
maximum: 100
default: 1
drain_seconds:
type: integer
minimum: 30
maximum: 3600
default: 120
description: >-
Período de carência após a retirada de rota e confirmações de proxy,
antes de excluir um membro aposentado. Sessões TCP/UDP de longa
duração podem terminar no prazo; ganchos de desligamento de
aplicativos arbitrários não são suportados.
Tags:
type: object
additionalProperties:
type: string
example:
environment: production
team: backend
LoadBalancer:
type: object
required:
- id
- crn
- account_id
- name
- type
- status
- faults
- subnet
- flavor_id
- replica_count
- desired_count
- min_count
- max_count
- floating_ips
- tags
- created_at
- updated_at
properties:
rollout_surge:
type: boolean
readOnly: true
description: >-
Capacidade extra temporária dentro de max_count; não altera
desired_count.
desired_count:
type: integer
minimum: 1
maximum: 10
description: Alvo estável dentro de min_count e max_count.
example: 2
min_count:
type: integer
minimum: 1
maximum: 10
description: Capacidade mais baixa vinculada.
example: 1
max_count:
type: integer
minimum: 1
maximum: 10
description: Capacidade superior limitada, incluindo aumento de lançamento.
example: 5
autoscaling:
$ref: '#/components/schemas/AutoscalingPolicy'
autoscaling_status:
$ref: '#/components/schemas/AutoscalingStatus'
id:
type: string
format: uuid
example: 4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c
crn:
type: string
description: CRN de recurso do IAM
example: crn:loadbalancer:sa-saopaulo-1:my-account:load-balancer/web-lb
account_id:
type: string
format: uuid
example: 6f9619ff-8b86-4d01-b42d-00cf4fc964ff
name:
description: >-
Os nomes de recursos não devem começar com o prefixo literal crn: ou
ser UUIDs (formas canônicas, compactas, entre colchetes ou
urn:uuid:, em qualquer caso).
type: string
example: web-lb
type:
type: string
enum:
- application
- network
description: Forma ALB (L7) vs forma NLB (L4)
example: application
status:
type: string
enum:
- provisioning
- active
- error
- deleting
example: active
faults:
type: array
description: >-
Falhas ativas; status é erro exatamente quando uma falha de erro
ativo permanece.
items:
$ref: '#/components/schemas/Fault'
example: []
subnet:
anyOf:
- $ref: '#/components/schemas/Subnet'
- type: object
nullable: true
enum:
- null
description: >-
Posicionamento de sub-rede; nulo quando a sub-rede referenciada não
existe mais.
flavor_id:
type: string
format: uuid
description: >-
Compute flavor em que cada instância de LB é executada. Deve ser um
loadbalancer-family flavor.
example: e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1
replica_count:
deprecated: true
type: integer
minimum: 1
maximum: 10
description: Alias obsoleto de desired_count.
example: 2
internal_ipv4:
type: string
description: >-
IP virtual para o balanceador de carga; o tráfego é distribuído para
backends por conexão.
example: 203.0.113.50
internal_ipv6:
type: string
description: VIP IPv6 interno (definido quando a sub-rede é de pilha dupla).
example: 2001:db8::32
public_ipv6:
type: string
description: >-
IP flutuante IPv6 público selecionado explicitamente, traduzido para
endereços IPv6 de réplica em uma sub-rede GUA ou ULA.
example: 2a13:9500:1a6:101::a
floating_ip_id:
type: string
format: uuid
description: IP flutuante IPv4 público opcional. O IPv6 público é independente.
example: f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2
floating_ips:
type: array
description: >-
Todos os IPs flutuantes públicos e privados anexados, incluindo
alocações privadas automáticas.
items:
$ref: '#/components/schemas/FloatingIp'
dns_name:
type: string
example: web-lb.my-account.lb.sa-saopaulo-1.basaltic.sh
description: >-
Nome de host de conveniência publicado automaticamente para o
balanceador de carga,
`{name}.{account-handle}.lb.{region}.{base-domain}`. Resolve para o
IP flutuante em um LB voltado para a Internet e para o VIP privado
de outra forma. Omitidos em regiões onde o DNS automático não está
configurado — o VIP e o FIP permanecem autoritativos de qualquer
maneira.
tags:
$ref: '#/components/schemas/Tags'
created_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
updated_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Código de erro identificando o tipo de erro
example: INVALID_INPUT
message:
type: string
description: Mensagem de erro legível pelo ser humano
example: Invalid request parameters
params:
type: object
additionalProperties: true
description: >-
Valores não sensíveis opcionais para interpolação de erros
localizados, codificados por código de erro. Nunca presente para
erros de servidor.
example:
instances: 2
pools: 0
request_id:
type: string
format: uuid
description: Solicitar ID para depuração
example: 550e8400-e29b-41d4-a716-446655440000
ScalingMetric:
type: object
additionalProperties: false
required:
- source
- target_type
- target_value
description: >
CPU usa source=cpu, target\_type=utilization e um alvo de porcentagem
\<=100. Utilização é o número de segundos de CPU por segundo dividido
pelas vCPUs alocadas em todos os membros prontos. O dimensionamento de
CPU habilitado requer min\_count\>=1.
A demanda personalizada usa source=telemetry e
target_type=average_value. O nome e os rótulos da métrica selecionam
séries na conta, organização e região do recurso. A agregação temporal é
aplicada dentro de cada série antes de combinar séries; amostras de
medidores repetidas nunca são somadas como demanda extra. A contagem
desejada é ceil(combined value / target_value): 750 trabalhos pendentes
com uma meta de 100 por instância recomenda 8. A demanda personalizada
pode escalar um grupo de clientes a partir de 0. Os produtores devem
publicar zeros novos para filas ociosas; dados ausentes não são zero.
properties:
source:
type: string
enum:
- cpu
- telemetry
example: telemetry
target_type:
type: string
enum:
- utilization
- average_value
example: average_value
target_value:
type: number
minimum: 0
exclusiveMinimum: true
example: 100
name:
type: string
pattern: ^[a-zA-Z_:][a-zA-Z0-9_:]{0,199}$
example: queue_depth
labels:
type: object
maxProperties: 10
additionalProperties:
type: string
maxLength: 256
description: >-
Rótulos de correspondência exata; rótulos de locação e __name__ não
podem ser fornecidos.
example:
queue: orders
sample_aggregation:
type: string
enum:
- last
- avg
- max
- rate
default: last
description: >-
Use last para medidores de fila; rate para contadores que aumentam
monotonicamente, com manipulação de reset.
series_aggregation:
type: string
enum:
- sum
- avg
- max
default: sum
expected_series:
type: integer
minimum: 1
maximum: 1000
default: 1
description: >-
Cardinalidade exata esperada; seletores incompletos ou ambíguos não
estão disponíveis.
window_seconds:
type: integer
minimum: 30
maximum: 3600
default: 120
max_age_seconds:
type: integer
minimum: 30
maximum: 3600
default: 90
description: >-
Idade real da observação mais recente por série; não deve exceder
window_seconds. O padrão é o menor de 90 e a janela.
AutoscalingStatus:
type: object
readOnly: true
required:
- status
- reason
- history
properties:
status:
type: string
enum:
- pending
- disabled
- stable
- scaling
- waiting
- warming_up
- metrics_unavailable
- stabilizing
- cooldown
- draining
reason:
type: string
example: waiting for sustained lower demand
evaluated_at:
type: string
format: date-time
last_scaled_at:
type: string
format: date-time
history:
type: array
maxItems: 50
items:
type: object
required:
- at
- from
- to
- reason
properties:
at:
type: string
format: date-time
from:
type: integer
minimum: 0
to:
type: integer
minimum: 0
reason:
type: string
Fault:
type: object
required:
- code
- severity
- message
- details
- first_at
- last_at
- occurrences
properties:
code:
type: string
description: >-
Código estável legível por máquina pertencente à operação de
relatório.
example: BACKUP_FAILED
severity:
type: string
enum:
- error
- warning
message:
type: string
example: Backup upload failed.
details:
type: object
nullable: true
additionalProperties: true
description: >-
Contexto estruturado; cadeias de caracteres legadas são preservadas
em legacy_text.
first_at:
type: string
format: date-time
description: Primeira observação nesta série de ocorrências ativas.
last_at:
type: string
format: date-time
description: Última observação nesta série de ocorrências ativas.
occurrences:
type: integer
minimum: 1
example: 1
Subnet:
type: object
required:
- id
- crn
- vpc
- route_table
- name
- cidr_ipv4
- gateway_ipv4
- tags
- created_at
- updated_at
properties:
id:
type: string
format: uuid
readOnly: true
crn:
type: string
readOnly: true
example: crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/prod-web
vpc:
$ref: '#/components/schemas/Vpc'
route_table:
$ref: '#/components/schemas/RouteTableSummary'
name:
description: >-
Os nomes de recursos não devem começar com o prefixo literal crn: ou
ser UUIDs (formas canônicas, compactas, entre colchetes ou
urn:uuid:, em qualquer caso).
type: string
example: prod-web
description:
type: string
example: Public web-tier subnet
cidr_ipv4:
type: string
example: 10.0.1.0/24
gateway_ipv4:
type: string
example: 10.0.1.1
cidr_ipv6:
type: string
nullable: true
readOnly: true
description: >-
O IPv6 /64 de pilha dupla, se a sub-rede estiver habilitada para v6.
Sua presença (vs o v4 cidr_ipv4) é como um cliente diz as famílias
da sub-rede separadas.
example: 2a13:9500:1a6:100::/64
gateway_ipv6:
type: string
nullable: true
readOnly: true
example: 2a13:9500:1a6:100::1
tags:
type: object
additionalProperties:
type: string
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
FloatingIp:
type: object
required:
- id
- crn
- address
- family
- attached_to
- members
- tags
- created_at
- updated_at
- visibility
properties:
id:
type: string
format: uuid
readOnly: true
crn:
type: string
readOnly: true
example: crn:network:sa-saopaulo-1:my-account:floating-ip/
description:
type: string
example: Public IP for the web load balancer
family:
$ref: '#/components/schemas/IpFamily'
attached_to:
type: string
nullable: true
readOnly: true
description: >
CRN canônico da interface vinculada, pool de instâncias ou
balanceador de carga; nulo quando não conectado. Um endereço de
propriedade do pool nomeia seu pool mesmo quando o pool tem zero
membros. Somente endereços de propriedade do pool podem ter vários
membros de NIC. Gerencie suas ligações através dos endpoints IP
flutuantes do pool de instâncias; a conexão e o desconexão diretos
são recusados.
example: >-
crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/public/interface/eth0
members:
type: array
description: >
Os bindings do IP flutuante. Um IP flutuante faz frente a 0 membros
(alocados, não anexados), 1 membro (o caso comum) ou N membros para
um pool de instâncias — um IP flutuante anycast, onde um IP público
é entregue a N NICs de VM em hosts (cada um anunciado como um /32 do
host que o mantém).
Os membros podem compartilhar um hypervisor. Dois deles em um host
costumava significar que um era servido e o outro silenciosamente
obscuro; a regra de encaminhamento de um membro agora nomeia o
membro, e o host divide conexões entre os membros que ele possui,
então onde os membros ficam é uma decisão de capacidade em vez de
uma decisão de correção. O endereço de um pool de instâncias obtém
seus membros das réplicas ativas do pool — cada uma delas — para que
uma escalabilidade externa se junte e uma escalabilidade interna
saia sem um anexo por réplica.
Com mais de um membro UM membro serve cada conexão, escolhida por
hash dos endereços e portas do fluxo, e cada pacote dessa conexão
vai para o mesmo. Os membros são instâncias separadas que não
compartilham nada, então isso espalha conexões e sobrevive à perda
de um host — não é um balanceador de carga: nada verifica se o
serviço dentro da instância está ativo, e as conexões em andamento
para um membro que sai não são movidas, elas terminam.
O endereço de um POOL é a exceção, e somente para inicialização. Uma
réplica se junta ao endereço assim que é colocada, mas não recebe
tráfego até que tenha alcançado o serviço de metadados da instância
— evidência de que o convidado inicializou, e não de que sua máquina
virtual foi iniciada. Até então é um membro com `health`
`unhealthy`. Uma réplica cuja imagem nunca entra em contato com o
serviço de metadados é admitida de qualquer maneira após alguns
minutos, então uma imagem incomum atrasa o tráfego em vez de nunca
obtê-lo.
items:
$ref: '#/components/schemas/FloatingIpMember'
tags:
type: object
additionalProperties:
type: string
health_check:
allOf:
- $ref: '#/components/schemas/FloatingIpHealthCheck'
description: >
A verificação de prontidão aplicada aos membros deste endereço.
Ausente quando nenhum está configurado. Consulte
`FloatingIpHealthCheck`.
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
address:
type: string
description: Endereço público ou privado alocado.
example: 212.66.52.71
visibility:
type: string
enum:
- public
- private
subnet_id:
type: string
format: uuid
nullable: true
description: Sub-rede de alocação para IPs flutuantes privados.
vpc_id:
type: string
format: uuid
description: Alocação VPC para IPs flutuantes privados.
Vpc:
type: object
required:
- id
- crn
- name
- cidr_ipv4
- tags
- created_at
- updated_at
properties:
id:
type: string
format: uuid
readOnly: true
crn:
type: string
readOnly: true
description: Nome do recurso da nuvem (baseado em nome, região+escopo de conta).
example: crn:network:sa-saopaulo-1:my-account:vpc/prod
name:
type: string
description: >-
1-63 caracteres, minúsculo alfanumérico + hífen Os nomes de recursos
não devem começar com o prefixo literal crn: ou ser UUIDs (formas
canônicas, compactas, entre colchetes ou urn:uuid:, em qualquer
caso).
example: prod
description:
type: string
example: Production VPC for web and app tiers
cidr_ipv4:
type: string
description: >-
Bloco IPv4 CIDR dividido por sub-redes. Deve ser privado (RFC 1918):
dentro de 10.0.0.0/8, 172.16.0.0/12 ou 192.168.0.0/16. Imutável após
criar.
example: 10.0.0.0/16
cidr_ipv6:
type: string
nullable: true
readOnly: true
description: GUA regional associado ou prefixo ULA privado.
example: 2a13:9500:1a6:100::/60
tags:
type: object
additionalProperties:
type: string
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
RouteTableSummary:
type: object
nullable: true
additionalProperties: false
description: >
Tabela de rotas usada por uma sub-rede, sem repetir sua VPC. Nulo quando
a pesquisa não proprietária não é mais resolvida, por exemplo, durante a
reassociação e exclusão simultâneas da tabela anterior. A exclusão de
uma tabela ainda associada a sub-redes é recusada.
required:
- id
- crn
- name
properties:
id:
type: string
format: uuid
readOnly: true
crn:
type: string
readOnly: true
example: >-
crn:network:sa-saopaulo-1:my-account:vpc/prod/route-table/prod-private-rt
name:
type: string
example: prod-private-rt
IpFamily:
type: string
enum:
- ipv4
- ipv6
description: >
A família de endereços IP. Os IPs flutuantes suportam qualquer família e
podem ter visibilidade pública ou privada. Os IPs flutuantes públicos
alocam do pool de endereços públicos da região; os IPs flutuantes
privados alocam do intervalo de sub-rede selecionado para essa família.
A anexação de um IP flutuante a uma interface requer um endereço da
mesma família nessa interface. O IPv6 não requer que o IPv4 seja ativado
na sub-rede. A acessibilidade à Internet também depende de rotas e
regras de segurança.
A anexação de um IP flutuante IPv6 não desabilita o endereço IPv6
roteável globalmente nativo da interface. Ambos os endereços permanecem
acessíveis quando as regras de roteamento e segurança permitirem, e as
respostas a conexões de entrada retêm o endereço que recebeu a conexão.
Um endereço IPv6 privado não se torna diretamente roteável pela internet
ao anexar um IP flutuante.
example: ipv6
FloatingIpMember:
type: object
description: Uma ligação de um IP flutuante.
required:
- interface
- health
- reason
- created_at
properties:
interface:
type: object
nullable: true
description: >-
Resumo de NIC vinculada; nulo para uma vinculação de balanceador de
carga nomeada por attached_to.
required:
- id
- crn
- instance
properties:
id:
type: string
format: uuid
crn:
type: string
example: >-
crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/public/interface/eth0
instance:
type: object
nullable: true
description: >-
Instância proprietária; nulo quando a interface não tem
instância proprietária.
required:
- id
- crn
- name
properties:
id:
type: string
format: uuid
crn:
type: string
example: crn:compute:sa-saopaulo-1:my-account:instance/web
name:
type: string
health:
type: string
enum:
- unknown
- healthy
- unhealthy
description: >
O que a plataforma sabe sobre este membro.
`unknown` — não há verificação em execução. Esse é o estado de um
membro anexado manualmente a um endereço sem verificação de
integridade: você escolheu quando anexá-lo, e a plataforma não
recebe sinais sobre o que está em execução na instância. O membro
continua anunciado.
`healthy` — a plataforma tem evidências de que o membro está ativo
e, se houver uma verificação de integridade configurada no endereço,
de que ela está passando.
`unhealthy` — a plataforma ainda não recebeu essa confirmação ou uma
verificação configurada está falhando. O membro permanece associado
ao endereço, mas não recebe tráfego até se recuperar.
Sem uma verificação de integridade, `healthy` confirma apenas que o
sistema da instância está ativo, não que o serviço esteja aceitando
conexões. Configure `health_check` no IP flutuante para verificar
também se a aplicação está pronta.
example: unknown
reason:
type: string
enum:
- unprobed
- booting
- probe_failed
- passing
description: >
Por que o membro lê a `health` que ele faz — para que você possa
dizer "seu serviço não está respondendo" de "o convidado ainda não
iniciou".
`unprobed` — ninguém está verificando (sem verificação de saúde,
anexado à mão). `booting` — a plataforma ainda não viu o guest
aparecer. `probe_failed` — a verificação de integridade configurada
está falhando. `passing` — o convidado está ativo e, se uma
verificação estiver configurada, ele passa.
example: unprobed
created_at:
type: string
format: date-time
readOnly: true
address_id:
type: string
format: uuid
nullable: true
description: Endereço de filho de destino na interface de membro.
FloatingIpHealthCheck:
type: object
description: >
Uma verificação de prontidão para membros de um IP flutuante
compartilhado (anycast) — o mesmo vocabulário que uma verificação de
integridade de grupo alvo de balanceador de carga, que você já conhece.
A plataforma verifica o endereço privado de cada membro dentro da VPC.
Um membro que falha pára de receber tráfego através do IP flutuante e
retorna quando ele passa novamente. Se TODOS os membros falharem, o
endereço inteiro fica escuro — uma verificação mal configurada é uma
interrupção visível causada por você, não a plataforma anunciando
silenciosamente algo que acredita estar inativo.
A verificação é feita no endereço, não por membro: os membros são
backends intercambiáveis, e um pool os deriva. Um endereço sem
verificação se comporta exatamente como antes — liveness apenas para
membros do pool, sempre anunciado para os anexados à mão.
required:
- protocol
- port
- interval_sec
- timeout_sec
- healthy_threshold
- unhealthy_threshold
properties:
protocol:
type: string
enum:
- tcp
- http
- https
default: tcp
description: >
`tcp` abre uma conexão; `http`/`https` emite um GET e compara o
status com o `matcher`. Não há `udp`: uma sonda de prontidão precisa
de uma resposta — verifique um serviço udp em uma porta de saúde tcp
em vez disso.
example: http
path:
type: string
example: /healthz
description: Caminho HTTP sondado; ignorado para tcp.
port:
type: integer
minimum: 1
maximum: 65535
example: 8080
description: Porta sondada no membro.
interval_sec:
type: integer
minimum: 1
maximum: 300
default: 30
example: 30
timeout_sec:
type: integer
minimum: 1
maximum: 60
default: 5
example: 5
description: Tempo limite por sonda; deve ser menor que interval_sec.
healthy_threshold:
type: integer
minimum: 1
maximum: 10
default: 3
example: 3
description: Passagens consecutivas antes de um membro virar saudável.
unhealthy_threshold:
type: integer
minimum: 1
maximum: 10
default: 3
example: 3
description: Falha consecutiva antes de um membro virar insalubre.
matcher:
type: string
default: '200'
example: 200-299
description: Status ou intervalo HTTP que conta como passando; ignorado para tcp.
responses:
BadRequest:
description: Parâmetros de solicitação inválidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INVALID_INPUT
message: Invalid request parameters
request_id: 550e8400-e29b-41d4-a716-446655440000
Unauthorized:
description: Autenticação necessária ou token inválido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
Forbidden:
description: Permissões insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
Conflict:
description: Conflito de recursos (por exemplo, já existe, estado inválido)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: CONFLICT
message: Resource with this name already exists
request_id: 550e8400-e29b-41d4-a716-446655440000
UnprocessableEntity:
description: >
A solicitação está bem formada, mas não pode ser processada conforme
enviada. Nas operações que aceitam `Idempotency-Key` este é o caso de
reutilização de chave: a chave foi vista pela primeira vez com uma carga
de solicitação diferente, então reproduzir o resultado armazenado
responderia a uma pergunta que o chamador não fez.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: IDEMPOTENCY_KEY_REUSED
message: >-
This Idempotency-Key was already used with a different request
payload
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >+
Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `.
Esta é a forma recomendada de autenticação.
Obtenha o token trocando o par de chaves de acesso de uma conta de
serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`.
Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis
com OAuth podem obter e renovar o token para você.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso
também serve como credencial AWS SigV4 para o endpoint de objetos
compatível com S3, que aceita somente esse método de autenticação.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.