Gerenciando entidades definidas no VMware Cloud Director

Para criar extensões que fornecem recursos adicionais do VMware Cloud Director aos tenants, os provedores de serviços podem usar a API do VMware Cloud Director.

Entidades definidas representam recursos externos que o VMware Cloud Director pode gerenciar. Os desenvolvedores de plug-ins de extensão e IU podem criar entidades definidas em tempo de execução, permitindo que extensões e plug-ins de UI armazenem e manipulem as informações específicas da extensão no VMware Cloud Director. Ao criar uma extensão, você precisar armazenar um estado ou referências a recursos externos, a extensão poderá usar entidades definidas em tempo de execução em vez de um banco de dados local. Por exemplo, uma extensão do Kubernetes pode armazenar informações sobre os clusters do Kubernetes que ela gerencia em entidades definidas em tempo de execução. A extensão pode fornecer APIs de extensão para gerenciar esses clusters usando as informações das entidades definidas em tempo de execução.

Você pode acessar entidades definidas em tempo de execução somente por meio da API do VMware Cloud Director. Os usuários com privilégios de administrador podem rastrear e observar a maneira como as extensões operam verificando o estado das entidades definidas que as extensões criam. Os estados das entidades definidas também podem ajudá-lo a solucionar problemas com as extensões.

Tipo de Entidade Definida

Você define em tempo de execução o esquema das informações que você pode armazenar usando entidades definidas. O esquema é definido no tipo de entidade por meio de um documento JSON. Quando cria um tipo de entidade definido, você cria um novo tipo personalizado do VMware Cloud Director semelhante a VMs e vApps, que pode ser gerenciado por extensões e comportamentos. Por exemplo, se considerarmos o tipo de entidade do NativeContainerCluster, cada instância desse tipo conterá informações sobre um cluster Kubernetes específico. Para obter as informações sobre o cluster, o VMware Cloud Director Container Service Extension se comunica com o VMware Cloud Director por meio da API do VMware Cloud Director e fornece as informações necessárias aos usuários.

Depois de criar uma instância de um tipo de entidade definido, você não poderá mais alterar o tipo, o esquema e os comportamentos. Para adicionar novas funcionalidades ao tipo de entidade, você deve criar uma nova versão do tipo. Quando uma instância de entidade definida é baseada em uma versão anterior do tipo de entidade, você pode fazer upgrade da entidade definida para usar uma versão posterior do tipo, definindo a propriedade de tipo da entidade para o ID do novo tipo. Ao criar uma entidade definida, na chamada de API, o conteúdo da propriedade da entidade deve corresponder ao esquema JSON especificado no tipo de entidade. Você pode conceder acesso a um tipo de entidade apenas para usuários e organizações específicos. Você pode definir restrições de acesso diferentes para as diferentes versões de um tipo de entidade.

O esquema do tipo de entidade pode especificar o acesso aos diferentes campos de conteúdo. Você pode marcar propriedades como public, protected ou private.

Tabela 1. Controle de Acesso de Propriedade do Tipo de Entidade
Status da Propriedade	Controle de Acesso
Public	Todos os usuários podem visualizar e modificar o campo.
Protected	Todos os usuários podem visualizar o campo. Somente usuários com acesso de Controle Total podem criar e modificar o campo. Os usuários devem ter o direito Controle Total de Administrador: TIPO ou o direito Controle Total: TIPO e uma ACL de Controle Total.
Private	Somente usuários com acesso ao Controle Total podem visualizar, criar e modificar o campo. Os usuários devem ter o direito Controle Total de Administrador: TIPO ou o direito Controle Total: TIPO e uma ACL de Controle Total

Por exemplo, o esquema JSON para a propriedade de entidade do clusterState pode ser o seguinte.

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

Interfaces e comportamentos

As entidades definidas também têm interfaces que você pode usar para definir comportamentos. Se usarmos o exemplo do Kubernetes, cada tipo de entidade de cluster terá uma implementação diferente dos comportamentos definidos na interface do cluster de contêiner. Os comportamentos do tipo de cluster do Tanzu Kubernetes se comunicam com o vSphere para realizar as ações necessárias e os comportamentos do tipo de cluster do contêiner nativo se comunicam com o VMware Cloud Director Container Service Extension.

Todos os usuários podem ver as interfaces de entidades definidas.

Existem diferentes maneiras de definir comportamentos.

Você pode criar e publicar um fluxo de trabalho do VMware Aria Automation Orchestrator e criar um comportamento que invoca o fluxo de trabalho.
Você pode vincular qualquer funcionalidade a um comportamento usando um WebHook.
Com os comportamentos MQTT, você pode chamar uma funcionalidade em uma extensão. Usando o MQTT, você pode se comunicar diretamente com a extensão e a extensão pode fornecer um status mais detalhado.

O diagrama mostra que cada tipo de entidade tem uma implementação diferente dos comportamentos definidos na interface de entidade definida em tempo de execução. — Figura 1. Interfaces de entidade definidas em tempo de execução

As interfaces, tipos e comportamentos de entidades definidas de tempo de execução têm IDs de API específicos.

Os IDs da API de interface estão na forma de urn:vcloud:interface:vendor_name:interface_name:version.
Os IDs de API de tipo estão na forma de urn:vcloud:type:vendor_name:type_name:version.
Os IDs de API de comportamento estão na forma de urn:vcloud:behavior-interface:behavior_name:vendor_name:interface_name:version ouurn:vcloud:behavior-type:behavior_name:vendor_name:interface_name:version.

Criação de uma entidade definida de tempo de execução

