This is a cache of https://docs.okd.io/latest/machine_management/cluster_api_machine_management/cluster-api-getting-started.html. It is a snapshot of the page at 2025-07-01T18:52:04.858+0000.
Getting started with the Cluster <strong>api</strong> - Managing machines with the Cluster <strong>api</strong> | Machine management | OKD 4
  1. Documentation
×

Getting started with the Cluster api

The Machine api and Cluster api are distinct api groups that have similar resources. You can use these api groups to automate the management of infrastructure resources on your OKD cluster.

Managing machines with the Cluster api is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

When you install a standard OKD cluster that has three control plane nodes, three compute nodes, and uses the default configuration options, the installation program provisions the following infrastructure resources in the openshift-machine-api namespace

  • One control plane machine set that manages three control plane machines.

  • One or more compute machine sets that manage three compute machines.

  • One machine health check that manages spot instances.

When you install a cluster that supports managing infrastructure resources with the Cluster api, the installation program provisions the following resources in the openshift-cluster-api namespace:

  • One cluster resource.

  • One provider-specific infrastructure cluster resource.

On clusters that support migrating Machine api resources to Cluster api resources, a two-way synchronization controller creates these primary resources automatically. For more information, see Migrating Machine api resources to Cluster api resources.

Creating the Cluster api primary resources

For clusters that do not support migrating Machine api resources to Cluster api resources, you must manually create the following Cluster api resources in the openshift-cluster-api namespace:

  • One or more machine templates that correspond to compute machine sets.

  • One or more compute machine sets that manage three compute machines.

Creating a Cluster api machine template

You can create a provider-specific machine template resource by creating a YAML manifest file and applying it with the OpenShift CLI (oc).

Prerequisites

  • You have deployed an OKD cluster.

  • You have enabled the use of the Cluster api.

  • You have access to the cluster using an account with cluster-admin permissions.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Create a YAML file similar to the following. This procedure uses <machine_template_resource_file>.yaml as an example file name.

    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: <machine_template_kind> (1)
metadata:
  name: <template_name> (2)
  namespace: openshift-cluster-api
spec:
  template:
    spec: (3)
    1 Specify the machine template kind. This value must match the value for your platform. The following values are valid:
    Cluster infrastructure provider Value

    Amazon Web Services (AWS)

    AWSMachineTemplate

    Google Cloud Platform (GCP)

    GCPMachineTemplate

    Microsoft Azure

    AzureMachineTemplate

    OpenStack

    OpenStackMachineTemplate

    VMware vSphere

    VSphereMachineTemplate

    Bare metal

    Metal3MachineTemplate
    2 Specify a name for the machine template.
    3 Specify the details for your environment. These parameters are provider specific. For more information, see the sample Cluster api machine template YAML for your provider.

  2. Create the machine template CR by running the following command:

    $ oc create -f <machine_template_resource_file>.yaml
Verification

  • Confirm that the machine template CR is created by running the following command:

    $ oc get <machine_template_kind> -n openshift-cluster-api

    where <machine_template_kind> is the value that corresponds to your platform.

    Example output
    NAME              AGE
<template_name>   77m
Additional resources

Creating a Cluster api compute machine set

You can create compute machine sets that use the Cluster api to dynamically manage the machine compute resources for specific workloads of your choice.

Prerequisites

  • You have deployed an OKD cluster.

  • You have enabled the use of the Cluster api.

  • You have access to the cluster using an account with cluster-admin permissions.

  • You have installed the OpenShift CLI (oc).

  • You have created the machine template resource.

Procedure

  1. Create a YAML file similar to the following. This procedure uses <machine_set_resource_file>.yaml as an example file name.

    apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineSet
metadata:
  name: <machine_set_name> (1)
  namespace: openshift-cluster-api
spec:
  clusterName: <cluster_name> (2)
  replicas: 1
  selector:
    matchLabels:
      test: example
  template:
    metadata:
      labels:
        test: example
    spec: (3)
# ...
    1 Specify a name for the compute machine set. The cluster ID, machine role, and region form a typical pattern for this value in the following format: <cluster_name>-<role>-<region>.
    2 Specify the name of the cluster. Obtain the value of the cluster ID by running the following command: 
    $  oc get infrastructure cluster \
   -o jsonpath='{.status.infrastructureName}'
    3 Specify the details for your environment. These parameters are provider specific. For more information, see the sample Cluster api compute machine set YAML for your provider.

  2. Create the compute machine set CR by running the following command:

    $ oc create -f <machine_set_resource_file>.yaml

  3. Confirm that the compute machine set CR is created by running the following command:

    $ oc get machineset.cluster.x-k8s.io -n openshift-cluster-api
    Example output
    NAME                 CLUSTER          REPLICAS   READY   AVAILABLE   AGE   VERSION
