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

# Atualizar instância

> Atualize a descrição, os metadados, as tags ou a função do IAM de carga de trabalho de uma instância. Seu nome é imutável. A substituição de função é atômica e não precisa de reinicialização. Omita iam_role para preservá-lo; envie uma string vazia para detach. Edições simultâneas são serializadas na ordem de commit, e repetir a associação atual é um no-op. As credenciais STS existentes mantêm sua validade (até uma hora).


<Info>
  Requer a ação do IAM **`compute:UpdateInstance`**. 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.
</Info>


## OpenAPI

````yaml /pt/api-reference/specs/compute.yaml patch /v1/instances/{instance_id}
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/instances/{instance_id}:
    patch:
      tags:
        - Compute
      summary: Atualizar instância
      description: >
        Atualize a descrição, os metadados, as tags ou a função do IAM de carga
        de trabalho de uma instância. Seu nome é imutável. A substituição de
        função é atômica e não precisa de reinicialização. Omita iam_role para
        preservá-lo; envie uma string vazia para detach. Edições simultâneas são
        serializadas na ordem de commit, e repetir a associação atual é um
        no-op. As credenciais STS existentes mantêm sua validade (até uma hora).
      operationId: updateInstance
      parameters:
        - $ref: '#/components/parameters/InstanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceUpdateRequest'
      responses:
        '200':
          description: Instância atualizada
          content:
            application/json:
              schema:
                type: object
                properties:
                  instance:
                    $ref: '#/components/schemas/Instance'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    InstanceId:
      name: instance_id
      in: path
      description: ID da instância
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    InstanceUpdateRequest:
      type: object
      additionalProperties: false
      properties:
        iam_role:
          type: string
          description: >
            Anexe ou substitua a função de carga de trabalho da instância usando
            seu ID, nome ou CRN. Omita este campo para manter a função atual;
            envie uma string vazia para separá-la. Nulo não é aceito. Requer
            compute:UpdateInstance; attach/replace também requer iam:PassRole e
            uma política de confiança de função que permita essa instância.
            Somente instâncias gerenciadas pelo cliente em execução ou
            interrompidas sem operação em andamento são compatíveis com edições
            de função. Os membros do pool usam o modelo de lançamento do pool.
            Novas solicitações IMDS observam a associação confirmada
            imediatamente. As credenciais emitidas anteriormente não são
            revogadas e permanecem válidas até expirarem (até uma hora); os
            pedidos a bordo podem ser completados com a sua associação anterior.
          example: workload-role
        description:
          type: string
          maxLength: 1000
          example: Primary web server
        metadata:
          $ref: '#/components/schemas/Metadata'
        tags:
          $ref: '#/components/schemas/Tags'
    Instance:
      type: object
      required:
        - faults
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        crn:
          type: string
          readOnly: true
          description: Nome do recurso da nuvem
          example: crn:compute:sa-saopaulo-1:my-account:instance/web-01
        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-server-01
        description:
          type: string
          example: Primary web server
        task_state:
          type: string
          nullable: true
          description: Transição em andamento, se houver; nulo quando resolvido.
          example: null
        flavor:
          allOf:
            - $ref: '#/components/schemas/Flavor'
          description: >-
            Resolveu o tipo de instância (tamanho de cálculo) em que a instância
            é executada. Omitida se a linha de tipo de instância referenciada
            tiver sido aposentada.
        image:
          allOf:
            - $ref: '#/components/schemas/Image'
          description: >-
            Resolveu a imagem de origem da qual a instância inicializou. Omitida
            para uma inicialização somente de volume ou se a linha de imagem
            referenciada desaparecer.
        user_data:
          type: string
          description: >-
            Dados de usuário cloud-init codificados em Base64 fornecidos no
            lançamento.
        iam_role:
          allOf:
            - $ref: '#/components/schemas/InstanceRole'
          description: >-
            Resumo da função do IAM anexada, visível com acesso de leitura de
            instância 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.
        metadata:
          $ref: '#/components/schemas/Metadata'
        tags:
          $ref: '#/components/schemas/Tags'
        faults:
          type: array
          description: >-
            Falhas ativas ordenadas por last_at descendente, em seguida, o
            histórico interno id descendente para um desempate estável. Recursos
            saudáveis retornam [].
          items:
            $ref: '#/components/schemas/Fault'
        created_at:
          type: string
          format: date-time
          readOnly: true
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          readOnly: true
          example: '2024-01-15T10:30:00Z'
        launched_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          example: '2026-01-15T09:31:12Z'
        terminated_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          example: null
        desired_state:
          type: string
          enum:
            - running
            - stopped
            - deleted
          example: running
          description: >
            O que foi pedido. Apenas três valores, porque há apenas três coisas
            que você pode pedir para uma instância ser: Create/Start/Reboot para
            execução, Stop para parada, Delete para exclusão.
        current_state:
          $ref: '#/components/schemas/CurrentState'
          example: running
          description: >
            Leia este para responder "is it up" — os estados de transição vivem
            aqui, não em desired\_state, porque ninguém pede para eles serem
            criados. `stopping`.


            desired_state=running com current_state=stopped é uma instância que
            foi solicitada para iniciar e ainda não foi exibida.
    Metadata:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
    Tags:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
    Flavor:
      type: object
      description: >-
        Um tamanho de computação (vCPU + RAM). Um flavor não carrega nenhum
        tamanho de disco — o disco de inicialização é um volume do cliente com o
        tamanho no lançamento, limitado pelo min_disk_gb da imagem.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        crn:
          type: string
          readOnly: true
          description: Nome do recurso da nuvem
          example: crn:compute:sa-saopaulo-1:platform:flavor/standard-2
        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: m1.medium
        description:
          type: string
          example: Medium instance with 2 vCPUs and 4GB RAM
        vcpus:
          type: integer
          description: Número de CPUs virtuais
          example: 2
        ram_mb:
          type: integer
          description: Memória RAM em MB
          example: 4096
        class:
          type: string
          description: >-
            Roteamento de pool de host. "compartilhada" sobrescrever CPU para
            maior densidade; "dedicado" pinos cada vCPU 1:1 para um núcleo
            físico.
          enum:
            - shared
            - dedicated
          example: shared
        family:
          type: string
          description: >-
            Qual produto pode reservar o tipo de instância. Os tipos de
            instância "geral" são para instâncias regulares e pools de
            instâncias; os tipos de instância "loadbalancer" e "base de dados"
            são reservados para os produtos gerenciados (seus nós são operados
            por plataforma e têm preços correspondentes) e não podem ser usados
            para instâncias regulares.
          enum:
            - general
            - loadbalancer
            - database
          example: general
        net_mbps:
          type: integer
          minimum: 1
          readOnly: true
          description: >-
            Limite agregado de transferência de rede da instância em megabits
            por segundo. Omitido quando não há limite.
          example: 10000
        cpu_baseline_pct:
          type: integer
          minimum: 1
          readOnly: true
          description: >-
            Mínimo de CPU garantido como porcentagem de cada vCPU. Omitido
            quando não há mínimo garantido.
          example: 100
        cpu_burst_pct:
          type: integer
          minimum: 1
          readOnly: true
          description: >-
            Limite de CPU como porcentagem de cada vCPU. O valor 100 ou a
            omissão do campo permite usar todas as vCPUs.
          example: 100
        status:
          type: string
          enum:
            - active
            - disabled
          example: active
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    Image:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        crn:
          type: string
          example: >-
            crn:compute:sa-saopaulo-1:my-account:image/ubuntu-24.04/architecture/amd64/version/20260901
        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: ubuntu-24.04
        description:
          type: string
          example: Ubuntu 24.04 LTS (Noble Numbat)
        os:
          type: string
          example: ubuntu
        os_version:
          type: string
          example: '24.04'
        architecture:
          type: string
          example: amd64
        version:
          type: string
          description: >
            A identidade da compilação dentro de seu nome. Único lá: um nome é
            uma tag móvel, então não pode ser também o que diz duas construções
            separadas. Carimbado como um timestamp UTC quando o carregador não
            escolheu um.
          example: '20260807'
        is_current:
          type: boolean
          description: >
            Se esta é a versão resolve-by-name retorna para o seu (nome,
            arquitetura) — i.e. o alvo de tag atual do nome.
          example: true
        eol_date:
          type: string
          format: date
          description: >
            O dia em que a versão do SO desta imagem para de receber
            atualizações de segurança gratuitas para uma instalação padrão.
            Ausente quando ninguém registrou um — o que significa desconhecido,
            não "suportado indefinidamente".


            As imagens da plataforma são retiradas do catálogo após um período
            de carência após essa data. Eles permanecem inicializáveis por id
            até então, e a data é publicada bem antes para que você possa
            planejar a mudança.
          example: '2026-08-31'
        size_bytes:
          type: integer
          format: int64
          example: 2361393152
        min_disk_gb:
          type: integer
          minimum: 0
          maximum: 16384
          example: 10
        min_ram_mb:
          type: integer
          minimum: 0
          example: 1024
        status:
          type: string
          enum:
            - pending
            - importing
            - active
            - error
            - deleting
            - withdrawn
          description: >-
            Erro exatamente enquanto uma falha de erro ativo existe; o progresso
            de importação e exclusão permanecem independentemente retentáveis.
          example: active
        withdrawal_reason:
          type: string
          description: >
            Por que esta imagem foi retirada. Presente para imagens retiradas,
            incluindo aquelas com uma falha de erro independente: end_of_life
            para retirada de lançamento de plataforma (veja eol_date), ou legado
            para uma retirada migrada cuja razão original é desconhecida. As
            imagens retiradas retêm seus dados, mas não podem ser lançadas.
          example: end_of_life
        deletion_retention:
          type: object
          readOnly: true
          description: >
            Apresentar em respostas de lista de proprietários/detalhes enquanto
            a exclusão de imagem está esperando por referências de instância
            existente, reserva de origem ou pool de instâncias. As contagens
            incluem todas as contas de referência sem divulgar suas identidades.
            Os dados de backup permanecem intactos; a limpeza retoma quando as
            referências desaparecem. Falhas independentes ainda podem definir o
            status para erro.
          required:
            - reason
            - instances
            - instance_pools
          properties:
            reason:
              type: string
              enum:
                - in_use
            instances:
              type: integer
              minimum: 0
            instance_pools:
              type: integer
              minimum: 0
        faults:
          type: array
          readOnly: true
          description: >-
            Falhas ativas, mais recentes primeiro. Vazio para uma imagem
            saudável. As falhas de erro definem o status como erro sem
            desabilitar uma reintentância de importação ou limpeza elegível.
          items:
            $ref: '#/components/schemas/Fault'
        tags:
          $ref: '#/components/schemas/Tags'
        attributes:
          type: object
          additionalProperties:
            type: string
        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'
      required:
        - id
        - crn
        - name
        - version
        - architecture
        - status
        - faults
        - created_at
        - updated_at
    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
    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
    CurrentState:
      type: string
      description: >
        Os estados de transição vivem aqui, não em desired\_state — ninguém pede
        para eles serem criados. `stopping`.
      enum:
        - pending
        - building
        - running
        - stopping
        - stopped
        - rebooting
        - migrating
        - deleting
        - deleted
        - error
        - crashed
        - paused
        - suspended
    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
  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
    NotFound:
      description: Página não encontrada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              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
    InternalServerError:
      description: Erro interno do servidor
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An internal error occurred
              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 <token>`.
        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.