Rancher

The Oxide Rancher node driver is used to provision Oxide instances that Rancher uses to launch and manage Kubernetes clusters.

This guide describes how to use the Oxide Rancher node driver to deploy a Kubernetes cluster on Oxide.

Requirements

To follow this guide you’ll need the following.

  • An Oxide project. We’ll create the Rancher instance and the Kubernetes cluster within this project using the project’s default VPC.

  • Oxide API credentials. Refer to Authentication for instructions on generating and using API credentials.

  • An Oxide image within the Oxide project using a Rancher RKE2 supported operating system. We’ll use this image to run Rancher and the Kubernetes nodes.

Install Rancher

We’ll run a development installation of Rancher on a single Oxide instance using Docker for the purpose of this guide. If you have access to a production installation of Rancher you can use that instead.

  1. Create an Oxide instance to run Rancher. Any operating system that’s supported by Rancher will work, but we’ll use Ubuntu 24.04 LTS in this guide. Allocate 4 vCPUs, 16 GiB of memory, and a 20 GiB disk to this instance.

  2. Update the instance’s VPC firewall rules to allow inbound connections to ports 80/TCP and 443/TCP. We’ll connect to Rancher using the instance’s IP address using these ports.

  3. Install Docker on the instance and run a single-node Rancher server. Modify the CATTLE_BOOTSTRAP_PASSWORD as desired.

    docker run \
      --detach \
      --restart=unless-stopped \
      --env CATTLE_BOOTSTRAP_PASSWORD=oxide \
      --publish 80:80 \
      --publish 443:443 \
      --privileged \
    docker.io/rancher/rancher:latest

  4. Open a browser and connect to Rancher using the instance’s IP address. Log in with username admin and the password from CATTLE_BOOTSTRAP_PASSWORD.

Configure Kubernetes Access

Here’s how you can configure kubectl access to a Rancher-managed Kubernetes cluster. Rancher itself runs within a Rancher-managed Kubernetes cluster named local, which is the cluster we’ll connect to in order to interact with Rancher.

  1. Install kubectl.

  2. Open Rancher in your browser and click the desired Kubernetes cluster in the sidebar. Alternatively, access the cluster directly at the URL https://${RANCHER_HOST}/dashboard/c/${CLUSTER_NAME}/explorer.

  3. In the top navigation bar, click Download KubeConfig download the kubeconfig file for the desired Kubernetes cluster.

  4. Configure kubectl to use the downloaded kubeconfig file.

  5. Verify kubectl access to the desired Kubernetes cluster.

    kubectl get node

Install the Oxide Rancher Node Driver

  1. Create the following oxide-nodedriver.yaml Kubernetes manifest. Update the url and checksum to use the latest stable Oxide Rancher node driver, which can be found on GitHub releases.

    # NodeDriver defines the Oxide Rancher node driver.
    ---
    apiVersion: management.cattle.io/v3
    kind: NodeDriver
    metadata:
      name: oxide
      annotations:
        privateCredentialFields: token
        publicCredentialFields: host
      finalizers:
      - controller.cattle.io/node-driver-controller
    spec:
      active: true
      addCloudCredential: true
      builtin: false
      checksum: f68726fd27312a669ccd01bdc84d568babc24d53496a542ea401670176f97cad
      description: "Oxide Rancher node driver."
      displayName: oxide
      externalId: ""
      uiUrl: ""
      url: "https://github.com/oxidecomputer/rancher-machine-driver-oxide/releases/download/v0.7.2/docker-machine-driver-oxide"

  2. Apply the Kubernetes manifest to create the Oxide Rancher node driver.

    $ kubectl apply -f oxide-nodedriver.yaml
    nodedriver.management.cattle.io/oxide created

  3. Verify the Oxide Rancher node driver was successfully created.

    $ kubectl get nodedriver oxide
    NAME    AGE
    oxide   75s

Create the Oxide Kubernetes Cluster

  1. Create an Oxide cloud credential. The Oxide node driver uses this cloud credential to communicate with Oxide. Replace $OXIDE_HOST and $OXIDE_TOKEN with values appropriate for your environment.

    $ kubectl create secret generic oxide-cloud-credential \
      --namespace cattle-global-data \
      --type Opaque \
      --from-literal=oxidecredentialConfig-host=$OXIDE_HOST \
      --from-literal=oxidecredentialConfig-token=$OXIDE_TOKEN

    $ kubectl annotate secret oxide-cloud-credential \
      --namespace cattle-global-data \
      field.cattle.io/name=oxide-cloud-credential \
      provisioning.cattle.io/driver=oxide

  2. Create the following oxide-k8s.yaml Kubernetes manifest describing the Oxide machine configuration and the Oxide Kubernetes cluster. Change $OXIDE_PROJECT, $BOOT_DISK_IMAGE_ID, and $SSH_USER to values appropriate for your environment. We’ll use an Ubuntu 24.04 LTS image and the ubuntu username in this guide.

    # OxideConfig contains configuration for the Oxide Rancher node driver.
    ---
    apiVersion: rke-machine-config.cattle.io/v1
    kind: OxideConfig
    metadata:
      name: oxide-machine-config
      namespace: fleet-default
    bootDiskImageId: "$BOOT_DISK_IMAGE_ID"
    project: "$OXIDE_PROJECT"
    sshUser: "$SSH_USER"

    # Cluster defines the Oxide Kubernetes cluster.
    ---
    apiVersion: provisioning.cattle.io/v1
    kind: Cluster
    metadata:
      name: oxide-k8s-cluster
      namespace: fleet-default
    spec:
      cloudCredentialSecretName: cattle-global-data:oxide-cloud-credential
      kubernetesVersion: v1.31.9+rke2r1
      rkeConfig:
        machinePools:
          - name: oxide-k8s-pool
            quantity: 1
            machineConfigRef:
              kind: OxideConfig
              name: oxide-machine-config
            etcdRole: true
            workerRole: true
            controlPlaneRole: true

  3. Apply the Kubernetes manifest to create the Oxide Kubernetes cluster.

    $ kubectl apply -f oxide-k8s.yaml
    oxideconfig.rke-machine-config.cattle.io/oxide-machine-config created
    cluster.provisioning.cattle.io/oxide-k8s-cluster created

  4. Verify the Oxide Kubernetes cluster is successfully provisioned.

    $ kubectl get cluster --namespace fleet-default oxide-k8s-cluster
    NAME                CLUSTERCLASS   PHASE         AGE     VERSION
    oxide-k8s-cluster                  Provisioned   4m45s

Run a Workload on the Oxide Kubernetes Cluster

  1. Follow Configure Kubernetes Access to connect to the oxide-k8s-cluster Kubernetes cluster.

  2. Run an example workload on the Oxide Kubernetes cluster.

    $ kubectl apply -f https://k8s.io/examples/application/deployment.yaml
    deployment.apps/nginx-deployment created

  3. Verify the example workload returns ready.

    $ kubectl get deployment
    NAME               READY   UP-TO-DATE   AVAILABLE   AGE
    nginx-deployment   2/2     2            2           85s

Delete the Oxide Kubernetes Cluster

  1. Follow Configure Kubernetes Access to connect to the local Kubernetes cluster.

  2. Delete the Oxide Kubernetes cluster.

    $ kubectl delete clusters.provisioning.cattle.io --namespace fleet-default oxide-k8s-cluster
    cluster.provisioning.cattle.io "oxide-k8s-cluster" deleted

  3. Delete the Oxide instance running Rancher.

References