Para criar uma entidade definida, comece configurando os recursos externos e adicionando as informações necessárias à entidade definida. Esse processo pode exigir algumas iterações. Para resolver a entidade definida, você deve verificar se o conteúdo do esquema tem todas as informações necessárias. Se o conteúdo não corresponder ao esquema JSON especificado no tipo, o estado da entidade definida será alterado para Resolution_Error. Se você preencher as informações corretamente, o estado da entidade definida será alterado para Resolved e estará pronto para uso.

Como as tarefas rastreiam todas as operações de entidade definidas de tempo de execução de longa duração, você pode usar a UI do VMware Cloud Director para monitorar a criação de entidades definidas, invocação de comportamento e assim por diante. Quando o status de uma entidade definida é alterado para Resolved, a tarefa correspondente na UI aparece como Succeeded.

Quando você cria uma entidade definida em uma organização de tenant, não pode compartilhar a entidade definida com tenants em outra organização. Se você criar uma entidade definida na organização do System, poderá compartilhá-la com usuários ou organizações de tenant.

Chamada à API de amostra para criar uma entidade definida

O exemplo fornece uma chamada de API de amostra para criar uma nova entidade do tipo do 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"]
      }
   }
}

Acesso a instâncias de entidades definidas

Dois mecanismos complementares controlam o acesso a entidades definidas em tempo de execução.

Direitos - Ao criar um tipo de entidade definida de tempo de execução, você cria um pacote de direitos para o tipo. Para fornecer acesso a operações específicas, você deve atribuir direitos desse pacote a outras funções. Cada pacote tem cinco direitos específicos de tipo: Exibir: TYPE, Editar: TYPE, Controle Total: TYPE, Exibição do Administrador: TYPE e Controle Total do Administrador: TYPE.

Os direitos Exibir: TYPE, Editar: TYPE e Controle Total: TYPE funcionam apenas em combinação com uma entrada ACL.
Lista de controle de acesso (ACL) - A tabela da ACL contém entradas que definem os usuários de acesso com entidades específicas no sistema. Ela fornece um nível extra de controle sobre as entidades. Por exemplo, enquanto um direito Editar: TYPE especifica que um usuário pode modificar entidades às quais eles têm acesso, a tabela de ACL define quais entidades o usuário tem acesso.

Os administradores do sistema com o direito Exibir ACL Geral podem exibir as ACLs atribuídas a uma entidade definida específica usando a API de accessControls. Consulte OpenAPI do VMware Cloud Director.

Os administradores do sistema com o direito Gerenciar ACL Geral podem criar, modificar e remover ACLs específicas usando a API de accessControls.

Tabela 2. Direitos e entradas da ACL para operações da RDE
Operação da entidade	Opção	Descrição
Leitura	Direito Exibição do Administrador: TYPE	Os usuários com esse direito podem ver todas as entidades definidas em tempo de execução desse tipo em uma organização.
Leitura	Direito Exibir: TYPE e entrada da ACL >= Exibir	Os usuários com esse direito e uma ACL de nível de leitura podem exibir entidades definidas de tempo de execução desse tipo.
Modificar	Direito Controle Total do Administrador: TYPE	Os usuários com esse direito podem criar, visualizar, modificar e excluir entidades definidas em tempo de execução desse tipo em todas as organizações.
Modificar	Direito Editar: TYPE e entrada da ACL >= Alterar	Os usuários com esse direito e a ACL de nível de modificação podem criar, exibir e modificar entidades definidas de tempo de execução desse tipo.
Excluir	Direito Controle Total do Administrador: TYPE	Os usuários com esse direito podem criar, visualizar, modificar e excluir entidades definidas em tempo de execução desse tipo em todas as organizações.
Excluir	Direito Controle Total: TYPE e entrada da ACL = Controle Total	Os usuários com esse direito e a ACL de nível de controle total podem criar, exibir, modificar e excluir entidades definidas de tempo de execução desse tipo.

Você pode usar a API ou a interface de usuário do VMware Cloud Director para publicar o pacote de direitos em todas as organizações que você deseja gerenciar as entidades desse tipo. Depois de publicar o pacote de direitos, você pode atribuir direitos do pacote a funções na organização.

Você pode usar a API do VMware Cloud Director para editar a tabela da ACL.

Acesso a operações de interface de entidade definida e de tipo

A interface de entidade definida e as operações de tipo exigem direitos específicos que certos provedores de serviços podem não ter. Antes de realizar uma operação, verifique se você tem os direitos necessários.

Tabela 3. Direitos para operações de interface de entidade definida e tipo
Operação	Requisito
Exibir e consultar interface	Todos os usuários têm os direitos necessários.
Criar interface	Você deve ter o direito Criar nova definição da entidade personalizada.
Editar interface	Você deve ter o direito Editar definição da entidade personalizada.
Excluir interface	Você deve ter o direito Excluir definição da entidade personalizada.
Criar tipo	Você deve ter o direito Criar nova definição da entidade personalizada.
Exibir tipo	O requisito mínimo é Tipo ACL do `ReadOnly`.
Editar e excluir tipo	Você deve ter o direito de Editar/Excluir definição da entidade personalizada e um Tipo ACL do `FullControl`.

Trabalhar com Entidades Definidas em Tempo de Execução

Para invocar comportamentos em uma entidade definida, ela deve estar no estado Resolved. Para excluir uma entidade definida, ela deve estar no estado Resolved ou Resolution_Error.

Você pode modificar tipos de entidade e interfaces somente se eles não tiverem instâncias. Você só pode modificar o tipo de entidade referenciada alterando sua versão.

Para diagnosticar problemas com o acesso a entidades definidas, você pode usar as APIs de consulta da ACL de entidade e verificar os direitos necessários. Além disso, o pacote de direitos de um tipo de entidade deve ser publicado para os tenants que você deseja usá-lo.