tutor-contrib-k8s

Helper plugin for Kubernetes deployments of Open edX. It extends Tutor’s K8s environment with deployment patches and configuration knobs for autoscaling and resource sizing of LMS, CMS, their workers, MFEs, and Caddy.

This release targets Open edX Ulmo with Tutor 21.x.

What it does

Adds Kubernetes patch templates that tweak deployments, HPAs, and resource requests/limits for Tutor services.
Exposes K8S_* configuration settings so you can tune replicas, HPA behavior, and resources without editing manifests by hand.
Includes PodDisruptionBudget resources for core services with configurable availability thresholds. Each PDB can be toggled with the K8S_*_PDB_ENABLE settings.
Adds VerticalPodAutoscaler templates for core services with configurable update mode, min/max allowed resources, and controlled resources.
Adds startup, readiness, and liveness probes to the LMS and CMS deployments. The startup probe calls the Open edX /heartbeat endpoint with the required internal Host header, so a pod does not join its Service until Open edX can genuinely serve. Readiness and liveness use TCP checks, so a stall in a shared dependency cannot eject or restart every replica at once.

Installation

From Github:

pip install git+https://github.com/aulasneo/tutor-contrib-k8s.git

From PyPI:

pip install tutor-contrib-k8s

Usage

tutor plugins enable k8s

Configuration

All settings are regular Tutor config values prefixed with K8S_. You can set them via tutor config save or by editing your Tutor config file.

tutor config save \
  --set K8S_LMS_REPLICAS=2 \
  --set K8S_LMS_MAX_REPLICAS=6

After changing settings, re-render or redeploy your Tutor K8s environment as you normally would so the updated templates are applied.

Health probes

LMS and CMS health probes are enabled by default with K8S_OPENEDX_HEALTH_PROBES_ENABLE. The startup probe calls /heartbeat on port 8000 and allows up to 10 minutes for Open edX to initialize. Because Kubernetes suspends the readiness and liveness probes until the startup probe first succeeds, no pod joins its Service until Open edX has genuinely answered a full health check.

Readiness and liveness then use TCP checks on port 8000 rather than /heartbeat. This is deliberate. /heartbeat verifies MySQL and the modulestore, which every pod shares, so a database stall fails the probe on all replicas simultaneously:

On liveness, Kubernetes would restart the whole deployment, turning a short dependency blip into a prolonged outage since each replacement pod must pay full Open edX startup time.
On readiness, Kubernetes removes every pod from the Service endpoints. The ingress then has nowhere to send traffic and refuses connections, so the site is completely down even though every pod is healthy and idle. Not restarting the pods is little consolation when no request can reach them.

A probe should answer “can this pod serve?”, not “is the shared database healthy?”. Correlated dependency checks turn a slowdown into an outage, and they do it at the worst possible moment — under load, when the database is already struggling. Genuine dependency failures surface as application errors and in monitoring, which is where they belong.

If every replica has independent dependencies and you want dependency-aware readiness, set K8S_OPENEDX_READINESS_PROBE_USE_HEARTBEAT to true to restore the /heartbeat readiness check. Be aware that timing settings alone are not a safe substitute: a dump holding table locks, or any stall lasting minutes, will outlast any reasonable timeoutSeconds × failureThreshold budget.

The probe timing settings are:

K8S_OPENEDX_STARTUP_PROBE_PERIOD_SECONDS
K8S_OPENEDX_STARTUP_PROBE_TIMEOUT_SECONDS
K8S_OPENEDX_STARTUP_PROBE_FAILURE_THRESHOLD
K8S_OPENEDX_READINESS_PROBE_PERIOD_SECONDS
K8S_OPENEDX_READINESS_PROBE_TIMEOUT_SECONDS
K8S_OPENEDX_READINESS_PROBE_FAILURE_THRESHOLD
K8S_OPENEDX_READINESS_PROBE_USE_HEARTBEAT (default false)
K8S_OPENEDX_LIVENESS_PROBE_PERIOD_SECONDS
K8S_OPENEDX_LIVENESS_PROBE_TIMEOUT_SECONDS
K8S_OPENEDX_LIVENESS_PROBE_FAILURE_THRESHOLD

