Skip to content

Trussium Operator

Trussium logo

The Trussium Operator is the Kubernetes-native lifecycle manager for Trussium runtime instances.

It provides a declarative Kubernetes API for deploying, configuring, upgrading, and observing released Trussium runtime containers.

Project status: Production workload hardening is implemented, including health probes, non-root execution, secure container defaults, graceful termination, zero-unavailable rolling updates, topology spreading, PodDisruptionBudget management, and constrained scheduling customization.

Architecture

TrussiumRuntime custom resource
             │
             ▼
      Trussium Operator
             │
             ├── validates referenced Secrets
             ├── reconciles ConfigMap
             ├── reconciles ServiceAccount
             ├── reconciles Service
             ├── reconciles Deployment
             ├── updates runtime status
             └── emits Kubernetes Events
                         │
                         ▼
       ghcr.io/trussiumhq/trussium:<version>

The operator does not contain or compile the Trussium Python runtime. It consumes released runtime container images and manages their Kubernetes deployment lifecycle.

Installation

Install a released operator version with its CRDs and controller deployment:

kubectl apply -f \
  https://github.com/trussiumhq/trussium-operator/releases/download/v<version>/install.yaml

Replace v<version> with an operator release that includes the bundle. The release bundle pins the controller image to that same version.

Helm

The operator also has its own Helm chart. It installs the operator CRD and controller; it does not install a Trussium runtime workload:

Install the runtime chart separately, then use TrussiumRuntime resources for operator-managed runtime instances. See the chart documentation for values and local installation.

To limit reconciliation to a single tenant namespace, set the manager's watchNamespace Helm value. Leave it empty to watch all namespaces.

For Prometheus Operator installations, the Helm chart can optionally create a ServiceMonitor for the authenticated HTTPS metrics endpoint. See the chart documentation for its TLS configuration requirements.

Custom Resource

The initial API is:

Group:   runtime.trussium.io
Version: v1alpha1
Kind:    TrussiumRuntime
Scope:   Namespaced

Example:

apiVersion: runtime.trussium.io/v1alpha1
kind: TrussiumRuntime
metadata:
  name: private-ai
  namespace: trussium
spec:
  image:
    repository: ghcr.io/trussiumhq/trussium
    tag: v1.22.0

  provider:
    type: ollama
    model: llama3.2
    baseURL: http://ollama.ollama.svc.cluster.local:11434/v1

See docs/CUSTOM_RESOURCE.md for the complete API contract.

Core Reconciliation

For every TrussiumRuntime, the operator manages:

  • ConfigMap
  • ServiceAccount
  • Service
  • Deployment
  • PodDisruptionBudget
  • Optional NetworkPolicy
  • Optional CPU-based HorizontalPodAutoscaler

The controller uses stable labels, controller owner references, deterministic resource names, and create-or-update reconciliation.

It recreates deleted managed resources and corrects configuration drift.

NetworkPolicy reconciliation is opt-in. When enabled for a runtime, the operator restricts ingress to explicit client selectors on the runtime Service port while leaving egress unrestricted for DNS and provider connectivity. See docs/CUSTOM_RESOURCE.md for the full contract and CNI prerequisite.

CPU autoscaling is also opt-in. It requires a resource metrics provider and a CPU request for the runtime container; while enabled, the HPA controls the Deployment replica count. See docs/CUSTOM_RESOURCE.md.

See docs/RECONCILIATION.md for the reconciliation contract.

Runtime Status

The operator reports:

  • Observed generation
  • Ready replicas
  • Available replicas
  • Current runtime image
  • Internal Service endpoint
  • Configuration validity
  • Deployment progress
  • Runtime availability
  • Runtime readiness
  • Degraded state

Referenced provider and image-pull Secrets are checked for existence without reading their values.

The operator emits transition-based events.k8s.io/v1 Events for readiness, progress, recovery, configuration failures, degraded state, and reconciliation failures.

See docs/STATUS_AND_EVENTS.md.

High Availability

The Helm chart enables controller leader election by default. Set replicaCount above one only with leaderElection.enabled=true, which ensures one active manager reconciles runtime resources at a time. See the chart configuration.

Repository Responsibilities

This repository owns:

  • Kubernetes custom resource definitions
  • Kubernetes controllers
  • Runtime deployment reconciliation
  • Runtime configuration projection
  • Kubernetes status reporting
  • Kubernetes lifecycle Events
  • Operator packaging and installation
  • Runtime and operator compatibility documentation

The public trussium repository owns:

  • Runtime APIs
  • Provider adapters
  • AI execution behaviour
  • Runtime configuration semantics
  • Runtime container images
  • Runtime package and container releases

Production Workload Contract

Managed runtime Pods include:

  • Startup, liveness, and readiness probes
  • Numeric non-root execution
  • RuntimeDefault seccomp
  • Read-only root filesystem
  • Disabled privilege escalation
  • Dropped Linux capabilities
  • Graceful Kubernetes termination
  • Zero-unavailable rolling updates
  • Topology spreading
  • PodDisruptionBudget protection

Supported Pod customization includes:

  • Additional metadata
  • Node selectors
  • Tolerations
  • Affinity

See docs/PRODUCTION_RUNTIME.md.

Technology

  • Go
  • Kubebuilder
  • controller-runtime
  • controller-tools
  • Kustomize
  • envtest
  • Kind
  • Helm in a later milestone

Development

See https://github.com/trussiumhq/trussium-operator/blob/main/DEVELOPMENT.md for local setup and validation.

Run:

make generate
make manifests
make fmt
make vet
make test
make lint
make test-e2e

Runtime Upgrades

The operator observes runtime image transitions through Kubernetes Deployment status.

Upgrade status reports:

  • Desired runtime image
  • Deployment-configured runtime image
  • Last successfully rolled-out image
  • Upgrade progress
  • Upgrade completion
  • Upgrade failure

Runtime configuration changes also trigger Deployment revisions through a deterministic Pod-template checksum.

The operator does not automatically roll back failed upgrades and does not require Pod or ReplicaSet permissions.

See:

Roadmap

The public operator roadmap is maintained in https://github.com/trussiumhq/trussium-operator/blob/main/ROADMAP.md.

The next milestone hardens the managed Trussium runtime workload for production Kubernetes operation.

Contributing

Read https://github.com/trussiumhq/trussium-operator/blob/main/CONTRIBUTING.md before opening a change.

Security

Do not report suspected vulnerabilities through public issues. Follow https://github.com/trussiumhq/trussium-operator/blob/main/SECURITY.md.

Licence

Trussium Operator is licensed under the Apache License 2.0.