diff --git a/docs/img/chartrepo/chart_dependencies.png b/docs/img/chartrepo/chart_dependencies.png new file mode 100644 index 000000000..bc19cd0b8 Binary files /dev/null and b/docs/img/chartrepo/chart_dependencies.png differ diff --git a/docs/img/chartrepo/chart_details.png b/docs/img/chartrepo/chart_details.png new file mode 100644 index 000000000..132994512 Binary files /dev/null and b/docs/img/chartrepo/chart_details.png differ diff --git a/docs/img/chartrepo/chart_values.png b/docs/img/chartrepo/chart_values.png new file mode 100644 index 000000000..26e7b379b Binary files /dev/null and b/docs/img/chartrepo/chart_values.png differ diff --git a/docs/img/chartrepo/list_chart_versions.png b/docs/img/chartrepo/list_chart_versions.png new file mode 100644 index 000000000..ec515717c Binary files /dev/null and b/docs/img/chartrepo/list_chart_versions.png differ diff --git a/docs/img/chartrepo/list_charts.png b/docs/img/chartrepo/list_charts.png new file mode 100644 index 000000000..92bbdbc02 Binary files /dev/null and b/docs/img/chartrepo/list_charts.png differ diff --git a/docs/img/chartrepo/upload_charts.png b/docs/img/chartrepo/upload_charts.png new file mode 100644 index 000000000..f817c2903 Binary files /dev/null and b/docs/img/chartrepo/upload_charts.png differ diff --git a/docs/user_guide.md b/docs/user_guide.md index f5e232323..c0d79f89a 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -437,3 +437,116 @@ Kubernetes users can easily deploy pods with images stored in Harbor. The setti 1. When your Harbor instance is hosting http and the certificate is self signed. You need to modify daemon.json on each work node of your cluster, for details please refer to: https://docs.docker.com/registry/insecure/#deploy-a-plain-http-registry 2. If your pod references an image under private project, you need to create a secret with the credentials of user who has permission to pull image from this project, for details refer to: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ + +## Manage Helm Charts +Helm charts is a good way to package, share and use software built for Kubernetes. From version 1.6.0, Harbor is upgraded to be a composite cloud-native registry, which supports both image management and helm charts management. The charts are also isolated by projects and controlled by RBAC access control system. + +### Manage Helm Charts via portal +#### List charts +Click your project to enter the project detail page after successful logging in. The existing helm charts will be listed under the tab `Helm Charts` which is beside the image `Repositories` tab with the following information: +* Name of helm chart +* The status of the chart: Active or Deprecated +* The count of chart versions +* The created time of the chart + +![list charts](img/chartrepo/list_charts.png) + +You can click the icon buttons on the top right to switch views between card view and list view. + +#### Upload new chart +Click the `UPLOAD` button on the top left to open the chart uploading dialog. Choose the uploading chart from your filesystem. Click the `UPLOAD` button to upload it to the chart repository server. + +![upload charts](img/chartrepo/upload_charts.png) + +If the chart is signed, you can choose the corresponding provenance file from your filesystem and Click the `UPLOAD` button to upload them together at once. + +If the chart is successfully uploaded, it will be displayed in the chart list at once. + +#### List chart versions +Clicking the chart name from the chart list will show all the available versions of that chart with the following information: +* the chart version number +* the maintainers of the chart version +* the template engine used (default is gotpl) +* the created timestamp of the chart version + +![list charts versions](img/chartrepo/list_chart_versions.png) + +Obviously, there will be at least 1 version for each of the charts in the top chart list. Same with chart list view, you can also click the icon buttons on the top right to switch views between card view and list view. + +Check the checkbox at the 1st column to select the specified chart versions: +* Click the `DELETE` button to delete all the selected chart versions from the chart repository server. Batch operation is supported. +* Click the `DOWNLOAD` button to download the chart artifact file. Batch operation is not supported. +* Click the `UPLOAD` button to upload the new chart version for the current chart + +#### View chart version details +Clicking the chart version number link will open the chart version details view. You can see more details about the specified chart version here. There are three content sections: +* **Summary:** + * readme of the chart + * overall metadata like home, created timestamp and application version + * related helm commands for reference, such as `helm add repo` and `helm install` etc. +![chart details](img/chartrepo/chart_details.png) +* **Dependencies:** + * list all the dependant sun charts with 'name', 'version' and 'repository' fields +![chart dependencies](img/chartrepo/chart_dependencies.png) +* **Values:** + * display the content from `values.yaml` file with highlight code preview + * clicking the icon buttons on the top right to switch the yaml file view to k-v value pair list view +![chart values](img/chartrepo/chart_values.png) + +Clicking the `DOWNLOAD` button on the top right will start the downloading process. + +### Working with Helm CLI +As a helm chart repository, Harbor can work smoothly with Helm CLI. About how to install Helm CLI, please refer [install helm](https://docs.helm.sh/using_helm/#installing-helm). Run command `helm version` to make sure the version of Helm CLI is v2.9.1+. +``` +helm version + +#Client: &version.Version{SemVer:"v2.9.1", GitCommit:"20adb27c7c5868466912eebdf6664e7390ebe710", GitTreeState:"clean"} +#Server: &version.Version{SemVer:"v2.9.1", GitCommit:"20adb27c7c5868466912eebdf6664e7390ebe710", GitTreeState:"clean"} +``` +#### Add harbor to the repository list +Before working, Harbor should be added into the repository list with `helm repo add` command. Two different modes are supported. +* Add Harbor as a unified single index entry point + +With this mode, helm can aware all the charts located in the different projects which are accessable by the current authenticated user. +``` +helm repo add --ca-file ca.crt --cert-file server.crt --key-file server.key --username=admin --password=Passw0rd myrepo https://xx.xx.xx.xx/chartrepo +``` +**NOTES:** Providing both ca file and cert files is caused by an issue from helm. + +* Add Harbor project as separate index entry point + +With this mode, helm can only pull charts in the specified project. +``` +helm repo add --ca-file ca.crt --cert-file server.crt --key-file server.key --username=admin --password=Passw0rd myrepo https://xx.xx.xx.xx/chartrepo/myproject +``` + +#### Push charts to the repository server by CLI +As an alternative, you can also upload charts via the CLI. It is not supported by the native helm CLI. A plugin from the community should be installed before pushing. Run `helm plugin install` to install the `push` plugin first. +``` +helm plugin install https://github.com/chartmuseum/helm-push +``` +After a successful installation, run `push` command to upload your charts: +``` +helm push --ca-file=ca.crt --key-file=server.key --cert-file=server.crt --username=admin --password=passw0rd chart_repo/hello-helm-0.1.0.tgz myrepo +``` +**NOTES:** `push` command does not support pushing a prov file of a signed chart yet. + +#### Install charts +Before installing, make sure your helm is correctly initialized with command `helm init` and the chart index is synchronized with command `helm repo update`. + +Search the chart with the keyword if you're not sure where it is: +``` +helm search hello + +#NAME CHART VERSION APP VERSION DESCRIPTION +#local/hello-helm 0.3.10 1.3 A Helm chart for Kubernetes +#myrepo/chart_repo/hello-helm 0.1.10 1.2 A Helm chart for Kubernetes +#myrepo/library/hello-helm 0.3.10 1.3 A Helm chart for Kubernetes +``` +Everything is ready, install the chart to your kubernetes: +``` +helm install --ca-file=ca.crt --key-file=server.key --cert-file=server.crt --username=admin --password=Passw0rd --version 0.1.10 repo248/chart_repo/hello-helm +``` + +For other more helm commands like how to sign a chart, please refer to the [helm doc](https://docs.helm.sh/helm/#helm). +