microsoft/brewlet

Run Java applications from OCI artifacts using JDKs managed once on each Kubernetes node.

Brewlet separates the application from the Java runtime. Developers publish their JAR and launch metadata as a standard OCI artifact, while platform teams control the JDK distributions and launchers installed on each node. Kubernetes schedules the workload onto a compatible node and containerd starts it through the Brewlet runtime shim.

At fleet scale, this model is intended to lower the cost per Java workload, accelerate runtime security remediation, and reduce operational boilerplate for both developers and AI-assisted delivery workflows. It also gives platform teams a central control point for JDK policy, runtime optimization, and upgrades.

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.

Brewlet is a pre-1.0 preview. It is under active development, and its APIs, artifact formats, and operational behavior may change between minor releases. Evaluate it in a disposable environment, not a production or shared cluster.

• Documentation
• Getting started
• Ops workshop
• Developer workshop
• Latest release
• Specification
• Roadmap

 Platform operator                   Developer
 ─────────────────                   ─────────
 NodeProfile: approved JDKs          JAR + launch metadata,
 and launchers, pinned to            packaged by the CLI or
 OCI digests                         the Maven plugin
               │                                   │
               ▼                                   ▼
 ┌────────────────────────────┐      ┌────────────────────────────┐
 │ Node provisioner           │      │ OCI registry               │
 │ installs the shim and JDK  │      │ app JAR and launch spec,   │
 │ roots, labels the node     │      │ addressed by digest        │
 └─────────────┬──────────────┘      └─────────────┬──────────────┘
               │                                   │
               │                                   ▼
               │                     ┌────────────────────────────┐
               │                     │ Admission webhook          │
               │                     │ validates the pod runtime  │
               │                     │ and picks a capable node   │
               │                     └─────────────┬──────────────┘
               │                                   │
               │                       runtimeClassName: brewlet
               │                                   │
               ▼                                   ▼
 ┌────────────────────────────────────────────────────────────────┐
 │ Brewlet-enabled node                                           │
 │ containerd -> brewlet shim -> node-resident JDK                │
 └────────────────────────────────┬───────────────────────────────┘
                                  ▼
                           Java application

1. The platform operator installs Brewlet and defines the supported JDK and launcher inventory through one or more NodeProfile resources. Every runtime source is administrator-provided and pinned to an OCI SHA-256 digest.
2. The node provisioner installs the containerd shim and approved runtimes on matching nodes, then advertises their capabilities through node metadata.
3. The developer packages a Java application with the CLI or Maven plugin and publishes the resulting OCI artifact.
4. The admission webhook validates the runtime requirements and directs the pod to a compatible node.
5. The Brewlet shim assembles an OCI bundle and launches the application with the selected node-resident JDK.

The checksum-verifying installer selects the latest release's Linux or macOS archive and installs brewlet to $HOME/.local/bin. No Go toolchain or GitHub authentication is required:

curl -fsSL https://brewlet.sh/install.sh | sh -s -- --version latest --install-dir "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"
brewlet version

Change --version to pin a release or --install-dir to choose a different destination (and update PATH to match). See Getting started for the local application example and the CLI documentation for the artifact workflow.

For Brewlet development, build locally with Go 1.26+ instead:

git clone https://github.com/microsoft/brewlet.git
cd brewlet
make binaries
export PATH="$PWD/bin:$PATH"
brewlet version

Brewlet requires containerd 2.0+, cgroup v2, and permission to run a privileged host-modifying DaemonSet. Because that DaemonSet mutates the host, the chart has no every-node default or built-in JDK catalog: name the pools it may provision and choose the JDK source. Control-plane nodes are excluded by default; provisioner.includeControlPlane=true is an explicit opt-in for single-node development clusters.

Save this as my-jdks.yaml, replacing the placeholder with the full digest of an administrator-approved JDK image. Verify that the image supports your nodes' architectures and contains the given javaHome; this is a template, not an approved runtime catalog:

provisioner:
  jdks:
    - distribution: temurin
      feature: 21
      source:
        image: docker.io/library/eclipse-temurin@sha256:<64-lowercase-hex>
        javaHome: /opt/java/openjdk

Install the latest chart on your disposable cluster:

helm upgrade --install brewlet oci://ghcr.io/microsoft/charts/brewlet \
  --namespace brewlet \
  --create-namespace \
  --set provisioner.pools="{javaworkers}" \
  --values my-jdks.yaml

kubectl get nodes -L brewlet.sh/runtime
brewlet k8s doctor --namespace <developer-namespace>

Helm selects the latest chart when --version is omitted. Add --version x.y.z to pin a specific release instead; component images remain digest-pinned by the published chart.

Follow the installation guide for source-built component installation, pool labels, scoped node profiles, configuration, release replacement, and safe removal. Keep your reviewed values for reuse after adapting them to the target release. If GHCR denies an anonymous pull, see package access troubleshooting; package visibility is managed separately from repository visibility.

Development requires Go 1.26 or newer. Maven plugin development requires Maven 3.9+ and JDK 17+, while the optional AppCDS integration test requires a full JDK 17 or newer. Docker with Buildx is required for provisioner images.

Run all checks that do not require a Kubernetes cluster:

make check-all

This validates the core runtime, Kubernetes platform, Maven plugin, and host-only integration tiers. To build the CLI and shim into bin/:

make binaries

To run the full tiered integration harness against a suitable local cluster, see integration-tests/AGENTS.md.

Contributions are welcome. Read CONTRIBUTING.md for the development workflow and pull request requirements, and review the Microsoft Open Source Code of Conduct before participating.

Use GitHub Issues for bugs and feature requests. See SUPPORT.md for support expectations and SECURITY.md for confidential vulnerability reporting.

Brewlet is pre-GA. Compatibility policy defines the explicit promises and exceptions; release updates default to safe teardown/reinstallation, not in-place upgrades.

Before creating a release tag, update and commit the specification version to match the release. The release workflow checks this before publishing any artifacts.

Tags matching v* publish version-aligned artifacts:

Maven Central publishing requires the maven-central GitHub environment, Portal token credentials, and a PGP signing key. See the plugin publishing guide for setup and Central-only retries. Older GitHub releases are not automatically published to Central.

The Helm chart's appVersion selects matching component image tags by default. Release images support Linux amd64 and arm64; CLI archives support those architectures on Linux and macOS. Binary archives, JARs, images, and the published website carry their applicable third-party notices inside the artifact; container images also carry Microsoft's container legal notice.

Brewlet is licensed under the MIT License.

Brewlet builds on third-party open source software. The repository-level NOTICE.txt is an index: it lists the notices checked into this repository and the commands that regenerate the notices produced at build time, because each release artifact carries only the notices for the software it actually redistributes. See the third-party notice documentation for the same breakdown with the notice location in each artifact.

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.