Workshop Configuration

There are two main components to a workshop. The first is the workshop definition, which defines the setup requirements for deploying the workshop and how to configure the Educates environment for that workshop. The second is the workshop files, consisting of the workshop instructions, setup files for the workshop, and any exercise files required for the workshop.

Workshop setup requirements

Workshop images can be deployed directly to a container runtime. To manage deployments into a Kubernetes cluster, the Educates operator is provided. Configuration for the Educates operator is defined by a Workshop custom resource definition. When using the workshop template to create the initial files for a workshop, this definition is found in the resources/workshop.yaml file.

apiVersion: training.educates.dev/v1beta1
kind: Workshop
metadata:
  name: lab-markdown-sample
spec:
  title: Markdown Sample
  description: A sample workshop using Markdown
  workshop:
    files:
    - git:
        url: https://github.com/vmware-tanzu-labs/lab-markdown-sample
        ref: origin/main
      includePaths:
      - /workshop/**
      - /exercises/**
      - /README.md
  session:
    namespaces:
      budget: small
    applications:
      console:
        enabled: true
      editor:
        enabled: true

In this sample workshop files are downloaded from a Git repository hosted on GitHub. This is specified in the workshop.files section of the workshop definition. The workshop files will be overlaid on top of the standard workshop base image.

As well as the standard workshop base image, Educates also provides workshop base images for working with Java and Python. To select the workshop base image with Java JDK 17 support you would use:

apiVersion: training.educates.dev/v1beta1
kind: Workshop
metadata:
  name: lab-markdown-sample
spec:
  title: Markdown Sample
  description: A sample workshop using Markdown
  workshop:
    image: jdk17-environment:*
    files:
    - git:
        url: https://github.com/vmware-tanzu-labs/lab-markdown-sample
        ref: origin/main
      includePaths:
      - /workshop/**
      - /exercises/**
      - /README.md
  session:
    namespaces:
      budget: small
    applications:
      console:
        enabled: true
      editor:
        enabled: true

In this case the alternate workshop image was specified by setting the workshop.image property.

As well as selecting one of the alternate workshop base images provided by Educates, you could also nominate a custom workshop image of your own:

apiVersion: training.educates.dev/v1beta1
kind: Workshop
metadata:
  name: lab-markdown-sample
spec:
  title: Markdown Sample
  description: A sample workshop using Markdown
  workshop:
    image: ghcr.io/vmware-tanzu-labs/lab-markdown-sample:latest
  session:
    namespaces:
      budget: small
    applications:
      console:
        enabled: true
      editor:
        enabled: true

When using a custom workshop image it can include the workshop files, or you can still download them separately and overlay them on top.

As well as being used to specify the workshop base image to use and the source of any workshop files, the Workshop definition is used to configure the workshop environment and workshop session. This includes details such as whether the embedded editor or Kubernetes web console is enabled, but also details such as additional resources to deploy with a workshop environment or session, what memory and storage requirements a workshop session has, or what quota is available when deploying workloads into the Kubernetes cluster.

For more details see the separate documentation on the Workshop definition.

Instructions rendering options

Educates currently supports two different renderers for workshop instructions.

The first and original renderer for workshop instructions included in Educates is called the classic renderer. This is a custom dynamic web application for rendering the workshop instructions. It supports the use of Markdown or AsciiDoc.

The second renderer for workshop instructions is the hugo renderer. As the name suggests this makes use of Hugo to generate workshop instructions as static HTML files, using custom layouts provided by Educates. Hugo only supports the use of Markdown.

In both cases, the pages making up the workshop instructions are placed in the workshop/content directory. When configuration is needed to specify the navigation path through the workshop instructions, how it is done differs based on the renderer used.

Classic renderer configuration

When using the classic renderer for workshop instructions, 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 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:
  00-workshop-overview:
    name: Workshop Overview
    exit_sign: Start Workshop
  01-workshop-instructions:
    name: Workshop Instructions
  99-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: Workshop

modules:
  activate:
  - 00-workshop-overview
  - 01-workshop-instructions
  - 99-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.

Hugo renderer configuration

When using the hugo renderer for workshop instructions, the need to specify explicitly via a separate configuration file the navigation path through the instructions is optional.

By default when using the hugo renderer, all pages will be included within the navigation path of the workshop instructions. The order in which pages are included will be calculated based on the pathname of the pages within the workshop/content directory. If you would prefer instead to use Hugo’s default page ordering mechanism, you can add page weight fields in the metadata of each page to dictate ordering. In that case the ordering will be based on page weight followed by page title. To specify the title for a page, you can add a title field in the metadata of each page.

If you would prefer to specify the order of pages via a YAML file, only have certain pages included, or have the option of multiple pathways which can be selected, a workshop/config.yaml file can be provided which defines this information.

If you elect to use the workshop/config.yaml, the structure it would contain where using it to define the navigation pathways would be as follows:

pathways:
  default: workshop

  paths:
    workshop:
      title: "Workshop"

      steps:
      - 00-workshop-overview
      - 01-workshop-instructions
      - 99-workshop-summary

modules:
- name: 00-workshop-overview
  title: Workshop Overview
- name: 01-workshop-instructions
  title: Workshop Instructions
- name: 99-workshop-summary
  title: Workshop Summary

Unlike with the classic render, the modules section is optional even when specifying the navigation pathway. When a module which is part of a pathway is being rendered, without an entry in modules it will use any page title defined in the metadata of the page itself.

If you want multiple possible pathways, you can list the steps for each in separate sections under pathways.paths. The pathways.default value should specify the default pathway. You can override the workshop title in the title field of a specific pathway.

To select which pathway is used when the workshop is started, you can set the PATHWAY_NAME environment variable in the workshop definition to the name of the pathway.

When using the hugo renderer, there is no way to override navigation button labels or where clicking on them will direct you as was possible with the classic renderer.