CloudInit CRD

Available as of v1.3.0

You can use the CloudInit CRD to configure Harvester operating system settings either manually or using GitOps solutions.

Background

The Harvester operating system uses the elemental-toolkit, which has a unique form of cloud-init support.

Settings configured during the Harvester installation process are written to the elemental cloud-init file in the /oem directory. Because the Harvester operating system is immutable, the cloud-init file ensures that node-specific settings are applied on each reboot.

The Harvester CloudInit CRD exposes the cloud-init file through a Kubernetes CRD. This allows you to modify node-specific settings after installation without needing to take steps to make the root filesystem writable.

In addition, the CloudInit CRD is persisted and synchronized with the underlying hosts so that changes made directly to the Harvester operating system are not lost whenever nodes are rebooted and upgraded.

CloudInit CRD - 图1note

The CloudInit CRD is a cluster-scoped resource. Ensure that your user account has the permissions required to access the resource (via Rancher role-based access control).

Getting Started

The following example adds SSH keys to all nodes in an existing Harvester cluster.

  1. apiVersion: node.harvesterhci.io/v1beta1
  2. kind: CloudInit
  3. metadata:
  4.   name: my-ssh-keys
  5. spec:
  6.   matchSelector: 
  7.     harvesterhci.io/managed: "true"
  8.   filename: 99-my-ssh-keys
  9.   contents: |
  10.     stages:
  11.       network:
  12.         - name: "add my ssh keys"
  13.           authorized_keys:
  14.             rancher:
  15.             - ssh-rsa key1
  16.             - ssh-rsa key2
  17.   paused: false

The spec field contains the following:

  • matchSelector (required): Label selector used to identify the nodes that the change must be applied to. harvesterhci.io/managed: "true" is a Harvester-specific label that you can use to select all nodes.
  • filename (required): Name of the file in /oem. cloud-init files in /oem are applied in alphabetical order. This can be used to ensure that file changes are applied during booting.
  • content (required): Inline content for the Elemental cloud-init resource that is written to target nodes.
  • paused (optional): Used to pause CloudInit CRD reconciliation. The Harvester controllers monitor Elemental cloud-init files that are managed by the CloudInit CRD. Direct changes made to these files are immediately reconciled back to the defined state unless the CRD is paused.

Once the object is created, you can log in to the target nodes to verify the results.

In the following example, a file named /oem/99-my-ssh-keys.yaml is created and subsequently monitored by the Harvester controllers.

  1. harvester-qhgd4:/oem # more 99-my-ssh-keys.yaml
  2. stages:
  3.   network:
  4.     - name: "add my ssh keys"
  5.       authorized_keys:
  6.         rancher:
  7.         - ssh-rsa key1
  8.         - ssh-rsa key2

The status subresource can be used to track the rollout of a change to the underlying Harvester nodes.

In the following example, the status values indicate that the change was applied to all three nodes in the cluster.

  1. status:
  2.   rollouts:
  3.     harvester-kfs2c:
  4.       conditions:
  5.       - lastTransitionTime: "2024-08-26T03:57:33Z"
  6.         message: ""
  7.         reason: CloudInitApplicable
  8.         status: "True"
  9.         type: Applicable
  10.       - lastTransitionTime: "2024-08-26T03:57:33Z"
  11.         message: Local file checksum is the same as the CloudInit checksum
  12.         reason: CloudInitChecksumMatch
  13.         status: "False"
  14.         type: OutOfSync
  15.       - lastTransitionTime: "2024-08-26T03:57:33Z"
  16.         message: 99-my-ssh-keys.yaml is present under /oem
  17.         reason: CloudInitPresentOnDisk
  18.         status: "True"
  19.         type: Present
  20.     harvester-qhgd4:
  21.       conditions:
  22.       - lastTransitionTime: "2024-08-26T03:57:33Z"
  23.         message: ""
  24.         reason: CloudInitApplicable
  25.         status: "True"
  26.         type: Applicable
  27.       - lastTransitionTime: "2024-08-26T04:00:00Z"
  28.         message: Local file checksum is the same as the CloudInit checksum
  29.         reason: CloudInitChecksumMatch
  30.         status: "False"
  31.         type: OutOfSync
  32.       - lastTransitionTime: "2024-08-26T04:00:00Z"
  33.         message: 99-my-ssh-keys.yaml is present under /oem
  34.         reason: CloudInitPresentOnDisk
  35.         status: "True"
  36.         type: Present
  37.     harvester-rmvzg:
  38.       conditions:
  39.       - lastTransitionTime: "2024-08-26T03:57:33Z"
  40.         message: ""
  41.         reason: CloudInitApplicable
  42.         status: "True"
  43.         type: Applicable
  44.       - lastTransitionTime: "2024-08-26T03:57:33Z"
  45.         message: Local file checksum is the same as the CloudInit checksum
  46.         reason: CloudInitChecksumMatch
  47.         status: "False"
  48.         type: OutOfSync
  49.       - lastTransitionTime: "2024-08-26T03:57:33Z"
  50.         message: 99-my-ssh-keys.yaml is present under /oem
  51.         reason: CloudInitPresentOnDisk
  52.         status: "True"
  53.         type: Present

CloudInit CRD - 图2note

Once the cloud-init changes are applied, you must reboot the nodes to ensure that the elemental-toolkit applies the requested changes to the operating system.

Deleting the CloudInit CRD results in the removal of associated files from the underlying Harvester nodes. As with other cloud-init resources, the effects of this change are not exhibited until the impacted nodes are rebooted.

You are encouraged to leverage Fleet and the CloudInit CRD to manage changes to the Harvester operating system.