Lançar uma instância

Os exemplos de cliente usam CLI v0.21.0 e Go SDK v0.24.0. Veja Configuração da CLI e Configuração do Go. Os snippets Go assumem um cfg configurado, um ctx de context.Background(), e importações para log, basaltic (github.com/basaltic-sh/sdk-go) e compute (github.com/basaltic-sh/sdk-go/compute).

Console
API
CLI
Go

Vá para Compute → Instances e escolha Create instance. O formulário é um cartão por decisão — Details, Flavor, Boot volume, Data volumes, Networking, IAM role, User data — com um resumo em execução ao lado deles.Networking é o cartão para desacelerar. Cada interface carrega seu próprio VPC, Subnet, Security groups e Public floating IPs; Add network interface adiciona outro, e o primeiro na lista é o NIC primário.

Substitua as identidades de exemplo por recursos em sua conta. Essa solicitação mistura um UUID de tipo de instância, um nome de imagem atual e um CRN de sub-rede aninhado.

POST https://compute.sa-saopaulo-1.basaltic.sh/v1/instances
{
  "name": "web-01",
  "flavor": "550e8400-e29b-41d4-a716-446655440000",
  "image": "debian-13",
  "networks": [
    { "subnet": "crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/private",
      "security_groups": ["c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"],
      "floating_ip_assignment": "ipv4" }
  ]
}

basaltic compute instance create --name web-01 \
  --flavor 550e8400-e29b-41d4-a716-446655440000 --image debian-13 \
  --networks '[{"subnet":"crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/private","security_groups":["c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"],"floating_ip_assignment":"ipv4"}]'

_, err := compute.New(cfg).CreateInstance(ctx, &compute.InstanceCreateRequest{
    Name: "web-01", Flavor: "550e8400-e29b-41d4-a716-446655440000",
    Image: basaltic.String("debian-13"),
    Networks: []*compute.NetworkConfig{{
        Subnet: "crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/private",
        SecurityGroups: []string{"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"},
        FloatingIPAssignment: basaltic.String("ipv4"),
    }},
})
if err != nil {
    log.Fatal(err)
}

A chamada responde 202 com a instância em pending. A construção do disco de inicialização, as interfaces e a semente acontece após a resposta, então faça a consulta GET /v1/instances/{instance_id} e observe current_state.

Grupos de segurança são por interface. Eles pertencem a networks[].security_groups, não a um campo de nível superior. Uma NIC provisionada com uma lista vazia não recebe filtragem por interface, o que não é a mesma coisa que uma instância fechada.

Uma instância sem entrada de networks inicializa sem rede. Nada falha e nada avisa você — o convidado não tem interface, então nada o alcança e ele não alcança nada. Envie pelo menos uma entrada; o índice 0 torna-se a NIC primária, a que carrega a rota padrão do convidado e sua rota para o serviço de metadados.

Tamanho: tipos de instância

Um flavor é CPU e memória, e nada mais. Ele carrega nenhum tamanho de disco — o disco de inicialização é um volume com o tamanho no lançamento — então GET /v1/flavors é um catálogo de formas de computação, não de tipos de máquina.

shared | dedicated

shared sobre-subscreve CPU para maior densidade. dedicated fixa cada vCPU 1:1 a um núcleo físico. Ambas as classes são executadas nos mesmos hosts; a classe decide como a instância desenha nos threads de um host.

general | loadbalancer | database

Somente os flavors general podem executar instâncias e pools de instâncias. Os outros dois são reservados para os produtos gerenciados, cujos nós são operados e preços pela plataforma, e são recusados aqui. Passe ?family=general ao listar.

percent of one vCPU

O piso garantido e o teto. A instância tem direito a vcpus × cpu_baseline_pct / 100 núcleos, por mais ocupados que seus vizinhos fiquem, e não pode exceder o limite de explosão, mesmo em um host ocioso. Ausente significa que o flavor não garante nenhum piso ou impõe nenhum teto além da contagem de vCPUs.

aggregate throughput

O limite de rede da instância, em megabits/s, em todas as suas interfaces. Ausente significa sem limite. Um resize move isso com o tipo de instância.

