Create a Multi-Node CLuster

Command: cluster create

The pf9ctl cluster create command is used to create a single or multi-node, single or multi-master cluster on a set of physical or virtual machines. The command does the following:

  • securely connects to a list of nodes specified
  • installs all the required pre-requisites on the nodes
  • installs Platform9 host agent and other required software on the nodes
  • authorizes the nodes to be associated with the PMK management plane
  • creates the cluster and attaches the nodes to the cluster, with appropriate roles - masters and/or workers

Usage

Usage:

pf9ctl cluster create --master-ip MASTER_IP_ADDRESS [OPTIONS] CLUSTER_NAME
  • --masterVip TEXT - IP address for VIP for master nodes. Required if you are creating a multi-master cluster. For more information about VIP, read BareOS multi-master architecture

  • --masterVipIf TEXT - Name of the network interface on this node on which the VIP should bind to. Required if you are creating a multi-master cluster. For a single master cluster, VIP is optional. Make sure that the virtual IP specified above is accessible on this network interface, and that all master nodes use the same interface name for the interface to be associated with the virtual IP

  • --metallbCidr TEXT - IP range for MetalLB (specified in ‘Start IP - End IP’ range format). You should specify this value if you would like to use MetalLB as an option for service load balancing. For more information about MetalLB, read Service load balancing with MetalLB

  • --containersCidr TEXT - Defaults to 10.20.0.0/16. The CIDR for containers running on your cluster. (Specified in CIDR format. Example - 192.0.2.0/24). Kubernetes uses this CIDR to route packets between pods or containers in the cluster. You should specify an unused subnet here. And this subnet should be treated as Kubernetes internal subnet. Make sure that your network equipment does not route or otherwise is aware of this subnet.

  • --servicesCidr TEXT - Defaults to 10.21.0.0/16. The CIDR for services running on your cluster. (Specified in CIDR format. Example - 192.0.2.0/24). Kubernetes uses this CIDR to route packets between the services in the cluster. You should specify an unused subnet here. And this subnet should be treated as Kubernetes internal subnet. Make sure that your network equipment does not route or otherwise is aware of this subnet.

  • --externalDnsName TEXT - External DNS name for master VIP. (Specified in FQDN format. Example myhostname.mydomainname.com) If you specify this, it means you have associated this DNS name to the IP address you specified for the --masterVip parameter. This DNS name will be used for the cluster API server endpoint. This DNS name will be appear for the ‘server’ property for when users download kubeconfig for this cluster. It will also appear under the column ‘API endpoint’ in the PMK UI Clusters grid view. (If no DNS name is specified, the ‘server’ property in kubeconfig and the ‘API endpoint’ column in the Clusters grid view will simply reference the IP of the cluster)

  • --privileged BOOLEAN - Defaults to True. Specify if the cluster should be enabled to run privileged containers. Note that being able to run privileged containers within the cluster is a prerequisite if you wish to enable service type loadbalancer using MetalLB. By default a container is not allowed to access any devices on the host, but a “privileged” container is given access to all devices on the host. For more information, see Priviledged Policy Reference

  • --appCatalogEnabled BOOLEAN - Defaults to False. Enable Helm application catalog for the cluster

  • --allowWorkloadsOnMaster BOOLEAN - Defaults to False. Specify if you wish to allow workloads to run on the master nodes. Setting it to true would mean both master and worker nodes will be used to schedule workloads on. Note that for production clusters, we recommend you do not run workloads on the master nodes, but instead allocate sufficient capacity on the worker nodes to run your applications. This ensures that the master nodes will have sufficient resources to keep the cluster running.

  • --networkPlugin TEXT - Defaults to flannel. The network plugin you’d like to create the cluster with. Accepted options - calico and flannel. By default, the cluster will be created with flannel as the network plugin.

  • -u, --user TEXT - Username for nodes. Required if you are creating a multi-node cluster, so the CLI can authenticate with each node. Refer to ‘SSH Setup for Remote Nodes’ section under [PMK CLI Overview](/kubernetes/PMK-CLI/ for more information.

  • -p, --password TEXT - Password for node. You need to specify either the password or the ssh-key if you are creating a multi-node cluster, so the CLI can authenticate with each node. Refer to ‘SSH Setup for Remote Nodes’ section under [PMK CLI Overview](/kubernetes/PMK-CLI/ for more information.

  • -s, --ssh-key TEXT - SSH private key for nodes. You need to specify either the password or the private ssh-key if you are creating a multi-node cluster, so the CLI can authenticate with each node. Refer to ‘SSH Setup for Remote Nodes’ section under [PMK CLI Overview](/kubernetes/PMK-CLI/ for more information.

  • -m, --master-ip TEXT - Required parameter. IP of the node you wish to attach as a master node for this cluster. You need to specify atleast one IP address for the create command to work. Repeat this option multiple times to specify multiple nodes as masters. If you wish to make the current node also a master, specify it as ‘localhost’ or specify the current node’s IP address

  • -w, --worker-ip TEXT- IP of the node you wish to attach as a worker node for this cluster. Repeat this option multiple times to specify multiple nodes as workers. If you wish to make the current node also a worker, specify it as ‘localhost’ or specify the current node’s IP address

  • --help- Show this message and exit.

Example

This sample command creates a multi-master cluster with 3 masters, and 1 worker node, with calico as the network plugin. It also specifies a range of IP addresses for metalLB

pf9ctl cluster create --masterVip 10.1.1.1 --masterVipIf eth0 --metallbCidr 10.1.1.2-10.1.1.10 --externalDnsName productcluster.mycompany.net  --allowWorkloadsOnMaster True --networkPlugin calico -u testuser -s ~/.ssh/id_rsa.pub -m 150.20.7.65 -m 150.20.7.66 -m 150.20.7.67 -w 150.20.7.68 MyPMKCluster

Troubleshooting

See CLI Troubleshooting