KubeStellar User Guide

This document is an overview of the User Guide. See the KubeStellar overview for architecture and other information.

This user guide is an project. If you find errors, please point them out in our Slack channel or open an issue in our github repository!

Simple Examples

If you want to try a simple installation process and example then you can try out Getting Started, which uses kind and a helm chart. The helm chart supports many options; the instructions on the Getting Started page show the chart’s usage in that recipe.

Another simple example, which starts with (a slightly modified version of) the OCM Quick Start is here.

In Brief

If you want a simple rough grouping, you can divide the concepts here into:

• “setup” (steps 1—7 below), exemplified in the Set Up A Demo System section of Getting Started, and
• “usage” (the remaining steps), illustrated by the example scenarios document.

However, you do not need to follow that dichotomy. As noted below, the relevant components can be organized more flexibly.

The Full Story

Installing and using KubeStellar progresses through the following steps.

1. Install software prerequisites. See prerequisites.
2. Acquire the ability to use a Kubernetes cluster to serve as the KubeFlex hosting cluster. See Acquire cluster for KubeFlex hosting.
3. Initialize that cluster as a KubeFlex hosting cluster.
4. Inventory and Transport Space (ITS).
   1. Create something to serve as ITS.
   2. Register the ITS as a KubeFlex ControlPlane.
5. Workload Description Space (WDS).
   1. Create something to serve as WDS.
   2. Register the WDS as a KubeFlex ControlPlane and initialize it for KubeStellar usage.
6. Create a Workload Execution Cluster (WEC).
7. Register the WEC in the ITS.
8. Maintain workload desired state in the WDS.
9. Maintain control objects in the WDS to bind workload with WEC and modulate the state propagation back and forth. The API reference documents all of them. There are control objects for the following topics.
   1. Binding workload with WEC(s).
   2. Transforming desired state as it travels from WDS to WEC.
   3. Summarizing reported state from WECs into WDS.
10. Enjoy the effects of workloads being propagated to the WEC.
11. Consume reported state from WDS.

By “maintain” we mean create, read, update, delete, list, and watch as you like, over time. KubeStellar is eventually consistent: you can change your inputs as you like over time, and KubeStellar continually strives to achieve what you are currently asking it to do.

There is some flexibility in the ordering of those steps. The following flowchart shows the key ordering constraints.

You can have multiple ITSes, WDSes, and WECs, created and deleted over time as you like.

Besides “Start”, the other green items in that graph are entry points for extending usage at any later time. You could also see them as distinct user roles or authorities, or as additional layers of setup/install.

KubeStellar’s Core Helm chart combines (a) initializing the KubeFlex hosting cluster, (b) optionally creating and certainly registering some ITSes, and (c) optionally creating and certainly registering and initializing some WDSes.

You can find an example run through of steps 2—7 in Getting Started. This dovetails with the example scenarios document, which shows examples of the later steps.

There is also an example run through of steps 2—7 that starts with (a slightly modified version of) the OCM Quick Start and also dovetails with the example scenarios. See here.

Observability and Monitoring

KubeStellar provides several endpoints and integrations for observability, including Prometheus metrics and debug endpoints. See the Observability page for details on available metrics, endpoints, and how to access them.

Troubleshooting

See the Troubleshooting guide.

Teardown

See Teardown for how to tear everything down to unadorned Kubernetes clusters.