Skip to content

Resources and Requirements

Requirements

  • Kubernetes
  • For bare metal/lab installs, we recommend K3s
  • Helm
  • vCenter/Proxmox (for virtualization)
  • OAuth Provider: We typically use Keycloak

Crucible Applications and GitHub Pages

Crucible Helm Charts

All Crucible applications have Helm charts in the SEI's Helm charts repository. README files alongside each application's chart document the chart and the application's settings. Modify the settings using the values YAML file in your deployment.

To add the SEI's Helm charts repository:

helm repo add sei https://helm.cmusei.dev/charts
helm repo update

In addition to the application charts, there is a Crucible Umbrella Chart that includes all application charts and some third-party charts as dependent sub-charts. Using the Umbrella chart will deploy the full Crucible stack under one Crucible Helm deployment. More details on deployment using the Umbrella chart are in the Umbrella Chart Deployment section.

Other Helm Charts

The Crucible stack relies on other open source services that vendor their own Helm charts.

  • Moodle - open source Learning Management System (LMS) for online courses and training
  • MetalLB - Bare-metal load balancer for Kubernetes that assigns external IPs to services
  • ingress-nginx - Ingress controller using nginx for routing external traffic to cluster services
  • Rancher - Kubernetes cluster management and operations platform
  • Longhorn - Distributed block storage system for persistent volumes in Kubernetes
  • StackStorm - Event-driven automation and orchestration engine
  • RocketChat - open source team communication and messaging platform
  • Webmail - Web-based email client for in-platform messaging

Kubernetes Operators

Kubernetes Operators are software extensions that use custom resources to manage applications and their components. Operators encode operational knowledge—like how to deploy, configure, and recover a stateful service—into a controller that runs inside the cluster. Crucible relies on the following operators to manage its database and identity provider:

Crucible Terraform Provider

Terraform providers are plugins that allow Terraform to interact with APIs and services. The Crucible Terraform Provider exposes Crucible resources—such as exercises, users, and permissions—as Terraform-managed infrastructure, enabling repeatable, version-controlled deployments:

Example Umbrella Helm Chart Deployment

A Crucible deployment using umbrella Helm charts consists of four Helm charts to orchestrate the entire stack. Review the documentation for each of these charts to determine how to configure the settings for your deployment.

  1. crucible-operators - Install Kubernetes Operators for Keycloak and PostgreSQL before deploying applications.
  2. crucible-infra - Install prerequisite infrastructure (e.g., an ingress controller, storage provider, etc.) before deploying applications.
  3. crucible-apps - Install all Crucible applications.
  4. crucible-monitoring - Install a Grafana logging, open telemetry, and metrics stack to monitor the Kubernetes cluster and Crucible applications.

Step 1: Install Operators

Crucible uses Kubernetes operators for PostgreSQL and Keycloak. These are cluster-scoped infrastructure that install Custom Resource Definitions (CRDs) and watch all namespaces, so they deploy separately from the application charts. This provides privilege separation (cluster-admin for operators, namespace access for apps), independent upgrade cycles, and CRD safety.

The crucible-operators Helm chart installs both operators in a single release:

Operator Version Purpose
Keycloak Operator 26.5.6 Manages Keycloak instances via Keycloak and KeycloakRealmImport Custom Resources (CRs)
CloudNative-PG 0.25.0 (chart) Manages PostgreSQL clusters via Cluster CRs 
helm install crucible-operators charts/crucible-operators --wait

Verify both operators are running:

kubectl get pods -l app.kubernetes.io/instance=crucible-operators

Warning

When uninstalling, remove all CRs (Keycloak, KeycloakRealmImport, CloudNative-PG Cluster) before removing operators. Deleting CRDs removes all CRs cluster-wide.

Step 2: Deploy Infrastructure

The crucible-infra chart deploys:

  1. CloudNative-PG PostgreSQL cluster - Primary database for all Crucible applications. Managed by the CloudNative-PG Operator above.
  2. ingress-nginx - Routes external traffic to services within the cluster
  3. NFS storage provisioner - Provides dynamic NFS-backed persistent volumes for shared storage
  4. pgAdmin4 - Web-based PostgreSQL management interface

Configure or disable each of these services in the values file to match your deployment's needs.

helm install crucible-infra charts/crucible-infra -f crucible-infra.values.yaml

Step 3: Deploy Applications

The crucible-apps chart deploys all applications that are part of the Crucible Framework as well as the following third-party applications:

  1. Keycloak - Identity provider for authenticating to the platform. Managed by the Keycloak Operator above.
  2. Moodle - open source LMS for online courses and training.
helm install crucible-apps charts/crucible-apps -f crucible-apps.values.yaml

Step 4: Deploy Monitoring (optional)

The crucible-monitoring chart deploys a Grafana logging, open telemetry, and metrics stack to monitor the Kubernetes cluster and Crucible applications. The stack includes:

  1. Grafana - Observability dashboards for visualizing metrics, logs, and traces.
  2. Prometheus - Time-series metrics collection and alerting system.
  3. Loki - Log aggregation system designed for efficient storage and querying.
  4. Tempo - Distributed tracing back end for end-to-end request tracking.
  5. Grafana Alloy - OpenTelemetry collector for shipping metrics, logs, and traces.
helm install crucible-monitoring charts/crucible-monitoring -f crucible-monitoring.values.yaml