Administración del administrador de paquetes del sistema operativo mediante Azure IoT y OSConfig

Importante

La versión 1.0.3 (publicada el 28 de junio de 2022) incluye cambios importantes en los nombres de miembros que pueden afectar a los usuarios existentes. Para obtener más información, consulte: Los nombres de miembro pasan de PascalCase a camelCase en la versión 1.0.3.

Audiencia y ámbito

Este artículo está diseñado para admitir a los usuarios que aprovisionan o administran dispositivos con Azure IoT. Si eso no suena como usted, considere la posibilidad de echar un vistazo a la documentación de Audiences for OSConfig.

Este artículo trata sobre cómo obtener el estado del administrador de paquetes y establecer el estado deseado del administrador de paquetes. Por ejemplo:

Capacidad	Casos de uso
Asegúrese de que los administradores de paquetes extraen de los orígenes deseados	• La directiva de funcionamiento es que los administradores de paquetes de dispositivos deben extraer de un repositorio de paquetes privado con versiones aprobadas de bibliotecas y componentes. • Necesita dispositivos para obtener paquetes del repositorio de un proveedor específico.
Informar a los administradores de paquetes de los paquetes deseados	• La directiva de funcionamiento es que los dispositivos deben tener un paquete específico como "library-XYZ-v2" • La directiva de funcionamiento es que los dispositivos deben tener un gráfico de dependencias específico de los paquetes.
Comparación del paquete de dispositivos listas de orígenes o	• La directiva de funcionamiento es que la lista de paquetes instalados de los dispositivos implementados debe coincidir con un dispositivo correcto conocido.

Si está aquí para obtener información de referencia en lugar de ejemplos de casos de uso interactivos, puede ir directamente a la sección de referencia.

Importante

En este momento, las distribuciones basadas en apt , incluidas Debian y Ubuntu, están en el ámbito. Si desea desarrollar compatibilidad con distribuciones basadas en RPM, consulte la documentación de extensibilidad.

En un entorno sin apt (por ejemplo, la compilación a partir del origen y la ejecución en una distribución de la familia Red Hat), es posible que vea los siguientes mensajes de registro que indican que el módulo PackageManagerConfiguration no es aplicable.

• En osconfig_pmc.log, líneas que incluyen el texto siguiente:
  [ERROR] Cannot run on this platform, could not find required tool apt-get
• En osconfig_pnp_agent.log, líneas que incluyen el texto siguiente:
  [ERROR] PackageManagerConfiguration.state: MpiGet failed with 500

Ejemplos de casos de uso

Estos ejemplos pueden servir como puntos de partida para adaptarse a su entorno único.

Requisitos previos para probar los ejemplos en sistemas activos

Si usa este artículo como referencia, no hay requisitos previos. Puede revisar los ejemplos, copiar nombres de propiedad, etc.

Si desea probar los ejemplos en sistemas activos (recomendado), siga estos pasos:

1. Creación de una cuenta gratuita de Azure o uso de una cuenta existente

2. Conectar al menos un dispositivo habilitado para OSConfig a un IoT Hub

   Sugerencia

   Para crear fácilmente un IoT Hub con dispositivos (virtuales) conectados, consulte Creación de un entorno de laboratorio de OSConfig (con Azure IoT) en 5 minutos.

3. Prepárese para seguir las instrucciones de Azure Portal o las instrucciones de la CLI de Azure en los ejemplos:

Si prefiere usar el Azure Portal

1. Inicio de sesión en el Azure Portal y acceso a la página Información general de la IoT Hub

-OR- Si prefiere usar la CLI de Azure

1. RECOMENDADO: Use Azure Cloud Shell como entorno de Bash iniciando sesión en Azure Portal y, a continuación, iniciando Azure Cloud Shell en modo bash Captura de pantalla .
2. ALTERNATIVA: Si prefiere usar su propio entorno de Bash en lugar de Cloud Shell, instale la CLI de Azure e inicie sesión.
3. Asegúrese de que la extensión de Azure IoT está lista mediante la ejecución de az extension add --name azure-iot

---

Ejemplo 1. Especificar orígenes de paquetes deseados

