Deploy a Workload to Your Own Hardware

A location backed by your own servers takes the place of a cloud region: Control Plane deploys every workload in a GVC that spans it onto your hardware, and one GVC can span it and cloud regions at once. It is a CPLN BYOK location, so its workloads reach AWS, GCP, and Azure services through Universal Cloud Identity, and private addresses in your network through their external firewall.

Pick a Path for Your Hardware

What you have	What you do
A Kubernetes cluster you run, such as k3s, RKE2, kubeadm, EKS, GKE, or AKS	Apply the location’s install command to the cluster
Linux servers or VMs with no cluster	Build a cluster from them with the Generic provider of Managed Kubernetes, and let its `CPLN Platform` add-on install the location

Prerequisites

The create and use permissions on locations. For the Linux servers path, also create and clusterAdmin on Managed Kubernetes clusters.
The cpln CLI and kubectl.
Capacity for the BYOK components, which run on your nodes beside your workloads: at least 2 nodes with 2 CPUs and 8 GB of memory each, as listed with the rest of the BYOK requirements.
For an existing cluster: at least one node labeled cpln.io/nodeType=core, a load balancer controller that assigns LoadBalancer services an address, a default StorageClass, and no service mesh.
For Linux servers: each server meets the Generic provider server requirements.
Outbound internet access from every node. For an air-gapped site, contact support@controlplane.com.

Create the Location

Console
CLI
Terraform
Pulumi

Open the location form

Click Locations in the left menu, then click New.

Create the location

Enter a name such as my-hardware and click Create. The location page opens.

cpln location create --name my-hardware

resource "cpln_custom_location" "my_hardware" {
  name           = "my-hardware"
  cloud_provider = "byok"
  enabled        = true
}

TypeScript
Python
Go
C#

import * as cpln from "@pulumiverse/cpln";

const myHardware = new cpln.CustomLocation("my-hardware", {
  name: "my-hardware",
  cloudProvider: "byok",
  enabled: true,
});

import pulumiverse_cpln as cpln

my_hardware = cpln.CustomLocation("my-hardware",
    name="my-hardware",
    cloud_provider="byok",
    enabled=True)

package main

import (
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
	"github.com/pulumiverse/pulumi-cpln/sdk/go/cpln"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := cpln.NewCustomLocation(ctx, "my-hardware", &cpln.CustomLocationArgs{
			Name:          pulumi.String("my-hardware"),
			CloudProvider: pulumi.String("byok"),
			Enabled:       pulumi.Bool(true),
		})
		return err
	})
}

using Pulumi;
using Pulumiverse.Cpln;

return await Deployment.RunAsync(() =>
{
    var myHardware = new CustomLocation("my-hardware", new CustomLocationArgs
    {
        Name = "my-hardware",
        CloudProvider = "byok",
        Enabled = true
    });
});

Connect Your Hardware

Existing Cluster
Linux Servers

Label the core nodes

BYOK runs its critical system pods on nodes labeled cpln.io/nodeType=core. Label at least one:

kubectl label node my-node-1 cpln.io/nodeType=core

Generate the install command

In the Console, open the location and choose Actions > Install. The Install Location dialog shows the command and the time left to apply it under Expires In. With the CLI:

cpln location install my-hardware

The first line of the output is the deadline:

# this commmand must be performed before 11/3/2026, 9:48:00 AM
kubectl apply -f 'https://byok-api.cpln.io/install/download/.../byok-agent.k8s.yaml'

The link downloads the location’s install token, so treat the command as a secret.

Apply the command to the cluster

With kubectl pointed at the cluster, run the kubectl apply command before its deadline. It creates the cpln-byok-agent deployment in the kube-system namespace.

Wait for the agent

kubectl get pod -l app=cpln-byok-agent -n kube-system

NAME                               READY   STATUS    RESTARTS   AGE
cpln-byok-agent-764ddcfd74-lpr6d   1/1     Running   0          9s

The agent then installs the rest of the BYOK components into namespaces of their own, such as controlplane, istio-system, and monitoring. Rerun kubectl get pods -A until every pod reports Running or Completed.

To serve the same location from another cluster, repeat these steps on that cluster.

Write the cluster manifest

Save this as my-cluster.yaml:

kind: mk8s
name: my-cluster
spec:
  version: 1.35.3
  provider:
    generic:
      location: aws-eu-central-1
      nodePools:
        - name: general
          labels:
            cpln.io/nodeType: core
  addOns:
    byok:
      location: //location/my-hardware
  firewall:
    - description: default
      sourceCIDR: 0.0.0.0/0

