Workshop Session

The WorkshopSession custom resource defines a workshop session.

The raw custom resource definition for the WorkshopSession custom resource can be viewed by running:

kubectl get crd/workshopsessions.training.educates.dev -o yaml

Note that as deployment and use of workshops is now all typically managed via a training portal, there is no need to interact with internal custom resources directly such as WorkshopEnvironment, WorkshopSession and WorkshopRequest directly. In other words this resource has become an internal implementation detail of the larger system. For that reason the documentation here may not be completely up to date.

Specifying the session identity

When running training for multiple people, it would be more typical to use the TrainingPortal custom resource to set up a training environment. Alternatively you would set up a workshop environment using the WorkshopEnvironment custom resource, then create requests for workshop instances using the WorkshopRequest custom resource. If doing the latter and you need more control over how the workshop instances are set up, you can use WorkshopSession custom resource instead of WorkshopRequest.

To specify the workshop environment the workshop instance is created against, set the environment.name field of the specification for the workshop session. At the same time, you must specify the session ID for the workshop instance.

apiVersion: training.educates.dev/v1beta1
kind: WorkshopSession
metadata:
  name: lab-markdown-sample-user1
spec:
  environment:
    name: lab-markdown-sample
  session:
    id: user1

The name of the workshop specified in the metadata of the training environment needs to be globally unique for the workshop instance being created. You would need to create a separate WorkshopSession custom resource for each workshop instance you want.

The session ID needs to be unique within the workshop environment the workshop instance is being created against.

Specifying the login credentials

Access to each workshop instance can be controlled through login credentials. This is so that a workshop attendee cannot interfere with another.

If you want to set login credentials for a workshop instance, you can set the session.username and session.password fields.

apiVersion: training.educates.dev/v1beta1
kind: WorkshopSession
metadata:
  name: lab-markdown-sample
spec:
  environment:
    name: lab-markdown-sample-user1
  session:
    username: educates
    password: lab-markdown-sample

If you do not specify login credentials, there will not be any access controls on the workshop instance and anyone will be able to access it.

Specifying the ingress domain

In order to be able to access the workshop instance using a public URL, you will need to specify an ingress domain. If an ingress domain isn’t specified, the default ingress domain that the Educates operator has been configured with will be used.

When setting a custom domain, DNS must have been configured with a wildcard domain to forward all requests for sub domains of the custom domain, to the ingress router of the Kubernetes cluster.

To provide the ingress domain, you can set the session.ingress.domain field.

apiVersion: training.educates.dev/v1beta1
kind: WorkshopSession
metadata:
  name: lab-markdown-sample
spec:
  environment:
    name: lab-markdown-sample-user1
  session:
    ingress:
      domain: training.educates.dev

A full hostname for the session will be created by prefixing the ingress domain with a hostname constructed from the name of the workshop environment and the session ID.

If overriding the domain, by default, the workshop session will be exposed using a HTTP connection. If you require a secure HTTPS connection, you will need to have access to a wildcard SSL certificate for the domain. A secret of type tls should be created for the certificate in the Educates operator namespace. The name of that secret should then be set in the session.ingress.secret field.

apiVersion: training.educates.dev/v1beta1
kind: WorkshopSession
metadata:
  name: lab-markdown-sample
spec:
  environment:
    name: lab-markdown-sample-user1
  session:
    ingress:
      domain: training.educates.dev
      secret: training.educates.dev-tls

If HTTPS connections are being terminated using an external load balancer and not by specificying a secret for ingresses managed by the Kubernetes ingress controller, with traffic then routed into the Kubernetes cluster as HTTP connections, you can override the ingress protocol without specifying an ingress secret by setting the session.ingress.protocol field.

apiVersion: training.educates.dev/v1beta1
kind: WorkshopSession
metadata:
  name: lab-markdown-sample
spec:
  environment:
    name: lab-markdown-sample-user1
  session:
    ingress:
      domain: training.educates.dev
      protocol: https

If you need to override or set the ingress class, which dictates which ingress router is used when more than one option is available, you can add session.ingress.class.

apiVersion: training.educates.dev/v1beta1
kind: WorkshopSession
metadata:
  name: lab-markdown-sample
spec:
  environment:
    name: lab-markdown-sample-user1
  session:
    ingress:
      domain: training.educates.dev
      secret: training.educates.dev-tls
      class: nginx

Setting the environment variables

If you want to set the environment variables for the workshop instance, you can provide the environment variables in the session.env field.

apiVersion: training.educates.dev/v1beta1
kind: WorkshopSession
metadata:
  name: lab-markdown-sample
spec:
  environment:
    name: lab-markdown-sample
  session:
    id: user1
    env:
    - name: REPOSITORY_URL
      value: https://github.com/vmware-tanzu-labs/lab-markdown-sample

Values of fields in the list of resource objects can reference a number of pre-defined parameters. The available parameters are:

  • session_id - A unique ID for the workshop instance within the workshop environment.

  • session_namespace - The namespace created for and bound to the workshop instance. This is the namespace unique to the session and where a workshop can create their own resources.

  • environment_name - The name of the workshop environment. For now this is the same as the name of the namespace for the workshop environment. Don’t rely on them being the same, and use the most appropriate to cope with any future change.

  • workshop_namespace - The namespace for the workshop environment. This is the namespace where all deployments of the workshop instances are created, and where the service account that the workshop instance runs as exists.

  • service_account - The name of the service account the workshop instance runs as, and which has access to the namespace created for that workshop instance.

  • ingress_domain - The host domain under which hostnames can be created when creating ingress routes.

  • ingress_protocol - The protocol (http/https) that is used for ingress routes which are created for workshops.

  • services_password - A unique random password value for use with arbitrary services deployed with a workshop.

  • ssh_private_key - The private part of a unique SSH key pair generated for the workshop session.

  • ssh_public_key - The public part of a unique SSH key pair generated for the workshop session.

  • ssh_keys_secret - The name of the Kubernetes secret in the workshop namespace holding the SSH key pair for the workshop session.

  • platform_arch - The CPU architecture the workshop container is running on, amd64 or arm64.

The syntax for referencing one of the parameters is $(parameter_name).

Note that if the workshop environment had specified a set of extra environment variables to be set for workshop instances, it is up to you to incorporate those in the set of environment variables you list under session.env. That is, anything listed in session.env of the WorkshopEnvironment custom resource of the workshop environment is ignored.