En este ejemplo se muestra el flujo de trabajo de Azure IoT para asegurarse de que los dispositivos usan, como uno de sus orígenes de paquetes, el canal packages.microsoft.com prod para Ubuntu 18.04. Puede adaptar este ejemplo para usar cualquier origen de paquete. Por ejemplo, un repositorio público de distribución o versión diferente, un repositorio de un proveedor determinado o un repositorio privado que se conserva.

Las instrucciones están disponibles en tipos para el portal, la CLI, el dispositivo específico y el aprovisionamiento y la administración a escala.

Portal: dispositivo específico

1. En la página del portal de la IoT Hub, vaya al gemelo OSConfig para el dispositivo que desea administrar y agregue lo siguiente a la properties.desired sección, seguido de una coma para separarla del siguiente elemento de properties.desired.

   "PackageManagerConfiguration": {
      "desiredState": {
         "gpgKeys": {
            "pkgs-msft_key": "https://packages.microsoft.com/keys/microsoft.asc"
         },
         "sources": {
            "pkgs-msft_insiders-slow": "deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main"
         },
         "packages": [
         ]
      }
   }
   
   

   

Portal: a escala

Para establecer la configuración del administrador de paquetes para una flota de dispositivos, creará una configuración de IoT Hub (también conocida como IoT Hub Automatic Administración de dispositivos [ADM]).

1. En la página del portal de la Azure IoT Hub, elija Administración de dispositivos -->Configuraciones -->Agregar configuración del módulo.

2. Especifique un nombre y establezca la configuración de gemelos con la configuración deseada del administrador de paquetes. Establezca Module Twin Property (Propiedad de módulo gemelo)properties.desired. PackageManagerConfiguration en y establezca module Twin Property Content (Contenido de propiedad del módulo gemelo) en lo siguiente:

   {"desiredState": {
      "gpgKeys": {
         "pkgs-msft_key": "https://packages.microsoft.com/keys/microsoft.asc"
      },
      "sources": {
         "pkgs-msft_insiders-slow": "deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main"
      },
      "packages": [
      ]
   }}
   

3. Cree una métrica personalizada con el nombre correctoConfigured y los criterios de métrica , como se muestra a continuación. Esta consulta de métrica identificará todos los dispositivos que han alcanzado el estado deseado.

   SELECT deviceId FROM devices.modules
   where moduleId='osconfig'  
   and properties.reported.PackageManagerConfiguration.state.executionState=2
   

4. Para los módulos de destino, especifique los criterios para los que los dispositivos están en el ámbito. En este ejemplo, estableceremos como destino todos los dispositivos habilitados para OSConfig, especificando una condición de destino de FROM devices.modules where moduleId='osconfig'

   

CLI: dispositivo específico

1. Use el siguiente comando de ejemplo para establecer el gemelo OSConfig de un solo dispositivo, reemplazando <el identificador> de dispositivo o <el nombre> del centro para que coincida con el entorno.

   az iot hub module-twin update -m osconfig --desired \
   '{
     "PackageManagerConfiguration": {
       "desiredState": {
         "gpgKeys": {
           "pkgs-msft_key": "https://packages.microsoft.com/keys/microsoft.asc"
         },
         "sources": {
           "pkgs-msft_insiders-slow": "deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main"
         },
         "packages": [
         ]
       }
     }
   }' -d <device id> --hub-name <hub name>
   

   

CLI: a escala

Para establecer la configuración del administrador de paquetes para una flota de dispositivos, creará una configuración de IoT Hub (también conocida como IoT Hub Automatic Administración de dispositivos [ADM]).

1. Use el siguiente comando de ejemplo para crear una configuración de IoT Hub. Esta configuración incluye criterios de selección de destino, la configuración deseada y una métrica personalizada denominada successfullyConfigured. Asegúrese de reemplazar <el nombre> del centro por el nombre del IoT Hub.

   az iot hub configuration create --content "{
       \"moduleContent\": {
          \"properties.desired.PackageManagerConfiguration\": {
             \"desiredState\": {
             \"gpgKeys\": {
                \"pkgs-msft_key\": \"https://packages.microsoft.com/keys/microsoft.asc\"
             },
             \"sources\": {
                \"pkgs-msft_insiders-slow\": \"deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main\"
             },
             \"packages\": [
             ]
             }
          }
       }
   }" \
   --target-condition "from devices.modules where moduleId='osconfig'" --priority 10 \
   --metrics "{
     \"metrics\": {
       \"queries\": {
         \"successfullyConfigured\": \"select deviceId from devices.modules where moduleId='osconfig' AND properties.reported.PackageManagerConfiguration.state.executionState='2'\"
       }
     }
   }" --config-id my_pkg_mgr_config --hub-name <hub name>
   

   

