Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
    2. history bug_report picture_as_pdf
×

Getting started with the Cluster API

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 OpenShift Container Platform 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 OpenShift Container Platform 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

  1. 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).

    • VSphereCluster: The cluster is running on VMware vSphere.

  2. 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

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 OpenShift Container Platform 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

  1. 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/v1beta2: The version that Amazon Web Services (AWS) clusters use.

    • infrastructure.cluster.x-k8s.io/v1beta1: The version that Google Cloud Platform (GCP) and VMware vSphere 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.

    • VSphereCluster: The cluster is running on vSphere.
    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.

  2. 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 OpenShift Container Platform 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

  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:

    • AWSMachineTemplate: The cluster is running on Amazon Web Services (AWS).

    • GCPMachineTemplate: The cluster is running on Google Cloud Platform (GCP).

    • VSphereMachineTemplate: The cluster is running on VMware vSphere.
    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>

    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 OpenShift Container Platform 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

  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.
    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.

  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 -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