Oxide Rancher Machine Driver

This repository contains the Oxide Rancher machine driver, also known as a node driver in Rancher parlance. Rancher uses this node driver to provision virtual machines on Oxide that can then be used to deploy Kubernetes clusters.

Building

Build the binary using make.

make

Deploying

The binary name must match the format docker-machine-driver-* (e.g., docker-machine-driver-oxide) otherwise Rancher will error when trying to use the node driver.

Rancher Kubernetes

Important

You must deploy the Oxide node driver using the Kubernetes API rather than the Rancher UI otherwise Rancher will be unable to use the Oxide node driver. See #11 for more information.

1. Upload the docker-machine-driver-oxide binary somewhere accessible from Rancher Kubernetes.

2. Ensure your kubectl context is configured to use your Rancher Kubernetes cluster.

3. Create the following oxide-nodedriver.yaml Kubernetes manifest.

   ---
   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: <SHA256SUM_OF_NODE_DRIVER_BINARY>
     description: "Oxide Rancher node driver."
     displayName: oxide
     externalId: ""
     uiUrl: ""
     url: "https://example.com/docker-machine-driver-oxide"

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

   kubectl apply -f oxide-nodedriver.yaml

Rancher Machine CLI

1. Install rancher-machine.

2. Place the docker-machine-driver-oxide binary somewhere on PATH.

3. Use rancher-machine to create an Oxide instance.

   rancher-machine create \
     --driver oxide \
     --oxide-additional-ssh-public-key-ids 529885a0-2919-463a-a588-ac48f100a165 \
     --oxide-boot-disk-image-id feb2c8ee-5a1d-4d66-beeb-289b860561bf \
     --oxide-boot-disk-size "21474836480" \
     --oxide-host https://silo01.oxide.example.com \
     --oxide-memory "4294967296" \
     --oxide-project exampleproject \
     --oxide-ssh-user ubuntu \
     --oxide-subnet "default" \
     --oxide-token oxide-token-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
     --oxide-vcpus "2" \
     --oxide-vpc "default" \
     example-oxide-machine

Releasing

This project uses GoReleaser to build binaries and create GitHub releases. The release process is as follows.

1. Determine the version to be released. This could be a new major version or a minor or patch version (e.g., v1.0.0).

2. Determine the version control revision to be released (e.g., 1a0acaf). Usually this is the latest revision on the default branch for major version releases but it could be another revision for minor or patch releases.

3. Create a Git tag on the version control revision with a name that matches the version to be released (e.g., git tag -a v1.0.0 1a0acaf).

4. Push the newly created Git tag to GitHub (e.g., git push origin v1.0.0).

5. Monitor the latest Release GitHub Actions job to ensure it runs successfully.

6. Ensure the GitHub Releases page shows a new release for the desired version.

   1. Update the description for the release as necessary.

   2. Ensure the release is published, not a draft.