Settings and defaults

Resource settings

Setting suffix	Description
CPU_REQUEST	Amount of CPU reserved for the pod.
MEMORY_REQUEST	Amount of memory reserved for the pod.
CPU_LIMIT	Maximum CPU the pod can use; usage above this is throttled.
MEMORY_LIMIT	Maximum memory allowed; exceeding this leads to an OOM kill.
REPLICAS	Baseline number of replicas when autoscaling is disabled.
MAX_REPLICAS	Upper bound for autoscaling.

HPA settings

Setting suffix	Description
HPA_ENABLE	Enables HPA creation for the service.
HPA_CPU_ENABLE	Enables CPU utilization metrics in the HPA.
HPA_MEMORY_ENABLE	Enables memory utilization metrics in the HPA.
HPA_CPU_AVERAGE_UTILIZATION	Target average CPU utilization percentage.
HPA_MEMORY_AVERAGE_UTILIZATION	Target average memory utilization percentage.
HPA_SCALE_UP_STABILIZATION_WINDOW_SECONDS	Window to stabilize scale-up recommendations.
HPA_SCALE_UP_PERCENT	Max scale-up change as a percentage per period.
HPA_SCALE_UP_PODS	Max scale-up change as a number of pods per period.
HPA_SCALE_UP_PERIOD_SECONDS	Period for scale-up policies in seconds.
HPA_SCALE_DOWN_STABILIZATION_WINDOW_SECONDS	Window to stabilize scale-down recommendations.
HPA_SCALE_DOWN_PERCENT	Max scale-down change as a percentage per period.
HPA_SCALE_DOWN_PODS	Max scale-down change as a number of pods per period.
HPA_SCALE_DOWN_PERIOD_SECONDS	Period for scale-down policies in seconds.

PDB settings

Setting suffix	Description
PDB_ENABLE	Enables PodDisruptionBudget creation for the service.
MIN_AVAILABLE_REPLICAS	Minimum number of replicas that must remain available.

VPA settings

Setting suffix	Description
VPA_ENABLE	Enables VerticalPodAutoscaler creation for the service.
VPA_MIN_ALLOWED_CPU	Minimum CPU the VPA can recommend.
VPA_MAX_ALLOWED_CPU	Maximum CPU the VPA can recommend.
VPA_MIN_ALLOWED_MEMORY	Minimum memory the VPA can recommend.
VPA_MAX_ALLOWED_MEMORY	Maximum memory the VPA can recommend.
VPA_CONTROLLED_RESOURCES	Resource types controlled by VPA (cpu and/or memory).
VPA_UPDATE_MODE	Update mode for applying recommendations (Off, Initial, Auto).

Default settings

