Generic Provider

Convert any Linux-based server into a Managed Kubernetes worker node, whether deployed in public clouds, private clouds, or on-premises environments.

The Generic provider for Managed Kubernetes allows Linux-based servers to act as worker nodes of a Kubernetes cluster, irrespective of their deployment in public clouds (such as AWS, Azure, GCP, Hetzner, etc.) or in private cloud or on-premises environments. Once integrated, these servers join a Kubernetes cluster as worker nodes, enabling the deployment of Kubernetes workloads through the Kubernetes API.

The provider is vendor-agnostic: a physical server in your data center, a virtual machine on VMware or vSphere, and a cloud instance are all joined the same way.

This guide covers building the Kubernetes cluster. To then run Control Plane workloads on those servers — so your hardware becomes a location you deploy to — see Deploy a Workload to Your Own Hardware.

Supported Add-Ons

• Headlamp: Provides a Kubernetes dashboard UI for the cluster.
• AWS Workload Identity: Allows your pods to assume AWS IAM Roles.
• AWS ECR: Allows pulling images from private ECR registries.
• Local Path Storage: Creates PVCs backed by local volumes.
• Logs: Enables logging for pods and cluster auditing.

Step 1 - Server Setup

1. Prepare the servers: Create at least one server that meets the following server requirements:
   • Server requirements:
     • Linux kernel version higher than 5.4
     • Minimum CPU: 1 core
     • Minimum RAM: 512 MB
   • Servers require internet egress access.
   • Ensure you have SSH access to the servers.

Step 2 - Create a Managed Kubernetes Cluster with a Manifest

1. Optionally update the manifest below and save it as generic-mk8s-template.yaml.

YAML

kind: mk8s
name: generic-mk8s-example
description: generic-mk8s-example mk8s in gcp-us-east1
tags: {}
spec:
  provider:
    generic:
      location: gcp-us-east1
      nodePools:
        - name: general
          labels:
            environment: generic-mk8s-example
          taints: []
  addOns:
    headlamp: {}
    localPathStorage: {}
    awsWorkloadIdentity: {}
  firewall:
    - description: default
      sourceCIDR: 0.0.0.0/0
  version: 1.35.3

This example creates a generic cluster with the following configurations:

• Add-ons: Includes Headlamp, Local Path Storage, and AWS Workload Identity.
• Location: The cluster’s Kubernetes control plane will be managed in the gcp-us-east1 location. Placing worker nodes close to the control plane is recommended for optimal performance.
• Kubernetes API Firewall: Uses the default rule, allowing public access to the Kubernetes API. It is advisable to restrict API access to a known IP range for security purposes.
• Kubernetes Version: 1.35.3.
• Node Pool: A single general node pool.

2. Create the Cluster: Deploy the generic-mk8s-example cluster by applying the manifest.

   • CLI: Execute cpln apply -f generic-mk8s-template.yaml --org YOUR_ORG_HERE.
   • Console: Apply the generic-mk8s-template.yaml file using the >_ apply option in the upper right corner.

   Wait until the cluster is initialized.

Step 3 - Connect the Servers

1. Obtain the Join Script:

   • Using the CLI: a. Save the Join Script to a file: Execute the command cpln mk8s join generic-mk8s-example --type join-script --options nodePoolName=general > join_general.sh.

   • Using the UI: a. Navigate to the Control Plane Console: Visit the Control Plane Console. b. Access the Dashboard: In the Control Plane Console, navigate to Kubernetes in the left sidebar panel, click on the generic-mk8s-example cluster, and go to Node Pools. Click on More on the right side of the general Node Pool and select Generate Join Script.

2. Copy and Execute the Script on the Server: Connect to the remote server and execute the join script. After the execution, the server should be joined to the cluster as a node under the general node pool. Repeat these steps for all necessary servers.

Step 4 - Accessing the Cluster

1. Using the Terminal

1. Obtain the cluster’s kubeconfig file: Execute the command cpln mk8s kubeconfig generic-mk8s-example -f /tmp/generic-mk8s-example-conf.
2. Access the cluster with kubectl: Use the obtained kubeconfig file by running export KUBECONFIG=/tmp/generic-mk8s-example-conf for the current shell session.

2. Using Headlamp

1. Navigate to the Control Plane Console: Visit the Control Plane Console.
2. Open Headlamp: In the Control Plane Console, navigate to Kubernetes in the left sidebar panel and click on Headlamp under Dashboard for the cluster generic-mk8s-example.