Metatron is a Ruby library for creating Metacontroller-based custom Kubernetes controllers.
The intention is to make it as easy as possible to use Ruby to manage custom resources within your Kubernetes infrastructure. No Golang required! Use simple, Rack-based controllers to provide the logic for your custom resources. Metatron templates provide most Kubernetes boilerplate code for you, so you can focus on the logic that enables your custom resources to do what you need them to do.
For more information, see the Metatron Wiki on GitHub!
Metatron requires Ruby 3.4 or newer. Development and releases target the
version pinned in .ruby-version.
For help on how to get started, take a look at the User Guide in the Wiki!
Metatron controllers are HTTP endpoints. By default they answer any request that
looks like a Metacontroller sync request, which means any pod that can reach the
webhook port can drive your controller — and in controllers that re-render
existing child Secrets, can read credentials.
Metatron ships two opt-in middleware for the two things that matter most:
use Metatron::Middleware::BodyLimit # rejects bodies over 1 MiB with a 413
use Metatron::Middleware::Auth # requires the Bearer token shared with MetacontrollerBoth are configurable: METATRON_AUTH_SECRET (leave it unset and the auth
middleware stays inert) and METATRON_MAX_REQUEST_BODY_BYTES (1 MiB by default,
which is generous for sync payloads). See the
User Guide
for the full setup, including the webhook.authorization.secretRef half of the
handshake on the Metacontroller side.
Errors raised inside sync, customize, or finalize are caught and returned
as generic JSON 500 problem documents, with the details written to
Metatron.logger. Do not add Rack::ShowExceptions to a production stack.
If a controller implements calculate_sync_etag or
calculate_customize_etag, enable ETag handling on the Metacontroller webhook
(etag.enabled: true). Metatron answers a matching If-None-Match request
with 304 Not Modified, which Metacontroller uses to replay its cached
response instead of re-rendering unchanged children.
Unit tests run without any cluster dependencies:
bundle exec rake specThe cluster-backed integration suite runs Metatron against a real
Metacontroller installation in a throwaway k3d cluster. It
requires Docker, k3d, and kubectl:
bundle exec rake integrationSee the Contributing Guide for version overrides and debugging options.
If you're interested in contributing to Metatron, please see the Contributing Guide in the repository! Be sure to check out the Code of Conduct as well!