Setting	Default
K8S_VERSION	Plugin version
K8S_LMS_HPA_CPU_AVERAGE_UTILIZATION	80
K8S_LMS_HPA_MEMORY_AVERAGE_UTILIZATION	80
K8S_LMS_HPA_SCALE_UP_STABILIZATION_WINDOW_SECONDS	0
K8S_LMS_HPA_SCALE_UP_PERCENT	100
K8S_LMS_HPA_SCALE_UP_PODS	4
K8S_LMS_HPA_SCALE_UP_PERIOD_SECONDS	60
K8S_LMS_HPA_SCALE_DOWN_STABILIZATION_WINDOW_SECONDS	300
K8S_LMS_HPA_SCALE_DOWN_PERCENT	10
K8S_LMS_HPA_SCALE_DOWN_PODS	1
K8S_LMS_HPA_SCALE_DOWN_PERIOD_SECONDS	60
K8S_CMS_HPA_CPU_AVERAGE_UTILIZATION	80
K8S_CMS_HPA_MEMORY_AVERAGE_UTILIZATION	80
K8S_CMS_HPA_SCALE_UP_STABILIZATION_WINDOW_SECONDS	0
K8S_CMS_HPA_SCALE_UP_PERCENT	100
K8S_CMS_HPA_SCALE_UP_PODS	4
K8S_CMS_HPA_SCALE_UP_PERIOD_SECONDS	60
K8S_CMS_HPA_SCALE_DOWN_STABILIZATION_WINDOW_SECONDS	300
K8S_CMS_HPA_SCALE_DOWN_PERCENT	10
K8S_CMS_HPA_SCALE_DOWN_PODS	1
K8S_CMS_HPA_SCALE_DOWN_PERIOD_SECONDS	60
K8S_LMS_WORKER_HPA_CPU_AVERAGE_UTILIZATION	80
K8S_LMS_WORKER_HPA_MEMORY_AVERAGE_UTILIZATION	80
K8S_LMS_WORKER_HPA_SCALE_UP_STABILIZATION_WINDOW_SECONDS	0
K8S_LMS_WORKER_HPA_SCALE_UP_PERCENT	100
K8S_LMS_WORKER_HPA_SCALE_UP_PODS	4
K8S_LMS_WORKER_HPA_SCALE_UP_PERIOD_SECONDS	60
K8S_LMS_WORKER_HPA_SCALE_DOWN_STABILIZATION_WINDOW_SECONDS	300
K8S_LMS_WORKER_HPA_SCALE_DOWN_PERCENT	10
K8S_LMS_WORKER_HPA_SCALE_DOWN_PODS	1
K8S_LMS_WORKER_HPA_SCALE_DOWN_PERIOD_SECONDS	60
K8S_CMS_WORKER_HPA_CPU_AVERAGE_UTILIZATION	80
K8S_CMS_WORKER_HPA_MEMORY_AVERAGE_UTILIZATION	80
K8S_CMS_WORKER_HPA_SCALE_UP_STABILIZATION_WINDOW_SECONDS	0
K8S_CMS_WORKER_HPA_SCALE_UP_PERCENT	100
K8S_CMS_WORKER_HPA_SCALE_UP_PODS	4
K8S_CMS_WORKER_HPA_SCALE_UP_PERIOD_SECONDS	60
K8S_CMS_WORKER_HPA_SCALE_DOWN_STABILIZATION_WINDOW_SECONDS	300
K8S_CMS_WORKER_HPA_SCALE_DOWN_PERCENT	10
K8S_CMS_WORKER_HPA_SCALE_DOWN_PODS	1
K8S_CMS_WORKER_HPA_SCALE_DOWN_PERIOD_SECONDS	60
K8S_MFE_HPA_CPU_AVERAGE_UTILIZATION	80
K8S_MFE_HPA_MEMORY_AVERAGE_UTILIZATION	80
K8S_MFE_HPA_SCALE_UP_STABILIZATION_WINDOW_SECONDS	0
K8S_MFE_HPA_SCALE_UP_PERCENT	100
K8S_MFE_HPA_SCALE_UP_PODS	4
K8S_MFE_HPA_SCALE_UP_PERIOD_SECONDS	60
K8S_MFE_HPA_SCALE_DOWN_STABILIZATION_WINDOW_SECONDS	300
K8S_MFE_HPA_SCALE_DOWN_PERCENT	10
K8S_MFE_HPA_SCALE_DOWN_PODS	1
K8S_MFE_HPA_SCALE_DOWN_PERIOD_SECONDS	60
K8S_CADDY_HPA_CPU_AVERAGE_UTILIZATION	80
K8S_CADDY_HPA_MEMORY_AVERAGE_UTILIZATION	80
K8S_CADDY_HPA_SCALE_UP_STABILIZATION_WINDOW_SECONDS	0
K8S_CADDY_HPA_SCALE_UP_PERCENT	100
K8S_CADDY_HPA_SCALE_UP_PODS	4
K8S_CADDY_HPA_SCALE_UP_PERIOD_SECONDS	60
K8S_CADDY_HPA_SCALE_DOWN_STABILIZATION_WINDOW_SECONDS	300
K8S_CADDY_HPA_SCALE_DOWN_PERCENT	10
K8S_CADDY_HPA_SCALE_DOWN_PODS	1
K8S_CADDY_HPA_SCALE_DOWN_PERIOD_SECONDS	60
K8S_CMS_CPU_REQUEST	20m
K8S_CMS_MEMORY_REQUEST	1.5Gi
K8S_CMS_CPU_LIMIT	100m
K8S_CMS_MEMORY_LIMIT	2Gi
K8S_CMS_REPLICAS	1
K8S_CMS_MAX_REPLICAS	3
K8S_CMS_WORKER_CPU_REQUEST	20m
K8S_CMS_WORKER_MEMORY_REQUEST	1.5Gi
K8S_CMS_WORKER_CPU_LIMIT	100m
K8S_CMS_WORKER_MEMORY_LIMIT	2Gi
K8S_CMS_WORKER_REPLICAS	1
K8S_CMS_WORKER_MAX_REPLICAS	3
K8S_LMS_CPU_REQUEST	20m
K8S_LMS_MEMORY_REQUEST	1.5Gi
K8S_LMS_CPU_LIMIT	100m
K8S_LMS_MEMORY_LIMIT	2Gi
K8S_LMS_REPLICAS	1
K8S_LMS_MAX_REPLICAS	3
K8S_LMS_WORKER_CPU_REQUEST	20m
K8S_LMS_WORKER_MEMORY_REQUEST	1.5Gi
K8S_LMS_WORKER_CPU_LIMIT	100m
K8S_LMS_WORKER_MEMORY_LIMIT	2Gi
K8S_LMS_WORKER_REPLICAS	1
K8S_LMS_WORKER_MAX_REPLICAS	3
K8S_MFE_CPU_REQUEST	10m
K8S_MFE_MEMORY_REQUEST	30Mi
K8S_MFE_CPU_LIMIT	100m
K8S_MFE_MEMORY_LIMIT	100Mi
K8S_MFE_REPLICAS	1
K8S_MFE_MAX_REPLICAS	3
K8S_CADDY_CPU_REQUEST	10m
K8S_CADDY_MEMORY_REQUEST	50Mi
K8S_CADDY_CPU_LIMIT	100m
K8S_CADDY_MEMORY_LIMIT	100Mi
K8S_CADDY_REPLICAS	1
K8S_CADDY_MAX_REPLICAS	3
K8S_CMS_PDB_ENABLE	True
K8S_CMS_WORKER_PDB_ENABLE	True
K8S_LMS_PDB_ENABLE	True
K8S_LMS_WORKER_PDB_ENABLE	True
K8S_MFE_PDB_ENABLE	True
K8S_CADDY_PDB_ENABLE	True
K8S_CADDY_MIN_AVAILABLE_REPLICAS	1
K8S_LMS_MIN_AVAILABLE_REPLICAS	1
K8S_LMS_WORKER_MIN_AVAILABLE_REPLICAS	1
K8S_CMS_MIN_AVAILABLE_REPLICAS	1
K8S_CMS_WORKER_MIN_AVAILABLE_REPLICAS	1
K8S_MFE_MIN_AVAILABLE_REPLICAS	1
K8S_VPA_CONTROLLED_RESOURCES	["cpu"]
K8S_VPA_UPDATE_MODE	Off
K8S_CMS_VPA_ENABLE	True
K8S_CMS_VPA_MIN_ALLOWED_CPU	10m
K8S_CMS_VPA_MAX_ALLOWED_CPU	1000m
K8S_CMS_VPA_MIN_ALLOWED_MEMORY	1.5Gi
K8S_CMS_VPA_MAX_ALLOWED_MEMORY	4Gi
K8S_CMS_WORKER_VPA_ENABLE	True
K8S_CMS_WORKER_VPA_MIN_ALLOWED_CPU	10m
K8S_CMS_WORKER_VPA_MAX_ALLOWED_CPU	1000m
K8S_CMS_WORKER_VPA_MIN_ALLOWED_MEMORY	1.5Gi
K8S_CMS_WORKER_VPA_MAX_ALLOWED_MEMORY	4Gi
K8S_LMS_VPA_ENABLE	True
K8S_LMS_VPA_MIN_ALLOWED_CPU	10m
K8S_LMS_VPA_MAX_ALLOWED_CPU	1000m
K8S_LMS_VPA_MIN_ALLOWED_MEMORY	1.5Gi
K8S_LMS_VPA_MAX_ALLOWED_MEMORY	4Gi
K8S_LMS_WORKER_VPA_ENABLE	True
K8S_LMS_WORKER_VPA_MIN_ALLOWED_CPU	10m
K8S_LMS_WORKER_VPA_MAX_ALLOWED_CPU	1000m
K8S_LMS_WORKER_VPA_MIN_ALLOWED_MEMORY	1.5Gi
K8S_LMS_WORKER_VPA_MAX_ALLOWED_MEMORY	4Gi
K8S_MFE_VPA_ENABLE	True
K8S_MFE_VPA_MIN_ALLOWED_CPU	10m
K8S_MFE_VPA_MAX_ALLOWED_CPU	100m
K8S_MFE_VPA_MIN_ALLOWED_MEMORY	30Mi
K8S_MFE_VPA_MAX_ALLOWED_MEMORY	100Mi
K8S_CADDY_VPA_ENABLE	True
K8S_CADDY_VPA_MIN_ALLOWED_CPU	10m
K8S_CADDY_VPA_MAX_ALLOWED_CPU	100m
K8S_CADDY_VPA_MIN_ALLOWED_MEMORY	50Mi
K8S_CADDY_VPA_MAX_ALLOWED_MEMORY	100Mi

