Machine¶

The ghcr.io/captf-io/openstack-machine image implements the machine role for a TerraformMachine on OpenStack. It creates one Nova server on a Neutron port of the cluster’s subnet and boots it with the bootstrap payload; for a control-plane machine it first adds the port’s address to the cluster’s API pools. Everything about the cluster comes from captf_cluster_outputs, the cluster role’s exports.

What it creates¶

The server waits for the pool members, so a control-plane machine is in the API pools before it boots, as kubeadm init and RKE2 joins require (see Control-plane machines). It reads the server’s status for health, except while the server is in BUILD.

Inputs¶

Contract inputs used:

• captf_contract (validated), captf_object (the port name), captf_tags;
• captf_cluster_outputs: network, subnet, groups, server group, pools, zones and region, validated to schema captf.io/openstack-cluster/v1 or {};
• machine_name: the server name, member names, the Hostname address and the default zone pick;
• bootstrap_data and bootstrap_format (see Bootstrap);
• failure_domain: the server’s availability zone, one of the cluster’s;
• kubernetes_version: fills {version} and {semver} in image_name, without its +rke2rN suffix;
• control_plane: pool membership, the control-plane group and the server group.

captf_cluster is declared and unused.

User variables, set in the TerraformMachineTemplate’s spec.template.spec.variables (Module Variables; source: variables.tf):

Outputs¶

provider_id is what the OpenStack cloud controller manager writes to the Node: makeInstanceID in cloud-provider-openstack v1.34.1 returns openstack:///<id>, or openstack://<region>/<id> when OS_CCM_REGIONAL=true. The addresses mirror what it reports for a server without floating IPs. Without a requested failure domain, the module picks a zone from the sha256 of machine_name, the same way in every repository.

Health¶

From the server’s Nova status, re-read on every refresh.

Provider 3.4.0 reads only some of these. The server resource reads ACTIVE, BUILD, SHUTOFF, PAUSED, SHELVED, SHELVED_OFFLOADED, MIGRATING and ERROR; in any other status its refresh fails, and so does every drift Job and destroy until the server leaves that status. The status read is skipped while the server is in BUILD, where it would fail, so health then comes from the server itself and a server stuck building can still be destroyed.

Lifecycle¶

Machines are immutable: the module applies once, then refreshes for health and destroys on delete. Its inputs, captf_cluster_outputs included, are pinned at the first apply, so a later change to the cluster’s zones or exports never reaches a running machine. Changes outside Terraform show up in drift reports only:

• The server’s image is ignored after creation, so a rotated or deleted image never shows as drift (the provider would rebuild the server in place).
• A deleted flavor shows as a planned replacement; a renamed or resized one as an in-place resize.
• On destroy, the server goes before its pool members; Cluster API has drained the node by then, and the load balancer’s monitor takes the backend out.

Bootstrap¶

• bootstrap_data goes to Nova as user data unchanged: valid base64 passes through as is, so gzipped cloud-config works, and state keeps only a SHA1 of it. Gzipped Ignition fails a precondition.
• Nova accepts at most 65,535 bytes of base64 user data; a larger payload fails a precondition. Compress it (CAPRKE2 gzipUserData) if needed.
• Who can read it. OpenStack has no instance identity to fetch a staged payload with, so there is no bootstrap_delivery: the control-plane payload, with the cluster CA keys, sits in user data, and anything that reaches the metadata service (169.254.169.254) on the node can read it. A config drive does not turn the metadata service off. Deny 169.254.169.254/32 to pods with a CNI NetworkPolicy. Cluster API Provider OpenStack has the same exposure.

Limitations¶

• No spot. interruptible is always false.
• Port security groups. Keep the cloud controller manager’s manage-security-groups off: groups it adds to the port show as drift.

Exceptions¶

• The server is named machine_name, not the conventions’ prefixed name, because the cloud controller manager finds servers by Node name.
• The boot-from-volume root volume carries no tags: Nova creates it from the block device mapping, which takes no metadata, and a separately created, tagged volume would need a Cinder availability zone named like the Nova one.
• Bootstrap payloads are readable from the metadata service (see Bootstrap), a deviation from the contract’s checklist.
• There is no rejects_spot_control_plane test: Nova has no spot servers.
• No capacity labels on the image: there is no default flavor to describe.

Example¶

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachineTemplate
metadata:
  name: demo-md-0
spec:
  template:
    spec:
      source:
        image: ghcr.io/captf-io/openstack-machine:v0.1.0-opentofu
      variables:
        flavor_name: m1.large
        image_name: ubuntu-2404-kube-{version}