Recuperação de metadados de uma instância

Na maioria das vezes, você deseja coletar metadados de uma instância em execução e usá-los para inicializar outra instância de servidor virtual. Em outras ocasiões, talvez seja necessário coletar informações sobre anexos de rede ou anexos de volume. Revise o procedimento geral e as instruções passo a passo para habilitar o acesso ao serviço de metadados, criar um token de acesso de identidade e recuperar os metadados.

Procedimento geral para acessar os metadados da instância

A Tabela 1 descreve as etapas envolvidas no acesso aos metadados. As informações fornecem o contexto de cada etapa e os links para informações específicas para conclusão da etapa. Em um ambiente real, é mais provável que as etapas 3 a 5 sejam iniciadas pelo software de inicialização da sua instância no momento da inicialização ou por meio do cloud-init.

Procedimento geral para acessar metadados
Salto Contexto Chamado pelo serviço Ação do usuário
1 IBM Cloud VPC IU, CLI, API O acesso ao serviço de metadados está desativado por padrão. É possível habilitar o acesso ao serviço de metadados em uma instância existente no console, na CLI ou com a API.
2 IBM Cloud
Faça login na instância seguindo os procedimentos normais de inicialização.
3 Instância da VPC Serviço de metadados Execute o comando curl para chamar o serviço de tokens de metadados e obter um token de acesso de identidade.
4 Instância da VPC Serviço de metadados Execute um comando curl para chamar o serviço de metadados e recuperar as informações da instância. O token da etapa anterior é passado e os metadados são retornados.
5 Instância da VPC
Analise o JSON retornado na etapa anterior para adquirir os dados do usuário.

Procedimento de ponta a ponta para acessar metadados de uma instância

Localizar a instância em execução e habilitar o acesso ao serviço de metadados no console

  1. No console IBM Cloud, clique no ícone do menu Navegação > ícone VPC de infraestrutura > Computação > Instâncias do servidor virtual.

  2. Localize a instância em execução na lista. Clique no nome da instância para exibir seus detalhes. Na guia Overview (Visão geral), role até os detalhes da configuração Advanced (Avançada ) e clique no botão de alternância para permitir o acesso ao serviço de metadados.

  3. Se a instância já tiver um endereço IP flutuante (mostrado na guia Rede), use esse endereço para estabelecer uma conexão segura com o servidor. Se ele não tiver um endereço IP flutuante, atribua um a ele. Para obter mais informações, consulte as Próximas etapas no tópico Criação de instâncias de servidor virtual.

Localizar a instância em execução e habilitar o acesso ao serviço de metadados a partir da CLI

  1. Faça login na CLI do IBM Cloud.

  2. Localize a instância em execução usando o comando ibmcloud is instances, que lista as instâncias disponíveis na região.

    $ ibmcloud is instances
Listing instances in all resource groups and region us-south under account Test Account as user test.user@ibm.com...
ID                                          Name                    Status    Reserved IP    Floating IP      Profile    Image                                VPC                         Zone         Confidential Compute Mode   Enable Secure Boot   Resource group   Reservation Name   Cluster Network ID   Cluster Network Name   Cluster Network Attachments
0717_9c55d9d2-0685-4300-b475-49eb1b8c1faf   my-virtual-server-1     running   10.240.0.6     -                bx2-2x8    ibm-ubuntu-24-04-2-minimal-amd64-1   my-test-vpc                 us-south-1   disabled                    false                defaults         -                  -                    -                      -
0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6   my-virtual-server-2     running   10.240.64.11   169.47.94.48     bx2-2x8    ibm-ubuntu-24-04-6-minimal-amd64-3   my-test-vpc                 us-south-2   disabled                    false                defaults         -                  -                    -                      -
0727_d7ff31ef-75ed-42c6-b0fb-a5837a63d722   my-virtual-server-3     running   10.240.64.12   52.116.204.232   bx2-2x8    ibm-redhat-9-2-minimal-amd64-5       my-test-vpc                 us-south-2   disabled                    false                defaults         -                  -                    -                      -

    O serviço de metadados é suportado em todas as imagens customizadas e do banco de imagens, bem como nos perfis de CPU.

  3. Execute o comando ibmcloud is instance para confirmar se o acesso ao serviço de metadados está ativado. O exemplo a seguir mostra o valor false.

    $ ibmcloud is instance 0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6
Getting instance 0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6 under account Test Account as user test.user@ibm.com...
ID                                    0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6
Name                                  my-virtual-server-2
CRN                                   crn:v1:bluemix:public:is:us-south-2:a/a1234567::instance:0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6
Status                                running
Availability policy on host failure   restart
Confidential Compute Mode             disabled
Enable Secure Boot                    false
Startable                             true
Profile                               bx2-2x8
Architecture                          amd64
vCPU Manufacturer                     intel
vCPUs                                 2
Memory(GiB)                           8
Bandwidth(Mbps)                       4000
Volume bandwidth(Mbps)                1000
Network bandwidth(Mbps)               3000
Lifecycle Reasons                     Code   Message
                                      -      -
