Basic Configuration

Before creating a K8s Cluster, ensure that the minimum required components are configured and available.

OneKS Service

Verify that the OneKS service is running. On the command line of your OpenNebula Front-end, run the following command:

sudo systemctl status opennebula-ks.service

The service should be in the active (running) state.

OneGate Service

Verify that OneGate is configured and reachable. OneGate is required during K8s Cluster provisioning because the bootstrap process uses it to communicate with OpenNebula services.

Check the OneGate service status on the Front-end command line:

sudo systemctl status opennebula-gate.service

Validate the OneGate configuration using the OpenNebula OneGate documentation.

Transparent Proxy Configuration

Verify that the transparent proxy is configured to expose OneGate and the OpenNebula API through the a netowrk interconnecting the Front-end and Hosts.

The configuration is typically defined in the following location on the OpenNebula Front-end:

/var/lib/one/remotes/etc/vnm/OpenNebulaNetwork.conf

Example configuration:

:tproxy:
  - :remote_addr: 192.168.150.1 # Front-end IP
    :remote_port: 5030
    :service_port: 5030
  - :remote_addr: 192.168.150.1 # Front-end IP
    :remote_port: 2633
    :service_port: 2633

Replace 192.168.150.1 with the Front-end IP address used to connect to the Hosts and save the file. On Front-end command line, as the oneadmin system user, sync the OpenNebulaNetwork.conf file with the hypervisor Hosts, by running onehost sync -f.

Public and Private Virtual Networks

Identify the OpenNebula Virtual Network IDs that will be used by the K8s Cluster. On the Front-end command line, run the following command to inspect the available networks:

onevnet list

You need:

• A public Virtual Network, used as the gateway to the Internet and for external K8s Cluster connectivity.
• A private Virtual Network, used for internal communication between K8s Cluster nodes.

User Permissions

Verify that the user has permission to create and manage OneKS K8s Clusters and the related OpenNebula resources, including Virtual Machines, Virtual Networks, images, and templates.

OneKS stores its K8s Cluster and node-group definitions as OpenNebula documents. The user must therefore also have the required permissions to manage OpenNebula document resources. Without document permissions, OneKS may be able to reach the infrastructure resources but fail when creating, updating, or deleting the OneKS records that represent the K8s Cluster lifecycle.

Use OpenNebula ACL rules to grant the required permissions for the target users or groups. For more information, see the Managing ACL Rules documentation.

kubectl Client

kubectl is the official command-line interface for Kubernetes. kubectl communicates with K8s Clusters launched by OneKS remotely from the Front-end Host, removing the need to interact directly with the K8s Cluster VMs themselves. kubectl handles the following key functions:

• K8s Cluster Management: View nodes, health status, and resource usage.
• Workload Deployment: Create, update, and delete pods, services and containerized application deployments.
• Troubleshooting: Retrieving logs, describing pod and node statuses or errors.
• Configuration: Manage secrets, environment variables and storage.

kubectl must be installed on the Front-end Host machine. On a Linux machine, run the following command to install kubectl:

1. Download the latest release with the following command:

• Architecture:
• x86-64
• ARM64

curl -fsSL "https://dl.k8s.io/release/$(curl -L -s \
https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

curl -LO "https://dl.k8s.io/release/$(curl -L -s \
https://dl.k8s.io/release/stable.txt)/bin/linux/arm64/kubectl"

To download a specific version of kubectl, replace $(curl -L -s https://dl.k8s.io/release/stable.txt) in the above commands with the version number. E.g. for version 1.36.0:

• Architecture:
• x86-64
• ARM64

curl -fsSL "https://dl.k8s.io/release/v1.36.0/bin/linux/amd64/kubectl"

curl -LO "https://dl.k8s.io/release/v1.36.0/bin/linux/arm64/kubectl"

2. Install kubectl:

sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

chmod +x kubectl
mkdir -p ~/.local/bin
mv ./kubectl ~/.local/bin/kubectl
# and then append (or prepend) ~/.local/bin to $PATH

3. Ensure the version you have installed is up-to-date or the expected version:

kubectl version --client

If the above command is not suitable for your Front-end Host configuration, consult the kubectl installation documentation for MacOS or Windows.

Automatically Generated Resources

When OneKS starts, it automatically downloads the OneKS appliance from the OpenNebula Marketplace. During this process, OneKS creates the corresponding OpenNebula image and VM template in the OpenNebula database, making them ready to deploy K8s Clusters.

The generated image is used by the Seed VM to start the K8s Cluster deployment process. For more information about the Seed VM role during provisioning, see the Seed VM section in Core Concepts.

The appliance name and ID can be configured from the control-plane spec configuration file:

/var/lib/one/oneks/controlplane/general/controlplane.conf

You can also configure the datastore where the appliance image will be stored. This datastore must be accessible by the OpenNebula Hosts where the K8s Cluster VMs will be deployed.

Example configuration:

dependencies:
  - object: seed_vm
    options:
      creation_timeout: 2000
      destroy_on_running: true
      appliance_name: OneKS Appliance
      appliance_id: c3ecb387-e726-49fe-975d-fa39c6d40d05
      appliance_ds: 1

Next Steps

After completing the basic configuration steps described here, you are ready to start provisioning K8s Clusters with OneKS. Move on to the OneKS Quick-start Guide to learn how to deploy a basic K8s Cluster.