<machine_set_name>   <cluster_name>   1          1       1           17m

    When the new compute machine set is available, the REPLICAS and AVAILABLE values match. If the compute machine set is not available, wait a few minutes and run the command again.

Verification

  • To verify that the compute machine set is creating machines according to your required configuration, review the lists of machines and nodes in the cluster by running the following commands:

    • View the list of Cluster api machines:

      $ oc get machine.cluster.x-k8s.io -n openshift-cluster-api
      Example output
      NAME                             CLUSTER          NODENAME                                 PROVIDERID      PHASE     AGE     VERSION
<machine_set_name>-<string_id>   <cluster_name>   <ip_address>.<region>.compute.internal   <provider_id>   Running   8m23s

    • View the list of nodes:

      $ oc get node
      Example output
      NAME                                       STATUS   ROLES    AGE     VERSION
<ip_address_1>.<region>.compute.internal   Ready    worker   5h14m   v1.28.5
<ip_address_2>.<region>.compute.internal   Ready    master   5h19m   v1.28.5
<ip_address_3>.<region>.compute.internal   Ready    worker   7m      v1.28.5
Additional resources

Migrating Machine api resources to Cluster api resources

On clusters that support migrating Machine api resources to Cluster api resources, a two-way synchronization controller creates the following Cluster api resources in the openshift-cluster-api namespace:

  • One or more machine templates that correspond to compute machine sets.

  • One or more compute machine sets that manage three compute machines.

  • One or more Cluster api compute machines that correspond to each Machine api compute machine.

The two-way synchronization controller only operates on clusters with the MachineapiMigration feature gate in the TechPreviewNoUpgrade feature set enabled.

These Cluster api resources correspond to the resources that the installation program provisions in the openshift-machine-api namespace for a cluster that uses the default configuration options. The Cluster api resources have the same names as their Machine api counterparts and appear in the output of commands, such as oc get, that list resources. The synchronization controller creates the Cluster api resources in an unprovisioned (Paused) state to prevent unintended reconciliation.

For supported configurations, you can migrate a Machine api resource to the equivalent Cluster api resource by changing which api it considers authoritative. When you migrate a Machine api resources to the Cluster api, you transfer management of the resource to the Cluster api.

By migrating a Machine api resource to use the Cluster api, you can verify that everything works as expected before deciding to use the Cluster api in production clusters. After migrating a Machine api resource to an equivalent Cluster api resource, you can examine the new resource to verify that the features and configuration match the original Machine api resource.

When you change the authoritative api for a compute machine set, any existing compute machines that the compute machine set manages retain their original authoritative api. As a result, a compute machine set that manages machines that use different authoritative apis is a valid and expected occurrence in clusters that support migrating between these api types.

When you change the authoritative api for a compute machine, the instance on the underlying infrastructure that backs the machine is not recreated or reprovisioned. In-place changes, such as modifying labels, tags, taints, or annotations, are the only changes that the api group can make to the underlying instance that backs the machine.

You can only migrate some resources on supported infrastructure types.
Table 1. Supported resource conversions
Infrastructure Compute machine Compute machine set Machine health check Control plane machine set Cluster autoscaler

AWS

Technology Preview

Technology Preview

Not Available

Not Available

Not Available

All other infrastructure types

Not Available

Not Available

Not Available

Not Available

Not Available

Migrating a Machine api resource to use the Cluster api

You can migrate individual Machine api objects to equivalent Cluster api objects.

Migrating a Machine api resource to use the Cluster api is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
Prerequisites

  • You have deployed an OKD cluster on a supported infrastructure type.

  • You have enabled the use of the Cluster api.

  • You have enabled the MachineapiMigration feature gate in the TechPreviewNoUpgrade feature set.

  • You have access to the cluster using an account with cluster-admin permissions.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Identify the Machine api resource that you want to migrate to a Cluster api resource by running the following command:

    $ oc get <resource_kind> -n openshift-machine-api

    where <resource_kind> is one of the following values:

    machine.machine.openshift.io

    The fully qualified name of the resource kind for a compute or control plane machine.

    machineset.machine.openshift.io

    The fully qualified name of the resource kind for a compute machine set.

  2. Edit the resource specification by running the following command:

    $ oc edit <resource_kind>/<resource_name> -n openshift-machine-api

    where:

    <resource_kind>

    Specifies a compute machine with machine.machine.openshift.io or compute machine set with machineset.machine.openshift.io.

    <resource_name>

    Specifies the name of the Machine api resource that you want to migrate to a Cluster api resource.

  3. In the resource specification, update the value of the spec.authoritativeapi field:

    apiVersion: machine.openshift.io/v1beta1
