Skip to content

KubeStellar has multiple documentation versions to match its multiple releases.
Please make sure you are viewing the docs version which matches the release version of the code you are using!

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 ongoing 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 only 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:

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.

Ordering among installation and usage actions

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.

Troubleshooting#

See the Troubleshooting guide.