README.md

kubeteach

Kubeteach is an operator build with kubebuilder to learn kubernetes in kubernetes.

Kubeteach was created because I wanted to improve my golang and kubernetes operator knowledge. I came across kubebuilder and had the idea to learn kubernetes in kubernetes.

The idea is to get tasks as a kubernetes objects (custom resource) to learn how to interact with kubernetes/kubectl while solving tasks in the kubernetes cluster. Kubeteach checks whether a task has been completed successfully based on defined conditions.

⚠️ Note: kubeteach is not designed to deploy it to a production cluster. I recommend to use kind to use kubeteach and learn kubernetes. There is no deletion job for created objects from exercises.

🚧 Kubeteach is still in a very early stage of development, which means it may not always be stable and major api changes are necessary.

Learn kubernetes with kubeteach

⚠️ Unfortunately, only a few tasks are currently available. More tasks will be added soon.

Preparation

To install kubeteach you need a kubernetes cluster. I recommend kind as a local environment, checkout the kind quick start.

You need also kubectl to interact with your cluster and helm to install kubeteach to your cluster.

• Checkout the installation kubectl guide.
• Checkout the installation helm guide.

Installation

Add kubeteach helm repo

To be able to deploy kubeteach you need to add the kubeteach helm repo to your local helm installation.

helm repo add kubeteach https://dergeberl.github.io/kubeteach-charts

Install kubeteach with ExerciseSet

To deploy kubeteach with an ExerciseSet you can select one of this list.

With the following command you can install kubeteach with an ExerciseSet to your cluster. (Change <helm-chart to your selected helm chart. For example kubeteach/kubeteach-exerciseset1)

helm install exerciseset1 <helm-chart> --namespace exerciseset --create-namespace --render-subchart-notes

⚠️ Don't use the helm flag --wait, because some deployments won't get ready and the helm install command will fail.

Enable kubeteach dashboard

⚠️ The dashboard is an experimental feature. DO NOT MAKE IT AVAILABLE VIA INTERNET! ⚠️

To enable the dashboard you need to add 2 settings for the helm install command (see above):

--set kubeteach.dashboard.enabled=true --set kubeteach.webterminal.enabled=true

Example:

helm install exerciseset1 <helm-chart> --namespace exerciseset --set kubeteach.dashboard.enabled=true --set kubeteach.webterminal.enabled=true --render-subchart-notes
...
You can use it with the following command (to forward a local port):
kubectl port-forward -n exerciseset service/kubeteach-core-dashboard 8080:80

Now you can access the dashboard via http://localhost:8080
Username: kubeteach
Password: <yourpassword>

The command will prompt a command (kubectl port-forward) and the credentials which are needed to log in into the dashboard.

Update kubeteach

To update kubeteach you can run the following commands.

helm repo update
helm upgrade exerciseset1 <helm-chart> --namespace exerciseset --render-subchart-notes

⚠️ Don't use the helm flag --wait, because some deployments won't get ready and the helm install command will fail.

Usage

You can get the tasks that should be performed with kubectl get tasks -n exerciseset

kubectl get tasks
NAME    TITLE                           DESCRIPTION                                                                                                          STATUS
task01   Create namespace                Create a new namespace with the name kubeteach                                                                           active
task02   Create pod                      Create a pod in namespace kubeteach, name it pod1 and use nginx:latest as image                                         pending
...

To get more information of one task you can use kubectl describe task -n exerciseset <taskname>

In some task you can find a helpURL and/or a longDescription with more information about this task.

kubectl describe task task01   
Name:         task01
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  kubeteach.geberl.io/v1alpha1
Kind:         Task
Metadata:
  Creation Timestamp:  2021-03-14T18:35:49Z
  Generation:          1
  Owner References:
    API Version:     kubeteach.geberl.io/v1alpha1
    Kind:            TaskDefinition
    Name:            task1
    UID:             21b8853d-11d4-4930-bdfd-ea3c945ae536
  Resource Version:  633
  UID:               d392614d-6a42-4d97-8500-ee29f3121674
Spec:
  Description:  Create a new namespace with the name kubeteach
  Title:        Create namespace
Status:
  State:  active
Events:
  Type    Reason  Age   From  Message
  ----    ------  ----  ----  -------
  Normal  Active  12m   Task  Task has no pre required task, task is now active

Now you can solve tasks by doing what's described in the task.

For example task01: Create a new namespace with the name kubeteach

kubectl create namespace kubeteach

A few seconds later the task state is changed to successful.

kubectl get task task01            
NAME    TITLE              DESCRIPTION                                  STATUS
task01   Create namespace   Create a Namespace with the name kubeteach   successful

The task state pending shows that another task must be successfully done before.

If you need help you can take a look into the solution folder of the exercise set you use (for example dergeberl/kubeteach-charts/solutions/exerciseset1)

An update to a new status can take up to 5 seconds

List of ExerciseSets

name	description	link	helm
kubeteach-exerciseset1	Example ExerciseSet to try out kubeteach with basic tasks for first steps in kubernetes	dergeberl/kubeteach-charts/charts/exerciseset1	kubeteach/kubeteach-exerciseset1

How it works / How to write own exercises

Check out the docs/write-own-exercises.md

Contribution / Test setups

For more information about contribution and local test setup have a look at the contribution guideline.

New exercises or/and exercise sets are highly welcome, check out the helm repository.

If you have ideas feel free to open a PR or issue.