Obtención de metadatos de instancia

El servicio de metadatos de instancia (IMDS) proporciona información sobre una instancia en ejecución, incluida una variedad de detalles sobre la instancia, sus tarjetas de interfaz de red virtual (VNIC) asociadas, sus asociaciones de volúmenes asociadas activadas para rutas múltiples y los metadatos personalizados que defina. IMDS también proporciona información a cloud-init, que puede utilizar para varias tareas de inicialización del sistema.

Puede encontrar parte de esta información en la consola en la página Detalles de instancia, o bien puede acceder a la instancia conectándose a la misma y utilizando el servicio de metadatos. El servicio se ejecuta en cada instancia y es un punto final HTTP que recibe en 169.254.169.254. Si una instancia tiene varias VNIC, debe enviar la solicitud mediante la VNIC principal.

Importante

Para aumentar la seguridad de las solicitudes de metadatos, recomendamos encarecidamente que actualice todas las aplicaciones para utilizar el punto final de IMDS versión 2, si está soportado por la imagen. A continuación, desactive las solicitudes a IMDS versión 1.

Actualización al servicio de metadatos de instancia v2

El servicio de metadatos de instancia está disponible en dos versiones, la versión 1 y la versión 2. IMDSv2 ofrece una mayor seguridad en comparación con v1.

Al desactivar IMDSv1 y permitir solicitudes solo a IMDSv2, las siguientes cosas cambian:

  • Todas las solicitudes se deben realizar a los puntos finales de v2 (/opc/v2). Las solicitudes a los puntos finales de v1 (/opc/v1 y /openstack) se rechazan con un error 404 de no encontrado.
  • Todas las solicitudes a los puntos finales de v2 deben incluir una cabecera de autorización. Las solicitudes que no incluyen la cabecera de autorización se rechazan.
  • Las solicitudes que se reenvían con las cabeceras HTTP Forwarded, X-Forwarded-For o X-Forwarded-Host se rechazan.

Para actualizar el servicio de metadatos de instancia en una instancia informática, utilice los siguientes pasos de alto nivel:

  1. Verifique que la instancia utiliza una imagen que soporte IMDSv2.
  2. Identifique las solicitudes a los puntos finales de v1 heredados.
  3. Migre todas las aplicaciones para soportar los puntos finales de v2.
  4. Desactive todas las solicitudes a los puntos finales de v1 heredados.

Imágenes soportadas para IMDSv2

IMDSv2 está soportado en las siguientes imágenes de plataforma:

  • Imágenes de Oracle Autonomous Linux 7.x publicadas a partir de junio de 2020
  • Imágenes de Oracle Linux 8.x, Oracle Linux 7.x y Oracle Linux 6.x publicadas a partir de julio de 2020

Otras imágenes de plataforma, la mayoría de imágenes personalizadas y la mayoría de imágenes de Marketplace no soportan IMDSv2. Las imágenes personalizadas de Linux pueden soportar IMDSv2 si cloud-init se actualiza a la versión 20.03 o posterior y Oracle Cloud Agent se actualiza a la versión 0.0.19 o posterior. Las imágenes personalizadas de Windows pueden soportar IMDSv2 si Oracle Cloud Agent se actualiza a la versión 1.0.0.0 o posterior; cloudbase-init no soporta IMDSv2.

Identificación de las solicitudes a los puntos finales de IMDSv1 heredados

Para identificar los puntos finales de IMDS específicos a los que se están realizando solicitudes y los agentes que están realizando las solicitudes, utilice la métrica InstanceMetadataRequests.

Para identificar las versiones de IMDS activadas para una instancia, realice cualquiera de las siguientes acciones:

  • Mediante la consola:
    1. Abra el menú de navegación y haga clic en Recursos informáticos. En Recursos informáticos, haga clic en Instancias.
    2. Haga clic en la instancia en la que está interesado.
    3. En la sección Detalles de instancia, junto a Servicio de metadatos de instancia, anote los números de versión.
  • Mediante la API: utilice la operación GetInstance o la operación ListInstances. En la respuesta, el atributo areLegacyImdsEndpointsDisabled del objeto InstanceOptions devuelve false si IMDSv1 e IMDSv2 están activados para la instancia. Devuelve true si IMDSv1 está desactivado.

Desactivación de las solicitudes a los puntos finales de IMDSv1 heredados

Después de migrar todas las aplicaciones para que solo realicen solicitudes a los puntos finales de IMDSv2, debe desactivar todas las solicitudes a los puntos finales de IMDSv1 heredados.
Importante

