Machine¶

The ghcr.io/captf-io/gcp-machine image implements the machine role for a TerraformMachine, cloned from a TerraformMachineTemplate. It creates one Compute Engine instance per Machine, control plane or worker, and joins control-plane instances to the API load balancer.

What it creates¶

The instance runs machine_type from image, with a boot_disk_size_gib GiB boot disk of boot_disk_type, optionally encrypted with boot_disk_kms_key_id. It has Shielded VM with vTPM and integrity monitoring, Secure Boot unless secure_boot is off, OS Login on, project-wide SSH keys blocked and the serial console off. It runs with the cloud-platform scope, so the service account’s IAM roles alone decide its access, and carries the cluster’s node tag, its role tag and additional_network_tags.

The instance name is the Node name, because cloud-provider-gcp looks instances up by Node name: machine_name when it is a valid Compute Engine name, else machine_name with invalid characters replaced, m- in front when it starts with a digit, cut to 54 characters, then - and 8 hex characters of its sha256.

Inputs¶

Contract inputs it uses:

• machine_name: the instance name.
• bootstrap_data, bootstrap_format: the instance’s user data or the staged secret.
• failure_domain: the zone. Without one, the module picks a zone from the sha256 of machine_name.
• kubernetes_version: fills the image placeholders.
• control_plane: the service account, the network tag, staging and the API registration.
• captf_cluster_outputs: the cluster’s exports.
• captf_cluster, captf_object, captf_tags: descriptions and labels.

User variables, set with spec.template.spec.variables on the TerraformMachineTemplate (variables.tf):

The image placeholders take kubernetes_version: {version} gives v1.33.4, {semver} 1.33.4 and {slug} v1-33-4, all without an RKE2 +rke2rN suffix; {fullslug} keeps it, v1-33-4-rke2r1. Image names allow no dots or +.

Outputs¶

Extra outputs: api_instance_group_membership_id, instance_id (the numeric ID, which changes only when the instance is replaced) and instance_self_link.

Health¶

From the instance’s current_status, read on every refresh:

TERMINATED is Compute Engine’s word for stopped: the instance and its disk still exist. A preempted Spot VM is TERMINATED, so it reports stopped and a MachineHealthCheck can replace it.

Lifecycle¶

A machine is immutable: CAPTF applies it once. The image is a create-time property: changes to image are ignored on an existing instance, so a drift check never reports an image family’s newer image as a replacement. Roll a new image through a new TerraformMachineTemplate. The instance group membership is replaced with the instance, since a replaced instance keeps its self link but leaves the group.

Bootstrap¶

The staging script takes the instance’s access token from the metadata server, reads the secret version over the Secret Manager REST API with curl, and installs the data as /etc/cloud/cloud.cfg.d/99-captf-bootstrap.cfg (see Shared Behavior). It retries for five minutes, which covers the access binding’s IAM propagation. Destroying the machine deletes the secret.

Size limits: a secret version holds at most 64 KiB, and an instance metadata value 256 KB. A larger payload fails a precondition; gzip it.

Who can read the data:

• Staged: the control-plane service account, and anything on the node that can take its token from the metadata server, pods included. Block pod egress to 169.254.169.254 with a NetworkPolicy, except for the system components that need it.
• Inline: anyone with compute.instances.get in the project, which roles/viewer and roles/compute.viewer include, and anything on the node that reaches the metadata server. Worker data holds only a short-lived join token.

Limitations¶

• A failure domain must be one of the cluster’s zones, and a control-plane machine’s zone must have an API instance group.
• Control-plane machines refuse spot: a preempted control-plane node takes an etcd member with it.
• The staged script needs curl, sed, base64 and gzip in the image; set bootstrap_delivery = "inline" for images without them.

Exceptions¶

• Ignition control-plane data stays in instance metadata. Ignition cannot run the staging script’s authenticated fetch, so Ignition data goes inline, readable through compute.instances.get and the metadata server. bootstrap_delivery = "inline" makes the same trade for cloud-config.

Example¶

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachineTemplate
metadata:
  name: demo-md-0
  namespace: team-a
spec:
  template:
    spec:
      source:
        image: ghcr.io/captf-io/gcp-machine:v0.1.0-opentofu
      variables:
        image: projects/my-images/global/images/capi-ubuntu-2404-{slug}
        machine_type: n2-standard-4