Onboarding an Agent with VMware Data Services Manager

Onboarding an Agent with VMware Data Services Manager registers the vSphere Cluster or VMC cluster in which the Agent VM is deployed, creating an association that makes it an available target for database VMs provisioned by users in the owning organizations.

VMware vSphere is VMware's virtualization platform, which transforms data centers into aggregated computing infrastructures that include CPU, storage, and networking resources.

VMware Cloud on AWS (VMC) is an integrated cloud offering jointly developed by Amazon Web Services (AWS) and VMware. You can deliver a highly scalable and secure service by migrating and extending your on-premises VMware vSphere-based environments to the AWS Cloud running on Amazon Elastic Compute Cloud (Amazon EC2).

You can onboard an Agent VM with VMware Data Services Manager:

Through an Agent console
Through a Provider console of VMware Data Services Manager.

Audience

The procedures in this topic are performed by a Provider Administrator or an Organization Administrator.

Prerequisites

Before you onboard an Agent, ensure that you have installed and configured all the Hardware and Software Requirements and you can identify:

Your Provider Administrator or Organization Administrator login credentials for the VMware Data Services Manager console, and you have reset your login password (Local user only).
The fully-qualified distinguished name or IP Address of the Provider VM.
If you want to onboard an Agent through the Provider console of VMware Data Services Manager, ensure that you can also identify the Provider username and password along with the Provider IP. Also, it is recommended to be able to identify the Provider API certificate to ensure enhanced security.
The fully-qualified distinguished name or IP Address of your vCenter Server instance.
The vSphere or VMC datacenter and cluster in which the Agent VM was deployed.
The IP Address of the Agent VM.
The VM Folder in which to locate the database VMs.
The S3-compatible object store URL, bucket, and keys for the Agent Local Storage and Cloud Storage; you must pre-create the buckets.
You have the credentials of two Single-Sign-On vSphere users if you want to onboard an Agent to a vSphere cluster.
You have the credentials of a cloud admin user([email protected]) if you want to onboard an Agent to a VMC cluster.

Configuring vSphere SSO Users

If you want to onboard an Agent to a vSphere cluster, ensure that you have created two SSO users, for example dsm-user and dsm-read-only-user as follows:

Create roles with privileges defined as follows:

Role Name	Role Description	Privileges
dsm-root	This role is applied at the root level	Sessions.ValidateSession
dsm-dc	This role is applied at the datacenter	Datastore.FileManagement
dsm-cluster	This role is applied at the cluster and VM folder level	Datastore.AllocateSpace, Datastore.Browse, Datastore.DeleteFile, Datastore.FileManagement, Datastore.UpdateVirtualMachineFiles, Datastore.UpdateVirtualMachineMetadata, Folder.Create, Folder.Delete, Folder.Move, Folder.Rename, Global.CancelTask, Host.Inventory.EditCluster, Network.Assign, Resource.AssignVMToPool, ScheduledTask.Create, ScheduledTask.Delete, ScheduledTask.Edit, ScheduledTask.Run, VApp.ApplicationConfig, VApp.Import, VApp.InstanceConfig, VirtualMachine.Config.AddExistingDisk, VirtualMachine.Config.AddNewDisk, VirtualMachine.Config.AddRemoveDevice, VirtualMachine.Config.AdvancedConfig, VirtualMachine.Config.Annotation, VirtualMachine.Config.ChangeTracking, VirtualMachine.Config.CPUCount, VirtualMachine.Config.DiskExtend, VirtualMachine.Config.DiskLease, VirtualMachine.Config.EditDevice, VirtualMachine.Config.HostUSBDevice, VirtualMachine.Config.Memory, VirtualMachine.Config.QueryFTCompatibility, VirtualMachine.Config.QueryUnownedFiles, VirtualMachine.Config.RawDevice, VirtualMachine.Config.ReloadFromPath, VirtualMachine.Config.RemoveDisk, VirtualMachine.Config.Rename, VirtualMachine.Config.ResetGuestInfo, VirtualMachine.Config.Resource, VirtualMachine.Config.Settings, VirtualMachine.Config.SwapPlacement, VirtualMachine.Config.UpgradeVirtualHardware, VirtualMachine.Interact.AnswerQuestion, VirtualMachine.Interact.ConsoleInteract, VirtualMachine.Interact.DeviceConnection, VirtualMachine.Interact.GuestControl, VirtualMachine.Interact.PowerOff, VirtualMachine.Interact.PowerOn, VirtualMachine.Interact.Reset, VirtualMachine.Interact.SetCDMedia, VirtualMachine.Interact.SetFloppyMedia, VirtualMachine.Interact.Suspend, VirtualMachine.Interact.ToolsInstall, VirtualMachine.Inventory.Create, VirtualMachine.Inventory.CreateFromExisting, VirtualMachine.Inventory.Delete, VirtualMachine.Inventory.Move, VirtualMachine.Provisioning.Clone, VirtualMachine.Provisioning.CloneTemplate, VirtualMachine.Provisioning.CreateTemplateFromVM, VirtualMachine.Provisioning.Customize, VirtualMachine.Provisioning.DeployTemplate, VirtualMachine.Provisioning.DiskRandomRead, VirtualMachine.Provisioning.GetVmFiles, VirtualMachine.Provisioning.MarkAsTemplate, VirtualMachine.Provisioning.MarkAsVM, VirtualMachine.Provisioning.ModifyCustSpecs, VirtualMachine.Provisioning.ReadCustSpecs, VirtualMachine.State.CreateSnapshot, VirtualMachine.State.RemoveSnapshot, VirtualMachine.State.RenameSnapshot, VirtualMachine.State.RevertToSnapshot
dsm-datastore	This role is applied at the datastore	Datastore.AllocateSpace, Datastore.Browse, Datastore.Config, Datastore.DeleteFile, Datastore.FileManagement, Datastore.UpdateVirtualMachineFiles, Datastore.UpdateVirtualMachineMetadata, Folder.Create, Folder.Delete, Folder.Move, Folder.Rename, Global.CancelTask, Host.Inventory.EditCluster, Resource.AssignVMToPool, ScheduledTask.Create, ScheduledTask.Delete, ScheduledTask.Edit, ScheduledTask.Run, System.Anonymous, System.Read, System.View, VApp.Import, VApp.InstanceConfig, VApp.ApplicationConfig, VirtualMachine.Config.AddExistingDisk, VirtualMachine.Config.AddNewDisk, VirtualMachine.Config.AddRemoveDevice, VirtualMachine.Config.AdvancedConfig, VirtualMachine.Config.CPUCount, VirtualMachine.Config.ChangeTracking, VirtualMachine.Config.DiskExtend, VirtualMachine.Config.DiskLease, VirtualMachine.Config.EditDevice, VirtualMachine.Config.HostUSBDevice, VirtualMachine.Config.Memory, VirtualMachine.Config.QueryFTCompatibility, VirtualMachine.Config.QueryUnownedFiles, VirtualMachine.Config.RawDevice, VirtualMachine.Config.ReloadFromPath, VirtualMachine.Config.RemoveDisk, VirtualMachine.Config.Rename, VirtualMachine.Config.ResetGuestInfo, VirtualMachine.Config.Resource, VirtualMachine.Config.Settings, VirtualMachine.Config.SwapPlacement, VirtualMachine.Config.UpgradeVirtualHardware, VirtualMachine.Interact.AnswerQuestion, VirtualMachine.Interact.ConsoleInteract, VirtualMachine.Interact.DeviceConnection, VirtualMachine.Interact.GuestControl, VirtualMachine.Interact.PowerOff, VirtualMachine.Interact.PowerOn, VirtualMachine.Interact.Reset, VirtualMachine.Interact.SetCDMedia, VirtualMachine.Interact.SetFloppyMedia, VirtualMachine.Interact.Suspend, VirtualMachine.Interact.ToolsInstall, VirtualMachine.Inventory.Create, VirtualMachine.Inventory.CreateFromExisting, VirtualMachine.Inventory.Delete, VirtualMachine.Inventory.Move, VirtualMachine.Provisioning.Clone, VirtualMachine.Provisioning.CloneTemplate, VirtualMachine.Provisioning.CreateTemplateFromVM, VirtualMachine.Provisioning.Customize, VirtualMachine.Provisioning.DeployTemplate, VirtualMachine.Provisioning.DiskRandomRead, VirtualMachine.Provisioning.GetVmFiles, VirtualMachine.Provisioning.MarkAsTemplate, VirtualMachine.Provisioning.MarkAsVM, VirtualMachine.Provisioning.ModifyCustSpecs, VirtualMachine.Provisioning.ReadCustSpecs, VirtualMachine.State.CreateSnapshot, VirtualMachine.State.RemoveSnapshot, VirtualMachine.State.RenameSnapshot, VirtualMachine.State.RevertToSnapshot
dsm-network	This role is applied at the network	Network.Assign, System.Anonymous, System.Read, System.View