Verifique que la instancia no utilice los puntos finales de IMDSv1 antes de desactivar las solicitudes para IMDSv1. Si la instancia sigue dependiendo de IMDSv1 al desactivar las solicitudes, puede perder alguna funcionalidad.

Realice cualquiera de las siguientes acciones:

  • Mediante la consola:
    1. Abra el menú de navegación y haga clic en Recursos informáticos. En Recursos informáticos, haga clic en Instancias.
    2. Haga clic en la instancia en la que está interesado.
    3. En la sección Detalles de instancia, junto a Servicio de metadatos de instancia, haga clic en Editar.
    4. Para Versión de IMDS permitida, seleccione la opción Solo versión 2.
    5. Haga clic en Guardar cambios.
  • Mediante la API: utilice la operación UpdateInstance. En el cuerpo de solicitud, en el objeto InstanceOptions, transfiera el valor true para el atributo areLegacyImdsEndpointsDisabled.
Nota

Si desactiva IMDSv1 en una instancia que no soporta IMDSv2, es posible que no pueda conectarse a la instancia al iniciarla. Para volver a activar IMDSv1: mediante la consola, en la página Detalles de instancia, junto al servicio de metadatos de instancia, haga clic en Editar. Seleccione la opción Versión 1 y versión 2, guarde los cambios y, a continuación, reinicie la instancia. Mediante la API, utilice la operación UpdateInstance.

Política de IAM necesaria

No es necesaria ninguna política de IAM si se ha conectado a la instancia y utiliza cURL para obtener los metadatos.

Para administradores: los usuarios también pueden obtener metadatos de instancia a través de la API de Compute (por ejemplo, con GetInstance ). La política de Permitir que los usuarios inicien instancias de Compute abarca esa capacidad. Si el grupo especificado no necesita iniciar instancias o asociar volúmenes, puede simplificar esa política para que solo incluya manage instance-family y elimine las sentencias que involucran volume-family y virtual-network-family.

Para requerir que los puntos finales de IMDSv1 heredados estén desactivados en cualquier instancia nueva que se cree, utilice la siguiente política:

Allow group InstanceLaunchers to manage instances in compartment ABC
 where request.instanceOptions.areLegacyEndpointsDisabled= 'true'
Si no está familiarizado con las políticas, consulte Introducción a las políticas y Políticas comunes. Para obtener material de referencia sobre cómo escribir políticas para instancias, redes en la nube u otros recursos de la API de servicios principales, consulte Detalles de los servicios principales.

Limitación de solicitudes

Oracle Cloud Infrastructure aplica la limitación a solicitudes de servicio de metadatos de instancia para evitar el uso accidental o abusivo de los recursos. Para evitar la limitación, en lugar de consultar las credenciales de seguridad de cada transacción, almacene en caché las credenciales hasta que estén cerca de la caducidad.

Si realiza demasiadas solicitudes muy rápidamente, puede que vea algunas correctas y otras que fallan. Si experimenta limitación, Oracle recomienda volver a intentar con una inactividad exponencial.

Obtención de metadatos de instancia en imágenes de plataforma

Puede obtener metadatos de instancia para imágenes de plataforma mediante cURL en instancias de Linux. En instancias de Windows, puede utilizar cURL (si está soportada por la versión de Windows) o un explorador de Internet.

Todas las solicitudes del servicio de metadatos de instancia v2 deben incluir la siguiente cabecera:

Authorization: Bearer Oracle

Los metadatos de instancia a los que se accede mediante IMDSv2 están disponibles en las siguientes URL raíz:

  • Toda la información de la instancia:

    http://169.254.169.254/opc/v2/instance/
  • Información sobre las VNIC asociadas a la instancia:

    http://169.254.169.254/opc/v2/vnics/
  • Información sobre un volumen asociado a la instancia con asociación activada para rutas múltiples:

    http://169.254.169.254/opc/v2/volumeAttachments/

Los metadatos de instancia a los que se accede mediante IMDSv1 están disponibles en las siguientes URL raíz. No se necesita ninguna cabecera.

  • Toda la información de la instancia:

    http://169.254.169.254/opc/v1/instance/
  • Información sobre las VNIC asociadas a la instancia:

    http://169.254.169.254/opc/v1/vnics/
  • Información sobre un volumen asociado a la instancia con asociación activada para rutas múltiples:

    http://169.254.169.254/opc/v1/volumeAttachments/

