> ## 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.

# Volumes e interfaces

> Hot-plug de discos e NICs em uma instância em execução, quais deles sobrevivem e de onde vem um endereço público.

## Volumes

`GET /v1/instances/{instance_id}/volumes` lista os anexos na ordem de inicialização, disco de inicialização primeiro, cada um resolvido com o nome atual do volume, camada, tamanho e status.

<Tabs>
  <Tab title="Console">
    **Attach volume** na guia **Volumes** da instância abre uma caixa de diálogo pedindo o **Volume** e, opcionalmente, um **Device name** — *Deixe em branco para atribuir o próximo nome disponível* — um **Mount path** e um **Filesystem**. Apenas os volumes que a instância pode realmente assumir são oferecidos.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST /v1/instances/{instance_id}/volumes
    { "volume": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "mount_path": "/data", "fstype": "ext4" }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic compute instance attach-volume <instance-id> \
      --volume 7c9e6679-7425-40de-944b-e07fc1f90ae7 \
      --mount-path /data --fstype ext4
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    _, err := compute.New(cfg).AttachInstanceVolume(ctx, instanceID,
        &compute.AttachInstanceVolumeRequest{
            Volume: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            MountPath: basaltic.String("/data"),
            Fstype: basaltic.String("ext4"),
        })
    ```
  </Tab>
</Tabs>

O volume deve estar na mesma conta e em status `available`, e a instância deve estar `running` ou `stopped`. O disco é conectado a quente; `device` escolhe o próximo slot livre (`vdb`, `vdc`, …) a menos que você nomeie um.

Com `mount_path` definido, o agente in-guest formata o disco — **somente se ele estiver em branco** — e o monta lá. `fstype` escolhe o sistema de arquivos: `ext4` por padrão, ou `xfs`. Nada mais é aceito. Deixe `mount_path` vazio e você obtém o dispositivo de bloco e nada mais.

O desligamento é `DELETE /v1/instances/{instance_id}/volumes/{volume_id}`, também `202`, também requer `running` ou `stopped`. No console, é a ação de linha na guia **Volumes** da instância, confirmada como **Detach volume** — e o disco de inicialização não tem esse controle lá, porque o desligamento é recusado de qualquer maneira.

<a id="network-interfaces" />

## Interfaces de rede

`GET /v1/instances/{instance_id}/nics` é a fonte de cada endereço de instância. Cada NIC retorna um array de `addresses`, com resumos IP flutuantes aninhados sob seu endereço de destino. O objeto de instância não tem campos de IP primário ou público.

Essa listagem é ordenada pelo índice de inicialização, principal primeiro, e cada entrada resolve o MAC, IPv4, IPv6, sub-rede e VPC atuais da interface.

O posicionamento retorna como um objeto `subnet` incorporado em vez dos antigos campos `subnet_id` e `vpc_id`. Ele carrega a VPC pai e o resumo da tabela de rotas nuláveis descrito em [subnet placement](/pt/networking/subnets#reading-placement), então `subnet.name` e `subnet.vpc.name` são legíveis diretamente da NIC — nenhuma leitura separada de subnet ou VPC é necessária para mostrar onde uma interface está localizada:

```json theme={null}
{
  "nics": [
    {
      "interface_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "boot_index": 0,
      "subnet": {
        "id": "9b2e4f1a-3c5d-4e6f-8a90-1b2c3d4e5f60",
        "crn": "crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/private",
        "name": "private",
        "cidr": "10.0.1.0/24",
        "vpc": { "id": "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9", "name": "production" },
        "route_table": { "id": "…", "crn": "…", "name": "private-routes" }
      }
    }
  ]
}
```

`subnet` é **null** quando a sub-rede referenciada não resolve mais — uma sub-rede excluída enquanto a NIC ainda a registra. Trate isso como um posicionamento indisponível e atualize; isso não significa que a interface não tenha sub-rede. Em Go, verifique `nic.Subnet != nil` antes de ler `nic.Subnet.VPC`.

As solicitações de lançamento usam referências de string `networks[].subnet`. Anexos de NIC posteriores requerem uma referência de `interface` existente. Não passe o objeto de sub-rede incorporado para qualquer operação.

<a id="attaching-and-detaching" />

### Anexação e desmontagem

`POST /v1/instances/{instance_id}/nics` anexa uma interface autônoma existente usando o campo `interface`. Ele mantém seu endereço, MAC e grupos de segurança. Não é possível criar uma NIC durante o anexo: crie-a primeiro através da API de interface de rede. A separação retorna-o ao estado autônomo.

A instância deve ser `running` ou `stopped`O anexo é durável no momento em que a chamada retorna — ele faz parte das especificações da instância e sobrevive a reinicializações — mas o convidado não tem o dispositivo quando a chamada retorna. A entrega é assíncrona e a resposta diz o que é necessário:

```json theme={null}
{ "attachment": { "interface_id": "...", "mac": "02:1a:2b:3c:4d:5e", "ip": "10.0.1.42", "boot_index": 1 } }
```

Uma instância **parada** aparece com o dispositivo em seu próximo início, e `restart_required` está ausente.

Uma instância **running** é dada ao dispositivo enquanto ele está em execução, onde a região pode fazer isso: o anexo não relata `restart_required`, e a interface aparece no convidado momentos depois. Pesquise `GET /v1/instances/{instance_id}/nics` para o anexo, ou observe o guest para um link que carrega o `mac` acima — esse MAC é a identidade da interface na rede, então é o que o dispositivo chega com.

Onde a região não pode, a resposta carrega `restart_required: true`, e uma reinicialização **hard** entrega-o:

```bash theme={null}
POST /v1/instances/{instance_id}/reboot
{ "hard": true }
```

Uma reinicialização suave não vai — é uma reinicialização ACPI dentro do mesmo lançador, e uma interface além da primeira é uma rede nesse lançador, fixa para a sua vida útil.

<Note>
  Quantas interfaces uma instância pode carregar é uma propriedade da região, e também se um convidado em execução pode receber uma. Onde o limite é um, um segundo encadeamento é recusado com **409** e um lançamento pedindo dois com **400**. Trate `restart_required` como a resposta para a região em que você está ao invés de assumir qualquer comportamento: ele está ausente quando não há nada a fazer, mas espere.
</Note>

<Warning>
  **O endereço é do DHCP, e o convidado tem que pedir por ele.** Nada configura a nova interface dentro do convidado — a plataforma coloca o dispositivo lá e o DHCP da sub-rede mantém seu aluguel. Uma imagem que traz um dispositivo de rede quando ele aparece (cloud-init com hotplug de rede habilitado, NetworkManager, `systemd-networkd` com uma correspondência de curinga) pega-o por conta própria; uma que configura apenas as interfaces com as quais ele inicializou irá manter o novo link, sem endereço, até que algo pergunte:

  ```bash theme={null}
  sudo dhclient -1 <device>
  ```

  Uma reinicialização configura-o de qualquer maneira, e é por isso que um convidado que ganhou o dispositivo ao vivo ainda pode parecer não configurado até que seu gerenciador de rede seja informado sobre isso.
</Warning>

<Tabs>
  <Tab title="Console">
    Abra a guia **Networking** da instância e escolha **Attach NIC**. Selecione uma **Interface** existente e, em seguida, **Attach interface**. A ação create do seletor abre a criação de interface quando você precisa de uma nova NIC autônoma.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST /v1/instances/{instance_id}/nics
    { "interface": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic compute instance attach-nic <instance-id> \
      --interface 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    _, err := compute.New(cfg).AttachInstanceNIC(ctx, instanceID,
        &compute.AttachInstanceNICRequest{
            Interface: "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        })
    ```
  </Tab>