kind: <resource_kind> (1)
metadata:
  name: <resource_name> (2)
  [...]
spec:
  authoritativeapi: Clusterapi (3)
  [...]
status:
  authoritativeapi: Machineapi (4)
  [...]
    1 The resource kind varies depending on the resource kind. For example, the resource kind for a compute machine set is MachineSet and the resource kind for a compute machine is Machine.
    2 The name of the resource that you want to migrate.
    3 Specify the authoritative api that you want this resource to use. For example, to start migrating a Machine api resource to the Cluster api, specify Clusterapi.
    4 The value for the current authoritative api. This value indicates which api currently manages this resource. Do not change the value in this part of the specification.
Verification

  • Check the status of the conversion by running the following command:

    $ oc -n openshift-machine-api get <resource_kind>/<resource_name> -o json | jq .status.authoritativeapi

    where:

    <resource_kind>

    Specifies a compute machine with machine.machine.openshift.io or compute machine set with machineset.machine.openshift.io.

    <resource_name>

    Specifies the name of the Machine api resource that you want to migrate to a Cluster api resource.

    • While the conversion progresses, this command returns a value of Migrating. If this value persists for a long time, check the logs for the cluster-capi-operator deployment in the openshift-cluster-api namespace for more information and to identify potential issues.

    • When the conversion is complete, this command returns a value of Clusterapi.

Deploying Cluster api compute machines by using a Machine api compute machine set

You can configure a Machine api compute machine set to deploy Cluster api compute machines. With this process, you can test the Cluster api compute machine creation workflow without creating and scaling a Cluster api compute machine set.

A Machine api compute machine set with this configuration creates nonauthoritative Machine api compute machines that use the Cluster api as authoritative. The two-way synchronization controller then creates corresponding authoritative Cluster api machines that provision on the underlying infrastructure.

Deploying Cluster api compute machines by using a Machine api compute machine set is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
Prerequisites

  • You have deployed an OKD cluster on a supported infrastructure type.

  • You have enabled the use of the Cluster api.

  • You have enabled the MachineapiMigration feature gate in the TechPreviewNoUpgrade feature set.

  • You have access to the cluster using an account with cluster-admin permissions.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. List the Machine api compute machine sets in your cluster by running the following command:

    $ oc get machineset.machine.openshift.io -n openshift-machine-api

  2. Edit the resource specification by running the following command:

    $ oc edit machineset.machine.openshift.io <machine_set_name> \
  -n openshift-machine-api

    where <machine_set_name> is the name of the Machine api compute machine set that you want to configure to deploy Cluster api compute machines.

  3. In the resource specification, update the value of the spec.template.spec.authoritativeapi field:

    apiVersion: machine.openshift.io/v1beta1
kind: MachineSet
metadata:
  [...]
  name: <machine_set_name>
  [...]
spec:
  authoritativeapi: Machineapi (1)
  [...]
  template:
    [...]
    spec:
      authoritativeapi: Clusterapi (2)
status:
  authoritativeapi: Machineapi (3)
  [...]
    1 The unconverted value for the Machine api compute machine set. Do not change the value in this part of the specification.
    2 Specify Clusterapi to configure the compute machine set to deploy Cluster api compute machines.
    3 The current value for the Machine api compute machine set. Do not change the value in this part of the specification.
Verification

  1. List the machines that are managed by the updated compute machine set by running the following command:

    $ oc get machines.machine.openshift.io \
  -n openshift-machine-api \
  -l machine.openshift.io/cluster-api-machineset=<machine_set_name>

  2. To verify that a machine created by the updated machine set has the correct configuration, examine the status.authoritativeapi field in the CR for one of the new machines by running the following command:

    $ oc describe machines.machine.openshift.io <machine_name> \
  -n openshift-machine-api

    For a Cluster api compute machine, the value of the field is Clusterapi.

Additional resources