El ejemplo 1 consiste en definir un nuevo origen de paquete. Para informar sobre lo mismo, continúe con el ejemplo 2.

Ejemplo 2. Informe sobre el estado y la configuración del administrador de paquetes

En este ejemplo, informaremos sobre:

1. Qué orígenes de paquetes se han agregado
2. Si algún dispositivo está experimentando errores de PackageManagerConfiguration

Portal: dispositivo específico

En el ejemplo 1 anterior, agregamos un valor PackageManagerConfiguration deseado al módulo gemelo OSConfig de un dispositivo específico. Ahora podemos observar los resultados.

1. Espere 1 minuto (para las comunicaciones de red, la actividad del lado del dispositivo, etc.) después de haber agregado el packageManagerConfiguration deseado en el ejemplo anterior.

2. En el módulo gemelo OSConfig del mismo dispositivo, vaya a las propiedades y, a continuación, notifique, PackageManagerConfiguration y, a continuación, estado.

3. Esto mostrará el estado más reciente de la configuración del administrador de paquetes.

   1. sourcesFileNames debe reflejar los dos canales agregados
   2. executionStatus debe ser 2. Para conocer los valores posibles, consulte la documentación sobre extensibilidad.

   

Portal: a escala

En el ejemplo 1 anterior, creamos una configuración de IoT Hub. Ahora podemos examinar las consultas de métricas de esa configuración para ver qué dispositivos se han configurado correctamente.

1. Vaya a la configuración de IoT Hub que creó en el ejemplo 1.

2. Observe la métrica Aplicada ; esto muestra qué dispositivos gemelos (en la nube) se han establecido con las propiedades deseadas.

   1. Esto puede tardar hasta 5 minutos después de crear la configuración.

3. Observe la métrica correctamenteConfigurada ; esto refleja qué dispositivos han completado la configuración de un extremo a otro

   

Sugerencia

La métrica Aplicada existe de forma predeterminada en todas las configuraciones de IoT Hub. La métrica successfullyConfigured se definió explícitamente al crear la configuración en el ejemplo 1.

1. Opcional: También puede observar la lista de dispositivos en los que la configuración del paquete y los paquetes designados se aplicaron correctamente mediante IoT Hub Consultas. Vaya a Administración de dispositivos -->Queries y ejecute la consulta siguiente:

   SELECT deviceId FROM devices.modules
    where moduleId='osconfig'  
    and properties.reported.PackageManagerConfiguration.state.executionState=2
   

   

CLI: dispositivo específico

1. Use el siguiente comando de ejemplo para mostrar la parte PackageManagerConfiguration.state del gemelo OSConfig de un solo dispositivo, reemplazando <el identificador> de dispositivo o <el nombre> del centro para que coincida con el entorno.

   az iot hub module-twin show -m osconfig --query properties.reported.PackageManagerConfiguration.state --output jsonc -d <device id> -n <hub name> 
   

   

CLI: a escala

En el ejemplo 1 anterior, creamos una configuración de IoT Hub. Ahora podemos examinar las consultas de métricas de esa configuración para ver qué dispositivos se han configurado correctamente.

1. Observe la métrica Aplicada

   Esto muestra qué dispositivos gemelos (en la nube) se han establecido con las propiedades deseadas.

   Esto puede tardar hasta 5 minutos después de crear la configuración.

   az iot hub configuration show-metric --metric-id appliedCount -c my_pkg_mgr_config -n <hub name> --metric-type system
   

2. Observe la métrica correctamenteConfigurada

   Esto refleja qué dispositivos han completado la configuración de un extremo a otro.

   az iot hub configuration show-metric --metric-id successfullyConfigured -c my_pkg_mgr_config -n <hub name> --metric-type user
   

   

3. Opcional: Informes, fuera de la configuración

   No es obligatorio usar la característica Métricas de IoT Hub Configuraciones para almacenar y usar consultas de informes o cumplimiento. También puede usar directamente la función query de IoT Hub, por ejemplo:

   az iot hub query -q \
   "SELECT deviceId, properties.reported.PackageManagerConfiguration.state FROM devices.modules WHERE moduleId='osconfig'" \
   --hub-name <hub name>
   

