Scaffolds and outlines "Delivering Your Application as a Kubernetes A…

…ppliance" (#329)

TL;DR
-----

Frames up the Embedded Cluster lab

Details
-------

Provides an initial outline of and overview lab for the Embedded Cluster. Each
challenge explains what that step of the lab is about and has a full set of
lifecycle scripts with an extremely minimal implementation. Track setup scripts
are not yet implemented.

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/assignment.md

@@ -0,0 +1,72 @@
+---
+slug: getting-to-know-the-template
+id: bvpn5mxammoz
+type: challenge
+title: Getting to Know the Template
+teaser: Some tips and tricks for using this template
+notes:
+- type: text
+  contents: Let's learn about this template
+tabs:
+- title: Shell
+  type: terminal
+  hostname: shell
+- title: Cluster
+  type: terminal
+  hostname: cluster
+difficulty: basic
+timelimit: 300
+---
+
+👋 Introduction
+===============
+
+This template is a baseline for labs that need to persist their shell
+environment across challenges. This may be because you as the learner
+to set some environment variables, or because they've started a long
+running process, or just to make it feel more like the real world
+where they're doing everything in the same shell session.
+
+As a cool side-effect, you can also use this template if you want
+to interact with the contents of the learner's shell session. The
+track uses `tmux` to persist the shell, and with that comes the
+opportunity to read the content of the entire `tmux` pane. That
+content includes the commands the learner types and the output of
+those commands. This can come in very handy in lifecycle scripts, as
+can `tmux`'s ability to send keystrokes into the session.
+
+
+🔤 Basics
+=========
+
+You don't really have to do anything special to use this template.
+It's configured to start a shell container and a single node Kubernetes
+cluster. The shell uses our Instruqt shell image, and runs a `tmux`
+session named `shell`. In that sesion it starts a login shell as the
+user `replicant` using `su`.
+
+The first challenge will create the session, and additional challenges
+will connect to the existing session. This is enabled by following
+command which is the `shell` specified in `config.yml` for the `Shell`
+sandbox.
+
+```yaml
+- name: shell
+  image: gcr.io/kots-field-labs/shell:instruqt-feature-tmux-template
+  shell: tmux new-session -A -s shell su - replicant
+```
+
+This one command will either create a new session named `shell` running
+`su - replicant`, or join an existing session named `shell`. The existing
+session will continue with whatever command it was running in the prior
+challenge which may just be `replicant`'s shell.
+
+🧪 Try It
+=========
+
+Let's set an environment variable in this challenge so we can take
+advantage of it in the next one.
+
+```shell
+export THIS="the way"
+```

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/check-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/check-shell

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+HOME_DIR=/home/replicant
+source /etc/profile.d/header.sh
+
+# save the entire session to check user inputs and outputs
+tmux capture-pane -t shell -S -
+SESSION=$(tmux save-buffer -)
+
+# check for disconnection
+if ! grep -qE 'THIS=[A-Za-z "]+' <(echo ${SESSION}) ; then
+  fail-message 'Please try it out by setting the environment variable `$THIS`'
+  exit 1
+fi
+

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/cleanup-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/cleanup-shell

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+HOME_DIR=/home/replicant
+source /etc/profile.d/header.sh
+
+# clear the tmux pane and scrollback to look like a fresh shell
+tmux clear-history -t shell 
+tmux send-keys -t shell clear ENTER
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/setup-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+# source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/setup-shell

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+HOME_DIR=/home/replicant
+source /etc/profile.d/header.sh
+
+### Assure the tmux session exists
+#
+# In a test scenario Instuqt does not run the user shell for the
+# challenge, which means the tmux session is never established. We
+# need to session for the solve scripts for other challenges to 
+# succeed, so let's create it here.
+#
+if ! tmux has-session -t shell ; then
+  tmux new-session -d -s shell su - replicant
+fi
+
+# Wait for Instruqt bootstrap to be complete
+while [ ! -f /opt/instruqt/bootstrap/host-bootstrap-completed ]
+do
+  echo "Waiting for Instruqt to finish booting the VM"
+  sleep 1
+done

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/solve-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/01-getting-to-know-the-template/solve-shell

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+HOME_DIR=/home/replicant
+source /etc/profile.d/header.sh
+
+# set the variable into the shell
+tmux send-keys -t shell export SPACE 'THIS="the way"' ENTER

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/assignment.md

