Administrar entidades definidas en VMware Cloud Director

Para crear extensiones que proporcionen funcionalidades de VMware Cloud Director adicionales a los tenants, los proveedores de servicios pueden utilizar la API de VMware Cloud Director.

Las entidades definidas representan recursos externos que VMware Cloud Director puede administrar. Los desarrolladores de complementos de interfaz de usuario y extensiones pueden crear entidades definidas en tiempo de ejecución, lo cual permite a las extensiones y los complementos de interfaz de usuario almacenar y manipular la información específica de la extensión en VMware Cloud Director. Si crea una extensión y esta necesita almacenar un estado o referencias a recursos externos, la extensión puede utilizar entidades definidas en tiempo de ejecución en lugar de una base de datos local. Por ejemplo, una extensión de Kubernetes puede almacenar en entidades definidas en tiempo de ejecución la información sobre los clústeres de Kubernetes que administra. La extensión puede entonces proporcionar distintas API de extensión para administrar esos clústeres utilizando la información de las entidades definidas en tiempo de ejecución.

Solo puede acceder a las entidades definidas en tiempo de ejecución a través de la API de VMware Cloud Director. Los usuarios con privilegios de administrador pueden realizar un seguimiento y observar el funcionamiento de las extensiones comprobando el estado de las entidades definidas que crean las extensiones. Los estados de las entidades definidas también pueden ayudarle a solucionar problemas relacionados con las extensiones.

Tipo de entidad definida

En tiempo de ejecución se define el esquema de la información que se puede almacenar mediante entidades definidas. El esquema se define en el tipo de entidad a través de un documento JSON. Al crear un tipo de entidad definida, se crea un nuevo tipo de VMware Cloud Director personalizado similar a máquinas virtuales y vApps que se pueden administrar mediante extensiones y comportamientos. Por ejemplo, si consideramos el tipo de entidad NativeContainerCluster, cada instancia de este tipo contiene información sobre un clúster de Kubernetes específico. Para obtener la información sobre el clúster, VMware Cloud Director Container Service Extension se comunica con VMware Cloud Director a través de la API de VMware Cloud Director y proporciona la información necesaria a los usuarios.

Una vez que cree una instancia de un tipo de entidad definida, ya no podrá cambiar el tipo, el esquema ni los comportamientos. Para agregar nuevas funcionalidades al tipo de entidad, debe crear una nueva versión del tipo. Cuando una instancia de entidad definida se basa en una versión anterior del tipo de entidad, puede actualizar la entidad definida para utilizar una versión posterior del tipo estableciendo como valor para la propiedad tipo de la entidad el identificador del nuevo tipo. Cuando se crea una entidad definida, en la llamada de API, el contenido de la propiedad de entidad debe coincidir con el esquema JSON especificado en el tipo de entidad. Solo puede conceder acceso a un tipo de entidad a usuarios y organizaciones específicos. Puede establecer diferentes restricciones de acceso para las diferentes versiones de un tipo de entidad.

El esquema del tipo de entidad puede especificar el acceso a los diferentes campos de contenido. Puede marcar las propiedades como public, protected o private.

Tabla 1. Control de acceso a propiedad de tipo de entidad
Estado de propiedad	Control de acceso
Public	Todos los usuarios pueden ver y modificar el campo.
Protected	Todos los usuarios pueden ver el campo. Solo los usuarios con acceso de control total pueden crear y modificar el campo. Los usuarios deben tener el derecho Control total de administración: Tipo o tanto el derecho Control total: Tipo como ACL Control total.
Private	Solo los usuarios con acceso de control total pueden ver, crear y modificar el campo. Los usuarios deben tener el derecho Control total de administración: Tipo o tanto el derecho Control total: Tipo como ACL Control total

Por ejemplo: el esquema JSON de la propiedad de entidad clusterState puede ser el siguiente.

"clusterState" : {
  "type" : "string",
  "x-vcloud-restricted" : "protected"
}

Interfaces y comportamientos