Lifecycle State                       stable
Metadata service                      Enabled   Protocol   Response hop limit
                                      false     http       1
Image                                 ID                                          Name
                                      r006-aa2af291-45b3-4f18-801c-8b7985e928f7   ibm-ubuntu-24-04-6-minimal-amd64-3
Numa Count                            1
VPC                                   ID                                          Name
                                      r006-01030e3c-2663-4f7d-ac55-651929dafe37   my-test-vpc
Zone                                  us-south-2
Resource group                        ID                                 Name
                                      6edefe513d934fdd872e78ee6a8e73ef   defaults
Created                               2025-03-06T19:24:02+00:00
Network Attachments                   Interface   Name   ID                                          Subnet         Subnet ID                                   Floating IP    VNI                                         Reserved IP
                                      Primary     eth0   0727-a3ff4d3e-be95-4a52-8025-b55b3c3285ea   my-subnet-01   0727-f24237f5-bdf0-4b94-ab4c-167a44b8bcb5   169.47.94.48   0727-dda9244a-64b9-421b-87e9-70549a70b4c3   10.240.64.11
Boot volume                           ID                                          Name                                Attachment ID                               Attachment name
                                      r006-9afd6e01-0466-4e7b-a38b-75bf39469a42   eat-client-poc-boot-1741289020000   0727-241f39a8-3573-4ebc-b512-33508eb970c9   undaunted-starved-slander-galleria
Reservation Affinity Policy           automatic
Reservation Affinity Pool             -
Reservation                           -
Health State                          ok

  4. Habilite o acesso ao serviço de metadados executando o comando ibmcloud is instance-update com a opção --metadata-service true.

    $ ibmcloud is instance-update  0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6 --metadata-service true
Updating instance 0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6 under account Test Account as user test.user@ibm.com...
ID                                    0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6
Name                                  my-virtual-server-2
CRN                                   crn:v1:bluemix:public:is:us-south-2:a/a1234567::instance:0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6
Status                                running
Availability policy on host failure   restart
Confidential Compute Mode             disabled
Enable Secure Boot                    false
Startable                             true
Profile                               bx2-2x8
Architecture                          amd64
vCPU Manufacturer                     intel
vCPUs                                 2
Memory(GiB)                           8
Bandwidth(Mbps)                       4000
Volume bandwidth(Mbps)                1000
Network bandwidth(Mbps)               3000
Lifecycle Reasons                     Code   Message
                                      -      -
Lifecycle State                       stable
Metadata service                      Enabled   Protocol   Response hop limit
                                      true      http       1
Image                                 ID                                          Name
                                      r006-aa2af291-45b3-4f18-801c-8b7985e928f7   ibm-ubuntu-24-04-6-minimal-amd64-3
Numa Count                            1
VPC                                   ID                                          Name
                                      r006-01030e3c-2663-4f7d-ac55-651929dafe37   my-test-vpc
Zone                                  us-south-2
Resource group                        ID                                 Name
                                      6edefe513d934fdd872e78ee6a8e73ef   defaults
Created                               2025-03-06T19:24:02+00:00
Network Attachments                   Interface   Name   ID                                          Subnet              Subnet ID                                   Floating IP    VNI                                         Reserved IP
                                      Primary     eth0   0727-a3ff4d3e-be95-4a52-8025-b55b3c3285ea   my-subnet-01   0727-f24237f5-bdf0-4b94-ab4c-167a44b8bcb5   169.47.94.48   0727-dda9244a-64b9-421b-87e9-70549a70b4c3   10.240.64.11
Boot volume                           ID                                          Name                                Attachment ID                               Attachment name
                                      r006-9afd6e01-0466-4e7b-a38b-75bf39469a42   eat-client-poc-boot-1741289020000   0727-241f39a8-3573-4ebc-b512-33508eb970c9   undaunted-starved-slander-galleria
Reservation Affinity Policy           automatic
Reservation Affinity Pool             -
Reservation                           -
Health State                          ok

  5. Se a instância já tiver um endereço IP flutuante, use esse endereço para estabelecer uma conexão segura com o servidor. Se ele não tiver um endereço IP flutuante, atribua um a ele. Para obter mais informações, consulte as Próximas etapas no tópico Criação de instâncias de servidor virtual.

