Create a cluster#

Info

For information on how to create a cluster in an air-gapped environment, refer to Offline installation.

Install dependecies#

Verify that you have installed the MKE 4 CLI (mkectl) and other dependencies on your system.

Configure cluster nodes#

Configure the cluster nodes in advance, in accordance with the System requirements.

Node provisioning is managed by the cluster administrators. You can, for instance, use Terraform to create the nodes in a cloud provider. Refer to Example Terraform configuration for an example.

Initialize deployment#

MKE 4 streamlines the cluster deployment through the use of a single YAML file, which details the desired cluster configuration. This approach simplifies the setup process and ensures consistency in cluster deployments:

Generate the mke4.yaml configuration file for your installation:
```
mkectl init > mke4.yaml
```
warning

Do not change the metadata.namespace value in the mke4.yaml file. MKE 4 deployment requires that the MkeConfig resource be present in the mke namespace, and thus the installation will fail if it is located in a different namespace.

In the generated configuration file:

Edit the hosts section to match your roster of nodes. Provide the SSH information for each cluster node, as well as the role of the node based on their functions within the cluster. The table below provides the list of available node roles and their descriptions:

Node Role	Description
controller+worker	A manager node that runs both control plane and data plane components. This role combines the responsibilities of managing cluster operations and executing workloads.
worker	A worker node that runs the data plane components. These nodes are dedicated to executing workloads and handling the operational tasks assigned by the control plane.

If access to a host requires you to connect through an SSH bastion host, specify the bastion settings under the ssh section of the mke4.yaml configuration file, as shown below:
```
hosts:
- ssh:
    address: 10.0.27.4            # private address
    keyPath: "/absolute/path/to/private/key.pem"
    port: 22
    user: ubuntu
    bastion:
      address: 3.5.7.9            # public bastion address
      keyPath: "/absolute/path/to/private/key.pem"
      port: 22
      user: ubuntu
  role: controller+worker
```
If a bastion section is not defined in the mke4.yaml configuration file, mkectl will connect directly to the host.

If the expectation is that all SSH traffic will route through a bastion, the bastion field must be set for each individual host.
By default, MKE 4 detects each node's internal IP address and uses it as both the Kubernetes API address (spec.api.address) and the etcd peer address (spec.storage.etcd.peerAddress). For most clusters, this requires no configuration. To pin the address explicitly, set privateAddress for the affected host in the spec.hosts[] section of mke4.yaml configuration file, at the same level as the ssh and role parameters:
```
hosts:
  - ssh:
      address: 10.0.27.4
      keyPath: "/absolute/path/to/private/key.pem"
      port: 22
      user: ubuntu
    role: controller+worker
    privateAddress: 10.0.27.4        # node internal IP, used for the API and etcd peer addresses
```
If the node internal IP is assigned dynamically, for DHCP for instance, but the interface name is stable, specify privateInterface rather than privateAddress:
```
hosts:
- ssh:
    address: 10.0.27.4
    keyPath: "/absolute/path/to/private/key.pem"
    port: 22
    user: ubuntu
  role: controller+worker
  privateInterface: ens5           # interface whose IP is used for the API and etcd peer addresses
```
Be aware that privateAddress and privateInterface are mutually exclusive, and thus you can only set one per host.
Specify the external address in the apiServer.externalAddress field. The external address is the domain name of the load balancer configured as described in System Requirements: Load balancer.

Important

You may need to add the SSH private key to your identity manager in order for mkectl to connect to it:

With ssh-agent:
```
ssh-add <path_to_your_SSH_private_key>
```
Without ssh-agent, ensure that the SSH private key is accessible at the path specified in the keyPath field of the mke4.yaml configuration file.

Info

MKE 4 supports Calico OSS by default. You can, though, deploy a different CNI as an unmanaged CNI, such as Calico Enterprise. For more information, refer to Install an unmanaged CNI plugin.

Create a cluster#

Warning

Before you create a new MKE 4 cluster you must first verify that a cluster does not already exist in the system. If you attempt to create a cluster where a cluster is already present, even through the use of a different configuration file, you will lose the ability to use the MKE 4 CLI to access the original cluster.

For information on how to delete a cluster, refer to Uninstall a cluster.

To create a new cluster, run the mkectl apply command with the generated YAML configuration file:

mkectl apply -f mke4.yaml

Info

The MKE 4 CLI mkectl apply command configures the mke context in the default kubeconfig file located at ~/.kube/config. If the default kubeconfig is changed, and the mke context becomes invalid or unavailable, the MKE 4 CLI will not be able to manage the cluster until the kubeconfig is restored.

Once the new cluster is viable, you can start interacting with it using kubectl with the mke context.

Warning

Always deploy an odd number of managers.

MKE 4 embeds an etcd cluster across manager (controller) nodes, and with two managers any single failure will break quorum. Refer to the etcd FAQ, Why an odd number of cluster members?, for more information.