Workshop Config

There are two main parts to the configuration for a workshop. The first specifies the structure of the workshop content and the second defines the runtime requirements for deploying the workshop.

Specifying structure of the content

There are multiple ways you can setup the configuration of a workshop to specify the structure of the content. The way used in the sample workshops is through YAML files.

The workshop/modules.yaml file provides details on the list of available modules which make up your workshop, and data variables for use in content.

In the case of the list of modules, not all modules may end up being used. This is because this list represents the full set of modules you have available and might use. You may want to run variations of your workshop, such as for different programming languages. As such, which modules are active and will be used for a specific workshop are listed in the separate workshop/workshop.yaml file, along with the name to be given to the workshop when using that set of modules.

By default the workshop.yaml file will be used to drive what modules are used. Where you want to deliver different variations of the workshop content, you can provide multiple workshop files with different names. You might for example instead provide workshop-java.yaml and workshop-python.yaml.

Where you have multiple workshop files, and don’t have the default workshop.yaml file, you can specify the default workshop file to use by setting the WORKSHOP_FILE environment variable in the runtime configuration for the workshop.

The format for listing the available modules in the workshop/modules.yaml file is:

modules:
    workshop-overview:
        name: Workshop Overview
        exit_sign: Setup Environment
    setup-environment:
        name: Setup Environment
        exit_sign: Start Workshop
    exercises/01-sample-content:
        name: Sample Content
    workshop-summary:
        name: Workshop Summary
        exit_sign: Finish Workshop

Each available module is listed under modules, where the name used corresponds to the path to the file containing the content for that module, with any extension identifying the content type left off.

For each module, set the name field to the page title to be displayed for that module. If no fields are provided and name is not set, the title for the module will be calculated from the name of the module file.

The corresponding workshop/workshop.yaml file, where all available modules were being used, would have the format:

name: Markdown Sample

modules:
    activate:
    - workshop-overview
    - setup-environment
    - exercises/01-sample-content
    - workshop-summary

The top level name field in this file is the name for this variation of the workshop content.

The modules.activate field is a list of modules to be used for the workshop. The names in this list must match the names as they appear in the modules file.

The order in which pages are traversed, is dictated by the order in which modules are listed under the modules.activate field in the workshop configuration file. The order in which modules appear in the modules configuration file is not relevant.

At the bottom of each page a “Continue” button will be displayed to go to the next page in sequence. The label on this button can be customised by setting the exit_sign field in the entry for the module in the modules configuration file.

For the last module in the workshop, a button will still be displayed, but where the user is taken when the button is pressed can vary.

If you want the user to be taken to a different web site upon completion you can set the exit_link field of the final module to an external URL. Alternatively, the RESTART_URL environment variable can be set from a workshop environment to control where the user is taken.

If a destination for the final page is not provided the user will be redirected back to the starting page of the workshop.

When using the training portal, it will override this environment variable so that at the completion of a workshop the user is directed back to the training portal.

The recommendation is that for the last page the exit_sign be set to “Finish Workshop” and exit_link not be specified. This will enable the destination to be controlled from the workshop environment or training portal.

Specifying the runtime configuration

Workshop images can be deployed directly to a container runtime. To manage deployments into a Kubernetes cluster, the eduk8s operator is provided. Configuration for the eduk8s operator is defined by a Workshop custom resource definition in the resources/workshop.yaml file:

apiVersion: training.eduk8s.io/v1alpha2
kind: Workshop
metadata:
  name: lab-markdown-sample
spec:
  vendor: eduk8s.io
  title: Markdown Sample
  description: A sample workshop using Markdown
  url: https://github.com/eduk8s/lab-markdown-sample
  content:
    image: quay.io/eduk8s/lab-markdown-sample:master
  duration: 15m
  session:
    namespaces:
      budget: small
    applications:
      console:
        enabled: true
      editor:
        enabled: true

In this sample, a custom workshop image is used which bundles the workshop content into its own container image. This was specified by the content.image setting. If instead workshop content was to be downloaded from a GitHub repository at runtime, you would use:

apiVersion: training.eduk8s.io/v1alpha2
kind: Workshop
metadata:
  name: lab-markdown-sample
spec:
  vendor: eduk8s.io
  title: Markdown Sample
  description: A sample workshop using Markdown
  url: https://github.com/eduk8s/lab-markdown-sample
  content:
    files: github.com/eduk8s/lab-markdown-sample
  duration: 15m
  session:
    namespaces:
      budget: small
    applications:
      console:
        enabled: true
      editor:
        enabled: true

The difference is the use of the content.files setting. The workshop content will be overlaid on top of the standard workshop base image. If you wanted to use an alternate base image with additional applications or packages installed, you would specify the alternate image against the content.image setting at the same time as setting content.files.

The format of this file and others in the resources directory will be covered later in the part of the documentation which discusses the setup of a workshop environment under Kubernetes.