Los valores de las claves de metadatos específicas están disponibles como subrutas por debajo de la URL raíz.

Para obtener metadatos de instancia para instancias de Linux

  1. Conexión a una instancia de Linux mediante SSH.
  2. Utilice cURL para emitir una solicitud GET a la URL de metadatos de instancia en la que está interesado. Por ejemplo:

    curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/instance/

Para obtener metadatos de instancia para instancias de Windows

Los pasos para obtener metadatos en una instancia de Windows dependen de la versión del servicio de metadatos de instancia del que esté solicitando metadatos.

Para obtener metadatos de instancia de Windows mediante IMDSv2:

  1. Conéctese a una instancia de Windows mediante una conexión de escritorio remoto.
  2. En función de si la versión de Windows incluye cURL, realice una de las siguientes acciones:

    • Si la versión de Windows incluye cURL, utilice cURL para emitir una solicitud GET a la URL de metadatos de instancia que le interese. Por ejemplo:

      curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/instance/
    • Si la versión de Windows no incluye cURL, puede obtener metadatos de instancia en su explorador de Internet. Navegue a la URL de metadatos de instancia que le interesa y transfiera una solicitud que incluya la cabecera de autorización. Consulte las instrucciones de su explorador para obtener más información sobre cómo incluir cabeceras en una solicitud. Es posible que necesite instalar una extensión de explorador de terceros que le permita incluir cabeceras de solicitud.

Para obtener metadatos de instancia de Windows mediante IMDSv1:

  1. Conéctese a una instancia de Windows mediante una conexión de escritorio remoto.
  2. Abra un explorador de Internet y, a continuación, navegue a la URL de metadatos de instancia en la que está interesado.

Reintentos para metadatos de instancia

El servicio de metadatos de instancia experimenta periódicamente cortos períodos de tiempo de inactividad para el mantenimiento. Por lo tanto, si intenta acceder a los puntos finales de IMDS, es posible que no estén disponibles. Como mejor práctica, implante la lógica de reintento al acceder a los puntos finales de IMDS. Se recomienda la siguiente estrategia: vuelva a intentarlo hasta tres veces con un timeout de 30 segundos si recibe una respuesta 404, 429 o 5xx. Para obtener más información y ejemplos, consulte la documentación del SDK para Java.

Claves de metadatos

Los metadatos de instancia incluyen claves de metadatos por defecto definidas por Compute y no se pueden editar, así como claves de metadatos personalizadas que cree.

Algunas entradas de metadatos son directorios que contienen claves de metadatos adicionales. En las siguientes tablas, las entradas con una barra final indican un directorio. Por ejemplo, regionInfo/ es un directorio que contiene otras claves de metadatos.

Claves de metadatos para una instancia

Los siguientes metadatos están disponibles sobre una instancia. Las rutas son relativas a http://169.254.169.254/opc/v2/instance/.

Entrada de metadatos Descripción
availabilityDomain

Dominio de disponibilidad en el que se está ejecutando la instancia. Este nombre incluye el prefijo específico del arrendamiento para el nombre de dominio de disponibilidad.

Ejemplo: Uocm:PHX-AD-1

faultDomain

Nombre del dominio de errores en el que se está ejecutando la instancia.

Ejemplo: FAULT-DOMAIN-1

compartmentId

OCID  del compartimento que contiene la instancia.

displayName Nombre fácil de recordar de la instancia.
hostname Nombre de host de la instancia.
id El OCID de la instancia.
image OCID de la imagen utilizada para iniciar la instancia.
metadata/

Directorio que contiene cualquier metadato personalizado que proporcione para la instancia.

Para consultar los metadatos de una clave de metadatos personalizada específica, utilice metadata/<key-name>, donde <key-name> es el nombre de la clave definida al crear la instancia.

metadata/ssh_authorized_keys Para las instancias de Linux, la clave SSH pública proporcionada al crear la instancia.
metadata/user_data Datos de usuario que cloud-init o cloudbase-init utilizará para ejecutar scripts personalizados o proporcionar una configuración personalizada.
region

Región que contiene el dominio de disponibilidad en el que se está ejecutando la instancia.

Para las regiones us-phoenix-1 y us-ashburn-1, se devuelven phx y iad, respectivamente. Para todas las demás regiones, se devuelve el identificador de región completo.

Ejemplos: phx, eu-frankfurt-1

canonicalRegionName

