Getting started with the Cluster API - Managing machines with the Cluster API | Machine management

Creating the Cluster API primary resources

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.

For the Cluster API Technology Preview, you must create the primary resources that the Cluster API requires manually.

Creating the Cluster API primary resources

To create the Cluster API primary resources, you must obtain the cluster ID value, which you use for the <cluster_name> parameter in the cluster resource manifest.

Obtaining the cluster ID value

You can find the cluster ID value by using the OpenShift cli (oc).

Prerequisites

You have deployed an OKD cluster.
You have access to the cluster using an account with cluster-admin permissions.
You have installed the OpenShift cli (oc).

Procedure

Obtain the value of the cluster ID by running the following command:

$  oc get infrastructure cluster \
   -o jsonpath='{.status.infrastructureName}'

You can create the Cluster API primary resources manually by creating YAML manifest files and applying them with the OpenShift cli (oc).

Creating the Cluster API cluster resource

You can create the cluster 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).
You have the cluster ID value.

Procedure

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

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <cluster_name> (1)
  namespace: openshift-cluster-api
spec:
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: <infrastructure_kind> (2)
    name: <cluster_name>
    namespace: openshift-cluster-api

1	Specify the cluster ID as the name of the cluster.
2	Specify the infrastructure kind for the cluster. The following values are valid: `AWSCluster`: The cluster is running on Amazon Web Services (AWS). `GCPCluster`: The cluster is running on Google Cloud Platform (GCP).

Create the cluster CR by running the following command:
```
$ oc create -f <cluster_resource_file>.yaml
```

Verification

Confirm that the cluster CR exists by running the following command:
```
$ oc get cluster
```
Example output
```
NAME             PHASE          AGE    VERSION
<cluster_name>   Provisioning   4h6m
```
The cluster resource is ready when the value of PHASE is Provisioned.

Additional resources

Cluster API configuration

Creating a Cluster API infrastructure resource

You can create a provider-specific infrastructure 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).
You have the cluster ID value.
You have created and applied the cluster resource.

Procedure

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

apiVersion: infrastructure.cluster.x-k8s.io/<version> (1)
kind: <infrastructure_kind> (2)
metadata:
  name: <cluster_name> (3)
  namespace: openshift-cluster-api
spec: (4)

1	The `apiVersion` varies by platform. For more information, see the sample Cluster API infrastructure resource YAML for your provider. The following values are valid: `infrastructure.cluster.x-k8s.io/v1beta1`: The version that Google Cloud Platform (GCP) clusters use. `infrastructure.cluster.x-k8s.io/v1beta1`: The version that Amazon Web Services (AWS) clusters use.
2	Specify the infrastructure kind for the cluster. This value must match the value for your platform. The following values are valid: `AWSCluster`: The cluster is running on AWS. `GCPCluster`: The cluster is running on GCP.
3	Specify the name of the cluster.
4	Specify the details for your environment. These parameters are provider specific. For more information, see the sample Cluster API infrastructure resource YAML for your provider.

Create the infrastructure CR by running the following command:
```
$ oc create -f <infrastructure_resource_file>.yaml
```

Verification

Confirm that the infrastructure CR is created by running the following command:
```
$ oc get <infrastructure_kind>
```
where <infrastructure_kind> is the value that corresponds to your platform.
Example output
```
NAME             CLUSTER          READY
<cluster_name>   <cluster_name>   true
```
This output might contain additional columns that are specific to your cloud provider.

Additional resources

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).
You have created and applied the cluster and infrastructure resources.

Procedure

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: `AWSMachineTemplate`: The cluster is running on Amazon Web Services (AWS). `GCPMachineTemplate`: The cluster is running on Google Cloud Platform (GCP).
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.

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>
```
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 cluster, infrastructure, and machine template resources.

Procedure

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.
2	Specify the name of the cluster.
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.

Create the compute machine set CR by running the following command:
```
$ oc create -f <machine_set_resource_file>.yaml
```
Confirm that the compute machine set CR is created by running the following command:
```
$ oc get machineset -n openshift-cluster-api (1)
```
1 Specify the openshift-cluster-api namespace.
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 -n openshift-cluster-api (1)

1	Specify the `openshift-cluster-api` namespace.

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