Create Clusters - K3s

How to Create K3s Clusters using Frontier CLI

To perform tasks within the frontier CLI application, you are required to authenticate using your organization’s OIDC provider. Refer to the Authentication using Frontier CLI guide if you need assistance on logging in for use of Frontier services.

Frontier administrators may want to create new objects within their organization’s management cluster.

K3s Cluster Creation Guide

Within projects, clusters will need to be created to fulfill tasks the organization is working on. Cluster, project, and frontier administrators have a wide variety of options to choose from how they would like their cluster to be created. You could always run the command to see what clusters are currently running in the project you are working on:

frontier get cluster all -n <project-name>

To being creating your new cluster, we will start off by navigating to this feature. When you run frontier, you should see a list of capabilites using Frontier-CLI.

Frontier CLI Main Menu

You can see all the actions you are able to perform within your Frontier-CLI menu options. We will run frontier create to see the creating options within the interface. The only roles who will have access to view the create menu are cluster administrators and above.

Frontier CLI Create Menu

Cluster, project, and frontier administrators are able to create clusters using the create actions. Run the following command below to view creation options:

frontier create cluster

Expected output:

Frontier CLI Create Cluster Options

These new clusters can be created upon different Kubernetes platforms. The currently supported Kubernetes platforms for FKP clusters are K3s, RKE2, and MicroK8s. This guide will cover K3s cluster creation. We can use -h flag to bring up the help menu. To see the help menu for creating K3s clusters, run the following command below:

frontier create cluster k3s -h

Expected output:

Frontier CLI Create K3s Cluster Help

NOTE: Cluster Administrators are restricted in deploying new workload clusters only to the projects that they are assigned to.

Cluster Creation Options

When creating K3s clusters through Frontier services, the client is provided with a large variety of options in how they would like their cluster to be created. These options vary pending on how the client sets up their flags in the command. We will divide this part of the tutorial into 4 different sections. We will cover each of the specific flags pertaining through clusters created through certain providers as well as global flags utilized across all of them. The providers that FKP currently supports are Metal-as-a-Service (MAAS), Amazon Web Services (AWS), and Microsoft Azure.

MAAS Logo

Metal-as-a-Service Flags

MAAS is a service that treats physical servers like virtual machines (instances) in the cloud. MAAS comprehensively meets the need to rapidly deploy, destroy, and reconfigure constellations of bare metal. Any application that requires frequently rearranging the server topology will benefit. This makes it a suitable option for workload clusters managed by your Frontier Management Cluster (FMC). Below are flags specified to create clusters through a MAAS provider:

  • --cp-cpucount: An integer containing the minimum desired number of vCPUs for each control plane node
  • --cp-memory: An integer containing the minimum desired memory size of each control plane node (in MBs)
  • --wk-cpucount: An integer containing the minimum desired number of vCPUs for each worker node
  • --wk-memory: An integer containing the minimum desired memory size of each worker node (in MBs)
  • --svclb: A string value containing the minimum desired service load balancer for the cluster

Although there are not any required flags, users are still given the opportunity of how they would like their MAAS workload clusters to be configured. The CPU count for control plane and worker nodes, as well as their memory size, can be specified prior to cluster creation. MAAS will auto-select machines that are best fitted for your minimum specified requirements upon each type of node whether it is on an AMD64 or ARM64 machine. If no minimum requirements are specified, FKP offers a recommended minimum for the machine specifications:

  • --cp-cpucount - Default Value: 1
  • --cp-memory - Default Value: 4096
  • --wk-cpucount - Default Value: 1
  • --wk-memory - Default Value: 4096

Outside of machine specifications, users also have the option to modify their service load balancer for metal nodes. For MAAS, users will have two options to choose from:

  • --svclb: Service load balancer
    • metallb
    • none
    • Default Value: metallb

FKP recommends using metallb for your service load balancer when using a MAAS cluster provider. This will allow the user to freely assign IP addresses or IP address pools based within their machine’s local network for their services within the cluster.

AWS Logo

Amazon Web Services Flags

AWS is the world’s most comprehensive and broadly adopted cloud, offering over 200 fully featured services from data centers globally. FKP can use the AWS cloud to successfully deploy workload clusters managed by your FMC cluster. These can go on instances that are either AMD64 or ARM64 processors using Ubuntu Amazon Machine Images (AMI). We can specify how we want to deploy AWS clusters using the specific flags below:

  • --aws-region: A Required string value containing the region of the AWS cluster to reside
  • --cp-type: A string value containing the type of AWS instance the user desires for their control plan machine nodes
  • --wk-type: A string value containing the type of AWS instance the user desires for their worker machine nodes

The only required value for AWS cluster creation is the region the instances and all configurations will reside in. The options available and tested for these regions are:

  • us-east-1
  • us-east-2
  • us-west-1
  • us-west-2