Create 2 SSO users, a management user and a monitoring user, for example, dsm-user and dsm-read-only-user.

Assign roles for different objects to these users as follows:

Note: Read-only role is an existing system-level role in vCenter.

Role Name	Object	Username	Propagate
dsm-root	Root folder	dsm-user	False
dsm-dc	Datacenter	dsm-user	False
dsm-cluster	Cluster	dsm-user	True
dsm-cluster	VM Folder	dsm-user	True
dsm-datastore	Datastore	dsm-user	True
dsm-network	Network	dsm-user	False
Read-only	Root Folder	dsm-read-only-user	False
Read-only	Datacenter	dsm-read-only-user	True
Read-only	Distributed Virtual Switch	dsm-user	False

Configuring VMC Cloud Admin User

If you want to onboard an Agent to a VMC cluster, ensure that you have created a VMC cloud admin user.

Procedure to Onboard an Agent Through Agent Console

Open a browser window and enter the IP Address of the Agent VM.
Sign in to the Agent Onboarding console using the Agent VM root credentials that you set when you deployed the VM.

The Agent Onboarding screen displays.
Follow the 5 Steps to complete Agent Onboarding configuration and validation.

Step1 Provider Authentication - Provide the following information in the Provider Authentication pane:

Field Name	Description
Provider FQDN/IP	The IP address or fully-qualified distinguished name of the Provider VM to which to onboard the Agent.
Username	A VMware Data Services Manager Local or LDAP user name that has been assigned a Provider Administrator or an Organization Administrator role.
Password	The password for the Username.

Click CONNECT.
Note: If you get any message of authentication failure, verify that:
- You have downloaded and installed the .ova files for the Provider and Agent from the same release.
- You have used the Agent VM root credentials to sign in to the Agent Onboarding console. You set this password when you deployed the VM.
- You have Validated Provider Readiness for Onboarding.
Examine the Provider thumbprint displayed in the Trust Provider Certificate dialog box, and click CONTINUE if you trust the host.

The Onboarding Type pane of the DMS Agent Console Onboarding Settings screen displays.
You have the option to create a new Agent environment, or restore an existing Agent environment. In this case:
1. Select your Organization name from the drop-down list.
2. Click Create New Environment, and then click CONTINUE.

Step2 - Specify the vCenter Configuration in the vCenter Authentication pane:

Property Name	Value
Cluster Type	VMC or VSPHERE
vCenter FQDN/IP	The IP address or fully-qualified distinguished name of your vCenter server instance in VMC or vSphere.

In the vCenter Credentials section of the vCenter Authentication pane, set the following:

Property Name	Value
Username	The vCenter management user name with respect to VMC or vSphere (for example, dms-user).
Password	The vCenter management password with respect to VMC or vSphere.

Click CONNECT.

Examine the VCENTER thumbprint displayed in the Trust VCENTER Certificate dialog box, and click CONTINUE if you trust the host.

In the Monitoring Read-Only Credentials section of the vCenter Authentication pane, set the following:

Property Name	Value
Username	The vCenter monitoring user name with respect to VMC or vSphere (for example, dms-read-only-user).
Password	The vCenter monitoring password with respect to VMC or vSphere.

Click CONNECT.

VMware Data Services Manager validates if the management user and monitoring users specified in the vCenter pane have the required privileges. If validation is successful, the Environment settings form displays. Else, an error message displays stating that the credentials are invalid. You can provide the valid credentials, and then click CONNECT to display the Environment pane.

Step3 - Specify the Placement Configuration in the Environment pane:

