Documentação do Oracle Cloud Infrastructure

Atualizando Metadados da Instância

Você pode adicionar e atualizar metadados personalizados para uma instância de computação usando a CLI ou a documentação da API REST.

Quando você criar uma instância usando a operação LaunchInstance, poderá especificar metadados personalizados para a instância nos atributos metadata ou extendedMetadata do tipo de dados LaunchInstanceDetails.

Para atualizar os metadados de uma instância, use a operação UpdateInstance, especificando os metadados personalizados nos atributos metadata ou extendedMetadata do tipo de dados UpdateInstanceDetails.

O atributo metadata suporta pares de string chave/valor. O atributo extendedMetadata suporta objetos JSON aninhados. O tamanho combinado desses dois atributos pode ter no máximo 32.000 bytes.

Pode levar até um minuto para que as alterações se reflitam no serviço de metadados de instância.

Para obter permissões, consulte Política Obrigatória do Serviço IAM para Trabalhar com Instâncias.

Usando a API

Quando você usar a operação UpdateInstance, os metadados da instância serão a combinação dos valores especificados nos atributos metadata ou extendedMetadata do tipo de dados UpdateInstanceDetails. Qualquer conjunto de pares de chave/valor especificado para esses atributos na operação UpdateInstance substituirá os valores existentes para esses atributos. Portanto, você precisa incluir todos os valores de metadados da instância em cada chamada, não apenas os que você deseja adicionar. Se você deixar o atributo vazio ao chamar UpdateInstance, os valores de metadados existentes nesse atributo serão usados. Você não pode especificar um valor para a mesma chave de metadados duas vezes; isso fará com que a operação UpdateInstance falhe por haver chaves duplicadas.

Para entender isso, considere o exemplo de cenário em que você criou uma instância usando a operação LaunchInstance e especificou o seguinte par de chave/valor para o atributo metadata :

"myCustomMetadataKey" : "myCustomMetadataValue"

Se então você chamar a operação UpdateInstance e adicionar novos metadados especificando pares de chave/valor adicionais no atributo extendedMetadata, mas deixar o atributo metadata vazio, não inclua a chave/valor myCustomMetadataKey no atributo extendedMetadata, pois isso fará com que a operação falhe, uma vez que a chave já existe. Se você especificar valores para o atributo de metadados, será necessário incluir a chave/valor myCustomMetadataKey para mantê-lo nos metadados da instância. Nesse caso, você pode especificá-lo em qualquer um dos atributos.

Existem duas chaves reservadas, user_data e ssh_authorized_keys, que só podem ser definidas para uma instância no momento da inicialização. Elas não podem ser atualizadas posteriormente. Se você usar o atributo de metadados para adicionar ou atualizar os metadados de uma instância, será necessário garantir a inclusão dos valores especificados no momento do início dessas duas chaves; caso contrário, a operação UpdateInstance falhará.

Melhores Práticas para Atualizar os Metadados de uma Instância

Ao usar a operação UpdateInstance, recomenda-se o seguinte:

  • Use a operação GetInstance para recuperar os metadados personalizados existentes para a instância para garantir que você inclua os valores que deseja manter nos atributos apropriados ao chamar UpdateInstance. Os valores de metadados são retornados nos atributos metadata e extendedMetadata da Instância. Para ver um exemplo de código que demonstra isso, consulte UpdateInstanceExample no SDK para Java.

  • A menos que você esteja atualizando metadados personalizados que foram adicionados usando o atributo metadata, use o atributo extendedMetadata para adicionar metadados personalizados. Caso contrário, será necessário incluir os valores de hora de início para as chaves reservadas user_data e ssh_authorized_keys. Se você usar o atributo metadata para adicionar valores e deixar de fora os valores dessas chaves reservadas ou especificar valores diferentes para elas, haverá falha na chamada UpdateInstance.