Onboarding an Agent with Data Management for VMware Tanzu

Onboarding an Agent with Data Management for VMware Tanzu 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.

You can onboard an Agent:

Through an Agent console
Through a Provider console of Data Management for VMware Tanzu.

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 Data Management for VMware Tanzu 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 Data Management for VMware Tanzu, 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 data center 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 dm-user and dms-read-only-user as follows:

Create roles with privileges defined as follows:

Role Name	Role Description	Privileges
dms-validate-session	This role is created on root level	Sessions.ValidateSession
dms-dc	This role is created on Datacenter	Datastore.FileManagement
dms	This role is created on vSphere cluster	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, Network.Assign, Resource.AssignVMToPool, ScheduledTask.Create, ScheduledTask.Delete, ScheduledTask.Edit, ScheduledTask.Run, System.Anonymous, System.Read, System.View, 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.ManagedBy, VirtualMachine.Config.Memory, VirtualMachine.Config.MksControl, 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

Create 2 SSO users, an management user and a monitoring user, for example, dms-user and dms-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
dms	vSphere cluster	dms-user	True
dms	VM Folder	dms-user	True
dms	Datastore	dms-user	True
dms	Network	dms-user	False
dms-dc	Datacenter	dms-user	False
dms-validate-session	Root Folder	dms-user	False
Read-only	Root Folder	dms-read-only-user	False
Read-only	Datacenter	dms-read-only-user	True
Read-only	Distributed Virtual Switch	dms-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 Data Management for VMware Tanzu 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.

Data Management for VMware Tanzu 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 data center from the dropdown list.
Cluster	Select the cluster to deploy compute resources for database VM provisioning.
VM Folder	Select the folder in which to place the database VMs.

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.
Application Networks	Click the plus icon to select one or more networks for the databases. Users and applications will access the service via one of the selected networks.
Control Plane Network	Select the control plane network for the databases from the dropdown list. The Control Plane Network that you configured for the Agent VM must be able to access this network.

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 (control plane and application network) that you select during onboarding an Agent VM creates the Namespace for that Agent VM and environment that is onboarded.

Procedure to Onboard an Agent Through Provider Console or Agent 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.
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 Data Management for VMware Tanzu using the Provider username and Provider password that you set when you installed the Agent .ova.

The Provider console's dashboard appears.
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 ONBOARD AGENT in the Actions column of the Agent's Environment that you want to onboard.
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.

Data Management for VMware Tanzu 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 data center from the dropdown list.
Cluster	Select the cluster to deploy compute resources for database VM provisioning.
VM Folder	Select the folder in which to place the database VMs.

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

Property Name	Value
Datastores	Click the plus icon to select one or more datastores.
Application Networks	Click the plus icon to select one or more networks for the database VMs. Users and applications will access the service via one of the selected networks.
Control Plane Network	Select the control plane network for the database VMs from the dropdown list. The Control Plane Network that you configured for the Agent VM must be able to access this network.

Click VALIDATE.
After Data Management for VMware Tanzu 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 Data Management for VMware Tanzu 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.

Next Steps

You successfully registered the Agent with Data Management for VMware Tanzu 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 Data Management for VMware Tanzu, 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: Data Management for VMware Tanzu 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 Data Management for VMware Tanzu 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

Data Management for VMware Tanzu 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

Data Management for VMware Tanzu 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.allowed-special-chars	!@#$%^&*	The special characters allowed in the `tdm-read-only` monitoring user password. This might be required if the organization has specific password policy requirements, and you want to ??add or?? remove certain special character from the SSO user's password.
password.policy.reset-before-days	3	The number of days before expiration that the `tdm-read-only` monitoring SSO user password will be reset.
password.expiry-poll-cron	0 0 0 * * * (Everyday midnight, 12 AM)	Scheduled CRON Job for validating `tdm-read-only` monitoring user password expiration.

Procedure

Perform the following procedure to customize one or more Data Management for VMware Tanzu 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.