License

This software is licensed under the terms of the AGPLv3.

Development Status
- 3 - Alpha
Intended Audience
- Developers
License
- OSI Approved :: GNU Affero General Public License v3
Operating System
- OS Independent
Programming Language

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tutor_contrib_k8s-21.1.1.tar.gz (23.5 kB view details)

Uploaded Aug 26, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

tutor_contrib_k8s-21.1.1-py3-none-any.whl (12.9 kB view details)

Uploaded Aug 26, 2026 Python 3

File details

Details for the file tutor_contrib_k8s-21.1.1.tar.gz.

File metadata

Download URL: tutor_contrib_k8s-21.1.1.tar.gz
Upload date: Aug 26, 2026
Size: 23.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tutor_contrib_k8s-21.1.1.tar.gz
Algorithm	Hash digest
SHA256	`27175b5b74a03518eee76d6a8f96de09918560b8fab407f250833fc92cb79a47`
MD5	`57085949656ada79de65b4080846b479`
BLAKE2b-256	`e783a3138e50852acf88889f5ff683b3d1eb1f2ece93ca7eecd75cd79ee68c4c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for tutor_contrib_k8s-21.1.1.tar.gz:

Publisher: publish.yml on aulasneo/tutor-contrib-k8s

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: tutor_contrib_k8s-21.1.1.tar.gz
- Subject digest: 27175b5b74a03518eee76d6a8f96de09918560b8fab407f250833fc92cb79a47
- Sigstore transparency entry: 2602670639
- Sigstore integration time: Aug 26, 2026
Source repository:
- Permalink: aulasneo/tutor-contrib-k8s@d01307da1ed80cd2d1b380ba2e678d290c3cd9dd
- Branch / Tag: refs/tags/v21.1.1
- Owner: https://github.com/aulasneo
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@d01307da1ed80cd2d1b380ba2e678d290c3cd9dd
- Trigger Event: push