Skip to content

Argo CD Plugin for Headlamp 0.1.0-alpha

Latest
Latest

Choose a tag to compare

View all tags
@illume illume released this 11 Aug 12:46
· 233 commits to main since this release
argocd-0.1.0-alpha
fe8b918

First public release. This release introduces native Argo CD visibility and Kubernetes-native operations inside Headlamp. Feedback and bug reports are welcome.

About

Argo CD is a declarative GitOps continuous delivery tool for Kubernetes. It continuously compares the desired state stored in Git with the live state in a Kubernetes cluster, then reports drift and can synchronize the Application when needed. Argo CD uses Kubernetes custom resources such as Application and AppProject to describe Git sources, deployment destinations, sync policies, and access boundaries.

Headlamp is an open-source, extensible Kubernetes web UI. Its plugin system lets Kubernetes projects add sidebar navigation, routes, resource models, list views, detail views, and actions that feel native to the rest of the interface.

Without this plugin, an operator often has to move between Headlamp, the Argo CD UI, and kubectl to understand how an Application is configured, what it manages, whether it is healthy, and what changed during previous deployments.

The Argo CD plugin brings that GitOps context into Headlamp. It provides Application and AppProject views, GitOps-focused Application details, managed-resource navigation, sync history, namespace-level GitOps insights, and Kubernetes-native Sync and Refresh actions that follow the user’s existing Kubernetes RBAC permissions.

Demo

0806.1.1.-compressed.mp4

What This Plugin Does

The Argo CD plugin for Headlamp adds native views for Argo CD resources inside the Headlamp dashboard.

You can browse Argo CD Applications and AppProjects, inspect Git sources and deployment destinations, view managed Kubernetes resources, understand sync policy, review sync history, and open supported managed resources directly in Headlamp.

The plugin also provides Kubernetes-native Sync and Refresh actions. These actions use the Kubernetes API and respect the user’s existing Kubernetes RBAC permissions.

Highlights

  • Argo CD Application list and detail views inside Headlamp.
  • Argo CD AppProject list and detail views.
  • GitOps Summary with source, revision, path, destination, sync, health, and project details.
  • Managed Resources table with sync and health information.
  • Native links from managed resources to supported Headlamp resource detail pages.
  • Sync Policy view for automated sync, self-heal, prune, retry settings, and sync options.
  • Sync History view based on the Argo CD Application status history.
  • Namespace GitOps Insights for Applications stored in or deploying to a Namespace.
  • Kubernetes-native Sync and Refresh actions.
  • RBAC-aware action visibility.
  • Argo CD CRD detection so the sidebar stays hidden when Argo CD is not installed.

Why This Plugin Matters

Argo CD operators need to understand both the GitOps configuration and the live Kubernetes resources created from it.

Without this plugin, that information is split across the Argo CD UI, Headlamp, and kubectl. The plugin brings those views together in Headlamp while keeping the workflow Kubernetes-native.

This helps operators:

  • See what Git source is driving an Application.
  • See where an Application deploys.
  • Inspect the Kubernetes resources managed by Argo CD.
  • Understand whether sync is automated or manual.
  • Review previous deployment revisions.
  • Navigate from GitOps information to live Kubernetes resources.
  • Use Sync and Refresh actions only when Kubernetes RBAC allows them.

Contributors

This plugin was created as part of the Linux Foundation Mentorship program and developed with review and guidance from the Headlamp community.

Contributor Role
@Joshna907 Plugin design, implementation, UI/UX decisions, documentation, testing, and demo preparation
@illume Maintainer review, technical guidance, and project mentorship
@ashu8912 Technical review and usability feedback
headlamp-k8s Maintainers and community

Thank you to the Headlamp maintainers and reviewers for helping shape the plugin through implementation feedback and review.

Installation

Build the plugin from source:

git clone https://github.com/headlamp-k8s/plugins
cd plugins/argocd
npm install
npm run build

Requirements

  • Headlamp Desktop or an in-cluster Headlamp installation.
  • Node.js v20.11.1 or later (required to build from source).
  • A Kubernetes cluster reachable from Headlamp.
  • Argo CD installed in the cluster with the Application and AppProject CRDs.
  • Kubernetes permissions to get, list, and watch Argo CD resources.
  • To use Sync and Refresh, your Kubernetes RBAC role also requires patch permission on Argo CD Application resources.

Compatibility

Component Compatibility
Plugin @headlamp-k8s/argocd v0.1.0-alpha
Headlamp Plugin Runtime @kinvolk/headlamp-plugin ^0.14.0
Argo CD Any installation exposing the argoproj.io/v1alpha1 Application and AppProject APIs
Kubernetes Any cluster reachable through Headlamp where Argo CD is installed
Node.js v20.11.1+ (required for building from source)

The plugin was tested with Argo CD running on a local kind cluster using Docker Desktop.

Features

Navigation and Sidebar

The plugin adds an Argo CD section to the Headlamp sidebar with dedicated Applications and Projects pages.

The sidebar uses Argo CD CRD detection. If the cluster does not have the Argo CD Application and AppProject CustomResourceDefinitions installed, the Argo CD navigation entries stay hidden. This keeps Headlamp clean on clusters where Argo CD is not used.

Image

Applications

The Applications page is the main GitOps overview. It shows Argo CD Applications directly inside Headlamp.

Each row shows the information an operator needs first:

  • Application name.
  • Project.
  • Source repository and target revision.
  • Application namespace and destination namespace.
  • Sync and health status.
  • Age and available actions.
Image
Related information is grouped together so that the table stays easier to scan when there are many Applications.

Application Detail and GitOps Summary