</Tabs>

<Warning>
  A desconexão da **única** NIC em uma instância é recusada. Não há como alcançar um convidado sem interface, então a API não o deixará com uma.
</Warning>

<a id="public-addresses" />

### Endereços públicos

`networks[].floating_ip_assignment` solicita IPs flutuantes públicos no lançamento:

| Valor de mercado | Alocação de recursos |
| - | - |
| `none` | Sem IP flutuante (padrão). |
| `ipv4` | Um IPv4 IP flutuante. |
| `ipv6` | Um IPv6 IP flutuante. |
| `dual_stack` | Um de cada família. |
| `auto` | IPv4 e, quando a NIC tiver IPv6, IPv6. |

Cada família solicitada precisa de um endereço diretamente anexado e uma rota padrão para um gateway de internet nessa família. As alocações contam contra a cota correspondente `floating_ips_v4` ou `floating_ips_v6`. Ativar o IPv6 posteriormente não adiciona um IP flutuante automaticamente.

Todos os endereços IPv4 públicos são IPs flutuantes. O acesso de saída IPv4 também pode usar um gateway NAT. O IPv6 global nativo pode alcançar a Internet sem um IP flutuante quando as regras de roteamento e segurança o permitirem; o ULA privado requer um IP flutuante IPv6 público para acesso à Internet. Anexando um FIP público faz o tráfego de saída de seu endereço de destino usar esse mapeamento. Um FIP privado traduz o tráfego para o endereço virtual privado e suas respostas, sem alterar a saída não relacionada.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.