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 atributosmetadata
eextendedMetadata
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 atributoextendedMetadata
para adicionar metadados personalizados. Caso contrário, será necessário incluir os valores de hora de início para as chaves reservadasuser_data
essh_authorized_keys
. Se você usar o atributometadata
para adicionar valores e deixar de fora os valores dessas chaves reservadas ou especificar valores diferentes para elas, haverá falha na chamadaUpdateInstance
.