Host
A Host is a physical machine that you supply to Private Cloud Director as a hypervisor. Once authorized and configured, virtual machines can be deployed on top of the host.
Once you have your Cluster Blueprint configured, Private Cloud Director has the information it needs to configure hosts that will be added to the cluster.
Host Agent
The Platform9 host agent is the first component you will install on each host. The host agent enables you to add hosts and configure their roles in your virtualized cluster. Based on each hosts' assigned role(s), the agent will download and configure the required software and integrate it with the Private Cloud Director management plane.
The host agent is also used for ongoing health monitoring of the host, including failure and error detection. It also helps Platform9 orchestrate an upgrade for the host when you choose to upgrade your Private Cloud Director deployment to a newer version.
Roles
As part of host authorization process, you can configure hosts to perform specific functions by assigning them one or more roles. Following are the supported roles:
Hypervisor Role
The Hypervisor role enables the Host to function as a KVM based Hypervisor in your Virtualized Cluster.
Typically, all hosts in your cluster will be assigned this role; unless you are experiencing performance bottlenecks and want to avoid running VM workloads on select hosts that are assigned other roles such as image library role or storage role.
VM Image Library Role
Every cluster needs to have at least one 'Image Library', which will host the cluster copy of Virtual Machine source images from which new VMs can be provisioned. Read more about Configuring Image Library Role here.
Block Storage Node Role
One or more hosts in your cluster will typically be configured as a 'Block Storage Node'. Read more about how to Configure Block Storage Role here.
Enable Advanced Remote Support
For certain troubleshooting situations, Platform9 support teams may request access to automatically gather detailed telemetry from a host that is experiencing some problems. Enabling Advanced Remote Support enables this mode. By default, this should be disabled and should only be enabled when requested by Platform9 support.
Add a Host (SaaS Deployment)
Ensure that the host that you are trying to add meets the pre-requisites.
Once you have the required pre-requisites confirmed, add hosts by navigating to Infrastructure > Cluster Hosts, and click "Add New Hosts". Follow the instructions as shown. You will enter the administrative user's password when prompted.
You will now see the two simple steps in the UI that you need to run on each of your hosts. Remember to ensure you have sudo privileges.
These commands download pcdctl CLI and invoke the prep-node command on pcdctl. The command will ask you for a number of inputs; the values for all of these specific to your environment are provided in your Private Cloud Director UI for ease of use.
It will typically take 2-3 minutes to download and install the Platform9 host agent and other necessary Platform9 software components, which will then allow you to proceed to the next step to assign role.
Add a Host (Self-Hosted & Community Edition Deployment)
Community Edition Note: Hypervisor hosts deployed as virtual machines must have virtualization support available inside the VM. Virtual machines on ARM CPUs are currently untested.
If you want to verify that nested virtualization is working in a VM, you can check for virtualization support inside the VM by running:
To add (onboard) a hypervisor host to a self-hosted or Community Edition deployment of Private Cloud Director, login to the host and follow the following steps as a root user.
Add DNS entries
As a root user, add DNS entries on each hypervisor host for both the infrastructure & workload region FQDNs using the /etc/hosts file.
Trust Management Plane SSL Certificate
As a root user, the self-signed management plane/workload region SSL certificate must be trusted on each target hypervisor host before beginning the host onboarding process.
An example output is shown below:
Prepare Host
In the Private Cloud Director user interface, navigate to Infrastructure > Cluster Hosts, and click "Add New Hosts". Follow the instructions as shown. You will enter the administrative user's password when prompted.
Authorize Host And Assign Roles
Now that your host is added, it will show up Infrastructure > Cluster Hosts with an "unauthorized" status, which means it is awaiting authorization and cluster role assignment. Select the host and click "Edit Roles". Configure the appropriate roles for this host based on your cluster architecture.
You can find more information about the respective roles in the documentation specific to that component. For eg read more about persistent storage role in this section of the block storage documentation - Assigning Hypervisors Block Storage Role.
Based on your desired cluster role assignment, the Private Cloud Director management plane will work with the Platform9 agent installed on your host to configure the required software on your host. This will typically take 3-5 minutes to complete. During this time, you will see the host status as converging in the Private Cloud Director UI.
Monitor Host Addition Status
While a host is in converging state, you can monitor the status of this activity by looking at the hostagent log. See Log Files for location of the hostagent log files. Tail the log file to monitor the status of host addition:
Success
Once the host is authorized and the role assignments have taken effect, your host is ready to use!
Remove a Host
Fully removing a host from your Private Cloud Director setup is a two step process. You must remove all roles assigned to the host first, and then, if required, decommission the host to cleanup any Private Cloud Director related data from that host. You must perform both steps if you plan to re-add the host to your current or another Private Cloud Director setup.
Remove All Roles And Deauthorize a Host
Removing all roles from a host is a first step towards fully removing a host from your Private Cloud Director setup. Removing all roles will uninstall any specific packages and software components specific to all roles assigned to the host.
Follow these pre-requisites before removing a host from your Private Cloud Director setup.
If the host is assigned
hypervisorrole, make sure that there are no VMs running on the host.If the host is assigned
persistent storagerole, make sure that there are no storage volumes being served by this host.If the host is assigned
image libraryrole, make sure that there are no images in the image library being served by the host.
Remove all roles using UI
To remove all roles assigned to the host using the Private Cloud Director UI, navigate to the Cluster Hosts menu in the UI, and click on the specific host. Then from the actions bar dropdown, click on the "Remove all roles" action.
If you haven't followed the pre-requisite steps mentioned above, the UI will warn you about any remaining objects that need to be cleaned up before the role removal operation can succeed.
Remove all roles using CLI
Use the following pcdctl command to remove all roles from a host.
Important
Removing all roles only uninstalls and removes software packages associated with all roles from the host. It does not however clean up and delete any directories or files created as part of the installation of these software components. You must decommission a host in order for all Private Cloud Director related data from that host to be removed.
Decommission a Host
When you remove all roles from a host using the command above, any Private Cloud Director specific packages and software components specific to those roles get uninstalled and removed from the host. However, any directories where the packages were installed are not cleaned up or deleted. This is to make sure that you still have access to the log files for those components if required for debugging.
To remove these directories and clean up any Private Cloud Director related data from the host, you need to run decommission host command.
Important
Before you can decommission a host, you must remove all roles from the host using the Private Cloud Director UI or CLI.
Always back up important data such as log files and configuration files from the host before decommissioning.
You must run decommission a host before you can add it again to your current or any other Private Cloud Director setup. Not doing so will result in problems when re-authorizing the host in the Private Cloud Director setup.
Decommissioning a host can only be performed using pcdctl CLI today.
Use the pcdctl to decommission a host by running the following command:
Once the command executes successfully, the host will be removed from the list of active hosts in the Private Cloud Director UI. If you encounter errors during decommissioning, check the logs for details and ensure the host is reachable.
Host States
Following are the different status values for a host:
ok - The host is online and healthy and Private Cloud Director is able to connect to it
converging - A new role is being applied to the host and or the host is being authorized and added to a cluster
offline - Private Cloud Director management plane is unable to connect with the host, the host appears to be offline. Check auto$ for steps to debug this.
failed / error - The host appears to be in a failed or error state. Check auto$ for more info.
Host Aggregates
A host aggregate is a group of hosts within your virtualized cluster that share common characteristics. Read Host Aggregate for more information and how to configure them.
Debugging Compute Service Problems
If your Private Cloud Director Service Health dashboard is showing that the Compute Service is unhealthy, this may be because a large percentage of your hosts with Hypervisor role assigned are either offline or the compute service is unresponsive on those hosts. Refer to the Log Files to debug the issue further.
Log Files
Important log files for debugging:
Log files for all services - Each host stores all its log files for the various components running on it at
/var/log/pf9. Here you will find logs for compute, image library, storage, networking and other services, depending on the roles assigned to that host. See the documentation for each individual service for more information about it's log files.Compute service log - The log file for the compute service is located at
/var/log/pf9/ostackhost.logon all hosts with hypervisor role assigned. Useful for debugging issues with virtual machine creation or updates.Host agent log - The log file for the Platform9 host agent that is installed on each host is located at
/var/log/pf9/hostagent.log. This is helpful for debugging issues with host agent install or connectivity with Private Cloud Director management plane.Communication agent log - Located at
/var/log/pf9/comms/comms.log. Log file for Platform9 communications agent that is responsible for ensuring the health and uptime of host agent. Helpful for debugging issues regarding connectivity.Libvirt logs - Located at
/var/log/libvirt/qemu/<vm-id>where should be the UUID of the VM and at/var/log/libvirt/libvirtd.log. Libvirt logs help with debugging any resource allocation or other issues with virtual machine instances.
Last updated
Was this helpful?