> ## 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 pool de instâncias
> Crie um pool a partir de um modelo de lançamento e uma contagem desejada. As instâncias desired_count são geradas de forma síncrona; um reconciliador de segundo plano então converge member_count para desired_count conforme ele é alterado. No momento da criação, min_count/max_count padrão é desired_count.
As `tags` de nível superior rotulam o pool em si; `template.tags` são estampas em cada instância que ele inicia.
Requer a ação do IAM **`compute:CreateInstancePool`**. Consulte [permissões de computação](/pt/compute/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política.
## OpenAPI
````yaml /pt/api-reference/specs/compute.yaml post /v1/instance-pools
openapi: 3.0.3
info:
title: API de Basaltic Compute
version: 1.0.0
description: >
Instâncias de máquina virtual e as imagens, os tipos e os pools de
instâncias a partir dos quais elas são criadas. Abrange todo o ciclo de vida
da instância: iniciar, parar, reiniciar, redimensionar e reinstalar.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://compute.{region}.basaltic.sh
description: Endpoint de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de região
security:
- BearerAuth: []
paths:
/v1/instance-pools:
post:
tags:
- Compute
summary: Criar um pool de instâncias
description: >
Crie um pool a partir de um modelo de lançamento e uma contagem
desejada. As instâncias desired_count são geradas de forma síncrona; um
reconciliador de segundo plano então converge member_count para
desired_count conforme ele é alterado. No momento da criação,
min_count/max_count padrão é desired_count.
As `tags` de nível superior rotulam o pool em si; `template.tags` são
estampas em cada instância que ele inicia.
operationId: createInstancePool
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InstancePoolCreateRequest'
responses:
'201':
description: Pool criado; instâncias iniciais geradas.
content:
application/json:
schema:
$ref: '#/components/schemas/InstancePoolResponse'
'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'
security:
- BearerAuth: []
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:
InstancePoolCreateRequest:
type: object
additionalProperties: false
description: >-
`template` é a configuração de lançamento — os mesmos campos que a
instância create toma. Os próprios campos do pool — descrição, tags,
dimensionamento — permanecem no nível superior, porque descrevem o pool
e não as instâncias nele. Um flavor e uma sub-rede primária são
necessários, como `template.flavor` + `template.networks[0].subnet`. Em
criar somente, omitido min_count e max_count padrão para desired_count.
required:
- name
- template
properties:
autoscaling:
$ref: '#/components/schemas/AutoscalingPolicy'
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-asg
description:
type: string
tags:
allOf:
- $ref: '#/components/schemas/Tags'
description: >-
Rótulos no recurso de pool, para condições do IAM
(`basalt:RequestTag/` aqui, `basalt:ResourceTag/` em
operações posteriores) e atribuição de custo. Eles não são
propagados para as instâncias que o pool lança; `template.tags` é
esse conjunto. Um campo de pool, enviado ao lado de `template`. As
tags de réplica só são acessíveis através de `template.tags`.
template:
$ref: '#/components/schemas/InstancePoolTemplateRequest'
desired_count:
type: integer
minimum: 0
maximum: 100
example: 2
min_count:
type: integer
minimum: 0
maximum: 100
example: 1
max_count:
type: integer
minimum: 0
maximum: 100
description: >-
Um valor de 0 significa que o pool não possui membros até que
max_count seja aumentado.
example: 3
InstancePoolResponse:
type: object
properties:
instance_pool:
$ref: '#/components/schemas/InstancePool'
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
InstancePoolTemplateRequest:
type: object
additionalProperties: false
required:
- flavor
- networks
description: >-
A configuração de lançamento do pool, na forma que uma instância
autônoma cria: mesmos nomes de campo, mesmos tipos, mesmos significados,
para que um cliente que possa criar uma instância possa criar um pool
deles sem um segundo contrato mais estreito para aprender. Pertence à
pool. Não há um recurso de modelo de lançamento separado para criar,
versão ou compartilhar entre pools. Networking é uma lista ordenada de
`networks`, sendo o índice 0 a NIC primária. `ip_address` e `mac` são
parte daquela forma de NIC compartilhada, mas são recusadas aqui: cada
réplica é iniciada a partir deste modelo, então um endereço fixo faria
com que a segunda réplica perguntasse por um que a primeira já possui.
properties:
flavor:
type: string
description: Referência de tipo de instância regional (UUID, CRN ou nome exato).
architecture:
type: string
default: amd64
image:
type: string
description: >-
Imagem para clonar o disco de inicialização de cada réplica. Aceita
os mesmos quatro formulários que o instance create: um CRN
qualificado para arquitetura, um id de imagem, `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, e o id de imagem
resultante é o que cada réplica inicializa — incluindo substituições
geradas meses depois. Uma tag re-resolvida por réplica permitiria
que um heal boot tivesse uma build 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.
networks:
type: array
description: >-
Interfaces por réplica. O índice 0 é a NIC primária e é obrigatório;
o resto são extras.
items:
$ref: '#/components/schemas/NetworkConfig'
minItems: 1
user_data:
type: string
format: byte
description: >-
Dados de usuário codificados em Base64 (cloud-init), carimbados em
cada réplica.
metadata:
$ref: '#/components/schemas/Metadata'
tags:
allOf:
- $ref: '#/components/schemas/Tags'
description: >-
Tags carimbadas em cada instância que este modelo lança. Estas são
as tags das réplicas, não do pool — as próprias etiquetas do pool
são as `tags` de nível superior, e as duas são independentes.
Alterá-los afeta apenas lançamentos FUTUROS. As instâncias já em
execução mantêm as tags com as quais foram lançadas, então entre a
mudança e uma atualização, o pool contém membros que carregam dois
conjuntos de tags diferentes; `stale_instance_count` é quantos ainda
estão na antiga. POST /v1/instance-pools/{pool_id}/refresh rolls
them onto the current template.
iam_role:
type: string
description: >-
Referência de função do IAM da mesma conta (UUID, CRN ou nome
exato). Aplica-se a autorização de confiança de PassRole e
instância.
volumes:
type: array
items:
$ref: '#/components/schemas/InstanceVolume'
description: >
Discos por réplica, o disco de inicialização incluído — marque-o com
`boot: true`. Cada nova réplica recebe o desempenho provisionado
configurado. O desempenho omitido usa a franquia incluída. Os
volumes existentes e as programações de instantâneos não são
suportados em modelos de pool.
InstancePool:
type: object
required:
- faults
description: >-
Um modelo de lançamento mais uma contagem desejada. A criação de um pool
gera instâncias de desired_count; um reconciliador converge member_count
para desired_count à medida que ele muda. member_count é quantos membros
o pool tem; live_count é quantos deles estão em execução. Um pool
carrega dois conjuntos de tags e eles respondem a perguntas diferentes.
`tags` rotula o recurso do pool — é o que uma condição do IAM lê como
`basalt:ResourceTag/` e o que um relatório de custo agrupa, e não
atinge nenhuma instância. `template.tags` é o conjunto estampado em cada
réplica que o pool lança.
properties:
autoscaling:
$ref: '#/components/schemas/AutoscalingPolicy'
autoscaling_status:
$ref: '#/components/schemas/AutoscalingStatus'
rollout_surge:
type: boolean
readOnly: true
description: >-
Capacidade de implantação temporária; desired_count permanece o alvo
estável.
retiring_instances:
type: array
readOnly: true
items:
$ref: '#/components/schemas/RetiringPoolMember'
id:
type: string
format: uuid
readOnly: true
example: 8f2a1c3d-4e5b-4a6f-9c0d-1e2f3a4b5c6d
crn:
type: string
readOnly: true
description: >-
Nome do recurso da nuvem. Esse é o valor que uma declaração de
política do IAM deve nomear para escopo de uma permissão somente
para esse pool; uma política escrita contra qualquer outra coisa não
corresponderá.
example: crn:compute:sa-saopaulo-1:my-account:instance-pool/web-pool
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-asg
description:
type: string
example: Front-end autoscaling group
desired_count:
type: integer
minimum: 0
maximum: 100
example: 2
min_count:
type: integer
minimum: 0
maximum: 100
example: 1
max_count:
type: integer
minimum: 0
maximum: 100
description: >-
Um valor de 0 significa que o pool não possui membros até que
max_count seja aumentado.
example: 3
live_count:
type: integer
readOnly: true
description: >
Quantos membros estão UP — instâncias vinculadas cujo current_state
é `running`.
example: 2
member_count:
type: integer
readOnly: true
description: >-
Quantas instâncias o pool contém, em execução ou não. Isso é o que o
conciliador converge para desired_count e o que `status` reflete,
então member_count == desired_count com live_count abaixo dele
significa que o pool tem os membros que foi solicitado e alguns
deles não estão ativos.
example: 2
refresh_in_progress:
type: boolean
readOnly: true
description: >-
True enquanto uma substituição contínua solicitada por meio de POST
/v1/instance-pools/{pool_id}/refresh ainda estiver em execução. Ele
se limpa quando todos os membros estão no modelo atual. O pool lê
`scaling` para a duração, uma vez que ele executa uma instância
sobre seu alvo enquanto uma substituição aparece.
example: false
stale_instance_count:
type: integer
readOnly: true
description: >-
Quantos membros foram lançados a partir de um modelo diferente do
atual do pool, ou seja, quantos seriam substituídos por uma
atualização. Não-zero após editar o `template` e antes de atualizar,
que é o sinal de que uma mudança de modelo ainda não foi lançada.
example: 0
status:
type: string
enum:
- active
- scaling
- error
- deleting
readOnly: true
description: >
Onde o pool está contra o seu alvo.
`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; leia live_count para isso.
`scaling` significa que não, e o conciliador está convergindo-o:
após uma criação, após uma alteração de desired_count, e pelo tempo
de uma atualização de instância, que executa o pool uma instância
sobre seu alvo enquanto uma substituição aparece.
`error` significa que existe uma falha de erro ativa. As falhas de
capacidade permanecem elegíveis para reconciliação; a exclusão com
falha mantém sua intenção de desmontagem e nunca recria membros.
`deleting` é desmontado sem um erro ativo.
example: active
faults:
type: array
readOnly: true
description: >-
Falhas ativas, mais recentes primeiro. Vazio para uma pool saudável.
A recuperação resolve apenas os códigos da operação bem-sucedida.
items:
$ref: '#/components/schemas/Fault'
managed_by:
type: string
readOnly: true
example: customer
tags:
allOf:
- $ref: '#/components/schemas/Tags'
description: >-
Rótulos no próprio POOL, para condições do IAM
(`basalt:ResourceTag/`) e atribuição de custo. Eles não estão
ligados a mais nada: nenhuma instância que o pool lança os carrega.
As tags com as quais uma réplica é lançada são `template.tags`. Ao
contrário dos outros campos de nível superior ao lado deste, `tags`
não é uma projeção do modelo de lançamento — é o próprio conjunto do
pool, e PATCHable por conta própria.
template:
allOf:
- $ref: '#/components/schemas/InstancePoolTemplate'
readOnly: true
description: >
A configuração de lançamento do pool, na forma instance create
takes. O único lugar onde aparece: uma cópia plana ao lado desta era
duas ortografias de uma coisa, e duas ortografias de deriva.
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.
NetworkConfig:
type: object
additionalProperties: false
required:
- subnet
properties:
subnet:
type: string
description: >-
UUID de sub-rede ou CRN completo de VPC/sub-rede. Nomes nulos exigem
um pai de VPC e são rejeitados aqui.
example: 9b2e4f1a-3c5d-4e6f-8a90-1b2c3d4e5f60
mac:
type: string
description: >
Endereço MAC opcional. Deve ser administrado localmente (`X2:`,
`X6:`, `XA:`, `XE:` no primeiro octet). Gerado quando omitido.
example: 02:1a:2b:3c:4d:5e
security_groups:
type: array
items:
type: string
example: c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f
description: >
Referências de grupo de segurança com escopo de conta (UUID, CRN ou
nome) para anexar a esta NIC. Cada um deve ser de propriedade da
mesma conta. Lista vazia = sem ACLs por NIC (o padrão de permissão
da plataforma permanece em vigor).
floating_ip_assignment:
type: string
enum:
- none
- ipv4
- ipv6
- dual_stack
- auto
default: none
description: >-
Aloque IPs flutuantes públicos para esta NIC no lançamento. Famílias
explícitas exigem endereços de hóspedes e rotas de internet
correspondentes. O desligamento deixa o FIP reservado. Não existe um
mapeamento IPv4 público comum.
addresses:
type: array
items:
$ref: '#/components/schemas/AddressRequest'
Metadata:
type: object
additionalProperties:
type: string
example:
environment: production
team: backend
InstanceVolume:
type: object
required:
- size_gb
description: >
Um disco criado com a instância. `boot: true` marca o clone de image_id;
cada outra entrada é um volume em branco que o agente convidado formata
e monta.
properties:
boot:
type: boolean
default: false
example: false
description: >
Marca o disco de inicialização. Não precisa de mount_path ou fstype
— ambos vêm da imagem — e o envio de qualquer um é recusado em vez
de ignorado.
size_gb:
type: integer
minimum: 1
example: 20
volume_type:
type: string
example: nvme
description: Tier; omitido = o padrão da região.
performance:
$ref: '#/components/schemas/VolumePerformanceRequest'
mount_path:
type: string
example: /data
fstype:
type: string
example: ext4
description: Sistema de arquivos com o qual o agente convidado formata o volume.
delete_on_termination:
type: boolean
default: true
example: true
description: Destruido com a instância, a menos que seja definido como false.
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
RetiringPoolMember:
allOf:
- $ref: '#/components/schemas/Retirement'
- type: object
required:
- instance_id
properties:
instance_id:
type: string
format: uuid
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
InstancePoolTemplate:
type: object
description: >-
Configuração de inicialização armazenada com identidades de
relacionamento UUID canônicas. Converta essas identidades para os campos
de solicitação em InstancePoolTemplateRequest ao substituir o modelo. A
identidade da imagem é fixada; a reutilização posterior do nome ou uma
nova versão da imagem atual não as altera.
properties:
flavor_id:
type: string
format: uuid
image_id:
type: string
format: uuid
description: >-
Resolveu o UUID da imagem fixado para cada réplica até a
substituição do modelo.
networks:
type: array
description: >-
Interfaces por réplica. O índice 0 é a NIC primária e é obrigatório;
o resto são extras.
items:
$ref: '#/components/schemas/NetworkConfigResponse'
minItems: 1
user_data:
type: string
format: byte
description: >-
Dados de usuário codificados em Base64 (cloud-init), carimbados em
cada réplica.
metadata:
$ref: '#/components/schemas/Metadata'
tags:
allOf:
- $ref: '#/components/schemas/Tags'
description: >-
Tags carimbadas em cada instância que este modelo lança. Estas são
as tags das réplicas, não do pool — as próprias etiquetas do pool
são as `tags` de nível superior, e as duas são independentes.
Alterá-los afeta apenas lançamentos FUTUROS. As instâncias já em
execução mantêm as tags com as quais foram lançadas, então entre a
mudança e uma atualização, o pool contém membros que carregam dois
conjuntos de tags diferentes; `stale_instance_count` é quantos ainda
estão na antiga. POST /v1/instance-pools/{pool_id}/refresh rolls
them onto the current template.
iam_role:
allOf:
- $ref: '#/components/schemas/InstanceRole'
description: >-
Resumo da função do IAM anexada a cada réplica, visível com acesso
de leitura de pool sem iam:GetRole. Omitida quando nenhuma função
está anexada, a função foi excluída ou pertence a outra conta.
Campos de função confidenciais permanecem disponíveis somente por
meio da API do IAM.
volumes:
type: array
items:
$ref: '#/components/schemas/InstanceVolume'
description: >
Discos por réplica, o disco de inicialização incluído — marque-o com
`boot: true`. Cada nova réplica recebe o desempenho provisionado
configurado. O desempenho omitido usa a franquia incluída. Os
volumes existentes e as programações de instantâneos não são
suportados em modelos de pool.
AddressRequest:
type: object
properties:
family:
type: string
enum:
- ipv4
- ipv6
address:
type: string
description: >-
Endereço fixo opcional ao criar uma interface ou instância NIC. Para
IPv6, use o primeiro endereço de um /96 alinhado dentro da sub-rede
/64 (últimos 32 bits zero); o primeiro e o último intervalo /96 são
reservados. Omitir para alocação automática. Nós de banco de dados
gerenciados e a operação de adicionar endereço exigem alocação
automática.
required:
- family
additionalProperties: false
VolumePerformanceRequest:
type: object
additionalProperties: false
description: >
Desempenho de leitura/gravação combinado total sustentado de
provisionamento independente. As dimensões omitidas mantêm seu valor
atual (incluído na criação). O SSD permite até 8000 IOPS e 250 MiB/s; o
NVMe até 12000 e 500 MiB/s. O mínimo é a cota incluída do volume; cotas
maiores permanecem disponíveis gratuitamente. O rendimento é inteiro
MiB/s, exceto uma fração exata de permissão de legado pode ser
selecionada para remover o complemento pago. Os aumentos exigem cota de
conta, capacidade regional e armazenamento saudável. Fatura de extras
aplicados por duração decorrido, incluindo enquanto desligado ou parado.
properties:
iops:
type: integer
minimum: 1
example: 6000
throughput_mib_s:
type: number
minimum: 0
example: 250
Retirement:
type: object
readOnly: true
required:
- requested_at
- drain_seconds
properties:
requested_at:
type: string
format: date-time
drain_seconds:
type: integer
minimum: 30
maximum: 3600
agent_acknowledged_at:
type: string
format: date-time
drain_until:
type: string
format: date-time
description: >-
Tempo de exclusão mais cedo; ausente enquanto a retirada está
pendente.
NetworkConfigResponse:
type: object
required:
- subnet
properties:
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.
mac:
type: string
description: >
Endereço MAC opcional. Deve ser administrado localmente (`X2:`,
`X6:`, `XA:`, `XE:` no primeiro octet). Gerado quando omitido.
example: 02:1a:2b:3c:4d:5e
security_group_ids:
type: array
items:
type: string
format: uuid
example: c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f
description: >
Referências de grupo de segurança com escopo de conta (UUID, CRN ou
nome) para anexar a esta NIC. Cada um deve ser de propriedade da
mesma conta. Lista vazia = sem ACLs por NIC (o padrão de permissão
da plataforma permanece em vigor).
floating_ip_assignment:
type: string
enum:
- none
- ipv4
- ipv6
- dual_stack
- auto
default: none
description: >-
Aloque IPs flutuantes públicos para esta NIC no lançamento. Famílias
explícitas exigem endereços de hóspedes e rotas de internet
correspondentes. O desligamento deixa o FIP reservado. Não existe um
mapeamento IPv4 público comum.
addresses:
type: array
items:
$ref: '#/components/schemas/AddressRequest'
InstanceRole:
type: object
required:
- id
- crn
- name
properties:
id:
type: string
format: uuid
example: b2c3d4e5-f6a7-8901-2345-67890abcdef1
crn:
type: string
description: >-
Identidade de função com escopo de conta, conforme usada em
documentos de política.
example: crn:iam::my-account:role/deploy
name:
type: string
description: Nome de função imutável.
example: deploy
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
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
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.