Each Application has a dedicated detail page. The GitOps Summary brings the most useful configuration and status information into one place:

  • Repository source.
  • Target revision.
  • Path or chart.
  • Deployment destination.
  • Argo CD project.
  • Sync state.
  • Health state.
Image
This gives an operator the key GitOps context before they need to inspect raw YAML.

Managed Resources

The Managed Resources section shows the Kubernetes API resources controlled by an Argo CD Application.

It includes:

  • Resource kind.
  • Resource name.
  • Namespace.
  • API version.
  • Sync status.
  • Health status.
Image
The page also displays sync and health distribution summaries, which become more useful when an Application manages many resources.

Supported resource names are clickable. For example, an operator can open a managed Deployment or Service directly in Headlamp’s Kubernetes resource detail view.

Sync Policy

The Sync Policy section explains how an Application behaves after Git changes are detected.

It shows:

  • Whether automated sync is enabled.
  • Whether self-heal is enabled.
  • Whether prune is enabled.
  • Whether empty Applications are allowed.
  • Retry configuration.
  • Configured sync options.

This makes it clear whether an Application is handled automatically or requires manual intervention.

Sync History

The Sync History section shows previous Argo CD deployment operations from the Application status history.

It includes:

  • Revision.
  • Deployment time.
  • Start time.
  • Source.
  • Initiator.
Image

This provides a lightweight deployment audit trail inside Headlamp.

AppProjects

The plugin also provides list and detail views for Argo CD AppProjects.

An AppProject defines the boundaries for Applications. Its detail page shows:

  • Allowed source repositories.
  • Allowed deployment destinations.
  • Cluster resource whitelist.
  • Project roles.
  • Basic project metadata.
Image


Image

This helps operators understand which repositories and clusters an Application is allowed to use.

Namespace GitOps Insights

The plugin extends Headlamp’s built-in Namespace detail page with a GitOps Insights section.

An Argo CD Application can be stored in the argocd Namespace while deploying workloads into another Namespace. This section helps explain that relationship.

It shows:

  • Applications stored in the current Namespace.
  • Applications deploying into the current Namespace.
  • Applications that need attention.
  • Sync and health state for related Applications.
Image

Kubernetes-native Sync and Refresh Actions

The plugin provides Sync and Refresh actions without depending on the Argo CD REST API or an Argo CD session token.

  • Sync patches the Application operation through the Kubernetes API.
  • Refresh applies the Argo CD refresh annotation through the Kubernetes API.
  • Both actions use the user's existing Kubernetes RBAC permissions.
  • If the user does not have patch permission for Applications, the actions are hidden.

This keeps Argo CD operations aligned with Kubernetes-native access control.

Changelog

Major features

  • Added the initial Argo CD plugin scaffold and sidebar navigation.
  • Added native Argo CD Application list and detail views.
  • Added native Argo CD AppProject list and detail views.
  • Added GitOps Summary to the Application detail page.
  • Added Managed Resources with sync and health information.
  • Added native Headlamp links for supported managed Kubernetes resources.
  • Added Sync Policy and Sync History sections.
  • Added Namespace GitOps Insights to the built-in Headlamp Namespace detail page.
  • Added Kubernetes-native Sync and Refresh actions.
  • Added RBAC-aware visibility for Sync and Refresh actions.
  • Added Argo CD CRD detection to hide plugin navigation when Argo CD is not installed.
  • Added support for multi-source Applications.

Key improvements

  • Grouped source, revision, namespaces, sync state, and health state in the Applications list for easier scanning.
  • Added clear sync and health status badges across Application views.
  • Added loading states and success or error feedback for Sync and Refresh operations.
  • Added unit tests for Kubernetes-native Sync and Refresh API operations.
  • Added documentation for required Kubernetes RBAC permissions.
  • Added resource model typings for Application sync history, managed resources, sync policy, multi-source configuration, and AppProject settings.
  • Added the official Argo CD icon to the Headlamp sidebar.

Foundation

  • Initial plugin scaffold and sidebar navigation: #806
  • Application CRD model and list view: #848
  • CRD guard, RBAC-aware actions, AppProjects, and enhanced Application detail: #906
  • Namespace GitOps Insights: #929
  • Application list readability improvements: #930
  • Application detail GitOps observability: #931

Known Limitations

  • The plugin supports Sync and Refresh operations, but it does not provide a dedicated Argo CD Application creation workflow.
  • Sync and Refresh operate through the Kubernetes API. The plugin does not use the Argo CD REST API or Argo CD session tokens.
  • A managed resource can only link to a Headlamp detail page when Headlamp recognizes the resource kind and the resource belongs to the selected cluster.
  • Applications targeting a different remote cluster cannot safely link to that cluster’s Headlamp resource page yet.
  • Managed-resource health is shown from the Argo CD Application status. If Argo CD reports a resource health state as Unknown, the plugin preserves that state.
  • The plugin does not replace the full Argo CD UI. Advanced Argo CD workflows and settings remain available through Argo CD itself.

What's Next

Possible next areas for the plugin include:

  • Create and edit workflows designed specifically for Argo CD Applications and AppProjects.
  • More detailed Application conditions and operation status views.
  • Better visibility for Applications that deploy to remote clusters.
  • Additional filtering and bulk workflows for large Application inventories.
  • More GitOps context in other relevant Headlamp resource pages.
  • Continued usability improvements based on feedback from Headlamp and Argo CD users.

Feedback

This is the first public release of the Argo CD plugin for Headlamp. Feedback, bug reports, and feature ideas are welcome.

Bug reports: Open an issue

Feature requests: Start a discussion

Contributing: Pull requests are welcome. See the repository contribution guidance.

Plugin source: headlamp-k8s/plugins/argocd

License: Apache 2.0

Assets 3
Loading