Rancher

The Oxide Rancher node driver lets Rancher provision Oxide instances as Kubernetes nodes. This guide shows how to use the node driver to deploy a Kubernetes cluster on Oxide with the Oxide cloud controller manager, which integrates cluster operations with Oxide infrastructure.

Requirements

To follow this guide, you need the following.

API credentials for your Oxide silo. Refer to Authentication for instructions on generating API credentials.
A project within your Oxide silo with a configured VPC and subnet. Rancher will provision Oxide instances in this project, VPC, and subnet to form the Kubernetes cluster.
An Oxide image in your project that uses a Rancher RKE2-supported operating system. The Oxide instances Rancher provisions will use this image.
An existing Rancher installation that can reach the Oxide API endpoint for your silo. Rancher uses the node driver to communicate with the Oxide API to provision instances. See oxidecomputer/showcase for Terraform configuration to deploy Rancher on Oxide, specifically the rke2 and rancher directories.
kubectl: Used to install the node driver into Rancher and connect to the Kubernetes cluster you create in this guide.

Configure kubectl

Rancher runs within a Rancher-managed Kubernetes cluster named local. Configure kubectl to access this Kubernetes cluster so you can interact with Rancher through the API. Use this context to install the node driver, create the cloud credential, and provision the Oxide-backed cluster.

Open Rancher in your browser and click the desired Kubernetes cluster in the sidebar (e.g., local). Alternatively, access the cluster directly at the URL https://${RANCHER_HOST}/dashboard/c/${CLUSTER_NAME}/explorer.
In the top navigation bar, click Download KubeConfig to download the kubeconfig file for the desired Kubernetes cluster.
Configure kubectl to use the downloaded kubeconfig file.
Verify kubectl access to the desired Kubernetes cluster.
```
kubectl get nodes
```

Install the node driver

Use the latest stable Oxide Rancher node driver release on GitHub. The release assets include the driver binary and a SHA-256 checksum file.

Placeholder Value

Placeholder	Value
`${VERSION}`	The node driver release tag (e.g., `v0.11.0`).
`${CHECKSUM}`	The SHA-256 checksum from the `docker-machine-driver-oxide_SHA256SUMS` release asset.

${VERSION}

The node driver release tag (e.g., v0.11.0).

${CHECKSUM}

The SHA-256 checksum from the docker-machine-driver-oxide_SHA256SUMS release asset.

Create the following nodedriver.yaml Kubernetes manifest.

nodedriver.yaml

---
apiVersion: management.cattle.io/v3
kind: NodeDriver
metadata:
  name: oxide
  annotations:
    privateCredentialFields: token
    publicCredentialFields: host
    nodedriver.cattle.io/file-to-field-aliases: "userDataFile:userDataFile"
  finalizers:
  - controller.cattle.io/node-driver-controller
spec:
  active: true
  addCloudCredential: true
  builtin: false
  checksum: "${CHECKSUM}"
  description: "Oxide Rancher node driver."
  displayName: oxide
  externalId: ""
  uiUrl: ""
  url: "https://github.com/oxidecomputer/rancher-machine-driver-oxide/releases/download/${VERSION}/docker-machine-driver-oxide"

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

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

Verify the Oxide Rancher node driver was successfully created.

$ kubectl get nodedriver oxide
NAME    AGE
oxide   75s

Create the cloud credential

Create an Oxide cloud credential. The node driver uses it to communicate with Oxide. Replace ${OXIDE_HOST} and ${OXIDE_TOKEN} with values for your Oxide silo.

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

Create the Kubernetes cluster

The cluster manifest defines how Rancher creates the Oxide instances and configures the Kubernetes cluster that runs on them. It disables the default RKE2 cloud controller in favor of an external cloud provider, and the additionalManifest section installs the Oxide cloud controller manager, which uses Oxide credentials to integrate the cluster with Oxide infrastructure.

Placeholder Value

Placeholder	Value
`${OXIDE_HOST}`	Oxide API endpoint for your silo.
`${OXIDE_TOKEN}`	Oxide API token for your silo.
`${OXIDE_PROJECT}`	Oxide project where Rancher provisions instances.
`${BOOT_DISK_IMAGE_ID}`	Oxide image ID for an RKE2-supported image in the target project.
`${SSH_USER}`	Default SSH user configured by the image.
`${VPC}`	VPC where Rancher provisions instances.
`${SUBNET}`	Subnet where Rancher provisions instances.
`${K8S_VERSION}`	Kubernetes version supported by your Rancher installation (e.g., `v1.36.1+rke2r1`).
`${OXIDE_CCM_VERSION}`	Oxide cloud controller manager version, (e.g., `0.7.1`). Found on GitHub.

${OXIDE_HOST}

Oxide API endpoint for your silo.

${OXIDE_TOKEN}

Oxide API token for your silo.

${OXIDE_PROJECT}

Oxide project where Rancher provisions instances.

${BOOT_DISK_IMAGE_ID}

Oxide image ID for an RKE2-supported image in the target project.

${SSH_USER}

Default SSH user configured by the image.

${VPC}

VPC where Rancher provisions instances.

${SUBNET}

Subnet where Rancher provisions instances.

${K8S_VERSION}

Kubernetes version supported by your Rancher installation (e.g., v1.36.1+rke2r1).

${OXIDE_CCM_VERSION}

Oxide cloud controller manager version, (e.g., 0.7.1). Found on GitHub.

Create the following cluster.yaml Kubernetes manifest describing the Oxide machine configuration and the Kubernetes cluster.

cluster.yaml

---
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}"
vpc: "${VPC}"
subnet: "${SUBNET}"
---
apiVersion: provisioning.cattle.io/v1
kind: Cluster
metadata:
  name: oxide-k8s-cluster
  namespace: fleet-default
spec:
  cloudCredentialSecretName: cattle-global-data:oxide-cloud-credential
  kubernetesVersion: ${K8S_VERSION}
  rkeConfig:
    machinePools:
      - name: oxide-k8s-pool
        quantity: 1
        machineConfigRef:
          kind: OxideConfig
          name: oxide-machine-config
        etcdRole: true
        workerRole: true
        controlPlaneRole: true
    machineGlobalConfig:
      disable-cloud-controller: true
      kubelet-arg:
        - "cloud-provider=external"
      kube-controller-manager-arg:
        - "cloud-provider=external"
    additionalManifest: |
      apiVersion: v1
      kind: Secret
      metadata:
        name: oxide-cloud-controller-manager
        namespace: kube-system
      type: Opaque
      stringData:
        oxide-host: "${OXIDE_HOST}"
        oxide-token: "${OXIDE_TOKEN}"
        oxide-project: "${OXIDE_PROJECT}"
      ---
      apiVersion: helm.cattle.io/v1
      kind: HelmChart
      metadata:
        name: oxide-cloud-controller-manager
        namespace: kube-system
      spec:
        bootstrap: true
        chart: oci://ghcr.io/oxidecomputer/helm-charts/oxide-cloud-controller-manager
        version: "${OXIDE_CCM_VERSION}"
        targetNamespace: kube-system

Apply the Kubernetes manifest to create the Kubernetes cluster.

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

Verify the 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 Kubernetes

Follow Configure kubectl to connect to the oxide-k8s-cluster Kubernetes cluster. Use this context to run workloads on the Oxide-backed cluster.

Run an example workload.

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

Verify the example workload is ready.

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

Delete the example workload.

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

Delete the Kubernetes cluster

Follow Configure kubectl to connect to the local Kubernetes cluster.

Delete the Kubernetes cluster.

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

Delete the cloud credential.

kubectl delete secret oxide-cloud-credential \
  --namespace cattle-global-data

Delete the node driver.

$ kubectl delete -f nodedriver.yaml
nodedriver.management.cattle.io/oxide deleted

Rancher

Table of Contents