Along with the region selected, users also have the option to modify the instance types for their control plane and worker nodes. Currently, the default value for each node is t3.medium which is tested and recommended by FKP. The specifications of these instances are 2 vCPU cores on AMD64 architecture with 4 GBs of memory. These instance types should meet most requirements pending on the organization’s desired tasks for their workload clusters.

Azure Logo

Microsoft Azure Flags

The Azure cloud platform is more than 200 products and cloud services designed to help you bring new solutions to life—to solve today’s challenges and create the future. Similar to AWS, FKP also utilizes Microsoft Azure as an alternative option to deploy your organization’s workload clusters managed by your FMC cluster. Users will have options available to them with how they would like their virtual machines to be configured with FKP K3S supported operating system images. Users can specify how they would like to set up their Microsoft Azure workload clusters using the flags below:

  • --az-region: A Required string value containing the region of the Azure cluster to reside
  • --cp-size: A string value containing the size of the Azure virtual machine the user desires for their control plan machine nodes
  • --wk-size: A string value containing the size of the Azure virtual machine the user desires for their worker machine nodes

Similar to AWS, the only required flag to deploy Azure clusters is the region. The region options available are:

  • eastus
  • eastus2
  • centralus
  • westus
  • westus2

With the Azure region selected, users will possess capabilities to specify what virtual machine sizes are desired for their Azure workload clusters. Standard_B2s remains the recommended virtual machine size by FKP. This virtual machine size contains 2 vCPU cores on AMD64 architecture with 8GBs of memory for Ubuntu operating systems. This machine type should be able to meet most requirements pending on the tasks desired by your organization.

Global Flags

Global flags remain to be a part of every workload cluster, regardless of the cluster provider specified to be in use. We will take a look at these options below:

  • --cluster-name: A Required string value containing the name of the cluster
  • -n, --project-name: A Required string value containing the name of the project for the new cluster
  • --provider: A Required string value containing the name of the provider for the new cluster
  • --kube-version: A string value containing the desired version of Kubernetes respective to the kube-type
  • --cp-replicas: An integer containing the desired number of control plane nodes
  • --wk-replicas: An integer containing the desired number of vCPUs for each worker node
  • --cni: A string value containing the desired Container Network Interface (CNI) for the cluster
  • --csi: A string value containing the desired Container Storage Interface (CSI) for the cluster
  • --ingress: A string value containing the desired ingress controller for the cluster
  • --os-image: A string value containing the desired operating system for the nodes of the cluster
  • -h, --help: help for cluster

The only required values to create a cluster using Frontier services is the name of the cluster, name of the project the cluster will reside in, and the name of the provider for the cluster to be launched on. As discussed previously, provider options range from MAAS, AWS, and Azure.

  • --provider: Cluster Provider
    • maas
    • aws
    • azure

Each of these providers may have required flags that come with them, please review each of the provider’s sections if in need of reference. All other flags are optional and can be changed if mentioned by the client upon creation. These following points will cover over string and integer-based value modifications with their default value. Each workload cluster will have a variety of different options to select for their version of Kubernetes respective to their type whether it is K3s, RKE2, or MicroK8s. The version can be specified by this flag:

  • --kube-version - Default Value: v1.23.6

Please ensure the version is typed correctly to avoid any possible errors. Additionally, cluster administrators will be able to set the number of replicas they desire for each of their nodes. These flags can be adjusted to the client’s preference as long as the value is the control plane replica count greater than 0:

  • --cp-replicas - Default Value: 2
  • --wk-replicas - Default Value: 2

For frontier workload cluster add-ons, it is required to have at least 1 replica for control plane and 2 replicas of the worker nodes for all containers and services to successfully run. It is encouraged to run more than 1 control plane replica nodes if you desire high availability for your newly created cluster. For cluster tools and plug-ins, these following points will cover over any supported features provided within Frontier services in each string value option along with their recommended default value:

  • --cni: Container Network Interface (CNI)
    • flannel
    • calico
    • none
    • Default Value: flannel
  • --csi: Container Storage Interface (CSI)
    • openebs
    • none
    • Default Value: openebs
  • --ingress: Ingress controller
    • ingress-nginx
    • none
    • Default Value: ingress-nginx
  • --os-image: Operating System
    • ubuntu/focal
    • TBD
    • Default Value: ubuntu/focal

If you need help refering to these options within the CLI, you can run frontier create cluster k3s -h to view all flags and supported values upon cluster creation.

Basic Cluster Creation

As mentioned previously, you are only required to fill in the cluster-name and project-name flags to create a cluster using Frontier services. To create a simple cluster, you can run the following command below for each provider. If you are using a Cloud Service Provider (CSP), you will be required to include the region you would like to deploy the cluster on. Refer to the AWS and Azure flag sections for potential values:

For MAAS
frontier create cluster k3s --cluster-name=<cluster-name> --project-name=<project-name> --provider=<provider-name>
For AWS
frontier create cluster k3s --cluster-name=<cluster-name> --project-name=<project-name> --provider=aws --aws-region=<region-value>
For Azure
frontier create cluster k3s --cluster-name=<cluster-name> --project-name=<project-name> --provider=azure --az-region=<region-value>

For an example, we will use the value <provider-name>-frontier-k3s for the cluster-name. In the project creation tutorial guide, we created a project by the name of frontier-test. We will use this project to satisfy the value of project-name. For this example, we will demonstrate the structure for all providers:

For MAAS
frontier create cluster k3s --cluster-name=maas-frontier-k3s --project-name=frontier-test --provider=maas
For AWS
frontier create cluster k3s --cluster-name=aws-frontier-k3s --project-name=frontier-test --provider=aws --aws-region=us-east-1
For Azure
frontier create cluster k3s --cluster-name=azure-frontier-k3s --project-name=frontier-test --provider=azure --az-region=eastus

Expected output (Azure Deployment Example):

Frontier CLI Create Azure K3s Cluster Example Output

This photo showcases an example where a cluster was created by the name of azure-frontier-k3s within the frontier-test project using a azure provider with the default options recommended by Frontier Kubernetes Platform (FKP).

Customizable Cluster Creation

If you would like to create a cluster with modified options, you can refer to the cluster creation options section as a guide for supported tools and plug-ins on your new cluster. For a completely customizable Frontier cluster, you can run the following command below:

For MAAS
frontier create cluster k3s --cluster-name=<cluster-name> --project-name=<project-name> --provider-name=maas --cp-replicas=<replica-count> --cp-cpucount=<cpu-count> --cp-memory=<memory-size> --wk-replicas=<replica-count> --wk-cpucount=<cpu-count> --wk-memory=<memory-size> --ingress=<ingress-name> --cni=<cni-name> --csi=<csi-name> --svclb=<svclb-name> --os-image=<os-name>
For AWS
frontier create cluster k3s --cluster-name=<cluster-name> --project-name=<project-name> --provider-name=aws --aws-region=<region-value> --cp-replicas=<replica-count> --cp-type=<instance-type> --wk-replicas=<replica-count> --wk-type=<instance-type> --ingress=<ingress-name> --cni=<cni-name> --csi=<csi-name> --os-image=<os-name>
For Azure
frontier create cluster k3s --cluster-name=<cluster-name> --project-name=<project-name> --provider-name=azure --az-region=<region-value> --cp-replicas=<replica-count> --cp-size=<vm-size> --wk-replicas=<replica-count> --wk-size=<vm-size> --ingress=<ingress-name> --cni=<cni-name> --csi=<csi-name> --os-image=<os-name>

For an example, we will use the value <provider-name>-frontier-k3s for the cluster-name. In the project creation tutorial guide, we created a project by the name of frontier-test. We will use this project to satisfy the value of project-name for each provider.

For MAAS
frontier create cluster k3s --cluster-name=maas-frontier-k3s --project-name=frontier-test --provider-name=maas --cp-replicas=3 --cp-cpucount=1 --cp-memory=4096 --wk-replicas=3 --wk-cpucount=2 --wk-memory=6144 --ingress=ingress-nginx --cni=calico --csi=openebs --svclb=metallb --os-image=ubuntu/focal 
For AWS
frontier create cluster k3s --cluster-name=aws-frontier-k3s --project-name=frontier-test --provider-name=aws --aws-region=us-east-1 --cp-replicas=3 --cp-type=t3.medium --wk-replicas=3 --wk-type=t3.medium --ingress=ingress-nginx --cni=calico --csi=openebs --os-image=ubuntu/focal
For Azure
frontier create cluster k3s --cluster-name=azure-frontier-k3s --project-name=frontier-test --provider-name=azure --az-region=eastus --cp-replicas=3 --cp-size=Standard_B2s --wk-replicas=3 --wk-size=Standard_B2s --ingress=ingress-nginx --cni=calico --csi=openebs --os-image=ubuntu/focal

Expected output (Azure Deployment Example):

Frontier CLI Create Azure K3s Cluster Example Output

TThis photo showcases an example where a cluster was created by the name of azure-frontier-k3s within the frontier-test project using the new options desired by the client’s command. The flags and options that can be modified strings are strict and must be in the exact same format as provided in the CLI help for K3s cluster creation. If these flags and options are not in the same format, the creation request will be denied. A response with the reason of denial will follow after the request has been made to help you troubleshoot any errors.