Property Name	Value
Datacenter	Select the vCenter datacenter from the dropdown list.
Cluster	Select the cluster to deploy compute resources for database VM provisioning.
Resource Pool (Optional)	Select the Resource Pool to be used by the Agent VM. You can select a parent Resource Pool or a child Resource Pool. For more information, see Resource Pools.
VM Folder	Select the folder in which to place the database VMs.

Note: If want to remove a selected Resource Pool, you can click CLEAR at the bottom of the drop down list.

Step3 - Specify the Datastore and Network Configuration in the Environment pane:

Property Name	Value
DB datastore	Click the plus icon to select one or more datastores.
Management Network	Select the management network from the dropdown list.
Database Networks (Optional)	The management network that you select is automatically configured as the default database network, and every time you change the management network, the default database network is automatically updated as the same. However, you can click the plus icon to add one or more networks to the list of database networks and select one of them as the default database network. Users and applications can access VMware Data Services Manager through one of the selected networks.

Note:

If you configure the database network and the management network as the same network and do not add any other network to the list of database networks, then you set up VMware Data Services Manager to always create databases using a single network.
If you configure a default database network and the management network as different networks and you do not add any other networks to the list of database networks, then you set up VMware Data Services Manager to always create databases with two networks.
If you configure the default database network and the management network as the same network and you then add other networks to the list of database networks, then you set up VMware Data Services Manager with the choice to create databases with either a single network or with two networks.

Click CONNECT.

The Template Storage pane displays.

Step4 - Specify the Template Storage Configuration in the Database Template Storage pane:

Property Name	Value
Template Storage Name	The unique name of the template storage configuration. It must be unique across all the storage configurations created by different organizations through multiple onboarding processes.
Template Storage Type	Select the type of storage from the drop-down list. You can choose S3_COMPATIBLE_STORAGE or AWS.
Endpoint URL/FQDN	The URL to the object store.
AWS Region	If you selected the AWS storage type, use the drop-down list to select the region.
Access Key	The access key for the object store.
Secret Key	The secret key to the object store.
Bucket	The name of the bucket.

Click CONNECT

Settings configuration is complete and the onboarding process begins.
Step5 - Review the Agent Environment Summary, and then click SAVE.

Onboarding is complete when Step3 and the Current Agent Settings in the Summary pane both display a green checkmark icon.

Note: If you run into any issues with the onboarding, you must delete the Agent VM, delete the environment, and re-start the Agent VM deployment and onboarding process from scratch.
Take note of the ENV ID assigned to the Agent VM in the Current Agent Settings section of the Summary pane; you will need this information should you be required to recover the Agent.
Validate the successful onboarding of the Agent by verifying that the onboarded environment is displayed in the Environment view table of the Environment pane.
In the Environment view, click the row that lists the currently onboarded environment.

Information about the agent is displayed in detail.
Click the Health tab and verify that all the rows of the Agent Health Status table has Status as OK.
Click the Health tab and verify that all the rows of the Tenant Health Status table has Status as OK.

Note: The default storage (datastore, local storage, cloud storage, and template storage) and network options (management network and database network) that you select while onboarding an Agent VM creates the Namespace for that Agent VM and the environment that is onboarded.

Procedure to Onboard an Agent or a Consolidated Agent Through Provider Console

Ensure that you have installed the Agent .ova in vCenter, and provided the Provider IP, Provider Username, Provider Password, and Provider API Certificate parameters during the installation process. Also, ensure that you have powered on the Agent VM.
Open a browser window and enter the IP Address of the Provider VM that you set when you installed the Agent .ova.
Sign in to the Provider console of VMware Data Services Manager using the Provider username and Provider password that you set when you installed the Agent .ova.

The Provider console's dashboard appears.

