Introduction
K3S is a highly available, Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations or inside IoT appliances.
Edge is fast becoming a reality, and k3s, a fully compliant Kubernetes distribution, is built ground up to allocate resource constraint Edge environments.
Using ZEDEDA, one can provision and manage the k3s Infrastructure at the Distributed Edge, using zero-touch provisioning capabilities of ZEDEDA Cloud and zero-trust operating system built for the Edge, the EVE-OS.
Prerequisites
You must have a 'remote connect manifest endpoint' from the third-party application workload management solution.
Operations using the ZEDEDA GUI
Create
After logging in to the ZEDEDA GUI, click on the 'Cluster Instances' (
) icon from the left navigation.
Note: Onboarding edge nodes and appropriately tagging them in ZEDEDA Cloud is required beforehand. These tags will be used to create a cluster comprised of the appropriate edge nodes.
- Step 1 > After clicking on the 'Cluster Instances' from the left navigation, click the Add (
) icon at the top right corner to trigger the new 'Add Cluster Instance' flow.
- Step 2 > Populate the input field values for the 'Identity' section, as instructed in the table.
- Step 3 > Add appropriate tags and click on the Add Tag (
) icon.
| Input Field | Value |
| Name(*) | Provide a unique name for a cluster in your enterprise. |
| Title(*) | This is user-defined and can be changed. |
| Description | An optional explanation of what the cluster instance is going to be used for. |
| Tags | Enter the appropriate key-value pair, which can be used for later identification of this cluster. |
- Step 4 > Select the appropriate project where the edge nodes that will make up the cluster instance have been added.
- Step 5 > Choose the edge nodes for matching tags and click on the Add Tag (
- Step 6 > Click the checkbox to choose the auto-deploy Network Instances if required.
- Step 7 > Provide the network instance identity details, as instructed in the table.
- Step 8 > Add appropriate tags and click on the Add Tag (
| Input Field | Value |
| Network Instance Name Prefix(*) | Provide the network instance name. |
| Network Instance Title Prefix(*) | This is user-defined and can be changed. |
| Tags | Enter the appropriate key-value pair, which can be used for later identification of this cluster. |
- Step 9 > Provide the 'Kind' details, as instructed in the table.
- Step 10 > Provide the 'Kind' details, as instructed in the table.
- Step 11 > If you select 'Port Tag Name,' the matching tag appears.
| Input Field | Value |
| Kind(*) |
This is a type of network. Select one of the Network Instances from the following dropdown list:
|
| Port(*) | Select the appropriate option from the dynamic dropdown list once you select the edge node. |
| Addressing |
Select one of the IP Address formats from the following dropdown list:
|
- Step 12 > Select the edge application you want to run on the server and agent node.
- Step 13 > Choose the 'Network Instance Assignment Method' from the list.
| Input Field | Value |
| Server/Agent Node Edge App (*) | Select the edge application (VM images with k3s bundled) that will run on the server or agent node. |
- Step 14 > You can choose 'Default' or 'Tag.'
Default–If there is no specific network instance configuration available, you can choose the default network instance of the edge node. In this case, the Default network instance is used for connecting with the Cluster network.
Tag–you will need to specify an appropriate tag. The tag must be the same as you used while creating the switch network instances on that edge node. The network instance(s) with that tag will be picked up on all edge nodes of the cluster to connect with the Cluster Network.
Note: To read more about creating the 'Switch' type network instance, click here.
- Step 15 > If you select 'Tag,' the matching tag appears. Provide the tags to choose or filter the network instance for the particular application instance (in case a custom network config is provided, then the tags at this step must be the same as step 8).
The following sections cover the cluster configuration details.
Manual Cluster Configuration
- Click on Manual.
- Paste the 'Remote Connect Manifest Endpoint' URL, copied from the prerequisites section.
- An example 'Remote Connect Manifest Endpoint' URL is shown. Populate the other input field values for the 'Configuration' section, as instructed in the table.
- Click on the 'Submit' button to add the cluster instance.
| Input Field | Value |
| Remote Connect Manifest Endpoint (*) | The manifest URL is used to stitch the cluster with the third-party application workload management solution like SUSE Rancher. |
|
Minimum Server Nodes (*)
|
Select the minimum number of server nodes required. The value '1' is auto-populated. |
| Maximum Server Nodes (*) | Select the maximum number of server nodes required. This is a maximum administrative limit on the number of K3S Server Nodes. The value '1' is auto-populated. |
| Minimum Agent Nodes (*) | Select the minimum number of agent nodes required. The value '1' is auto-populated. |
|
Maximum Agent Nodes (*)
|
Select the maximum number of agent nodes required. The value '1' is auto-populated. |
You can see that the new Cluster Instance is added in the Cluster Instances list view.
Automatic Cluster Configuration
- Click on Automatic.
- Select the 'Orchestrator Integration' from the dropdown. To know more about the Orchestrator Integration, click here.
- An example 'Orchestrator Integration' authentication type is shown. Populate the other input field values for the 'Configuration' section, as instructed in the table.
- Click on the 'Submit' button to add the cluster instance.
| Input Field | Value |
| Orchestrator Integration(*) | Third-party integration. SUSE Rancher in this case. |
| Minimum Server Nodes(*) | Select the minimum number of server nodes required. The value '1' is auto-populated. |
| Maximum Server Nodes(*) | Select the maximum number of server nodes required. This is a maximum administrative limit on the number of K3S Server Nodes. The value '1' is auto-populated. |
| Minimum Agent Nodes(*) | Select the minimum number of agent nodes required. The value '1' is auto-populated. |
| Maximum Agent Nodes(*) | Select the maximum number of agent nodes required. The value '1' is auto-populated. |
You can see that the new Cluster Instance is added in the Cluster Instances list view.
Read
The newly added cluster instance shows the status, Admin status, and Run state. When you click on this newly added cluster instance in the list view, you will take a detailed view. The detailed view shows three main sections: 'Status,' 'Basic Info,' and 'Events.'
- Click on the cluster instance from the list view to get various details of the cluster instance.
Status
This section shows the parameters of 'Information' and 'Deployment.' sub-sections for a selected cluster instance.
The table below describes the various Run States and their descriptions:
|
Run State
|
Description |
| Unknown | The status of the cluster instance is yet to be reported by EVE-OS. |
| Init |
ZEDEDA Cloud has started provisioning the cluster instance.
|
| Unhealthy | more than half of the cluster members are either not operational or not visible from ZEDEDA Cloud (i.e., EVE-OS is not sending any status messages, probably due to loss of connectivity). |
| Provisioning Seed Server | ZEDEDA Cloud is provisioning the first member in the cluster. |
| Provisioned Seed Server | ZEDEDA Cloud has provisioned the seed server. |
| Provisioning Nodes | ZEDEDA Cloud is in the process of provisioning the remaining nodes in the cluster. |
| Healthy | The cluster is fully operational. |
| Partially Healthy | The majority of the cluster members are online, but not all are. |
| Offline | The cluster is offline. |
a) Information
This subsection shows an overview of the selected cluster instance such as the 'Admin Status,' 'Run State.'
b) Deployment
This subsection shows the cluster instance where the edge application instance is deployed, edge node details, and each edge application instance's role. 'Edge App Instance' has two types of servers–normal server and seed server. The seed server is the first server that comes up. 'Edge Node' shows the details of one or more edge nodes used for the cluster instance deployment. 'Role' specifies if the edge application instance is an agent or a server.
Basic Info
This section shows the parameters of 'Identity,' 'Deployments,' and 'Configuration' sub-sections for a selected cluster instance. These parameters comprise both editable and non-editable fields.
a) Identity
This subsection shows the identity details of the particular cluster instance.
b) Deployments
This subsection shows details about the project, drives, resources, and network adapters.
c) Configuration
This subsection shows the configuration details, including the server node, agent node, and edge node details.
Events
a) List View
This subsection shows the edge node events with details such as date and time, severity, source, and summary.
b) Summary View
This subsection shows more details about a selected event, along with the debug information, if any.
Update
You can only perform the update/edit operation in the cluster instances detail view. After logging in to the ZEDEDA GUI, click on the 'Cluster Instances' menu from the left navigation to list already available cluster instances. Click on any of the cluster instances in the list view to show the detailed view of the same.
The update/edit view shows only in the 'Basic Info' section.
Update/edit a cluster instance using the following steps:
- Click on the Edit (
) icon.
- Update the editable fields of the 'Identity,' 'Deployments,' and 'Configuration' sections. Refer to the tables under the create operation for information on the editable field values and descriptions.
- Click on 'Submit' button.
Delete
The following are the steps to delete cluster instances.
- Click on the temporary cluster instance link to show the selected cluster instance's details.
- Click on the More (
) icon on the top right corner.
- From the dropdown, select 'Delete'.
- Click the 'Confirm' button on the modal dialogue.
Deleted Cluster Instance(s) cannot be restored again from ZEDEDA Cloud
Operations using zCLI
Note: zCLI is an easy-to-use interface that allows the interaction of ZEDEDA offering through standard REST-based API.
Create
You can create the Cluster Instance using the following command:
zcli>cluster-instance create<name> /
--k3s-edge-app=<edge-app-name> /
--project=<project-name>--cluster-config=<cluster-config> /
--edge-node-pool-tag=<key:value>... /
--network-assignment=<interfaceName:assignmentType> /
[--network-tag=<key:value>...][--title=<title>] /
[--description=<description>] /
[--tags=<key:value>...] /
An example of creating a cluster instance is as follows:
zcli cluster-instance create test_instance --k3s-edge-app=k3s_on_ubuntu_with_logs /
--project=adarsh-dev --edge-node-pool-tag=adarsh-k3s:dev2 /
--cluster-config="/root/cluster-inst.conf" --network-assignment=eth0:default /
--title="test title" --description="test description" /
--tags=clusterTagKey:clusterTagValue
The cluster instance creates a config. The file below is the sample for this file. This file should be a part of the below command:
--cluster-config=<cluster-config>
cluster-conf={
minEdgeDevices=1
maxEdgeDevices=1
minServerNodes=1
maxServerNodes=1
minAgentNodes=1
maxAgentNodes=1
callHomeURL=sampleCallHome.url
}
Show
You can read the Cluster Instance using the following command:
zcli>cluster-instance show[<name>|--uuid=<uuid>] /
[--name-pattern=<name-pattern>][--detail][--page-size=<page-size>] /
[--project=<project-name>]
Update
You can update the Cluster Instance using the following command:
zcli> cluster-instance update <name> [--title=<title>] /
[--description=<description>] [--tags=<key:value>...]
Delete
You can delete the Cluster Instance using the following command:
zcli> cluster-instance delete <name> [-f]
Note: -f in Reboot and Delete operations are used to forcefully make the delete request to the ZEDEDA Cloud, without prompting the user.