Identificador de región para la región que contiene el dominio de disponibilidad en el que se está ejecutando la instancia.

Ejemplo: us-phoenix-1

ociAdName

Dominio de disponibilidad en el que se está ejecutando la instancia. Este nombre se utiliza internamente y corresponde a la etiqueta del centro de datos.

Ejemplo: phx-ad-1

regionInfo/ Directorio que contiene información sobre la región que contiene el dominio de disponibilidad en el que se está ejecutando la instancia.
regionInfo/realmKey

Clave para el dominio  en el que se encuentra la región.

Ejemplo: oc1

regionInfo/realmDomainComponent

Dominio para el dominio.

Ejemplo: oraclecloud.com

regionInfo/regionKey

Clave de 3 letras para la región.

Ejemplo: PHX

regionInfo/regionIdentifier

Identificador de región.

Ejemplo: us-phoenix-1

shape Unidad de la instancia. La unidad determina el número de CPU y la cantidad de memoria asignada a la instancia. Puede enumerar todas las unidades disponibles llamando a la operación ListShapes.
state

Estado del ciclo de vida actual de la instancia. Para obtener una lista de valores permitidos, consulte Instancia.

Ejemplo: Running

timeCreated Fecha y hora de creación de la instancia, en el formato definido por RFC3339.
agentConfig/ Directorio que contiene información sobre el software y los plugins de Oracle Cloud Agent que se ejecutan en la instancia.
agentConfig/monitoringDisabled

Valor booleano que indica si el software Oracle Cloud Agent puede recopilar métricas de rendimiento y supervisar la instancia mediante los plugins de supervisión.

Los plugins de supervisión están controlados por este parámetro y por la configuración por plugin en el objeto pluginsConfig.

agentConfig/managementDisabled

Valor booleano que indica si el software Oracle Cloud Agent puede ejecutar todos los plugins de gestión disponibles.

Los plugins de gestión se controlan por este parámetro y por la configuración por plugin en el objeto pluginsConfig.

agentConfig/allPluginsDisabled Valor booleano que indica si Oracle Cloud Agent puede ejecutar todos los plugins disponibles. Esto incluye los plugins de gestión y supervisión.
agentConfig/pluginsConfig/ Directorio que contiene información sobre los plugins que Oracle Cloud Agent gestiona en la instancia.
agentConfig/pluginsConfig/name Nombre del plugin.
agentConfig/pluginsConfig/desiredState

Indica si el plugin debe estar activado o desactivado.

Para activar los plugins de supervisión y gestión, los atributos monitoringDisabled and managementDisabled también se deben definir en false.

freeformTags/ Directorio que contiene etiquetas de formato libre que se agregan a la instancia.
definedTags/ Directorio que contiene etiquetas definidas que se agregan a la instancia.

Esta es una respuesta de ejemplo que muestra toda la información de una instancia:

{
  "availabilityDomain" : "EMIr:PHX-AD-1",
  "faultDomain" : "FAULT-DOMAIN-3",
  "compartmentId" : "ocid1.tenancy.oc1..exampleuniqueID",
  "displayName" : "my-example-instance",
  "hostname" : "my-hostname",
  "id" : "ocid1.instance.oc1.phx.exampleuniqueID",
  "image" : "ocid1.image.oc1.phx.exampleuniqueID",
  "metadata" : {
    "ssh_authorized_keys" : "example-ssh-key"
  },
  "region" : "phx",
  "canonicalRegionName" : "us-phoenix-1",
  "ociAdName" : "phx-ad-1",
  "regionInfo" : {
    "realmKey" : "oc1",
    "realmDomainComponent" : "oraclecloud.com",
    "regionKey" : "PHX",
    "regionIdentifier" : "us-phoenix-1"
  },
  "shape" : "VM.Standard.E3.Flex",
  "state" : "Running",
  "timeCreated" : 1600381928581,
  "agentConfig" : {
    "monitoringDisabled" : false,
    "managementDisabled" : false,
    "allPluginsDisabled" : false,
    "pluginsConfig" : [ {
      "name" : "OS Management Service Agent",
      "desiredState" : "ENABLED"
    }, {
      "name" : "Custom Logs Monitoring",
      "desiredState" : "ENABLED"
    }, {
      "name" : "Compute Instance Run Command",
      "desiredState" : "ENABLED"
    }, {
      "name" : "Compute Instance Monitoring",
      "desiredState" : "ENABLED"
    } ]
  },
  "freeformTags": {
    "Department": "Finance"
  },
  "definedTags": {
    "Operations": {
      "CostCenter": "42"
    }
  }
}

