Installation Instructions
The installation instructions given here are only needed if you are installing into a dedicated Kubernetes cluster and not using the local Educates environment. Ensure you have read the general documentation about cluster requirements before proceeding with trying to install Educates.
Educates provides a package for installing an ingress controller and other operators it requires, such as Kyverno, so you do not need to have installed these first. Further information on installing these is given below.
Carvel command line tools
These instructions require that you have the Carvel command tools installed and available on the machine from which you are installing Educates. For installing these see:
The tools can be installed using a shell script provided by the Carvel project, or using Homebrew on macOS and Linux.
Ensure you are using an up to date version of the tools, and that if you used Homebrew to perform the install, and that was first done a long time ago, that the more recently added kctrl command line tool was included.
Installing kapp-controller
The standard method for installing Educates relies on the Carvel packaging system and requires that kapp-controller from Carvel be installed into the Kubernetes cluster.
If you are using a Kubernetes cluster created using Tanzu Kubernetes Grid (TKG) or Tanzu Mission Control (TMC), it will come preinstalled with kapp-controller and you do not need to install kapp-controller yourself.
If you do need to install kapp-controller, further information can be found at:
In most circumstances all you should need to do is run:
kapp deploy -a kc -f https://github.com/vmware-tanzu/carvel-kapp-controller/releases/latest/download/release.yml
Loading package definitions
The Carvel packaging ecosystem supports the concept of hosted package repositories, and Educates provides such a package repository.
To find what versions of the Educates package repository are available see:
To add the definitions from the Educates package repository to your Kubernetes cluster first create a namespace for holding them. You could instead use an existing namespace if you desire.
kubectl create ns educates-package
Then load the package repository definition by running the command:
kctrl package repository add -n educates-package --repository educates --url ghcr.io/vmware-tanzu-labs/educates-packages:X.Y.Z
In this example we have used X.Y.Z as the version of the package repository, however you should use whatever is the latest version available from the page linked above.
Once the package repository has been added to your Kubernetes cluster you can verify it is listed by running:
kctrl package repository list -n educates-package
You should see output which includes:
Name Source Status
educates (imgpkg) ghcr.io/vmware-tanzu-labs/educates-packages:X.Y.Z Reconcile succeeded
To see what packages are now available for installation run:
kctrl package available list -n educates-package
The list should include:
Name Display name
cluster-essentials.educates.dev Educates Cluster Essentials
training-platform.educates.dev Educates Training Platform
Neither of the packages has been installed as yet and that will be done in the following steps.
Installing cluster essentials
Educates requires that an ingress controller be installed into the Kubernetes cluster. The recommended ingress controller is Contour.
If an ingress controller has not already been installed, you can install the educates-cluster-essentials package to install Contour.
The educates-cluster-essentials package will also install Kyverno. Kyverno is used for security policy enforcement of workshop sessions.
To configure this package create a values file called educates-cluster-essentials-values.yaml containing:
clusterPackages:
contour:
enabled: true
settings: {}
kyverno:
enabled: true
settings: {}
clusterInfrastructure:
provider: ""
clusterSecurity:
policyEngine: "kyverno"
This represents the default configuration.
If a suitable ingress controller is already installed set clusterPackages.contour.enabled to false.
If you are installing on OpenShift, clusterPackages.contour.enabled must be set to false as OpenShift already provides an ingress controller in its default installation.
If a suitable version of Kyverno is already installed set clusterPackages.kyverno.enabled to false.
If neither is required you can skip installing the package completely.
If you are installing to a local Kubernetes cluster created using Kind, set clusterInfrastructure.provider to kind. The effect of setting this to kind will be to configure Contour to only create a ClusterIP service for Envoy and use host ports, and not a load balancer service. It is important that the Kubernetes cluster created using Kind exports the ingress controller host ports to the underlying host system in this case.
At this time there is no need to set clusterInfrastructure.provider for any other infrastructure provider, and in those cases Contour will use a LoadBalancer service for Envoy.
If you need to override any other configuration for Contour, you can add values to clusterPackages.contour.settings. These currently should correspond to the values accepted for the Contour Carvel package provided by TCE.
For Kyverno, you can add values to clusterPackages.kyverno.settings. The only setting that can currrently be supplied for Kyverno is replicaCount. This defaults to 1, but can be set to 3 if you want to deploy Kyverno in HA mode.
Next you must override the value of clusterSecurity.policyEngine. The value depends on how your Kubernetes cluster is configured.
If you are installing to OpenShift, clusterSecurity.policyEngine must be set to security-context-constraints.
If you are installing to a Kubernetes cluster which has pod security policies enabled, and it associates a default pod security policy with all authenticated users, clusterSecurity.policyEngine must be set to pod-security-policies.
For all other cases you should override clusterSecurity.policyEngine and set it to kyverno.
You can if necessary set clusterSecurity.policyEngine to none, but no security policy enforcement will be done, in which case workshop users would not be restricted from running containers with elevated privileges. Using none is okay for testing on your own local system, but should never be done where untrusted users would be doing workshops. If you do use none and develop your own workshops, you may also find those workshops will then not work on an Educates instance which does security policy enforcement. It is thus recommended to always at least set this to kyverno if not restricted otherwise by how the Kubernetes cluster is configured.
Note that the same setting used here for clusterSecurity.policyEngine will also need to be used later when installing the Educates training platform package.
To install the educates-cluster-essentials package first determine what versions are included with the Educates package repository you added by running:
kctrl package available get -n educates-package --package cluster-essentials.educates.dev
You can then install the desired version by running:
kctrl package install -n educates-package --package-install educates-cluster-essentials --package cluster-essentials.educates.dev --values-file educates-cluster-essentials-values.yaml --version "X.Y.Z"
Ensure you subsitute X.Y.Z with the actual version corresponding to the package definition which was loaded.
The --values-file option is used to supply the values file you created above.
Cluster ingress domain
For Educates to work it needs to be configured with an ingress domain.
If you want to configure Educates to use secure ingress, you need to have a wildcard TLS certificate for that ingress domain. If you do not have a wildcard TLS certificate for the ingress domain, then some features of workshops (such as per session image registries) will not work.
The preferred scenario is that you bring your own custom domain name and matching wildcard TLS certificate for that domain.
The first required step in using your own custom domain is to configure your DNS servers with a CNAME or equivalent entry to map all host name lookups under the domain (e.g., *.example.com) to the IP address or host name of the inbound ingress router for the Kubernetes cluster. How you calculate the IP address or host name of the inbound ingress router will depend on what infrastructure is being used to host the Kubernetes cluster and how the ingress controller was installed.
In the simplest case, using Contour installed with the educates-cluster-essentials package where a LoadBalancer service type for Envoy is being used, you may be able to determine the IP address or host name of the inbound ingress router by running:
kubectl get service/envoy -n projectcontour
If you have a matching wildcard TLS certificate for the ingress domain, you now need to create a Kubernetes secret for the certificate and load it into the Kubernetes cluster.
If you had used certbot to generate the certificate from LetsEncrypt using a DNS challenge, you should be able to create the secret resource file using a command similar to:
kubectl create secret tls example.com-tls --cert=$HOME/.letsencrypt/config/live/example.com/fullchain.pem --key=$HOME/.letsencrypt/config/live/example.com/privkey.pem --dry-run=client -o yaml > example.com-tls.yaml
Replace example.com with the name of your custom domain name.
Load the secret into the Kubernetes cluster using:
kubectl apply -n default -f example.com-tls.yaml
In this case we created the secret in the default namespace. You can use a different namespace if desired as the namespace will need to be listed explicitly in the configuration for Educates in a subsequent step.
If you do not have your own custom domain name, it is possible to use a nip.io address mapped to the IP address of the inbound ingress router host, however, because it will not be possible to obtain a TLS certificate for the domain, you will not be able to use secure ingress.
Create the configuration
With the pre-requisites now installed in the Kubernetes cluster, installation of the Educates training platform can be done using the educates-training-platform package.
To configure this package create a values file called educates-training-platform-values.yaml containing:
clusterIngress:
domain: "example.com"
tlsCertificateRef:
namespace: "default"
name: "example.com-tls"
clusterSecurity:
policyEngine: "kyverno"
workshopSecurity:
rulesEngine: "kyverno"
This is the most minimal configuration needed to install the Educates training platform.
Set clusterSecurity.policyEngine to the same value you used when installing the educates-cluster-essentials package.
That is, if you are installing to OpenShift, clusterSecurity.policyEngine must be set to security-context-constraints.
If you are installing to a Kubernetes cluster which has pod security policies enabled, and it associates a default pod security policy with all authenticated users, clusterSecurity.policyEngine must be set to pod-security-policies.
For all other cases you should override clusterSecurity.policyEngine and set it to kyverno.
The value of workshopSecurity.rulesEngine should also be set to kyverno. If can be set to none, and this is okay for testing on your own local system, but should never be done where untrusted users would be doing workshops.
For ingresses, set clusterIngress.domain to your custom domain name, or appropriate nip.io domain.
If you have a wildcard TLS certificate, update clusterSecurity.tlsCertificateRef.name, setting it to the name of the Kubernetes secret you created containing it. Change clusterSecurity.tlsCertificateRef.name if you created the secret in a namespace other than default.
If you do not have a wildcard TLS for the domain name you are using, delete the tlsCertificateRef section, including everything under it. If you comment out the section instead, you must use the #! comment prefix.
There are a range of other settings that can optionally be set. For more details on these settings and whether you may need to use them see the documentation on configuration settings.
Installing training platform
To install the educates-training-platform package first determine what versions are included with the Educates package repository you added by running:
kctrl package available get -n educates-package --package training-platform.educates.dev
You can then install the desired version by running:
kctrl package install -n educates-package --package-install educates-training-platform --package training-platform.educates.dev --values-file educates-training-platform-values.yaml --version "X.Y.Z"
Ensure you subsitute X.Y.Z with the actual version corresponding to the package definition which was loaded.
The --values-file option is used to supply the values file you created above.
Deleting the installation
It is recommended to remove any workshop environments before deleting Educates from the Kubernetes cluster. This will ensure that everything can be cleaned up properly.
To delete all current running workshop environments run:
kubectl delete workshops,trainingportals,workshoprequests,workshopsessions,workshopenvironments --all --cascade=foreground
The --cascade=foreground command ensures that the command only returns once all workshop environments have been deleted. This is necessary as otherwise deletion will occur in the background.
To make sure everything is deleted, run:
kubectl get workshops,trainingportals,workshoprequests,workshopsessions,workshopenvironments --all-namespaces
There should be nothing remaining.
The Educates training platform can then be deleted by running:
kctrl package installed delete -n educates-package --package-install educates-training-platform
and confirming that you want to delete it.
Once deletion has finished you can safely re-install the Educates training platform.
If you instead wanted to clean up everything, you can also delete the pre-requisites installed above using:
kctrl package installed delete -n educates-package --package-install educates-cluster-essentials
Note that if the educates-cluster-essentials package was used to install Contour and you were intending to use the Kubernetes cluster for some other purpose, you would need to re-install an ingress controller using some other method.