Skip to content

Repository files navigation

Headlamp Plugins Repository

This repository contains various plugins for Headlamp, a Kubernetes web UI. The plugins extend Headlamp's functionality for specific use cases.

Available Plugins

  • SSA Inspector: Inspect Apply/Update field ownership on Kubernetes resource detail pages, with any manager and optional status ownership.

  • Flux: Flux GitOps dashboard, list statistics and interactive Kustomization/HelmRelease inventory diagrams.

  • cert-manager: Certificate renewal and creation, expiry visibility, issuer health and interactive issuance relationship diagrams.

  • Velero: Manage backups, schedules, storage and restores; inspect archives, compare objects, and recover individual resources.

  • Bookmarks: Star navigation rows and resource pages, then pin those shortcuts to the top of the sidebar.

  • Shell: In-browser kubectl shell. The OIDC client and shell image come from buttah-shell-config/config.json.

  • Kubeconfig: Download a kubeconfig. The server and OIDC client come from buttah-kubeconfig-config/config.json.

  • Cleaner: Manage k8s-cleaner policies, latest reports, Lua selectors, manual runs, and rollback. Includes a live development workflow for kind.

  • KubeVirt: Adds support for managing KubeVirt resources like Virtual Machines and Instances.

  • Web Proxy: (Placeholder - under development)

Releases

Pull requests and pushes to main validate every plugin using Capsule's shared headlamp-test action, following the approach in projectcapsule/change-windows. These builds do not publish anything.

Pushing a tag such as v0.1.0 releases all nine plugins at version 0.1.0. The workflow stamps the package and lockfile versions in its checkout, including Flux's local SSA dependency; it does not commit these changes back to the source branch. All plugin checks must pass before publication starts.

Plugin Release archive Container image Plugin directory in image
cert-manager headlamp-k8s-cert-manager-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/cert-manager /plugins/headlamp_cert-manager
Cleaner cleaner-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/cleaner /plugins/cleaner
Flux headlamp-k8s-flux-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/flux /plugins/headlamp_flux
KubeVirt kubevirt-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/kubevirt /plugins/kubevirt
SSA Inspector ssa-inspector-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/ssa /plugins/ssa-inspector
Velero velero-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/velero /plugins/velero
Bookmarks buttah-bookmarks-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/buttah-bookmarks /plugins/buttah-bookmarks
Shell buttah-shell-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/buttah-shell /plugins/buttah-shell
Kubeconfig buttah-kubeconfig-<version>.tar.gz ghcr.io/buttahtoast/headlamp-plugins/buttah-kubeconfig /plugins/buttah-kubeconfig

The workflow packages the checked bundles once and uses those artifacts for the GitHub release and the linux/amd64 and linux/arm64 container images. Images are tagged with the version, the full Git tag, and sha-<commit>. Stable versions also update latest; prerelease tags such as v0.1.0-rc.1 create GitHub prereleases without changing latest.

After every image succeeds, the workflow publishes one GitHub release containing all plugin archives and SHA256SUMS. Capsule's shared headlamp-publish action then publishes versioned Artifact Hub metadata on the artifacthub branch, reusing the released archives. Metadata writes run one at a time. Register that branch in Artifact Hub; the root artifacthub-repo.yml supplies repository ownership. Each plugin's artifacthub.template.yml supplies its catalog description.

Commit and push the plugin sources and workflow before tagging:

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

Use a new version for changes to an already published release. If publication fails while the release is still a draft, rerun failed jobs. If only the Artifact Hub step fails, rerun that step to reuse the existing release archives.

Installing Plugins

In-Cluster

In an In-Cluster scenario, you can install plugins in two ways.

initContainer

Use an initContainer to copy built plugins from a custom image to a shared volume mounted in the Headlamp container.

initContainers:
  - name: headlamp-plugins
    image: ghcr.io/buttahtoast/headlamp-plugins/flux:0.1.0
    command: ["/bin/sh", "-c", "cp -r /plugins/* /build/plugins/"]
    volumeMounts:
      - name: headlamp-plugins
        mountPath: /build/plugins
volumes:
  - name: headlamp-plugins
    emptyDir: {}
volumeMounts:
  - name: headlamp-plugins
    mountPath: /build/plugins
config:
  pluginsDir: /build/plugins

Image Volume

Mount plugins from a pre-built image using a volume and initContainer to copy files.

Desktop App

Headlamp Desktop app supports installing plugins via the Plugin Catalog.

  1. Start the Headlamp app.
  2. Click on "Plugin Catalog" in the sidebar.
  3. Search for the desired plugin and install it.

For more details, refer to the official documentation.

Contact

For questions or feedback, open an issue on the GitHub repository.

Releases

Packages

Used by

Contributors

Languages