Claves de metadatos para VNIC asociadas

Los siguientes metadatos están disponibles sobre las VNIC asociadas a la instancia. Las rutas son relativas a http://169.254.169.254/opc/v2/vnics/.

Entrada de metadatos Descripción
vnicId El OCID de la VNIC.
privateIp Dirección IP privada del objeto privateIp principal en la VNIC. La dirección está dentro del CIDR de la subred de la VNIC.
vlanTag

Etiqueta VLAN asignada por Oracle de la VNIC asociada.

Si la VNIC pertenece a una VLAN como parte de la solución de VMware para Oracle Cloud, el valor vlanTag es en su lugar el valor del atributo vlanTag para la VLAN. Consulte Vlan.

macAddr

Dirección MAC de la VNIC.

Si la VNIC pertenece a una VLAN como parte de la solución de VMware para Oracle Cloud, se aprende la dirección MAC. Si la VNIC pertenece a una subred, la dirección MAC es un valor estático proporcionado por Oracle.

virtualRouterIp Dirección IP del enrutador virtual.
subnetCidrBlock Bloque de CIDR de subred.
nicIndex Tarjeta de interfaz de red (NIC) física que utiliza la VNIC. Algunas unidades de instancia con hardware dedicado tienen dos NIC físicas activas (0 y 1). Si agrega una VNIC secundaria a una de estas instancias, puede especificar qué NIC utilizará la VNIC. Para obtener más información, consulte Tarjetas de interfaz de red virtual (VNIC).

A continuación, se muestra una respuesta de ejemplo que muestra las VNIC asociadas a una instancia:

[ {
  "vnicId" : "ocid1.vnic.oc1.phx.exampleuniqueID",
  "privateIp" : "10.0.3.6",
  "vlanTag" : 11,
  "macAddr" : "00:00:00:00:00:01",
  "virtualRouterIp" : "10.0.3.1",
  "subnetCidrBlock" : "10.0.3.0/24",
  "nicIndex" : 0
}, {
  "vnicId" : "ocid1.vnic.oc1.phx.exampleuniqueID",
  "privateIp" : "10.0.4.3",
  "vlanTag" : 12,
  "macAddr" : "00:00:00:00:00:02",
  "virtualRouterIp" : "10.0.4.1",
  "subnetCidrBlock" : "10.0.4.0/24",
  "nicIndex" : 0
} ]

Claves de metadatos para volúmenes asociados a asociaciones activadas para rutas múltiples

Los siguientes metadatos están disponibles sobre las asociaciones de volúmenes activadas para rutas múltiples asociadas a la instancia. Las rutas son relativas a http://169.254.169.254/opc/v2/volumeAttachments/.

Entrada de metadatos Descripción
id OCID de la asociación de volumen.
instanceId El OCID de la instancia.
volumeId OCID del volumen.
ipv4 Dirección IPv4 del destino iSCSI.
iqn IQN del destino iSCSI.
port Puerto del destino iSCSI.
multipathDevices Lista de dispositivos de rutas múltiples secundarios con las propiedades iqn, iqn y port.

A continuación, se muestra una respuesta de ejemplo con las asociaciones de volúmenes activadas para rutas múltiples para una instancia:

[
  {
    "id": "ocid1.volumeattachment.oc1.phx.exampleuniqueID",
    "instanceId": "ocid1.instance.oc1.phx.exampleuniqueID",
    "volumeId": "ocid1.volume.oc1.phx.exampleuniqueID",
    "ipv4": "169.254.2.2",
    "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
    "port": 3260,
    "multipathDevices":
    [
      {
        "ipv4": "exampleIP",
        "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
        "port": 3260
      },
      {
        "ipv4": "exampleIP",
        "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
        "port": 3260
      },
      {
        "ipv4": "exampleIP",
        "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
        "port": 3260
      },
      {
        "ipv4": "exampleIP",
        "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
        "port": 3260
      },
      {
        "ipv4": "exampleIP",
        "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
        "port": 3260
      },
      {
        "ipv4": "exampleIP",
        "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
        "port": 3260
      },
      {
        "ipv4": "exampleIP",
        "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
        "port": 3260
      },
      {
        "ipv4": "exampleIP",
        "iqn": "iqn.2015-12.com.oracleiaas:exampleuniqueID",
        "port": 3260
      }
    ]
  }
]