Información de referencia

Descripción del modelo de objetos

En esta sección se describen las propiedades del gemelo y los comportamientos correspondientes.

Es útil comprender que en Azure IoT hay dos modelos mentales o perspectivas para describir el contenido de los gemelos.

• Perspectiva deseada o notificada sin formato

  Este es el modelo de objetos principal IoT Hub. Lo usa IoT Hub servicio query, IoT Hub servicio Configurations, az iot hub module-twin comandos y vistas de gemelo sin formato en Azure Portal e IoT Explorer.

• Perspectiva mejorada del lenguaje de definición de gemelo digital (DTDL)

  DTDL (con patrones correspondientes, como Azure IoT Plug and Play [PnP]) permite a las aplicaciones y servicios anticipar, validar y contextualizar mejor el contenido gemelo. Esto lo usan las vistas PnP en IoT Explorer, el servicio Azure Digital Twins y, potencialmente, la solución en la nube al interactuar con IoT Hub.

En la mayoría de los casos siguientes, no se necesita ninguna distinción. Por ejemplo, "gpgKeys" se denomina "gpgKeys" en cualquier punto de vista.

En ciertos casos, una distinción puede ser útil. Por ejemplo, los valores path indicados a continuación. En esos casos, primero se da la descripción deseada o notificada sin formato, seguida de una perspectiva mejorada de DTDL entre paréntesis.

desiredState (entrada del administrador)

• Ruta de acceso: properties.desired.PackageManagerConfiguration.desiredState (DTDL: PackageManagerConfiguration componente -->desiredState propiedad grabable)

• Descripción: Entrada del administrador; habilita la adición de orígenes de paquetes y paquetes a dispositivos

• Miembros

  Nombre	Tipo	Notas
  sources	mapa de sourceName: sourceDescriptor pares (cadenas)	Para cada par del diccionario: • sourceName es un identificador especificado por el administrador, por ejemplo: *my-source-foo* • sourceDescriptor es una cadena de definición de origen en el formato utilizado por el administrador de paquetes; por ejemplo: deb [arch=amd64,armhf,arm64 signed-by=my-repo-key] https://packages.microsoft.com/ubuntu/18.04/prod focal main • Dentro sourceDescriptor del valor pasado a signed-by= debe ser el nombre de una clave de gpgKeys (descrita a continuación); por ejemplo: signed-by=my-source-foo-key • Al agregar o modificar un origen, se rellenará un archivo en sources.list.d (sobrescribir el archivo existente si está presente) con el descriptor de origen. • Para especificar que los dispositivos no deben usar un origen determinado (suponiendo que se definió anteriormente en sources.list.d, no en ningún otro lugar del sistema), incluya un par como "my-source-bar": ""; Si existe un archivo denominado my-source-bar.list en sources.list.d , se quitará. • Si ya no necesita una directiva no debe usar (por ejemplo, my-source-bar ya no es relevante después de algún tiempo), puede quitarla del gemelo deseado cambiando el valor de "my-source-bar": "" a "my-source-bar": null
  gpgKeys	mapa de key-name: uri pares (cadenas)	Se usa para informar al paquete administrador de claves públicas del repositorio; Para cada par del diccionario: • key-name es un identificador especificado por el administrador; por ejemplo: my-repo-foo-key, al que se hace referencia desde signed-by en . sources • uri es la ubicación de la clave pública de un repositorio; por ejemplo: https://packages.microsoft.com/keys/microsoft.asc • La clave se agrega como un archivo a /usr/share/keyrings/; Tenga en cuenta que, para garantizar la aplicabilidad de la clave, se usa esta ruta de acceso no específica de apt; apt solo aplicará esa clave a los orígenes que están asociados explícitamente (a través de signed-by • Para quitar un archivo de clave de /usr/share/keyrings establecido key-name para que coincida con el nombre de archivo (sin extensión) y establecido uri en ""
  packages	matriz de identificadores de paquete (cadenas)	• Indica al administrador de paquetes que asegúrese de que estos paquetes están instalados. • Análogo a los nombres> de los paquetes de instalación < en Debian • Aditivo (no destructivo) por naturaleza; por ejemplo, una lista vacía significa "no hacer nada" (no "desinstalar todos los paquetes del sistema")

