Updating Instance Metadata
When you create an instance using the LaunchInstance operation you can specify custom metadata for the instance in the LaunchInstanceDetails datatype's
extendedMetadata attributes. To update an instance's metadata, use the UpdateInstance operation, specifying the custom metadata in the UpdateInstanceDetails datatype's
extendedMetadata attributes. The
metadata attribute supports key/value string pairs while the
extendedMetadata attribute supports nested JSON objects.
Required IAM Policy
To use Oracle Cloud Infrastructure, you must be given the required type of access in a An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. you should work in.
For administrators: The policy in Let users launch instances includes the ability to rename an instance. If the specified group doesn't need to launch instances or attach volumes, you could simplify that policy to include only
manage instance-family, and remove the statements involving
If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for instances, cloud networks, or other Core Services API resources, see Details for the Core Services.
Using the API
When you use the
UpdateInstance operation, the instance's metadata will be the combination of the values specified in the UpdateInstanceDetails datatype's
extendedMetadata attributes. Any set of key/value pairs specified for these attributes in the
UpdateInstance operation will replace the existing values for these attributes, so you need to include all the metadata values for the instance in each call, not just the ones you want to add. If you leave the attribute empty when calling
UpdateInstance, the existing metadata values in that attribute will be used. You cannot specify a value for the same metadata key twice, this will cause the
UpdateInstance operation to fail due to there being duplicate keys.
To understand this, consider the example scenario where you created an instance using the
LaunchInstance operation and specified the following key/value pair for the
"myCustomMetadataKey" : "myCustomMetadataValue"
If you then call the
UpdateInstance operation, and add new metadata by specifying additional key/value pairs in the
extendedMetadata attribute, but you leave the
metadata attribute empty, do not include the
myCustomMetadataKey key/value in the
extendedMetadata attribute, as this will cause the operation to fail since that key already exists. If you do specify values for the metadata attribute, you need to include the
myCustomMetadataKey key/value to maintain it in the instance's metadata. In this case, you can specify it in either of the attributes.
There are two reserved keys,
ssh_authorized_keys, that can only be set for an instance at launch time, they cannot be updated later. If you use the metadata attribute to add or update metadata to an instance, you need to ensure that you include the values specified at launch time for both these keys, otherwise the
UpdateInstance operation will fail.
Best Practices for Updating an Instance's Metadata
When using the
UpdateInstance operation, Oracle recommends the following:
Use the GetInstance operation to retrieve the existing custom metadata for the instance to ensure that you include the values you want to maintain in the appropriate attributes when you call
UpdateInstance. The metadata values are returned in the
extendedMetadataattributes for the Instance . For a code example demonstrating this, see the UpdateInstanceExample in the SDK for Java.
Unless you are updating custom metadata that was added using the
metadataattribute, use the
extendedMetadataattribute to add custom metadata. Otherwise you need to include the launch time values for the
ssh_authorized_keysreserved keys. If you use the
metadataattribute to add values and you leave out the values for these reserved keys or specify different values for them, the
UpdateInstancecall will fail.