openshift-docs/modules/machineset-creating.adoc

// Module included in the following assemblies:
//
// * machine_management/creating-infrastructure-machinesets.adoc
// * machine_management/creating_machinesets/creating-machineset-aws.adoc
// * machine_management/creating_machinesets/creating-machineset-azure.adoc
// * machine_management/creating_machinesets/creating-machineset-gcp.adoc
// * machine_management/creating_machinesets/creating-machineset-osp.adoc
// * machine_management/creating_machinesets/creating-machineset-vsphere.adoc
// * post_installation_configuration/cluster-tasks.adoc

ifeval::["{context}" == "creating-machineset-vsphere"]
:vsphere:
endif::[]

[id="machineset-creating_{context}"]
= Creating a MachineSet

In addition to the ones created by the installation program, you can create
your own MachineSets to dynamically manage the machine compute resources for
specific workloads of your choice.

.Prerequisites

* Deploy an {product-title} cluster.
* Install the OpenShift CLI (`oc`).
* Log in to `oc` as a user with `cluster-admin` permission.
ifdef::vsphere[]
* Create a tag inside your vCenter instance based on the cluster API name. This tag is utilized by the MachineSet to associate the {product-title} nodes to the provisioned virtual machines (VM). For directions on creating tags in vCenter, see the VMware documentation for link:https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.vcenterhost.doc/GUID-E8E854DD-AA97-4E0C-8419-CE84F93C4058.html[vSphere Tags and Attributes].
* Have the necessary permissions to deploy VMs in your vCenter instance and have the required access to the datastore specified.
endif::vsphere[]

.Procedure

. Create a new YAML file that contains the MachineSet Custom Resource sample,
as shown, and is named `<file_name>.yaml`.
+
Ensure that you set the `<clusterID>` and `<role>` parameter values.

.. If you are not sure about which value to set for a specific field, you can
check an existing MachineSet from your cluster.
+
[source,terminal]
----
$ oc get machinesets -n openshift-machine-api
----
+
.Example output
[source,terminal]
----
NAME                                DESIRED   CURRENT   READY   AVAILABLE   AGE
agl030519-vplxk-worker-us-east-1a   1         1         1       1           55m
agl030519-vplxk-worker-us-east-1b   1         1         1       1           55m
agl030519-vplxk-worker-us-east-1c   1         1         1       1           55m
agl030519-vplxk-worker-us-east-1d   0         0                             55m
agl030519-vplxk-worker-us-east-1e   0         0                             55m
agl030519-vplxk-worker-us-east-1f   0         0                             55m
----

.. Check values of a specific MachineSet:
+
[source,terminal]
----
$ oc get machineset <machineset_name> -n \
     openshift-machine-api -o yaml
----
+
.Example output
[source,yaml]
----
...
template:
    metadata:
      labels:
        machine.openshift.io/cluster-api-cluster: agl030519-vplxk <1>
        machine.openshift.io/cluster-api-machine-role: worker <2>
        machine.openshift.io/cluster-api-machine-type: worker
        machine.openshift.io/cluster-api-machineset: agl030519-vplxk-worker-us-east-1a
----
<1> The cluster ID.
<2> A default node label.

. Create the new `MachineSet`:
+
[source,terminal]
----
$ oc create -f <file_name>.yaml
----

. View the list of MachineSets:
+
[source,terminal]
----
$ oc get machineset -n openshift-machine-api
----
+
.Example output
[source,terminal]
----
NAME                                DESIRED   CURRENT   READY   AVAILABLE   AGE
agl030519-vplxk-infra-us-east-1a    1         1         1       1           11m
agl030519-vplxk-worker-us-east-1a   1         1         1       1           55m
agl030519-vplxk-worker-us-east-1b   1         1         1       1           55m
agl030519-vplxk-worker-us-east-1c   1         1         1       1           55m
agl030519-vplxk-worker-us-east-1d   0         0                             55m
agl030519-vplxk-worker-us-east-1e   0         0                             55m
agl030519-vplxk-worker-us-east-1f   0         0                             55m
----
+
When the new MachineSet is available, the `DESIRED` and `CURRENT` values match.
If the MachineSet is not available, wait a few minutes and run the command again.

. After the new MachineSet is available, check status of the machine and the
node that it references:
+
[source,terminal]
----
$ oc describe machine <name> -n openshift-machine-api
----
+
For example:
+
[source,terminal]
----
$ oc describe machine agl030519-vplxk-infra-us-east-1a -n openshift-machine-api
----
+
.Example output
[source,terminal]
----
status:
  addresses:
  - address: 10.0.133.18
    type: InternalIP
  - address: ""
    type: ExternalDNS
  - address: ip-10-0-133-18.ec2.internal
    type: InternalDNS
  lastUpdated: "2019-05-03T10:38:17Z"
  nodeRef:
    kind: Node
    name: ip-10-0-133-18.ec2.internal
    uid: 71fb8d75-6d8f-11e9-9ff3-0e3f103c7cd8
  providerStatus:
    apiVersion: awsproviderconfig.openshift.io/v1beta1
    conditions:
    - lastProbeTime: "2019-05-03T10:34:31Z"
      lastTransitionTime: "2019-05-03T10:34:31Z"
      message: machine successfully created
      reason: MachineCreationSucceeded
      status: "True"
      type: MachineCreation
    instanceId: i-09ca0701454124294
    instanceState: running
    kind: AWSMachineProviderStatus
----

. View the new node and confirm that the new node has the label that you
specified:
+
[source,terminal]
----
$ oc get node <node_name> --show-labels
----
+
Review the command output and confirm that `node-role.kubernetes.io/<your_label>`
is in the `LABELS` list.

[NOTE]
====
Any change to a MachineSet is not applied to existing machines owned by the MachineSet.
For example, labels edited or added to an existing MachineSet are not propagated to existing machines and Nodes
associated with the MachineSet.
====

.Next steps
If you need MachineSets in other availability zones, repeat this
process to create more MachineSets.

ifeval::["{context}" == "creating-machineset-vsphere"]
:!vsphere:
endif::[]