Set up your Bare Metal Kubernetes Cluster
You can deploy Kubernetes clusters on physical machines using the bare metal support for Private Cloud Director. Each cluster contains all the resources for your containerized workloads, such as nodes, pods, and services.
Learn more on how you can onboard physical machines to Private Cloud Director , create a Kubernetes cluster through the Private Cloud Director console, and verify if your cluster is working.
Information
Bare metal support for Kubernetes in Private Cloud Director is currently in beta
Prerequisites
Before you start, ensure you have:
One or more Ubuntu physical machines for your Kubernetes nodes. PCD supports Ubuntu 22.04 LTS and Ubuntu 24.04 LTS.
Network connectivity between all machines and the Private Cloud Director management cluster.
Administrator requires sudo or root access on all target machines.
Valid Private Cloud Director account credentials.
Access to your Private Cloud Director management console.
Step 1: Onboard your machines
Onboarding installs the host agent on each physical machine and registers it with Private Cloud Director. The console generates the commands for you, filled in with your own account values, so you never assemble them by hand.
Get your onboarding commands
In the Private Cloud Director console, navigate to Kubernetes > Infrastructure > Physical Hosts.
Select + Add Physical Host. The Add New Physical Host drawer opens.
The drawer's Adding a New Physical Host section holds two commands, each with its own copy button:
The first installs the host agent.
The second is a complete
byohctl onboardcommand, with your Account URL, Username, Domain, Tenant, Region, and client-token already substituted. Only the password is left as a placeholder.
The Here is your info for quick use panel below the commands lists those same values individually, each with a copy button, if you need any of them on their own.
The host agent package is personalized for your account. The generated commands embed credentials tied to your organization. Do not share them, or the package they install, with anyone outside your organization.
Install the host agent on each machine
Repeat this for every physical machine you want to add as a Kubernetes node.
Log in to the host terminal.
As the root user, run the first command from the drawer. It downloads and runs the setup script that installs the host agent on the machine.
As the root user, run the second command from the drawer, replacing
<password>with your own password.
Once the host agent is installed and registered, the machine appears on the Physical Hosts page.
Verify successful onboarding
Confirm that your machine has been properly registered with Private Cloud Director and the agent is communicating correctly.
Verify that the agent service is active and communicating by running the following command.
You should see the agent service is active and running.
Review the agent logs to confirm registration with Private Cloud Director by running the following command.
Confirm you see registration success messages in the logs.
Finally, confirm that Private Cloud Director has picked the machine up.
In the Private Cloud Director console, navigate to Kubernetes > Infrastructure > Physical Hosts.
Find your machine in the table by its Name. Use the Search box if you have many hosts.
Check the row:
Connection Status reads Online, which means the host agent is registered and communicating.
Cluster reads Not Assigned, because the machine is onboarded but not yet part of a cluster. It changes to the cluster name in Step 2.
IP Addresses, OS Image, and OS Name show what PCD detected on the machine, for example an OS Image of
Ubuntu 22.04.5 LTS.
Once the host shows as Online, onboarding is complete and the machine is ready to join a cluster.
Step 2: Create your Kubernetes cluster
Log in to your Private Cloud Director console.
Navigate to Kubernetes > Infrastructure > Clusters in the left-hand navigation menu.
Open the deployment wizard:
If you have not created a cluster yet, select Create New Cluster with Physical Nodes.
If you already have clusters, select Deploy New Cluster, then choose with Physical Nodes.
The Deploy A New Cluster wizard opens on the Cluster Architecture step. On the physical-node path, that step holds the cluster name and the control plane type. You select the machines themselves on the later steps.
In Cluster Name, enter a name that is unique among your clusters. This name identifies your cluster in the Private Cloud Director console.
Under Select the type of control plane, choose one of the two cards, then select Next.
Control plane type
Where it runs
What the wizard asks for
Managed Control Plane
The PCD management plane, operated for you
Nothing further. The wizard goes straight to Add Worker Nodes.
Colocated Control Plane
Dedicated nodes among the physical machines you onboarded
An extra Add Control Plane Nodes step, plus a Virtual IP and a Network Interface in step 8.
To compare the two types before you choose, see Control Plane Types.
Colocated control plane only: on the Add Control Plane Nodes step, select the onboarded machines that host the control plane. Choose an odd number of at least three nodes so that the control plane retains a quorum if a node is lost. Select Next.
On the Add Worker Nodes step, select the onboarded machines that run your workloads. At least one worker node is required. Select Next.
On the Configure your Cluster step, configure your Kubernetes cluster settings.
Settings
Action
Description
Kubernetes Version
Select from dropdown
Choose the Kubernetes version supported by your workloads.
Kubernetes Flags
Enable this flag
Customize kube-apiserver, Controller Manager, and Scheduler flags using the cluster API.
Core Add-ons
Enable as required
CoreDNS and Calico can be enabled individually. Customize add-ons using cluster API add-on configuration.
Other Add-ons
Enable as required
Optional add-ons like MetalLB and Nvidia GPU Operator are available.
Virtual IP
Enter an available IP address
Colocated control plane only. Use an address from the network on which your control plane hosts reside. kube-vip advertises it to provide a stable Kubernetes API server endpoint. Reserve the address for this cluster, and make sure it is not already assigned to another host or part of a DHCP pool.
Network Interface
Enter the interface name
Colocated control plane only. The network interface on the control plane hosts that kube-vip uses to advertise the virtual IP via ARP, for example ens3. The interface name must be the same on all control plane hosts.
Select Submit to start the deployment process.
The Private Cloud Director console now provisions your cluster using the physical machines you onboarded.
Step 3: Verify your cluster
Monitor cluster creation
Monitor your cluster creation progress in the Private Cloud Director console.
Navigate to Kubernetes > Infrastructure > Clusters.
Find your cluster in the list and watch its status until it becomes Active.
Confirm your machines joined the cluster
Each physical machine you selected in the wizard is claimed by the cluster as it is provisioned.
Navigate to Kubernetes > Infrastructure > Physical Hosts.
For each machine you selected, check the Cluster column. It shows Not Assigned until the machine is claimed, then changes to a link carrying your cluster's name.
Confirm that Connection Status stays Online for each of those hosts.
To narrow the table to one cluster's hosts, use the All Clusters filter above it and select your cluster.
When every machine you selected shows your cluster's name and an Online connection status, your cluster nodes have joined successfully.
Access your cluster
Download the kubeconfig file from the Private Cloud Director console.
Navigate to Kubernetes > Infrastructure > Clusters and then to your cluster.
Choose Download Kubeconfig.
Save the downloded file as
cluster-kubeconfig.yaml.
Set your
kubectlcontext by running the following command.
Verify your cluster is working by running the following command.
These commands show your cluster nodes, namespaces, and running pods.
You have successfully created and verified your bare metal Kubernetes cluster. Your physical machines are now ready to run containerized workloads.
Best Practices
Make sure your physical machines meet the minimum system requirements for Kubernetes nodes.
The
byohctlagent logs at/var/log/pf9/byoh/byoh-agent.logare useful for troubleshooting onboarding issues.Core add-ons are required for basic cluster functionality.
Your Kubernetes version must be supported by your Private Cloud Director management plane.
Related Pages
Control Plane Types: how Managed and Colocated control planes differ, and how to choose between them
Getting Started: the same deployment flow on virtualized nodes
Cluster Access - Kubeconfig: other ways to reach your cluster with
kubectl
Last updated
Was this helpful?