Las entidades definidas también tienen interfaces que se pueden utilizar para definir comportamientos. Si se utiliza el ejemplo de Kubernetes, cada tipo de entidad de clúster tiene una implementación diferente de los comportamientos definidos en la interfaz de clúster de contenedores. Los comportamientos de tipo clúster de Tanzu Kubernetes se comunican con vSphere para realizar las acciones necesarias y los comportamientos de tipo clúster de contenedor nativo se comunican con la VMware Cloud Director Container Service Extension.

Todos los usuarios pueden ver las interfaces de las entidades definidas.

Existen diferentes formas de definir comportamientos.

Puede crear y publicar un flujo de trabajo de VMware Aria Automation Orchestrator y crear un comportamiento que invoque el flujo de trabajo.
Puede vincular cualquier funcionalidad a un comportamiento mediante un WebHook.
Con los comportamientos MQTT, se puede llamar a una funcionalidad de una extensión. Al utilizar MQTT, es posible comunicarse directamente con la extensión y la extensión puede proporcionar un estado más detallado.

El diagrama muestra que cada tipo de entidad tiene una implementación diferente de los comportamientos definidos en la interfaz de entidad definida en tiempo de ejecución. — Figura 1. Interfaces de entidad definida en tiempo de ejecución

Las interfaces, los tipos y los comportamientos de entidad definida en tiempo de ejecución tienen identificadores de API específicos.

Los identificadores de API de interfaz tienen el formato urn:vcloud:interface:nombre_de_proveedor:nombre_de_interfaz:versión.
Los identificadores de API de tipo tienen el formato urn:vcloud:type:nombre_de_proveedor:nombre_de_tipo:versión.
Los identificadores de API de comportamiento tienen el formato urn:vcloud:behavior-interface:nombre_de_comportamiento:nombre_de_proveedor:nombre_de_interfaz:versión o urn:vcloud:behavior-type:nombre_de_comportamiento:nombre_de_proveedor:nombre_de_interfaz:versión.

Crear una entidad definida en tiempo de ejecución

Para crear una entidad definida, comience por configurar los recursos externos y agregar la información necesaria a la entidad definida. Este proceso puede requerir algunas iteraciones. Para resolver la entidad definida, debe comprobar que el contenido del esquema tenga toda la información necesaria. Si el contenido no se corresponde con el esquema JSON especificado en el tipo, el estado de entidad definida cambia a Resolution_Error. Si introduce la información correctamente, el estado de entidad definida cambia a Resolved y está listo para su uso.

Debido a que las tareas realizan un seguimiento de todas las operaciones de entidades definidas en tiempo de ejecución de larga duración, puede utilizar la interfaz de usuario de VMware Cloud Director para supervisar la creación de entidades definidas, la invocación de comportamientos, etc. Cuando el estado de una entidad definida cambia a Resolved, la tarea correspondiente en la interfaz de usuario se muestra como Succeeded.

Cuando se crea una entidad definida en una organización de tenant, no se puede compartir la entidad definida con tenants de otra organización. Si crea una entidad definida en la organización System, puede compartirla con usuarios tenant u organizaciones tenant.

Ejemplo de llamada API para crear una entidad definida

Este ejemplo proporciona una llamada API de ejemplo para crear una nueva entidad del tipo pksContainerCluster.

POST https://host/cloudapi/1.0.0/entityTypes/urn:vcloud:type:vendorA:pksContainerCluster:1.0.0
{
   "name": "testEntity",
   "entity": {
      "cluster": {
         "name": "testCluster",
         "nodes": ["node1"]
      }
   }
}

Acceso a instancias de entidad definidas

Dos mecanismos complementarios controlan el acceso a las entidades definidas en tiempo de ejecución.

Derechos: cuando crea un tipo de entidad definida en tiempo de ejecución, se crea un paquete de derechos para ese tipo. Para proporcionar acceso a determinadas operaciones, debe asignar derechos de este paquete a otras funciones. Cada paquete tiene cinco derechos específicos del tipo: Ver: Tipo, Editar: Tipo, Control total: Tipo, Vista de administración: Tipo y Control total de administración: Tipo.

