For BB-9977 I needed to test tutor-contrib-typesense on k8s. So I looked into using Tutor to deploy to a local k8s cluster.
Since it wasn’t trivial, here’s a tutorial that covers what worked for me:
-
Ensure docker is set up locally (you likely have it already if you’re using Tutor; I had rooted docker running).
-
Install KIND for your system, and then create a cluster:
kind create cluster
- (optional) If you need a custom openedx image (eg. with extra pip requirements, or local directories bind mounted at build time):
3.1. We’ll need a registry to push the image to, and for KIND to pull the image from. I used Docker Hub to avoid the hassle of setting up a local registry. Log in to Docker Hub locally:
docker login
3.2. Set a custom docker image path and tag in Tutor’s config.yml (this needs to be your Docker Hub namespace, but the repository doesn’t need to exist; tutor will create it):
DOCKER_IMAGE_OPENEDX: docker.io/samuelallan/openedx:20.0.1-main
3.3. Build and push the image with Tutor. Tutor will automatically tag and push using docker:
tutor images build openedx
tutor images push openedx
- Launch the Tutor deployment! You can leave the defaults, including the default local.openedx.io domains. Don’t set up TLS certs; this won’t work locally.
$ tutor k8s launch
==================================================
Interactive platform configuration
==================================================
Your website domain name for students (LMS) [local.openedx.io]
Your website domain name for teachers (CMS) [studio.local.openedx.io]
Your platform name/title [My Open edX]
Your public contact email address [contact@local.openedx.io]
The default language code for the platform [en]
Activate SSL/TLS certificates for HTTPS access? Important note: this will NOT work in a development environment. [y/N]
...
- Forward port 80 so you can access the deployment through the default domains. This must be done with root because 80 is a privileged port. This command must remain running to access the platform from the browser, so run this in a separate terminal window:
sudo kubectl "--kubeconfig=$HOME/.kube/config" --namespace=openedx port-forward svc/caddy 80
source: openedx/wg-devops#4 (comment)
- Now you have a deployment that you can access via the standard local.openedx.io domains. Note that you need to use port 80, not 8000. Tutor doesn’t appear to support changing the port, unless you’re using your own load balancer in front of Caddy.
Your Open edX platform is ready and can be accessed at the following urls:
http://local.openedx.io http://studio.local.openedx.io
Now you can create a user, import the demo course, etc. as usual. Just for the Tutor commands, you’ll need to use the k8s subcommand instead of `dev. Eg.
tutor k8s do createuser --staff --superuser samuel samuel@opencraft.com --password abcdef
tutor k8s do importdemocourse
Why not Minikube?
Minikube appeared to be the recommended option, but it didn’t work for me.
I did try to deploy Tutor on Minikube (minikube driver: docker) - it failed, as the containers couldn’t resolve host names:
ERROR 2005 (HY000): Unknown MySQL server host 'mysql' (-2)
[5/10] Waiting for MySQL service (this may take a while)...
mysql: [Warning] Using a password on the command line interface can be insecure.
Not sure why, but KIND worked fine.
I also tried Minikube locally with the kvm2 driver, but Minikube had other issues deploying the cluster:
❌ Exiting due to DRV_CORRUPT: Failed to start host: new host: Error attempting to get plugin server address for RPC: Failed to dial the plugin server in 10s
For context, I’m running Alpine Linux, edge channel, on x86_64.