Localizar a instância em execução e habilitar o acesso ao serviço de metadados com a API

  1. Localize a instância em execução listando as instâncias disponíveis na região. Selecione o ID da instância na resposta.

    curl -X GET "$vpc_api_endpoint/v1/instances?version=2025-05-13&generation=2" -H "Authorization: Bearer $iam_token"

  2. Recupere as informações da instância selecionada para confirmar se o acesso ao serviço de metadados está ativado.

    curl -X GET "$vpc_api_endpoint/v1/instances/0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6?version=2025-05-13&generation=2" -H "Authorization: Bearer $iam_token"

    A resposta da API mostra "enabled": false na seção metadata_service.

    {
 "availability_policy": {
     "host_failure": "restart",
     "host_maintenance": null
 },
 "bandwidth": 4000,
 "boot_volume_attachment": {
     "device": {
         "id": "0727-241f39a8-3573-4ebc-b512-33508eb970c9-mzpzd"
     },
     "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6/volume_attachments/0727-241f39a8-3573-4ebc-b512-33508eb970c9",
     "id": "0727-241f39a8-3573-4ebc-b512-33508eb970c9",
     "name": "undaunted-starved-slander-galleria",
     "volume": {
         "crn": "crn:v1:bluemix:public:is:us-south-2:a/a1234567::volume:r006-9afd6e01-0466-4e7b-a38b-75bf39469a42",
         "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-9afd6e01-0466-4e7b-a38b-75bf39469a42",
         "id": "r006-9afd6e01-0466-4e7b-a38b-75bf39469a42",
         "name": "eat-client-poc-boot-1741289020000",
         "resource_type": "volume"
     }
 },
 "confidential_compute_mode": "disabled",
 "created_at": "2025-03-06T19:24:02.000Z",
 "crn": "crn:v1:bluemix:public:is:us-south-2:a/a1234567::instance:0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6",
 "disks": [],
 "enable_secure_boot": false,
 "health_reasons": [],
 "health_state": "ok",
 "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6",
 "id": "0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6",
 "image": {
     "crn": "crn:v1:bluemix:public:is:us-south:a/a1234567::image:r006-aa2af291-45b3-4f18-801c-8b7985e928f7",
     "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-aa2af291-45b3-4f18-801c-8b7985e928f7",
     "id": "r006-aa2af291-45b3-4f18-801c-8b7985e928f7",
     "name": "ibm-ubuntu-24-04-6-minimal-amd64-3",
     "resource_type": "image"
 },
 "lifecycle_reasons": [],
 "lifecycle_state": "stable",
 "memory": 8,
 "metadata_service": {
     "enabled": false,
     "protocol": "http",
     "response_hop_limit": 1
 }
 .
 .
 .
}

  3. Habilite o acesso ao serviço de metadados fazendo uma PATCH /instances solicitação para a instância.

    curl -X PATCH "$vpc_api_endpoint/v1/instances/0727_ed12480a-40a4-41a0-98e3-6dfac8b25ad6?version=2025-05-13&generation=2" \
-H "Authorization: Bearer $iam_token" \
-d '{
     "metadata_service": {
        "enabled": true,
        "protocol": "http",
        "response_hop_limit": 1
        }
    }`

  4. Se a instância já tiver um endereço IP flutuante, use esse endereço para estabelecer uma conexão segura com o servidor. Se ele não tiver um endereço IP flutuante, atribua um a ele. Para obter mais informações, consulte Login na sua instância.

Estabelecimento de uma conexão segura com a instância do servidor virtual

Linux

O exemplo a seguir mostra a sintaxe de comando a ser usada para se conectar a uma instância de servidor baseada em Linux.

ssh -i <path to your private key file> <default-user-account>@<floating ip address>

Windows

Os usuários do Windows têm requisitos adicionais para acessar e utilizar o serviço de metadados. Para obter mais informações, consulte “Configurando servidores Windows para usar o serviço de metadados ”.

Se o servidor estiver executando um sistema operacional Windows, use um cliente RDP para se conectar a ele.

Para obter mais informações, consulte Conectando-se à sua instância do Linux ou Conectando-se à sua instância do Windows.

Coleta de informações do serviço de metadados

Na instância do servidor virtual, faça uma solicitação à API de identidade para recuperar um token de identidade. Especifique por quanto tempo você deseja que o token permaneça válido. Por exemplo, você pode especificar 3600 segundos (1 hora).

export identity_token=`curl -X PUT "http://api.metadata.cloud.ibm.com/identity/v1/token?version=2022-03-01"\
  -H "Metadata-Flavor: ibm"\
  -H "Accept: application/json"\
  -d '{
        "expires_in": 3600
      }' | jq -r '(.access_token)'`

A resposta fornece o token de acesso à identidade. O analisador o salva no arquivo .access_token.

O exemplo usa jq como um analisador sintático, uma ferramenta de terceiros licenciada sob a Licença MIT. Alguns sistemas operacionais não incluem o jq por padrão. Instale o jq antes de usar ou substitua-o por outro analisador JSON.

Recuperação das informações de inicialização

