Brewlet

Run applications from OCI artifacts using runtimes managed once on a
Kubernetes node pool.
Brewlet moves language runtimes into infrastructure, alongside the operating
system and Kubernetes. Developers publish application code, dependencies and
explicit launch metadata as standard OCI artifacts. Platform teams approve
digest-pinned runtime images and control which node pools provide them.
Kubernetes schedules each workload onto a compatible node, and containerd starts
it through the Brewlet runtime shim.
This separates application delivery from runtime maintenance. Platform teams can
rotate approved runtimes without rebuilding application artifacts, while
developers retain explicit control over their application's command and
dependencies. Java, Python, Node.js and .NET use the same language-neutral
contract; Java project intelligence belongs only to the optional Maven producer.
This repository contains the complete Brewlet implementation: the CLI and
runtime, Kubernetes platform, node provisioner, Maven plugin, specifications,
integration tests, website, and user-facing documentation.
Project status
[!IMPORTANT]
All 0.x releases are betas and are not stable. They can break or change
incompatibly between versions. General availability (GA)
will be 1.0.0.
Brewlet is a clean-slate, pre-GA implementation under active development.
Beta releases are published on
GitHub Releases. Evaluate them
in a disposable environment, not a production or shared cluster. Do not
substitute the 0.x CLI, chart, artifact format or runbooks.
The acceptance ledger records scoped successful
local evidence for the current requirements. This is not cloud-provider autoscaling
certification, physical alternate-architecture hardware qualification, or proof
of a published stable release. Unit and cross-compilation results remain
distinct from real-node evidence. See the
exact sources, commands and results and
verification boundaries.
How it works
Platform operator Developer
----------------- ---------
RuntimeImage: approved runtime Application + dependencies
source pinned to an OCI digest + explicit launch.json
NodeProfile: placement and policy packaged as an OCI artifact
| |
v v
+----------------------------+ +----------------------------+
| Node provisioner | | OCI registry |
| installs the shim and | | application layers under |
| approved runtime roots | | /app and launch metadata |
+-------------+--------------+ +-------------+--------------+
| |
| v
| +----------------------------+
| | Admission webhook |
| | validates the explicit |
| | runtime ID and placement |
| +-------------+--------------+
| |
| runtimeClassName: brewlet
| runtime-image.brewlet.sh/<container-name>: ID
| |
v v
+----------------------------------------------------------------+
| Brewlet-enabled node |
| containerd -> Brewlet shim -> approved node-resident runtime |
+--------------------------------+-------------------------------+
v
Application
- The platform operator approves
RuntimeImage inventory with digest-pinned
sources and defines placement and installation policy through NodeProfile
resources.
- The node provisioner installs and validates the containerd shim and runtime
roots, advertises capabilities, and removes the startup fence only when the
node is ready. OnDemand policy can defer fetching a root until first use.
- The developer packages application files confined to
/app,
with an explicit, language-neutral launch.json, and publishes the artifact.
- An ordinary Kubernetes workload selects the Pod-wide
runtimeClassName: brewlet and explicitly selects a runtime for each managed
container with the Pod annotation
runtime-image.brewlet.sh/<container-name>: <id>. Unselected containers
keep ordinary OCI behavior. Admission validates selections and joint
placement; Kubernetes schedules the Pod onto a compatible node.
- The shim assembles the application's OCI bundle and launches it with the
selected runtime generation. Running tasks retain that generation across
rotations.
There is no language detection, default runtime selection, JVM flag injection,
JavaApplication resource, or 0.x compatibility. The shared RuntimeClass reserves
64Mi memory and 50m CPU per pod for shim and staging overhead, not for the
language runtime. Workload requests and limits must cover the entire application
process, including its interpreter or VM.
Subprojects
| Subproject |
Path |
Responsibility |
| Core runtime |
cmd/, pkg/, shim/ |
Provides the Brewlet CLI, artifact tooling, shared runtime packages, and containerd Runtime v2 shim. |
| Node provisioner |
provisioner/ |
Installs, rotates and safely removes approved runtime roots, the shim and owned containerd configuration on Linux nodes. |
| Kubernetes platform |
kubernetes/ |
Provides the operator, admission webhook, RuntimeImage and NodeProfile APIs, manifests, RBAC, and Helm chart. |
| Maven plugin |
maven-plugin/ |
Packages Java applications through the language-neutral CLI; it does not deploy workloads. |
| Specifications |
specs/ |
Defines the authoritative architecture, artifact formats, runtime contracts, APIs, and compatibility rules. |
| Integration tests |
integration-tests/ |
Exercises application producers, runtime execution, Kubernetes placement, provisioning, rotation and cleanup. |
| Acceptance |
acceptance/ |
Tracks requirements, scoped evidence, and strict promotion qualification. |
| Website |
site/ |
Contains the static landing page, branding assets, and searchable MkDocs documentation preview. |
| User documentation |
docs/ |
Contains installation, configuration, operations, workload deployment, and troubleshooting guidance. |
Quick start
Install the CLI
curl -fsSL https://brewlet.sh/install.sh | sh
brewlet version
See the CLI reference for commands and artifact options.
Run your first Kubernetes application
Follow the local Kubernetes tutorial to create a new
disposable kind cluster, install released components, run a real Python HTTP
application, rotate its runtime without rebuilding the application, and remove
the installation normally. The tutorial uses a private kubeconfig and does not
require host Java, Node.js or .NET toolchains.
Nodes require Linux, containerd 2.x, runc, cgroup v2 and the supported host layout.
Provisioning is privileged and modifies host configuration. The
installation guide covers explicitly selected pools,
reviewed component images, CRDs, chart installation and runtime approval.
Installing the chart alone does not provision a runtime or prove that an
application can start.
Do not run installation or acceptance commands against an unspecified current
Kubernetes context. Follow safe removal before
uninstalling or reinstalling; do not bypass cleanup finalizers.
Publish application artifacts
brewlet build REF validates and packages a Brewlet application into a local
OCI layout (.brewlet/images/<REF> unless --store is given). brewlet push REF
then publishes that build. push also publishes an existing OCI layout given
with --store DIR without changing its bytes or digests; use --source to
select a local reference or SHA-256 digest when the layout has several roots.
push verifies blob identities, not Brewlet launch or layer policy; consumers
still validate the artifact.
The launch schema accepts optional top-level runtimeImages; the former
requires wrapper is rejected. See application packaging
and the language recipes for explicit launch examples.
Registry clients honor SSL_CERT_FILE for an additional trusted CA and
origin-bound BREWLET_REGISTRY_USERNAME / BREWLET_REGISTRY_PASSWORD credentials.
Use --registry-scheme https for a TLS-enabled loopback registry. TLS verification
remains enabled; --insecure explicitly selects HTTP instead. See
registry trust for configuration.
Contributing and support
Use GitHub Issues for bugs and
feature requests. See the contributing guide for building
from source, running tests, and contribution expectations.
Releases
Brewlet is pre-GA. release.json defines the release
identity. Every 0.x release (0.8.0 onward previews the 1.0.0 line) is a beta:
published as the latest GitHub release, but not stable and free to break or pivot.
GA will be 1.0.0.
| Artifact |
Intended location |
| CLI archives and checksums |
GitHub releases |
| Operator image |
ghcr.io/microsoft/brewlet-operator:VERSION |
| Admission webhook image |
ghcr.io/microsoft/brewlet-admission:VERSION |
| Node provisioner and shim image |
ghcr.io/microsoft/brewlet-node-provisioner:VERSION |
| Helm chart |
oci://ghcr.io/microsoft/charts/brewlet |
| Optional Maven producer |
sh.brewlet:brewlet-maven-plugin:VERSION |
Targets are Linux and macOS amd64/arm64 for the CLI and Linux
amd64/arm64 for component images. Pushing a vVERSION tag on a commit that
passed CI on main builds, verifies and publishes every artifact automatically.
See the maintainer release checklist, the
release distribution runbook and the
compatibility policy.
The current rewrite is inspired by Brewlet 0.x at
fa7085335b220e29df6affbece4558c5f1259ecb; its specification, label contract
and runbooks are not carried forward. See reference provenance.
License
Brewlet is licensed under the MIT License.
Third-party software
Brewlet builds on third-party open source software. The repository-level
NOTICE.txt indexes the notices for each built artifact and the
commands that generate them. CLI archives, images, JARs, the chart and the
website preview carry their applicable legal resources. See the
third-party notice documentation for locations
and verification.
Trademarks
This project may contain trademarks or logos for projects, products, or
services. Authorized use of Microsoft trademarks or logos is subject to and
must follow Microsoft's Trademark & Brand
Guidelines.
Use of Microsoft trademarks or logos in modified versions of this project must
not cause confusion or imply Microsoft sponsorship. Any use of third-party
trademarks or logos are subject to those third-party's policies.