From 9d921433b8f209356ecd6918c6fbf083f944101e Mon Sep 17 00:00:00 2001 From: Zuhair AlSader Date: Tue, 22 Nov 2022 16:31:21 -0500 Subject: [PATCH] Auto generate Helm chart docs (#19) * Use helm-docs * Move release instructions to RELEASE.md Add helm-docs instructions to RELEASE.md * Add docs-check.yml ci pipeline * Add more ignores, test the CI * Change values to configuration * Add links instead of ignores --- .github/workflows/docs-check.yml | 37 +++++++++++ CHANGELOG.md | 1 + README.md | 16 ----- RELEASE.md | 25 +++++++ charts/extended-ceph-exporter/Chart.yaml | 2 +- charts/extended-ceph-exporter/README.md | 65 ++++++++++++++----- .../extended-ceph-exporter/README.md.gotmpl | 56 ++++++++++++++++ charts/extended-ceph-exporter/values.yaml | 58 +++++++++++------ 8 files changed, 204 insertions(+), 56 deletions(-) create mode 100644 .github/workflows/docs-check.yml create mode 100644 RELEASE.md create mode 100644 charts/extended-ceph-exporter/README.md.gotmpl diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 0000000..e0023dd --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,37 @@ +name: docs-check +on: + push: + branches: + - main + pull_request: + branches: + - main + +# cancel the in-progress workflow when PR is refreshed. +concurrency: + group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.sha }} + cancel-in-progress: true + +jobs: + docs-check: + name: docs-check + runs-on: ubuntu-20.04 + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - uses: actions/setup-go@v3 + with: + go-version: 1.18 + + - name: Run helm-docs + run: | + GOBIN=$PWD GO111MODULE=on go install github.com/norwoodj/helm-docs/cmd/helm-docs@v1.11.0 + ./helm-docs --chart-search-root=${GITHUB_WORKSPACE}/charts + DIFF=$(git diff ${GITHUB_WORKSPACE}/charts/extended-ceph-exporter/README.md) + if [ ! -z "$DIFF" ]; then + echo "Please use helm-docs in your clone of the project, and commit an updated README.md for the chart. https://github.com/koor-tech/extended-ceph-exporter/blob/main/RELEASE.md#running-helm-docs" + fi + git diff --exit-code + rm -f ./helm-docs diff --git a/CHANGELOG.md b/CHANGELOG.md index f65e54e..70c590a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ ## ?? / 2022-11-15 +* [CHORE] Use [helm-docs](https://github.com/norwoodj/helm-docs) to create chart documentation * [FEATURE] Autodetect the RGW host and autogenerate the RGW access key and secret ## 1.0.2 / 2022-11-14 diff --git a/README.md b/README.md index 8de9283..65f6959 100644 --- a/README.md +++ b/README.md @@ -78,19 +78,3 @@ A VSCode debug config is available to run and debug the project. To make the exporter talk with a Ceph RGW S3 endpoint, create a copy of the `.env.example` file and name it `.env`. Be sure ot add your Ceph RGW S3 endpoint and credentials in it. - -### Create a new Release - -To create a new release (example is for release `v0.1.2`): - -1. Increase the version according to Semantic Versioning in the [`VERSION` file](VERSION). -2. Add a new entry to the [`CHANGELOG.md`](CHANGELOG.md) with the changes and improvements listed in it. -3. Set the new version, which will be the new container image tag, in [the `values.yaml` of the Helm chart here](https://github.com/koor-tech/extended-ceph-exporter/blob/main/charts/extended-ceph-exporter/Chart.yaml#L24) (`appVersion:` field). -4. Check out a new branch, which will be used for the pull request to update the version: `git checkout -b BRANCH_NAME` -5. Commit these changes now using `git commit -s -S`. -6. Push the branch using `git push -u origin BRANCH_NAME` with these changes and create a pull request on [GitHub](https://github.com/koor-tech/extended-ceph-exporter). -7. Wait for pull request to be approved and merge it (if you have access to do so). -8. Create the new tag using `git tag v0.1.2` and then run `git push -u origin v0.1.2` -9. In a few minutes, the CI should have built and published a draft of the release here [GitHub - Releases List](https://github.com/koor-tech/extended-ceph-exporter/releases). -10. Now edit the release and use the green button to publish the release. -11. Congratulations! The release is now fully published. diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..84121f5 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,25 @@ +# RELEASE PROCESS + +To create a new release (example is for release `v0.1.2`): + +1. Increase the version according to Semantic Versioning in the [`VERSION` file](VERSION). +2. Add a new entry to the [`CHANGELOG.md`](CHANGELOG.md) with the changes and improvements listed in it. +3. Set the new version, which will be the new container image tag, in [the `Chart.yaml` of the Helm chart here](charts/extended-ceph-exporter/Chart.yaml#L24) (`appVersion:` field). +4. If the [helm chart vlues](charts/extended-ceph-exporter/values.yaml) or documentation is updated, please [run helm-docs](#running-helm-docs) +5. Check out a new branch, which will be used for the pull request to update the version: `git checkout -b BRANCH_NAME` +6. Commit these changes now using `git commit -s -S`. +7. Push the branch using `git push -u origin BRANCH_NAME` with these changes and create a pull request on [GitHub](https://github.com/koor-tech/extended-ceph-exporter). +8. Wait for pull request to be approved and merge it (if you have access to do so). +9. Create the new tag using `git tag v0.1.2` and then run `git push -u origin v0.1.2` +10. In a few minutes, the CI should have built and published a draft of the release here [GitHub - Releases List](https://github.com/koor-tech/extended-ceph-exporter/releases). +11. Now edit the release and use the green button to publish the release. +12. Congratulations! The release is now fully published. + +## Running helm-docs +[helm-docs](https://github.com/norwoodj/helm-docs) is a tool that generates the README.md for a helm-chart automatically. We need to run helm-docs manually, and check in the resulting autogenerated README.md at the path [charts/extended-ceph-exporter/README.md](charts/extended-ceph-exporter/README.md) + +```console +GO111MODULE=on go install github.com/norwoodj/helm-docs/cmd/helm-docs@v1.11.0 +helm-docs +``` + diff --git a/charts/extended-ceph-exporter/Chart.yaml b/charts/extended-ceph-exporter/Chart.yaml index d85b24f..868f578 100644 --- a/charts/extended-ceph-exporter/Chart.yaml +++ b/charts/extended-ceph-exporter/Chart.yaml @@ -15,7 +15,7 @@ type: application # This is the chart version. This version number should be incremented each time you make changes # to the chart and its templates, including the app version. # Versions are expected to follow Semantic Versioning (https://semver.org/) -version: 1.2.0 +version: 1.2.1 # This is the version number of the application being deployed. This version number should be # incremented each time you make changes to the application. Versions are not expected to diff --git a/charts/extended-ceph-exporter/README.md b/charts/extended-ceph-exporter/README.md index 529541d..83fab6d 100644 --- a/charts/extended-ceph-exporter/README.md +++ b/charts/extended-ceph-exporter/README.md @@ -1,6 +1,8 @@ # extended-ceph-exporter -* Installs the extended-ceph-exporter +A Helm chart for deploying the extended-ceph-exporter to Kubernetes + +![Version: 1.2.1](https://img.shields.io/badge/Version-1.2.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: v1.0.2](https://img.shields.io/badge/AppVersion-v1.0.2-informational?style=flat-square) ## Get Repo Info @@ -11,29 +13,19 @@ helm repo update _See [helm repo](https://helm.sh/docs/helm/helm_repo/) for command documentation._ -## Installing the Chart +## Install Chart To install the chart with the release name `my-release`: ```console -helm install --namespace my-release extended-ceph-exporter/extended-ceph-exporter -``` - -or update `values.yaml` before running: - -```console -helm install --namespace my-release extended-ceph-exporter/extended-ceph-exporter -f values.yaml +helm install --namespace my-release extended-ceph-exporter/extended-ceph-exporter ``` -## Configuration +The command deploys extended-ceph-exporter on the Kubernetes cluster in the default configuration. -The following tables lists the configurable parameters of the rook-operator chart and their default values. +_See [configuration](#configuration) below._ -| Parameter | Description | Default | -|------------------------|-----------------------------------------------------------------------------------|-----------------------------| -| `config.rgw.host` | The Ceph RGW endpoint as a URL, e.g. `"https://your-ceph-rgw-endpoint-here:8443"` | First detected RGW endpoint | -| `config.rgw.accessKey` | The RGW admin access key | Randomly generated | -| `config.rgw.secretKey` | The RGW admin secret key | Randomly generated | +_See [helm install](https://helm.sh/docs/helm/helm_install/) for command documentation._ ### Development Build To deploy from a local build from your development environment: @@ -43,7 +35,7 @@ cd charts/extended-ceph-exporter helm install --namespace my-release . -f values.yaml ``` -## Uninstalling the Chart +## Uninstall Chart To uninstall/delete the my-release deployment: @@ -51,4 +43,41 @@ To uninstall/delete the my-release deployment: helm delete --namespace my-release ``` -The command removes all the Kubernetes components associated with the chart and deletes the release. +This removes all the Kubernetes components associated with the chart and deletes the release. + +_See [helm uninstall](https://helm.sh/docs/helm/helm_uninstall/) for command documentation._ + +## Configuration + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| additionalEnv | object | `{}` | Will be put in a Secret and used as env vars | +| affinity | object | `{}` | [Affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) | +| autoscaling | object | `{"enabled":false,"maxReplicas":100,"minReplicas":1,"targetCPUUtilizationPercentage":80}` | Autoscaling configuration | +| config.rgw.accessKey | string | Randomly generated | RGW admin access key | +| config.rgw.host | string | First detected RGW endpoint | The Ceph RGW endpoint as a URL, e.g. "https://your-ceph-rgw-endpoint-here:8443" | +| config.rgw.secretKey | string | Randomly generated | RGW admin secret key | +| fullnameOverride | string | `""` | Override fully-qualified app name | +| image.tag | string | `""` | Overrides the image tag whose default is the chart appVersion. | +| nameOverride | string | `""` | Override chart name | +| nodeSelector | object | `{}` | [Create a pod that gets scheduled to your chosen node](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#create-a-pod-that-gets-scheduled-to-your-chosen-node) | +| podAnnotations | object | `{}` | Annotations to add to the pod | +| podSecurityContext | object | `{}` | [Pod security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) | +| postInstallJob.enabled | bool | `true` | If enabled, will create a rgw admin user `extended-ceph-exporter` either on Rook/Ceph cluster pre upgrade(when having extended-ceph-exporter as a helm dependency) or on post install of extended-ceph-exporter(needs existing Rook/Ceph cluster). This user will be used for extended ceph metrics. | +| prometheusRule.additionalLabels | object | `{}` | Additional Labels for the PrometheusRule object | +| prometheusRule.enabled | bool | `false` | Specifies whether a prometheus-operator PrometheusRule should be created | +| prometheusRule.rules | prometheusrules.monitoring.coreos.com | `[]` | | +| replicaCount | int | `1` | Number of replicas of the exporter | +| resources | object | `{}` | We usually recommend not to specify default resources and to leave this as a conscious choice for the user. This also increases chances charts run on environments with little resources, such as Minikube. If you do want to specify resources, uncomment the following lines, adjust them as necessary, and remove the curly braces after 'resources:'. | +| securityContext | object | `{}` | [Security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) | +| service.port | int | `9138` | | +| service.type | string | `"ClusterIP"` | | +| serviceAccount.annotations | object | `{}` | Annotations to add to the service account | +| serviceAccount.create | bool | `true` | Specifies whether a service account should be created | +| serviceAccount.name | string | `""` | The name of the service account to use. If not set and create is true, a name is generated using the fullname template | +| serviceMonitor.additionalLabels | object | `{}` | Additional Labels for the ServiceMonitor object | +| serviceMonitor.enabled | bool | `false` | Specifies whether a prometheus-operator ServiceMonitor should be created | +| serviceMonitor.namespaceSelector | string | `nil` | | +| serviceMonitor.scrapeInterval | duration | `"30s"` | Interval at which metrics should be scraped | +| tolerations | list | `[]` | [Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) | + diff --git a/charts/extended-ceph-exporter/README.md.gotmpl b/charts/extended-ceph-exporter/README.md.gotmpl new file mode 100644 index 0000000..0f6ebd6 --- /dev/null +++ b/charts/extended-ceph-exporter/README.md.gotmpl @@ -0,0 +1,56 @@ +{{ template "chart.header" . }} +{{ template "chart.description" . }} + +{{ template "chart.badgesSection" . }} + +## Get Repo Info + +```console +helm repo add extended-ceph-exporter https://koor-tech.github.io/extended-ceph-exporter +helm repo update +``` + +_See [helm repo](https://helm.sh/docs/helm/helm_repo/) for command documentation._ + +## Install Chart + +To install the chart with the release name `my-release`: + +```console +helm install --namespace my-release extended-ceph-exporter/extended-ceph-exporter +``` + +The command deploys extended-ceph-exporter on the Kubernetes cluster in the default configuration. + +_See [configuration](#configuration) below._ + +_See [helm install](https://helm.sh/docs/helm/helm_install/) for command documentation._ + + +### Development Build +To deploy from a local build from your development environment: + +```console +cd charts/extended-ceph-exporter +helm install --namespace my-release . -f values.yaml +``` + +## Uninstall Chart + +To uninstall/delete the my-release deployment: + +```console +helm delete --namespace my-release +``` + +This removes all the Kubernetes components associated with the chart and deletes the release. + +_See [helm uninstall](https://helm.sh/docs/helm/helm_uninstall/) for command documentation._ + +{{ template "chart.requirementsSection" . }} + +## Configuration + +{{ template "chart.valuesTable" . }} + +{{ template "helm-docs.versionFooter" . }} diff --git a/charts/extended-ceph-exporter/values.yaml b/charts/extended-ceph-exporter/values.yaml index 798963c..cc8cf65 100644 --- a/charts/extended-ceph-exporter/values.yaml +++ b/charts/extended-ceph-exporter/values.yaml @@ -2,32 +2,41 @@ # This is a YAML-formatted file. # Declare variables to be passed into your templates. +# -- Number of replicas of the exporter replicaCount: 1 image: + # @ignore repository: docker.io/koorinc/extended-ceph-exporter + # @ignore pullPolicy: IfNotPresent - # Overrides the image tag whose default is the chart appVersion. + # -- Overrides the image tag whose default is the chart appVersion. tag: "" +# @ignore imagePullSecrets: [] +# -- Override chart name nameOverride: "" +# -- Override fully-qualified app name fullnameOverride: "" serviceAccount: - # Specifies whether a service account should be created + # -- Specifies whether a service account should be created create: true - # Annotations to add to the service account + # -- Annotations to add to the service account annotations: {} - # The name of the service account to use. + # -- The name of the service account to use. # If not set and create is true, a name is generated using the fullname template name: "" +# -- Annotations to add to the pod podAnnotations: {} +# -- [Pod security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) podSecurityContext: {} # fsGroup: 2000 +# -- [Security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) securityContext: {} # capabilities: # drop: @@ -36,17 +45,18 @@ securityContext: {} # runAsNonRoot: true # runAsUser: 1000 +# @ignore sidecars: [] service: type: ClusterIP port: 9138 +# -- We usually recommend not to specify default resources and to leave this as a conscious +# choice for the user. This also increases chances charts run on environments with little +# resources, such as Minikube. If you do want to specify resources, uncomment the following +# lines, adjust them as necessary, and remove the curly braces after 'resources:'. resources: {} - # We usually recommend not to specify default resources and to leave this as a conscious - # choice for the user. This also increases chances charts run on environments with little - # resources, such as Minikube. If you do want to specify resources, uncomment the following - # lines, adjust them as necessary, and remove the curly braces after 'resources:'. # limits: # cpu: 100m # memory: 128Mi @@ -54,6 +64,7 @@ resources: {} # cpu: 100m # memory: 128Mi +# -- Autoscaling configuration autoscaling: enabled: false minReplicas: 1 @@ -61,10 +72,13 @@ autoscaling: targetCPUUtilizationPercentage: 80 # targetMemoryUtilizationPercentage: 80 +# -- [Create a pod that gets scheduled to your chosen node](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#create-a-pod-that-gets-scheduled-to-your-chosen-node) nodeSelector: {} +# -- [Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) tolerations: [] +# -- [Affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) affinity: {} serviceMonitor: @@ -79,6 +93,7 @@ serviceMonitor: # matchNames: # - monitoring # any: true + # -- (duration) Interval at which metrics should be scraped scrapeInterval: 30s # honorLabels: true @@ -89,33 +104,34 @@ prometheusRule: additionalLabels: {} # Default: .Release.Namespace # namespace: "" - # prometheusRule.rules -- Checkout the file for example alerts + # prometheusRule.rules # Checkout the file for example alerts + # -- (prometheusrules.monitoring.coreos.com) rules: [] -# -- Config for the exporter +# Config for the exporter # pass during helm install or set prior to update this can also be done during runtime by using `--set`` -# the host defaults to the first CephObjectStore resource found in all namespaces. -# The access and secret keys are randomly generated by default config: rgw: - # The Ceph RGW endpoint as a URL, e.g. "https://your-ceph-rgw-endpoint-here:8443" + # -- The Ceph RGW endpoint as a URL, e.g. "https://your-ceph-rgw-endpoint-here:8443" + # @default -- First detected RGW endpoint host: "" - # RGW admin access key + # -- RGW admin access key + # @default -- Randomly generated accessKey: "" - # RGW admin secret key + # -- RGW admin secret key + # @default -- Randomly generated secretKey: "" # -- Will be put in a Secret and used as env vars additionalEnv: {} -# If enabled, will create a rgw admin user `extended-ceph-exporter` either on -# Rook/Ceph cluster pre upgrade(when having extended-ceph-exporter as a helm -# dependency) or on post install of extended-ceph-exporter(needs existing -# Rook/Ceph cluster). -# See more: https://github.com/koor-tech/extended-ceph-exporter/tree/main/charts/extended-ceph-exporter#installing-the-chart -# This user will be used for extended ceph metrics. postInstallJob: + # -- If enabled, will create a rgw admin user `extended-ceph-exporter` either on + # Rook/Ceph cluster pre upgrade(when having extended-ceph-exporter as a helm + # dependency) or on post install of extended-ceph-exporter(needs existing + # Rook/Ceph cluster). This user will be used for extended ceph metrics. enabled: true + # @ignore image: repository: quay.io/ceph/ceph pullPolicy: IfNotPresent