provider.generic.location is the Control Plane location that runs the cluster’s Kubernetes control plane. Pick the one closest to your servers; it cannot change after the cluster is created.
The cpln.io/nodeType: core label reaches every server that joins the general pool.
addOns.byok.location enables the CPLN Platform add-on, which installs the location into the cluster. It cannot change after it is set.
firewall controls who reaches the cluster’s Kubernetes API. Each server you join adds its own address, so narrow sourceCIDR to the addresses you run kubectl from.

When your servers have only private addresses, also add cpln.io/allowPrivateIPs: 'true' to the pool’s labels. Without it, the cluster’s load balancer has no address to give the BYOK ingress. See Ingress IPs.

Create the cluster

cpln apply -f my-cluster.yaml

Rerun cpln mk8s health my-cluster until it reports READY as true:

+-----------+------+-----------------+
|NAME       |READY |MESSAGE          |
|-----------|------|-----------------|
|my-cluster |true  |Cluster is ready |
+-----------+------+-----------------+

Join each server

cpln mk8s join my-cluster --type join-script --options nodePoolName=general > join.sh

Copy join.sh to each server and run it as root with sudo bash join.sh. The script carries the cluster’s join token, so treat it as a secret.

Wait for the nodes and the agent

cpln mk8s kubeconfig my-cluster -f my-cluster.kubeconfig
export KUBECONFIG=my-cluster.kubeconfig
kubectl get nodes
kubectl get pod -l app=cpln-byok-agent -n kube-system

Every server is listed as Ready, and the agent reports 1/1 Running.

Deploy a Workload to the Location

Create a GVC that spans the location, then a workload in it:

cpln gvc create --name my-gvc --location my-hardware
cpln workload create --name my-app --gvc my-gvc --image nginx:alpine --port 80 --public

To add the location to a GVC that already exists:

cpln gvc add-location my-gvc --location my-hardware

Adding the location to an existing GVC deploys every workload already in that GVC onto your hardware.

Verify

cpln workload get-deployments my-app --gvc my-gvc

The my-hardware row reports ready=true once the workload runs on your hardware. Its endpoints resolve to the address your load balancer controller gave the BYOK ingress gateway, so they answer from any network that can reach that address.

Troubleshoot

error: unable to read URL "https://byok-api.cpln.io/install/download/.../byok-agent.k8s.yaml", server reported 404 Not Found, status code=404

The install command’s link expired before kubectl ran it. Generate a new command and apply it before the deadline on its first line.

0/2 nodes are available: 2 Insufficient memory

BYOK pods stay Pending, and kubectl describe pod reports this event. The BYOK components alone fill nodes smaller than the BYOK requirements. Add nodes or memory until every node meets them.

BYOK PersistentVolumeClaims stay Pending

The BYOK components claim persistent volumes from the cluster’s default StorageClass, and the cluster has none. Install a storage provisioner or mark an existing StorageClass as the default.

The ingress gateway LoadBalancer service has no external address

The LoadBalancer services in the istio-system namespace stay <pending>, and workloads never report ready. On an existing cluster, install a load balancer controller. On Linux servers with only private addresses, label the nodes with cpln.io/allowPrivateIPs=true as described in Ingress IPs.

When to Use Something Else

Workloads stay in the cloud and only need to reach something in your network, such as a database: use a wormhole agent or native networking.
You want to declare Control Plane resources from kubectl or Argo CD: use the Kubernetes operator.
A single server, or nodes below the BYOK requirements: the BYOK components need that capacity before any workload runs.

How-to Guides

CLI Configuration

Integrations

Configure Resources

Create Resources

Deployment

GitOps

Images

Native Networking

Observability

Sandbox

Workload Access

Deploy a Workload to Your Own Hardware

Pick a Path for Your Hardware

Prerequisites

Create the Location

Connect Your Hardware

Deploy a Workload to the Location

Verify

Troubleshoot

When to Use Something Else

Next Steps

CPLN BYOK

Generic Provider

​Pick a Path for Your Hardware

​Prerequisites

​Create the Location

​Connect Your Hardware

​Deploy a Workload to the Location

​Verify

​Troubleshoot

​When to Use Something Else

​Next Steps

CPLN BYOK

Generic Provider

Pick a Path for Your Hardware

Prerequisites

Create the Location

Connect Your Hardware

Deploy a Workload to the Location

Verify

Troubleshoot

When to Use Something Else

Next Steps