> ## 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. # Lançar uma instância > Flavors, imagens, discos, chaves e cloud-init — e os dois campos cuja ausência silenciosamente custa uma rede. Os exemplos de cliente usam CLI v0.21.0 e Go SDK v0.24.0. Veja [Configuração da CLI](/pt/cli) e [Configuração do Go](/pt/reference-resolution#released-go-sdk). Os snippets Go assumem um `cfg` configurado, um `ctx` de `context.Background()`, e importações para `log`, `basaltic` (`github.com/basaltic-sh/sdk-go`) e `compute` (`github.com/basaltic-sh/sdk-go/compute`). 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. ```bash theme={null} 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" } ] } ``` ```bash theme={null} 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"}]' ``` ```go theme={null} _, 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` 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. 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. 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. O limite de rede da instância, em megabits/s, em todas as suas interfaces. Ausente significa sem limite. Um [resize](/pt/compute/lifecycle#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: `"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. Um UUID também identifica uma compilação, e é o que a API retorna para você. 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](/pt/compute/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: ```json theme={null} "volumes": [ { "boot": true, "size_gb": 40, "volume_type": "nvme" }, { "size_gb": 100, "mount_path": "/data", "fstype": "ext4" } ] ``` 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. 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. 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`. 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](/pt/compute/lifecycle#what-survives-a-delete). 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](/pt/storage/volumes) 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`. 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`: ```json theme={null} { "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`: ```json theme={null} { "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: ```bash theme={null} basaltic compute instance create --from-file instance.json ``` O sinalizador JSON `--volumes` aceita as mesmas entradas. Com SDK v0.24.0 ou posterior: ```go theme={null} _, 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](/pt/storage/snapshots#snapshot-policies) 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. 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: ```json theme={null} { "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: ```bash theme={null} basaltic compute instance create --from-file instance.json ``` O sinalizador JSON `--volumes` aceita o mesmo array. Definir `Volumes` em `compute.InstanceCreateRequest`: ```go theme={null} 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](/pt/compute/ssh) 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](/pt/iam/roles) 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`: ```json theme={null} { "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. 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**. ```bash theme={null} 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. ```bash theme={null} 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. ```go theme={null} 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](/pt/compute/instance-pools) 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 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`. `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. Leia as condições da política do IAM como `basalt:RequestTag/` na criação e `basalt:ResourceTag/` depois, e usado para atribuição de custo. Veja [políticas](/pt/iam/policies). 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](/pt/reference-resolution) 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.