O catálogo é pequeno e vem em uma página — GET /v1/flavors não é paginado.

Escolhendo uma imagem

image assume quatro formas, e a diferença importa para a reprodutibilidade:

Um nome nu
Nome: Versão
A CRN
Uma imagem id

"image": "debian-13" segue a tag. Você obtém a compilação que estiver atual no momento em que a instância for criada, então dois lançamentos com um mês de diferença podem inicializar bits diferentes.

"image": "debian-13:20260807" fixa uma compilação. É assim que você opta por não ter a tag se movendo abaixo de você.

crn:compute:sa-saopaulo-1:platform:image/debian-13/architecture/amd64/version/20260807 pins o proprietário, nome, arquitetura e versão.

Os nomes são resolvidos em suas próprias imagens mais o catálogo público da plataforma, e usam a arquitetura de solicitação (padrão amd64). Uma imagem completa CRN fixa sua arquitetura. Veja Images para saber como uma tag se move e o que a listagem mostra e não mostra.

Discos

volumes é uma lista, e o disco de inicialização é a entrada que diz assim:

"volumes": [
  { "boot": true, "size_gb": 40, "volume_type": "nvme" },
  { "size_gb": 100, "mount_path": "/data", "fstype": "ext4" }
]

boolean

Marca o disco de inicialização, clonado de image ou selecionado com volume. No máximo uma entrada pode definir isso. Uma entrada de inicialização não tem mount_path ou fstype; seu sistema de arquivos vem da imagem ou do disco existente.Ao usar image, omita a entrada de boot e você obtém seu min_disk_gb na camada padrão da região.

integer, 1–16384

Necessário para novos discos de dados; omitido para discos existentes. Em uma nova entrada de inicialização, isso não pode ir abaixo do min_disk_gb da imagem. Qualquer coisa menor é um 400 antes da linha de instância existir, não uma compilação falhada.

string

Com um caminho de montagem definido, o agente in-guest formata o disco — somente se ele estiver em branco — e monta-o lá, usando fstype: ext4 por padrão, ou xfs.

boolean

Novos volumes de tempo de inicialização são definidos como true. Os discos existentes têm o padrão false e não podem definir isso como true durante o lançamento. Os discos anexados após o lançamento também são padrão para false.

Novos volumes de inicialização e dados são excluídos com a instância por padrão. Defina delete_on_termination: false em suas entradas de inicialização para retê-los, ou altere o anexo após o lançamento — veja o que sobrevive a uma exclusão. Os discos existentes selecionados durante o lançamento são mantidos.

Desempenho e discos existentes

Novos discos de inicialização e dados podem provisionar IOPS e taxa de transferência independentemente da capacidade. A franquia incluída é de 3.000 IOPS / 125 MiB/s. O SSD suporta até 8.000 IOPS/250 MiB/s e o NVMe até 12.000 IOPS/500 MiB/s, sujeito a cotas de conta e capacidade regional. O resumo mostra desempenho adicional separadamente da capacidade de armazenamento; 3.500 IOPS / 250 MiB/s adiciona R$35/mês. Consulte preços por volume para obter taxas e proporções. Você também pode iniciar a partir de um disco inicializável existente e anexar discos de dados existentes. Eles devem estar disponíveis na mesma conta e região, sem uma alteração de desempenho pendente. Cada disco pode aparecer apenas uma vez. Os discos existentes mantêm seus dados, desempenho, programações de snapshot e encargos atuais. Eles são retidos se o lançamento falhar ou a instância for excluída, e suas cobranças contínuas são excluídas da estimativa de novos recursos. Isso requer compute:AttachVolume além de compute:CreateInstance.

Console
API
CLI
Go

Em Create instance, use Boot volume para escolher New volume from image ou Existing volume. Um novo disco de inicialização oferece Provisioned IOPS e Provisioned throughput (MiB/s). Cada entrada em Data volumes oferece a mesma escolha. Os discos existentes mostram seu desempenho atual. O resumo lista Additional performance separadamente.

Para um novo disco, adicione performance à sua entrada volumes:

{ "boot": true, "size_gb": 40, "volume_type": "ssd",
  "performance": { "iops": 3500, "throughput_mib_s": 250 } }

Para discos existentes, omita o nível superior image e use referências volume:

{
  "name": "web-02",
  "flavor": "s1.medium",
  "networks": [{ "subnet": "private" }],
  "volumes": [
    { "boot": true, "volume": "saved-root" },
    { "volume": "saved-data" }
  ]
}

volume aceita um UUID, nome ou CRN. As entradas existentes também não podem definir capacidade, tipo, desempenho, programações de snapshot ou delete_on_termination: true.

Com CLI v0.21.0 ou posterior, salve a solicitação completa como instance.json e execute:

basaltic compute instance create --from-file instance.json

O sinalizador JSON --volumes aceita as mesmas entradas.

Com SDK v0.24.0 ou posterior:

_, err := compute.New(cfg).CreateInstance(ctx, &compute.InstanceCreateRequest{
    Name: "web-02", Flavor: "s1.medium",
    Networks: []*compute.NetworkConfig{{Subnet: "private"}},
    Volumes: []*compute.InstanceLaunchVolume{
        {Boot: basaltic.Bool(true), Volume: basaltic.String("saved-root")},
        {Volume: basaltic.String("saved-data")},
    },
})

Novos discos usam Performance com compute.VolumePerformanceRequest. SizeGB é opcional na v0.24.0; use basaltic.Int(40) para um novo disco de 40 GB.

Essas opções se aplicam a instâncias individuais. Os modelos de pool de instâncias não podem reutilizar discos existentes ou provisionar desempenho adicional no lançamento.

Programações de snapshot no lançamento

Cada novo volume de inicialização ou de dados pode ter até 16 snapshot schedules independentes. Isso requer storage:CreateSnapshotPolicy além das permissões para iniciar uma instância. Os nomes de agendamento devem ser exclusivos em toda a conta, incluindo os outros volumes na mesma solicitação.

Console
API
CLI
Go

Em Boot volume ou uma nova entrada Data volumes, use Add snapshot schedule. Defina Schedule name, Every (minutes), Keep snapshots e, opcionalmente, Maximum age (days). Desmarque Enabled para criar uma programação em pausa. O resumo do lançamento inclui as programações solicitadas.

Inclua snapshot_schedules dentro de cada entrada no array volumes da solicitação de criação. Por exemplo:

{
  "boot": true,
  "size_gb": 40,
  "snapshot_schedules": [
    {"name": "web-boot-daily", "interval_minutes": 1440, "retention_count": 7},
    {"name": "web-boot-weekly", "interval_minutes": 10080, "retention_count": 4}
  ]
}

Adicione as programações aninhadas a volumes no arquivo de solicitação de instância completa:

basaltic compute instance create --from-file instance.json

O sinalizador JSON --volumes aceita o mesmo array.

Definir Volumes em compute.InstanceCreateRequest:

Volumes: []*compute.InstanceLaunchVolume{{
    Boot: basaltic.Bool(true),
    SizeGB: basaltic.Int(40),
    SnapshotSchedules: []*compute.SnapshotScheduleSettings{{
        Name: "web-boot-daily",
        IntervalMinutes: 1440,
        RetentionCount: 7,
    }},
}},

O conjunto de agendamento completo é criado durante o provisionamento. A reintentar o provisionamento não cria agendas duplicadas. Se o lançamento falhar e for revertido, suas programações serão removidas; os instantâneos já enviados serão preservados. Os volumes anexados posteriormente mantêm suas programações existentes. Modelos de pool de instâncias não suportam snapshot_schedules.

Acesso SSH e cloud-init

Use SSH access with IAM para logins humanos e de automação. Adicione uma chave pública à identidade e conceda acesso à instância. A plataforma instala o IAM SSH durante a primeira inicialização em imagens compatíveis; a criação de instância não tem campo de anexo de chave e não cria usuário de login compartilhado. user_data é base64-codificado cloud-init. A configuração base desabilita a senha e o login root. As chaves de nível superior do cliente substituem os valores base, enquanto a plataforma adiciona sua rota de metadados e instalação de agente convidado posteriormente. Seu próprio bloco users: pode criar usuários de aplicativos locais sem alterar a identidade e as permissões dos usuários do IAM.