• Carga de ejemplo (como se muestra en la sección del properties.desired gemelo de un gemelo IoT Hub)

  "PackageManagerConfiguration": {
      "desiredState": {
         "gpgKeys": {
            "pkgs-msft_key": "https://packages.microsoft.com/keys/microsoft.asc"
         },
         "sources": {
            "pkgs-msft_insiders-slow": "deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main"
         },
         "packages": [
            "cowsay"
         ]
      }
  }
  

state

• Ruta de acceso: properties.reported.PackageManagerConfiguration.state (perspectiva DTDL: PackageManagerConfiguration componente -->state propiedad de solo lectura)

• Descripción: Estado packageManagerConfiguration según lo notificado por el dispositivo

• Miembros

  Nombre	Tipo	Notas
  packagesFingerprint	string	• Huella digital opaca para la lista de todos los paquetes instalados en el dispositivo (no limitado a los paquetes a los que se hace referencia en desiredState.packages) • Se usa para comparar un gran número de dispositivos con un dispositivo conocido
  packages	matriz de identificadores de paquete (cadenas)	• Nombre y estado (versión o "error") de los paquetes especificados por el administrador de desiredState.packages • Si un paquete se ha instalado correctamente, el nombre va seguido del número de versión instalado. • Si no se pudo instalar un paquete, el nombre va seguido de "failed"
  sourcesFingerprint	string	• Huella digital opaca de los orígenes del paquete utilizados por el dispositivo • Se usa para comparar un gran número de dispositivos con un dispositivo conocido
  sourcesFilenames	matriz de nombres de archivo (cadenas)	• Lista de orígenes de paquete (como nombres de archivo, por ejemplo my-repo.list) que se han agregado al administrador de paquetes a través de /etc/apt/sources.list.d (en Debian) • Incluye cualquier fuente presente, independientemente de si se agregaron a través de desiredState.sources
  executionState	int	• Estado general de éxito/error • Los valores nominales son 0 (estado inicial, no se ha especificado desiredState) o 2 (correcto) • Para otros valores, consulte: documentación de extensibilidad
  executionSubstate	int	• Para conocer los valores posibles, consulte: documentación de extensibilidad.
  executionSubstateDetails	string	• Información adicional para solucionar problemas

• Carga de ejemplo (como se muestra en la sección del properties.reported gemelo)

  "PackageManagerConfiguration": {
      "state": {
         "packagesFingerprint": "9e7a85de3d067474e3621d7e1618f6ac0e2e8fc6cb9d60ee92af9927294114d3",
         "packages": [
            "cowsay=3.03+dfsg2-7"
         ],
         "executionState": 2,
         "executionSubstate": 0,
         "executionSubstateDetails": "",
         "sourcesFingerprint": "64b7de49c2be4ef2c180e4a978300fbb7b8a743a89e4038ba7ac6a91c31b625f",
         "sourcesFilenames": [
            "pkgs-msft_insiders-slow.list"
         ]
      }
  }
  

desiredState (notificado; confirmación del dispositivo)

• Ruta de acceso: properties.reported.PackageManagerConfiguration.desiredState (perspectiva de DTDL: PackageManagerConfiguration componente :> parte ACK de la desiredState propiedad que se puede escribir)

• Descripción: este elemento notificado adicional es una confirmación del dispositivo; para herramientas de administración e informes que complementa state, lo que permite que la cadena de herramientas de administración determine si el dispositivo aún ha recibido la intención de administrador capturada en el administrador grabable/deseado. desiredState

• Miembros

  Nombre	Tipo	Notas
  value	object	• Debe reflejarse properties.desired.PackageManagerConfiguration.desiredState
  ac	int	• Indica el éxito (valor 200) o error (valor 400) del dispositivo que recibe y procesa desiredState del administrador.

Pasos siguientes

Para obtener información general sobre los escenarios y funcionalidades de OSConfig, consulte:

• ¿Qué es OSconfig para IoT?

Para obtener ejemplos prácticos específicos, consulte:

• Creación de un entorno de laboratorio de OSConfig (con Azure IoT) en 5 minutos
• Inicio rápido: Consulta de ejemplos para empezar a trabajar con OSConfig y Azure IoT
• ¿Qué puedo aprovisionar y administrar?