From 104a2fa1a1397f6103dc50474b51cb9f893d1c90 Mon Sep 17 00:00:00 2001 From: Gaurav Mehta Date: Wed, 28 Aug 2024 15:17:02 +1000 Subject: [PATCH] addon development guide (#628) * addon development guide * include feedback from Kiefer * renamed addon to add-on to better reflect upcoming ui changes: https://github.com/harvester/dashboard/pull/1110 * Apply suggestions from code review include feedback for PR review. Co-authored-by: Jillian <67180770+jillian-maroket@users.noreply.github.com> * Update docs/developer/addon-development.md Co-authored-by: Alexandra Settle --------- Co-authored-by: Jillian <67180770+jillian-maroket@users.noreply.github.com> Co-authored-by: Alexandra Settle --- docs/developer/_category_.json | 10 +- docs/developer/addon-development.md | 67 +++++++ docs/developer/developer-mode-installation.md | 173 ------------------ 3 files changed, 70 insertions(+), 180 deletions(-) create mode 100644 docs/developer/addon-development.md delete mode 100644 docs/developer/developer-mode-installation.md diff --git a/docs/developer/_category_.json b/docs/developer/_category_.json index 26b42505e78..4d6123c19a3 100644 --- a/docs/developer/_category_.json +++ b/docs/developer/_category_.json @@ -1,10 +1,6 @@ { "position": 18, - "label": "Developer", - "collapsible": false, - "collapsed": false, - "link": { - "type": "doc", - "id": "developer-mode-installation" - } + "label": "Development Guides", + "collapsible": true, + "collapsed": true } diff --git a/docs/developer/addon-development.md b/docs/developer/addon-development.md new file mode 100644 index 00000000000..f66e56a0ff4 --- /dev/null +++ b/docs/developer/addon-development.md @@ -0,0 +1,67 @@ +--- +id: Add-on-development-guide +title: "Add-on Development Guide" +sidebar_position: 1 +sidebar_label: Add-on Development Guide +keywords: + - Harvester + - harvester + - Add-on Development +Description: How to write your own Harvester add-on +--- + +Harvester add-ons allow you to enable and disable specific Harvester and third-party components based on your requirements. Add-ons function as a wrapper for the [RKE2 HelmChart resource definition (CRD)](https://docs.rke2.io/helm#using-the-helm-crd). + + +## Prerequisites + +- An existing Harvester cluster + +## Add-on Specifications + +The `Addon` CRD supports the following fields: + +```yaml +apiVersion: harvesterhci.io/v1beta1 +kind: Addon +metadata: + name: example-add-on # Name of add-on + namespace: example-namespace # Namespace where the add-on CRD is deployed and where the associated Kubernetes components will be deployed + labels: # Optional add-on labels + Add-on.harvesterhci.io/experimental: "true" # Predefined label used on the Harvester UI to identify add-ons with the "experimental" maturity level +spec: + enabled: false # Boolean indicating if an add-on should be enabled or disabled on definition + repo: https://chartsrepo.com # Helm chart repository containing the Helm chart managed by the add-on + version: "v0.19.0" # Version of the Helm chart to be installed + chart: mychart # Name of the Helm chart in the Helm chart repository + valuesContent: |- # File (values.yaml) that must be passed to the Helm chart + contents of values.yaml + that need to be passed + to the chart +``` + +:::note + +Experimental add-ons are not directly packaged in Harvester. An example is the [rancher-vcluster](https://github.com/harvester/experimental-addons/blob/main/rancher-vcluster/rancher-vcluster.yaml) add-on. + +::: + +## Installation + +```bash +kubectl apply -f /path/to/add-on.yaml +``` + +## Usage + +After creating an `Addon` CRD, you can can toggle the `enabled` field to enable and disable the associated Helm chart. + +## Upgrade + +Changes to the `repo`, `version`, `chart` or `valueContent` fields will trigger a `helm upgrade`, which forces an upgrade of the existing Helm chart. + +## Uninstallation + +```bash +kubectl delete -f /path/to/Add-on.yaml +``` diff --git a/docs/developer/developer-mode-installation.md b/docs/developer/developer-mode-installation.md deleted file mode 100644 index 92446183251..00000000000 --- a/docs/developer/developer-mode-installation.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -id: developer-mode-installation -title: "Developer Mode Installation" -sidebar_position: 1 -sidebar_label: Developer -keywords: - - Harvester - - harvester - - Rancher - - rancher - - Developer Mode Installation -Description: Developer mode (dev mode) is intended to be used for testing and development purposes. ---- - -# Developer Mode - -:::caution attention - -Developer mode is intended to be used for development and testing purposes. Usage of this mode in production environments is not supported. - -::: - -## Prerequisites - -- The node has passed the [host-check](https://raw.githubusercontent.com/harvester/harvester/master/hack/host-check.sh) -- Helm 3 and Git are installed on your local machine. - -## Installation of the First Node - -You can install Harvester on an [RKE2](https://docs.rke2.io/) cluster using the [Helm](https://helm.sh/) CLI. For more information about installing and configuring the Harvester Helm chart, see the [readme](https://github.com/harvester/harvester/blob/master/deploy/charts/harvester/README.md). - -1. Create an RKE2 configuration file. - ```bash - sudo mkdir -p /etc/rancher/rke2 - cat <:9345 - token: token - EOF - ``` - -1. Install the RKE2 agent. - ```bash - curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sudo sh - - sudo systemctl enable rke2-agent.service --now - ``` - -## Uninstallation - -```bash -sudo /usr/local/bin/rke2-uninstall.sh -```