Ver: Tipo, Editar: Tipo y Control total: Tipo solo funcionan en combinación con una entrada de ACL.
Lista de control de acceso (ACL): la tabla de ACL contiene entradas que definen el acceso que tienen los usuarios a entidades específicas del sistema. Proporciona un nivel de control adicional para las entidades. Por ejemplo, mientras que el derecho Editar: Tipo especifica que un usuario puede modificar las entidades a las que tiene acceso, la tabla de ACL define las entidades a las que tiene acceso el usuario.

Los administradores del sistema con el derecho Ver ACL general pueden ver las ACL asignadas a una entidad definida específica mediante la API de accessControls. Consulte OpenAPI de VMware Cloud Director.

Los administradores del sistema con el derecho Administrar ACL general pueden crear, modificar y eliminar ACL específicas mediante la API de accessControls.

Tabla 2. Derechos y entradas de ACL para operaciones de RDE
Operación de entidad	Opción	Descripción
Leer	Derecho Vista de administración: Tipo	Los usuarios con este derecho pueden ver todas las entidades definidas en tiempo de ejecución de este tipo dentro de una organización.
Leer	Derecho Ver: Tipo y entrada de ACL >= Ver	Los usuarios con este derecho y una ACL de nivel de lectura pueden ver tiempo de ejecución de este tipo.
Modificar	Derecho Control total de administración: Tipo	Los usuarios con este derecho pueden crear, ver, modificar y eliminar entidades definidas en tiempo de ejecución de este tipo en todas las organizaciones.
Modificar	Derecho Editar: Tipo y entrada de ACL >= Cambiar	Los usuarios con este derecho y una ACL de nivel de modificación pueden crear, ver y modificar entidades definidas en tiempo de ejecución de este tipo.
Eliminar	Derecho Control total de administración: Tipo	Los usuarios con este derecho pueden crear, ver, modificar y eliminar entidades definidas en tiempo de ejecución de este tipo en todas las organizaciones.
Eliminar	Derecho Control total: Tipo y entrada de ACL = Control total	Los usuarios con este derecho y una ACL de nivel de control total pueden crear, ver, modificar y eliminar entidades definidas en tiempo de ejecución de este tipo.

Puede utilizar la API o la interfaz de usuario de VMware Cloud Director para publicar el paquete de derechos en cualquier organización que desee que administre las entidades de este tipo. Después de publicar el paquete de derechos, puede asignar derechos del paquete a funciones dentro de la organización.

Puede utilizar la API de VMware Cloud Director para editar la tabla de ACL.

Acceso a operaciones de tipo e interfaz de entidad definida

Las operaciones de tipo e interfaz de entidad definida requieren derechos específicos que es posible que algunos proveedores de servicios no tengan. Antes de realizar una operación, compruebe que tiene los derechos necesarios.

Tabla 3. Derechos para operaciones de tipo e interfaz de entidad definida
Operación	Requisito
Ver y consultar interfaz	Todos los usuarios tienen los derechos necesarios.
Crear interfaz	Debe tener el derecho Crear nueva definición de entidad personalizada.
Editar interfaz	Debe tener el derecho Editar definición de entidad personalizada.
Eliminar interfaz	Debe tener el derecho Eliminar definición de entidad personalizada.
Crear tipo	Debe tener el derecho Crear nueva definición de entidad personalizada.
Tipo de vista	El requisito mínimo es ACL de tipo `ReadOnly`.
Editar y eliminar tipo	Debe tener el derecho Editar/eliminar definición de entidad personalizada y una ACL de tipo `FullControl`.

Trabajar con entidades definidas en tiempo de ejecución

Para invocar comportamientos de una entidad definida, debe estar en el estado Resolved. Para eliminar una entidad definida, debe estar en el estado Resolved o Resolution_Error.

Puede modificar los tipos de entidades y las interfaces solo si no tienen instancias. Solo puede modificar el tipo de entidad al que se hace referencia cambiando su versión.

Para diagnosticar problemas relacionados con el acceso a entidades definidas, puede utilizar las API de consulta de ACL de entidades y comprobar los derechos necesarios. Además, el paquete de derechos de un tipo de entidad debe publicarse en los tenants que desee utilizar.