Seus dados de usuário devem ser decodificados para um documento cuja primeira linha seja #cloud-config. Um script de shell ou um pacote MIME de várias partes não é mesclado. Coloque comandos de shell no runcmd do cloud-init em vez disso.

Um documento #cloud-config contendo YAML inválido falha no provisionamento.

Dando uma identidade à instância

No lançamento, iam_role aceita um nome de função, UUID ou CRN e anexa essa função IAM. O software dentro do convidado então obtém credenciais de curta duração do serviço de metadados em 169.254.169.254 — nenhuma chave de acesso é escrita para a instância, e nada precisa ser girado.

Duas condições, e ambas são fáceis de perder. A política de confiança da função deve aceitar crn:compute:*:*:instance/* (ou o CRN da instância específica), e o principal que faz a chamada de lançamento precisa de iam:PassRole na função, separadamente de compute:CreateInstance. Sem a política de confiança, a instância é iniciada e as credenciais nunca são criadas; sem iam:PassRole, o lançamento em si é negado. Funções e identidade de instância percorre ambos.

As respostas de instância retornam iam_role como um resumo opcional em vez de uma referência de string ou iam_role_id:

{
  "iam_role": {
    "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
    "crn": "crn:iam::my-account:role/deploy",
    "name": "deploy"
  }
}

O resumo é visível com acesso de leitura de instância; ele não requer iam:GetRole. Ele contém apenas id, crn e name, excluindo campos de função sensíveis, como políticas. O campo é 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.

Alterar a função de uma instância existente

Você pode anexar, substituir ou remover uma função de carga de trabalho enquanto uma instância estiver em execução ou parada, sem nenhuma operação em andamento. Essas alterações não exigem reinicialização. Há uma função anexada por instância. A substituição é atômica; se a validação falhar, a função anterior permanece anexada.

Console
API
CLI
Go

Abra a instância e selecione Settings. Em IAM role, selecione uma função e clique em Save IAM role. Para desconectá-lo, clique em Remove role e, em seguida, em Remove IAM role.

curl -X PATCH "https://compute.sa-saopaulo-1.basaltic.sh/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Account-Id: $ACCOUNT" \
  -H "Content-Type: application/json" \
  -d '{"iam_role":"workload-role"}'

Envie {"iam_role":""} para desacoplar. Omita iam_role para manter a associação atual. Objetos de função null e embutidos não são aceitos.

basaltic compute instance update "$INSTANCE_ID" --iam-role workload-role
basaltic compute instance update "$INSTANCE_ID" --iam-role=""

O primeiro comando anexa ou substitui a função; o segundo a desliga. Requer CLI v0.17.0 ou posterior.

role := "workload-role"
_, err := compute.New(cfg).UpdateInstance(ctx, instanceID, &compute.InstanceUpdateRequest{
    IAMRole: &role,
})

Defina role para "" para desacoplar. Deixe IAMRole nil para preservá-lo. Requer SDK v0.20.0 ou posterior.

Cada edição requer compute:UpdateInstance na instância. Anexar e substituir também requer iam:PassRole na função selecionada, que deve pertencer à mesma conta e confiar nesta instância. A lista de funções do console requer iam:ListRoles. O desligamento não requer a passagem de uma função. Novas solicitações de metadados observam a associação salva imediatamente. Uma solicitação já em andamento pode ser completada com a associação anterior. A desconexão interrompe a recuperação subsequente de credenciais; a reconexão da mesma função obtém um novo conjunto de credenciais. As solicitações que se sobrepõem a uma alteração de função podem precisar tentar novamente a descoberta de função. Edições simultâneas se aplicam na ordem de commit, e repetir a associação atual deixa-a inalterada.

As credenciais emitidas anteriormente não são revogadas quando você substitui ou separa uma função. Eles permanecem válidos até o seu vencimento existente, por até uma hora. As credenciais de cache de aplicativos podem continuar usando a função antiga até a atualização.

As instâncias gerenciadas por serviço não podem ser editadas dessa maneira. Para um membro de pool de instâncias, altere o launch template do pool; o template define a função usada pelas instâncias de substituição. Uma edição de instância nunca modifica seu modelo de pool.

Nomes, tags e metadados

unique per account

1–128 caracteres, seguros para DNS: letras, dígitos, ponto, traço, sublinhado, alfanumérico inicial e final. Um nome que colidem com outra instância na conta é um 409.

not supported

PATCH /v1/instances/{instance_id} edita description, metadata, tags e iam_role. Um nome é fixado para a vida da instância.No console, esses são os cartões Details, Tags, Metadata e IAM role na guia Settings da instância. Nenhum tem um campo de nome.

IAM and cost

Leia as condições da política do IAM como basalt:RequestTag/<key> na criação e basalt:ResourceTag/<key> depois, e usado para atribuição de custo. Veja políticas.

replaced, not merged

O mapa que você PATCH se torna o conjunto inteiro de suas chaves.

Chaves de metadados sob o namespace basalt: são estados de plano de controle — como uma instância prova a qual pool ou recurso gerenciado ela pertence. Você não pode configurá-los, e você não pode removê-los: eles são preservados através de um PATCH, quer você os refaça ou não, e propor um valor diferente para um é um 400 ao invés de uma queda silenciosa. Leitura-modificação-gravação contra todo o mapa de metadados é, portanto, seguro.

Leitura de endereços de instância

A tabela de instâncias mostra IPv4 privado, IPv4 público e IPv6 da NIC primária. Os detalhes da instância mostram esses mesmos valores individualmente. A guia Networking lista cada NIC com seus endereços primários. Um IP flutuante IPv6 anexado é mostrado em vez do endereço IPv6 diretamente anexado da NIC. A visão geral mostra um endereço por instância, preferindo IPv4 público, depois IPv6 público e, em seguida, IPv4 privado.

Referências de recursos

Consulte Referências de recursos para classificação, versões de imagem e busca de uma instância por nome ou CRN. flavor, iam_role, e por-NIC security_groups aceitam um UUID, um CRN, ou um nome exato. Os tipos de instância são regionais; os grupos de segurança pertencem à sua conta e as funções do IAM pertencem à sua conta. subnet aceita um UUID ou um CRN completo de VPC/subnet. Um nome de sub-rede nu não pode ser resolvido sem seu pai VPC. O anexo de interface também requer um UUID ou um CRN completo de VPC/sub-rede/interface. Cada lista de computação aceita exatos filtros name e crn. Eles se cruzam com outros filtros e paginação. Um CRN estrangeiro ou não correspondido não corresponde a nenhuma linha; um CRN mal formado ou vazio retorna 400. Nomes vazios não ampliam a lista. Listas de instâncias também aceitam referências flavor e image. Os nomes da lista de NICs correspondem aos nomes de interface dentro das ligações de instância; nomes duplicados podem retornar várias interfaces. IPs flutuantes não têm identidade de nome.

Primeiros passos

Produtos

Plataforma

Ajuda

Lançar uma instância

Tamanho: tipos de instância

Escolhendo uma imagem

Discos

Desempenho e discos existentes

Programações de snapshot no lançamento

Acesso SSH e cloud-init

Dando uma identidade à instância

Alterar a função de uma instância existente

Nomes, tags e metadados

Leitura de endereços de instância

Referências de recursos

​Tamanho: tipos de instância

​Escolhendo uma imagem

​Discos

​Desempenho e discos existentes

​Programações de snapshot no lançamento

​Acesso SSH e cloud-init

​Dando uma identidade à instância

​Alterar a função de uma instância existente

​Nomes, tags e metadados

​Leitura de endereços de instância

​Referências de recursos

Tamanho: tipos de instância

Escolhendo uma imagem

Discos

Desempenho e discos existentes

Programações de snapshot no lançamento

Acesso SSH e cloud-init

Dando uma identidade à instância

Alterar a função de uma instância existente

Nomes, tags e metadados

Leitura de endereços de instância

Referências de recursos