Depois de obter o token de identidade, você pode fazer uma solicitação de API ao serviço de metadados para coletar as informações de inicialização:

curl -X GET "http://api.metadata.cloud.ibm.com/metadata/v1/instance/initialization?version=2024-11-12"\
   -H "Accept: application/json"\
   -H "Authorization: Bearer $identity_token"\
   | jq -r

A resposta da API contém informações como a chave SSH e os dados do usuário que foram especificados quando o servidor virtual foi provisionado. Se você tiver configurado senhas, essas informações também serão retornadas. Você pode usar essas informações para inicializar uma nova instância de servidor virtual.

Recuperação de informações da instância

Faça uma solicitação GET "/metadata/v1/instance" para obter informações detalhadas sobre a instância.

curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance?version=2025-04-22" -H "Authorization: Bearer $identity_token"

A resposta lista todos os detalhes de uma instância, incluindo interfaces de rede, perfil de cálculo e anexos de volume.

{
  "boot_volume_attachment": {
    "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
    "name": "my-boot-volume-attachment",
    "volume": {
      "crn": "crn:[...]",
      "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
      "name": "my-boot-volume"
    }
  },
  "created_at": "2021-10-19T16:11:57Z",
  "crn": "crn:[...]",
  "disks": [],
  "id": "eb1b7391-2ca2-4ab5-84a8-b92157a633b0",
  "image": {
    "crn": "crn:[...]",
    "id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366",
    "name": "my-image"
  },
  "memory": 8,
  "name": "my-instance",
  "network_interfaces": [
    {
      "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
      "name": "my-network-interface",
      "primary_ipv4_address": "10.0.0.32",
      "resource_type": "network_interface",
      "subnet": {
        "crn": "crn:[...]",
        "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
        "name": "my-subnet",
        "resource_type": "subnet"
      }
    }
  ],
  "primary_network_interface": {
    "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
    "name": "my-network-interface",
    "primary_ipv4_address": "10.0.0.32",
    "resource_type": "network_interface",
    "subnet": {
      "crn": "crn:[...]",
      "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
      "name": "my-subnet",
      "resource_type": "subnet"
    }
  },
  "profile": {
    "name": "bx2-2x8"
  },
  "resource_type": "instance",
  "vcpu": {
    "architecture": "amd64",
    "count": 2
  },
  "volume_attachments": [
    {
      "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
      "name": "my-boot-volume-attachment",
      "volume": {
        "crn": "crn:[...]",
        "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
        "name": "my-boot-volume"
      }
    },
    {
      "id": "e77125cb-4df0-4988-a878-531ae0ae0b70",
      "name": "my-volume-attachment-1",
      "volume": {
        "crn": "crn:[...]",
        "id": "2cc091f5-4d46-48f3-99b7-3527ae3f4392",
        "name": "my-data-volume"
      }
    }
  ],
  "volume_bandwidth_qos_mode": "weighted",
  "vpc": {
    "crn": "crn:[...]",
    "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f",
    "name": "my-vpc",
    "resource_type": "vpc"
  },
  "zone": {
    "name": "us-south-1"
  }
}
  1. Use outros métodos de API para recuperar mais informações sobre a instância, como anexos de volume e de rede, ou coletar informações sobre chaves SSH, grupos de posicionamento ou interfaces de rede virtual. Para obter mais informações, consulte a Referência da API do serviço de metadados e o Resumo das informações do serviço de metadados.

A tabela a seguir mostra mais métodos para solicitações GET da API que você pode fazer para obter informações específicas sobre a instância.

URIs de metadados
Terminal de API Descrição
/metadata/v1/instance/cluster_network_attachments Lista de anexos de rede do cluster
/metadata/v1/instance/cluster_network_attachments/{id} Recuperar uma conexão de rede do cluster
/metadata/v1/instance/network_attachments Listar anexos de rede
/metadata/v1/instance/network_attachments/{id} Recuperar um anexo de rede
/metadata/v1/instance/network_interfaces Listar metadados para todas as interfaces de rede de uma instância.
/metadata/v1/instance/network_interfaces/{id} Recuperar metadados para uma interface de rede por ID.
/metadata/v1/instance/software_attachments Listar os metadados de todos os anexos de software de uma instância.
/metadata/v1/instance/software_attachments/{id} Recuperar metadados de um anexo de software por ID.
/metadata/v1/instance/volume_attachments Listar metadados para todos os anexos de volume de uma instância.
/metadata/v1/instance/volume_attachment/{id} Recuperar metadados de um anexo de volume por ID.

Próximas etapas

Utilize o perfil confiável da instância e gere um token do IAM a partir do token de identidade e acesso para outros serviços compatíveis com o IAM. Consulte Usando um perfil confiável para chamar os serviços ativados pelo IAM.