Skip to content
jgnagyPublic

About

Metatron: a ruby gem for creating kubernetes metacontrollers

Topics

Resources

Code of conduct

Contributing

Stars

15 stars

Watchers

2 watching

Forks

Repository files navigation

Metatron

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!

Security

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 Metacontroller

Both 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.

ETags

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.

Development

Unit tests run without any cluster dependencies:

bundle exec rake spec

The 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 integration

See the Contributing Guide for version overrides and debugging options.

Contributing

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!

About

Metatron: a ruby gem for creating kubernetes metacontrollers

Topics

Resources

Code of conduct

Contributing

Stars

15 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages