MachinePool¶

The ghcr.io/captf-io/azure-machinepool image implements the machinepool role on Azure: one uniform Linux virtual machine scale set of worker nodes per MachinePool, in the cluster’s resource group, with an Azure Autoscale setting that holds its capacity. See Machine Pools for the objects to create.

What it creates¶

Without exports (an externally managed cluster and no external_cluster_exports) the scale set and autoscale setting are not created and a precondition fails.

Inputs¶

Contract inputs used: captf_cluster_outputs (the cluster’s exports), captf_tags, machinepool_name, replicas, bootstrap_data, bootstrap_format, failure_domains, cluster_failure_domains, kubernetes_version, node_labels and autoscaling. captf_contract is validated; captf_cluster and captf_object are not used.

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

Outputs¶

The scale set is named <machinepool_name, made valid, at most 41 characters>-<8 hex characters>, and its instances’ hostnames start with that name; cloud-provider-azure finds an instance by its hostname, so name the Nodes after it (nodeRegistration.name: '{{ ds.meta_data["local_hostname"] }}').

Health¶

The module lists the scale set first and reads its instances only when the listing finds it. Each instance’s power state maps like a machine’s; the pool follows the shared order:

Azure lists an instance until it is deleted, so no instance maps to terminated: a deleted instance leaves provider_id_list.

Lifecycle¶

The provider turns off roll_instances_when_required and reimage_on_manual_upgrade: with azurerm’s defaults every token rotation would reimage every instance. So nothing rolls by itself, and a version change creates a new scale set with create_before_destroy; the pool briefly needs twice its quota. There is no drain: pools have no Machines. Scheduled Events announce every deletion 5 minutes ahead, for a termination handler that drains.

Bootstrap¶

• Delivery. As for the machine role: custom data, cloud-config in a MIME multipart message after a boot hook, and Ignition unchanged (gzipped Ignition fails a precondition). The boot hook writes /etc/kubernetes/azure.json for the worker identity when the file is absent and renders the node labels as the shared behavior describes; Ignition with labels left to render fails a precondition.
• Size limit. 65,535 bytes of custom data, 87,380 base64 characters; a precondition stops a larger message.
• Who can read it. As for the machine role: not through the instance metadata service or a read of the scale set; on the node only root; and the pool’s state Secret on the management cluster.

Limitations¶

• Workers only: the control plane uses the machine role.
• Changes reach new instances only; a version change is the way to roll the pool.
• Capacity changes go through Azure Autoscale and take about a minute to reach the scale set; replicas follows at the next refresh.
• The scale set read fails if an instance disappears between listing it and reading its NICs; the next refresh succeeds.
• Azure public cloud only.

Exceptions¶

• pool/autoscaling-ignore-changes, a tfcapi-lint warning, is allowed: the scale set ignores changes to instances, its desired count, which the check’s pattern does not know, and Azure Autoscale holds the capacity in both modes.
• Version rolls by generation. The roll is a new scale set name with create_before_destroy, not terraform_data.kubernetes_version_roll: a replacement under the same name would collide with the old scale set.
• Other replacements. failure_domains, spot, trusted_launch and os_disk_storage_account_type replace the scale set, because azurerm 5.7.0 cannot update them in place.
• replicas is null once the scale set is gone: the capacity is then unknown, and an empty provider_id_list with an unknown capacity keeps Cluster API’s guard against deleting every Node engaged.
• The membership_excludes_terminated test asserts that stopped and deallocated instances stay members, since Azure has no terminated instance state; the ScaleSetNotFound reading has no test.

Example¶

apiVersion: infrastructure.cluster.x-k8s.io/v1alpha1
kind: TerraformMachinePool
metadata:
  name: demo-pool-0
  namespace: team-a
  labels:
    cluster.x-k8s.io/cluster-name: demo
spec:
  source:
    image: ghcr.io/captf-io/azure-machinepool:v0.1.0-opentofu
  variables:
    image_id: /communityGalleries/ClusterAPI-f72ceb4f-5159-4c26-a0fe-2ea738f0d019/images/capi-ubun2-2404/versions/{semver}
    autoscaling_scale_out_cpu_percent: 70