Note: You cannot [delete a Consolidated Agent](onboard_tenant.html#addressing-onboarding-issues-7) and then onboard the same Consolidated Agent again.
Click Environment in the left pane.
In the Environments view, ensure that the Provider Status is Ready to Onboard.
In the Available Agent VMs section of the Environments view, click the SETUP NEW ENVIRONMENT button or the DEPLOY NEW AGENT button.

The Setup New Environment dialog box appears or a Standalone Agent is deployed and listed in the table of the Available Agent VMs section of the Environments view.

Note: You can onboard only one Consolidated Agent or a combined Provider and Agent appliance in VMware Data Services Manager. Therefore, if you have onboarded a Consolidated Agent, you can see the DEPLOY NEW AGENT button instead of the SETUP NEW ENVIRONMENT button.
In the Setup New Environment dialog box, either select Consolidated Environment to onboard a combined Provider and Agent appliance or select Distributed Environment to deploy a Standalone Agent, and then click CONFIRM. By default, the Standard Environment is selected.

The process of setting up the onboarding of a Consolidated Agent (involves RPM installation, registration of environment with Provider, and so on) can take three to four minutes. After the onboarding of the Consolidated Agent is set up, the Agent Onboarding dialog box appears.

OR

In the Available Agent VMs section of the Environments view, click ONBOARD AGENT in the Actions column of the Agent's Environment that you want to onboard.

The Agent Onboarding dialog box appears.
Follow the 4 Steps to complete Agent Onboarding configuration and validation.

Step1 - Specify the vCenter Configuration in the vCenter Authentication form:

Property Name	Value
Cluster Type	VMC or VSPHERE
vCenter FQDN/IP	The IP address or fully-qualified distinguished name of your vCenter Server instance in VMC or vSphere.

In the vCenter Credentials section of the vCenter Authentication form, set the following:

Property Name	Value
Username	The vCenter management user name with respect to VMC or vSphere (for example, dms-user).
Password	The vCenter management password with respect to VMC or vSphere.

Click CONNECT.
If the VCENTER thumbprint is displayed for confirmation in the Trust VCENTER Certificate dialog box, click CONTINUE if you trust the host.

In the Monitoring Read-Only Credentials section of the vCenter Authentication form, set the following:

Property Name	Value
Username	The vCenter monitoring user name with respect to VMC or vSphere (for example, dms-read-only-user).
Password	The vCenter monitoring password with respect to VMC or vSphere.

Click CONNECT.

VMware Data Services Manager validates if the management user and monitoring users specified in the vCenter pane have the required privileges. If validation is successful, the Environment form displays. Else, an error message displays stating that the credentials are invalid. You can provide the valid credentials, and then click CONNECT to display the Environment form.
Click NEXT.

Step2 - Specify the Placement Configuration in the Environment form:

Property Name	Value
Datacenter	Select the vCenter datacenter from the dropdown list.
Cluster	Select the cluster to deploy compute resources for database VM provisioning.
Resource Pool (Optional)	Select the Resource Pool to be used by the Agent VM. You can select a parent Resource Pool or a child Resource Pool. For more information, see Resource Pools.
VM Folder	Select the folder in which to place the database VMs.

Note: If want to remove a selected Resource Pool, you can click CLEAR at the bottom of the drop down list.

Step2 - Specify the Datastore and Network Configuration in the Environment form:

Property Name	Value
DB datastore	Click the plus icon to select one or more datastores.
Management Network	Select the management network from the dropdown list.
Database Networks (Optional)	The management network that you select is automatically configured as the default database network, and every time you change the management network, the default database network is automatically updated as the same. However, you can click the plus icon to add one or more networks to the list of database networks and select one of them as the default database network. Users and applications can access VMware Data Services Manager through one of the selected networks.

Note:

If you configure the database network and the management network as the same network and do not add any other network to the list of database networks, then you set up VMware Data Services Manager to always create databases using a single network.
If you configure a default database network and the management network as different networks and you do not add any other networks to the list of database networks, then you set up VMware Data Services Manager to always create databases with two networks.
If you configure the default database network and the management network as the same network and you then add other networks to the list of database networks, then you set up VMware Data Services Manager with the choice to create databases with either a single network or with two networks.

Click VALIDATE.
After VMware Data Services Manager validates the infrastructure configuration settings, click NEXT.

The Template Storage form displays.

Step3 - Specify the Template Storage configuration in the Database Template Storage form:

Property Name	Value
Storage Name	The unique name of the template storage configuration and must be unique across all the storage configurations created by different organizations through multiple onboarding.
Storage Type	Select the type of template storage from the drop-down list. You can choose S3_COMPATIBLE_STORAGE or AWS.
Endpoint URL/FQDN	The URL to the object store.
AWS Region	If you selected the AWS storage type, use the drop-down list to select the region.
Access Key	The access key for the object store.
Secret Key	The secret key for the object store.
Bucket	The name of the bucket.

Click CONNECT.
After VMware Data Services Manager validates the template storage configuration settings, click NEXT.
Step4 - Review the Agent Environment Summary, and then click SAVE.

Onboarding is complete when Step3 and the Current Agent Settings in the Summary pane both display a green checkmark icon.

Note: If you run into any issues with the onboarding, you must delete the Agent VM, delete the environment, and re-start the Agent VM deployment and onboarding process from scratch.
Take note of the ENV ID assigned to the Agent VM in the Current Agent Settings section of the Summary pane; you will need this information should you be required to recover the Agent.
Validate the successful onboarding of the Agent by verifying that the onboarded environment is displayed in the Environment view table of the Environment pane.
In the Environment view, click the row that lists the currently onboarded environment.

Information about the agent is displayed in detail.
Click the Health tab and verify that all the rows of the Agent Health Status table has Status as OK.

Note: All the APIs for a Consolidated Agent uses Provider IP address and port 543.

Next Steps

You successfully registered the Agent with VMware Data Services Manager and now have an Onboarded Cluster. Next, you may choose to:

Contact the Provider Administrator and request that they add users to the Organization.
Log in to VMware Data Services Manager, and access the user console to provision a service such as a database.

When the vCenter management and monitoring credentials provided during onboarding an agent expire, the Status of the Environment that you onboarded turns DEGRADED and Database operations are affected. For more information about how to update these credentials, see Updating the Environment.

Addressing Onboarding Issues

If you run into an issue during Agent onboarding, you must delete the Environment and re-start the deployment and onboarding process.

Deleting Misconfigured Environment

Warning: VMware Data Services Manager supports deleting environment only to repair an issue that you encounter during Agent onboarding.

Perform the following procedure to delete a misconfigured environment:

Delete the Agent VM from vCenter.
Log in to the VMware Data Services Manager console.
Select Environment from the left navigation pane.
Examine the environments listed in the table, identify the environment that you want to delete, and navigate to that table row.
Click the environment's Agent VM IP.

The environment's information Details tab displays.
Click the ENVIRONMENT ACTIONS button located in the upper right-hand corner of the view, and select Delete from the pop-up menu.

The Confirmation dialog box displays.
If you are certain that you want to delete the environment, click CONFIRM.

Custom Onboarding Configuration

VMware Data Services Manager exposes certain onboarding properties. You can customize these properties before you begin onboarding, or if you face issues during the onboarding process.

Onboarding-related properties are located in the /opt/vmware/tdm-tenant/onboarding-service/config/application.yml file on the Agent VM.

Latency

If you face latency issues during onboarding, you can specify a custom values for these configuration properties:

Property Name	Default Value	Description
rabbitmq.start.timeout.seconds	120	The default timeout for the RabbitMQ Service. Onboarding fails if the RabbitMQ Service does not start up within this time period.
rabbitmq.shovel.creation.timeout.seconds	300	The default timeout for creating the RabbitMQ shovel. Onboarding fails if all RabbitMQ shovels are not running within this time period.
solution.user.session.timeout.seconds	3600	The default timeout for the Solution User session.

Password Policies

VMware Data Services Manager includes some pre-defined password policies. If these policies conflict with those defined in the organization, you can use the following properties to customize:

Property Name	Default Value	Description
password.policy.warning-before-days	15	VCENTER alert is raised as WARNING when SSO user’s password is about to expire in 15 days.
password.expiry-poll-cron	0 0 0 * * * (Everyday midnight, 12 AM)	Scheduled CRON Job for polling SSO user’s password expiry check.

Procedure

Perform the following procedure to customize one or more VMware Data Services Manager onboarding properties:

Identify the names of the properties that you wish to customize, and the new property values.
SSH into the Agent VM using vCenter.
Open the /opt/vmware/tdm-tenant/onboarding-service/config/application.yml in the editor of your choice, add or reset the properties, and then exit the editor.

Restart the onboarding service:

root@agent_vm$ systemctl restart onboarding.service

Log out of the Agent VM.
(Re)initiate the Agent VM onboarding procedure.