@kinvolk/headlamp-plugin
Version:
The needed infrastructure for building Headlamp plugins.
118 lines (89 loc) • 4.52 kB
Markdown
# App Catalog
This plugin adds an app catalog to Headlamp, powered by ArtifactHub and Helm.
## About the App Catalog
This plugin enables the ability to install Helm charts from artifacthub directly within Headlamp.
_Note: By default, the App Catalog plugin has its filter set to "Official". This can be changed by navigating to the settings page using the `Settings` button to the right of the title bar._
## Developing Headlamp Plugins
### Setting up the Environment
1. Run the Headlamp app from the main branch:
- In a terminal window use:
```bash
cd headlamp-k8s/headlamp/app
npm install
npm start
```
2. Set up the App Catalog:
- In a new terminal window, use:
```bash
cd headlamp-k8s/plugins/app-catalog
npm install
npm start
```
3. Ensure the App Catalog is enabled
- From within Headlamp, navigate to the `Settings` page via the sidebar or the gear icon in the top right corner.
- Select the `Plugins` tab located in the sidebar.
- Enable the App Catalog plugin by toggling the switch to the right of the menu.
- Navigate back to the main page of your cluster.
After completing these steps, you'll see the App Catalog link in the sidebar.
## App Catalog supported labels and annotations
The App-Catalog plugin in Headlamp discovers and lists application catalogs by scanning Kubernetes Service resources.
To be recognized as a catalog source, the Service must include specific labels and annotations that describe how the plugin should interact with it.
Catalogs can be either:
- External sources
- Internal in-cluster helm repositories or custom chart services
| Label | Description |
| ------------------------------- | ------------------------------------------------------------------------ |
| catalog.headlamp.dev/is-catalog | Indicates that this Service should be treated as an application catalog. |
| Annotaion | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| catalog.headlamp.dev/name | Internal identifier for the catalog. It'll be used as displayName if `displayName` is empty. |
| catalog.headlamp.dev/protocol | Specifies the catalog API protocol. Supported values are helm (for in-cluster service, artifacthub (for external service) |
| catalog.headlamp.dev/displayName | (optional) User-friendly display name shown in UI. |
| catalog.headlamp.dev/uri | URL or endpoint used to fetch catalog data. For external catalogs, this must be a valid HTTP(S) URL. |
### Sample external-service to access artifacthub.io
```yaml
apiVersion: v1
kind: Service
metadata:
name: artifacthub-catalog
namespace: artifacthub
labels:
catalog.headlamp.dev/is-catalog: ''
annotations:
catalog.headlamp.dev/name: artifacthub-catalog
catalog.headlamp.dev/protocol: artifacthub
catalog.headlamp.dev/uri: https://artifacthub.io
spec:
type: ExternalName
externalName: artifacthub.io
ports:
- name: http
port: 80
targetPort: 80
protocol: TCP
```
### Sample in-cluster service to access catalog running in-cluster
```yaml
apiVersion: v1
kind: Service
metadata:
name: demo-catalog
namespace: test-catalog
labels:
catalog.headlamp.dev/is-catalog: ''
annotations:
catalog.headlamp.dev/name: demo-catalog
catalog.headlamp.dev/protocol: helm
catalog.headlamp.dev/displayName: My demo catalog
spec:
type: NodePort
ports:
- name: http
port: 80
targetPort: 80
protocol: TCP
```
## Contributing
We welcome contributions! If you have ideas for improvements or encounter any issues, please open an issue or submit a pull request on our [GitHub repository](https://github.com/headlamp-k8s/plugins).