@@ -0,0 +1,26 @@
+---
+slug: specifying-the-cluster
+id: bvpn5mxammoz
+type: challenge
+title: Configuring the Embedded Cluster
+teaser: Enable and configure the embedded cluster
+notes:
+- type: text
+  contents: Let's enable the embedded cluster
+tabs:
+- title: Shell
+  type: terminal
+  hostname: shell
+- title: Release Editor
+  type: code
+  hostname: shell
+  path: /home/replicant
+difficulty: basic
+timelimit: 300
+---
+
+You can release you application as a Kubernetes applicance by
+specifying a few extra configuration files as part of your Replicated
+release. The first of these files is the configuration for the
+Embedded Cluster itself. This configuration can be very simple. All
+it's required to provide is the version of the cluster to use.

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/check-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/check-shell

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+HOME_DIR=/home/replicant
+source /etc/profile.d/header.sh
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/cleanup-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/cleanup-shell

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+HOME_DIR=/home/replicant
+source /etc/profile.d/header.sh
+
+# clear the tmux pane and scrollback to look like a fresh shell
+tmux clear-history -t shell 
+tmux send-keys -t shell clear ENTER
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/setup-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+# source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/setup-shell

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+HOME_DIR=/home/replicant
+source /etc/profile.d/header.sh
+
+### Assure the tmux session exists
+#
+# In a test scenario Instuqt does not run the user shell for the
+# challenge, which means the tmux session is never established. We
+# need to session for the solve scripts for other challenges to 
+# succeed, so let's create it here.
+#
+if ! tmux has-session -t shell ; then
+  tmux new-session -d -s shell su - replicant
+fi
+
+# Wait for Instruqt bootstrap to be complete
+while [ ! -f /opt/instruqt/bootstrap/host-bootstrap-completed ]
+do
+  echo "Waiting for Instruqt to finish booting the VM"
+  sleep 1
+done

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/solve-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0

instruqt/delivering-as-an-appliance/01-specifying-the-cluster/solve-shell

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+HOME_DIR=/home/replicant
+source /etc/profile.d/header.sh
+
+exit 0

instruqt/delivering-as-an-appliance/02-customize-for-your-app/02-using-the-template/assignment.md

@@ -0,0 +1,83 @@
+---
+slug: using-the-template
+id: ntcxaanufkcb
+type: challenge
+title: Using the Template
+teaser: Some guidance on using the template
+notes:
+- type: text
+  contents: How and Why to Use This Template
+tabs:
+- title: Shell
+  type: terminal
+  hostname: shell
+difficulty: basic
+timelimit: 300
+---
+
+✨ Uses
+=======
+
+## Environment Variables
+
+Only one shell runs across all challenges. This means the values of
+environment variables persist from challenge to challenge without the
+user setting them into their `.bashrc`.
+
+## Long Running Commands
+
+If a challenge needs to end with long running command (for example
+downloading an airgap bundle or starting a kURL install), tell the user
+they can click **Check** and leave the comamnd running. When the next
+challenge starts then their shell will look the same and the command
+will still be running (unless it happened to finish during the Cleanup
+and Check scripts).
+
+🔄 Lifecycle Scripts
+====================
+
+Lifecycle scripts can take advantage of `tmux` to read and write from
+the learner's session. This is useful in Check scripts, for example,
+to read what the user has typed and what the output was from those
+commands. It also means that Setup, Cleanup, and Solve scripts can
+type into the users shell to run commands.
+
+Here are a couple of `tmux` commands to be aware of to interact with
+the session:
+
+`tmux capture-pane`
+: This command the history of what's been done in the learner's
+shell so you can intertact with it, for example to test whether
+they typed the commands you expected
+
+`tmux save-buffer`
+: After you've captured what the learner has done, you can use the
+`save-buffer` command to access it. The combination of the two is
+useful in Check scripts
+
+`tmux send-keys`
+: Allows you to send keystrokes to the learner's shell. You have to
+be explicit about charaters like `SPACE` and `ENTER` so that they
+are sent to. This can be great for Solve scripts.
+
+`tmux clear-histry`
+: Clears the scrollback history (not the shell history) to keep
+what's captured by `capture-pane` nice and fresh.
+
+🧪 Did It Work?
+===============
+
+Remember that variable we set in the last step? Let's make sure it
+stuck around like we expected.
+
+```
+echo $THIS
+```
+
+It should have, so you should see
+
+```text
+replicant@shell:~$ echo $THIS
+the way
+replicant@shell:~$
+```

instruqt/delivering-as-an-appliance/02-customize-for-your-app/02-using-the-template/check-cluster

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# This set line ensures that all failures will cause the script to error and exit
+set -euxo pipefail
+source /etc/profile.d/header.sh
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+exit 0