Better readme to Helm chart

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Added missing geos dependency into Dockerfile (<https://github.com/openvinotoolkit/cvat/pull/4451>)
+- Improved helm chart readme (<https://github.com/openvinotoolkit/cvat/pull/4366>)
 
 ### Deprecated
 - TDB

helm-chart/README.md

@@ -1,58 +1,138 @@
-# FAQ
-## What should be configured before installation?
-1. You should have configured connection to existed k8s cluster
-2. Helm must be installed
-3. You should download chart external dependencies, using following commands:
-```
-   helm repo add bitnami https://charts.bitnami.com/bitnami
-   helm repo update
-   helm dependency update
-```
-4. (Optional) Install ingress of your choice (for example: <https://github.com/kubernetes/ingress-nginx>)
-5. (Optional) Create certificates for https (for example: <https://github.com/jetstack/cert-manager/>)
-6. (Optional) Create values.override.yaml and override there parameters you want
-7. Change postgresql password as described below
-8. Add ingress to values.override.yaml(example also below)
-7. Deploy cvat using command below
-## How to deploy new version of chart to cluster?
-Execute following command:
-```helm upgrade <release_name> --install ./helm-chart -f ./helm-chart/values.yaml  -f values.override.yaml(if exists) --namespace <desired namespace>```
-## How to create superuser?
-```
-HELM_RELEASE_NAMESPACE="<insert>" &&\
-HELM_RELEASE_NAME="<insert>" &&\
-BACKEND_POD_NAME=$(kubectl get pod --namespace $HELM_RELEASE_NAMESPACE -l tier=backend,app.kubernetes.io/instance=$HELM_RELEASE_NAME -o jsonpath='{.items[0].metadata.name}') &&\
-kubectl exec -it --namespace $HELM_RELEASE_NAMESPACE $BACKEND_POD_NAME -c cvat-backend-app-container -- python manage.py createsuperuser
-```
-## How to change embedded postgresql password?
-There are several passwords used here, for security reasons - better change them all.
+# CVAT chart manual
+
+- [CVAT chart manual](#cvat-chart-manual)
+  - [Prerequisites](#prerequisites)
+    - [Installing dependencies](#installing-dependencies)
+    - [Optional steps](#optional-steps)
+  - [Configuration](#configuration)
+    - [Postgresql password?](#postgresql-password)
+    - [Ingress parameters](#ingress-parameters)
+  - [Deployment](#deployment)
+    - [With overrides:](#with-overrides)
+    - [Without overrides:](#without-overrides)
+  - [Post-deployment configuration](#post-deployment-configuration)
+    - [How to create superuser?](#how-to-create-superuser)
+  - [FAQ](#faq)
+    - [What is kubernetes and how it is working?](#what-is-kubernetes-and-how-it-is-working)
+    - [What is helm and how it is working?](#what-is-helm-and-how-it-is-working)
+    - [How to enable ingress:](#how-to-enable-ingress)
+    - [How to understand what diff will be inflicted by 'helm upgrade'?](#how-to-understand-what-diff-will-be-inflicted-by-helm-upgrade)
+    - [I want to use my own postgresql/redis with your chart.](#i-want-to-use-my-own-postgresqlredis-with-your-chart)
+    - [I want to override some settings in values.yaml.](#i-want-to-override-some-settings-in-valuesyaml)
+    - [Why you used external charts to provide redis and postgres?](#why-you-used-external-charts-to-provide-redis-and-postgres)
+
+## Prerequisites
+1. Installed and configured [kubernetes](https://kubernetes.io/) cluster.
+2. Installed [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
+3. Installed [Helm](https://helm.sh/).
+4. Installed [dependencies](#installing-dependencies)
+
+### Installing dependencies
+To install and/or update run:
+```sh
+helm repo add bitnami https://charts.bitnami.com/bitnami
+helm repo update
+helm dependency update
 ```
+
+### Optional steps
+1. Install ingress of your choice (for example: <https://github.com/kubernetes/ingress-nginx>)
+2. Create certificates for https (for example: <https://github.com/jetstack/cert-manager/>)
+
+## Configuration
+1. Create `values.override.yaml` file inside `helm-chart` directory.
+2. Fill `values.override.yaml` with new parameters for chart.
+3. Override [postgresql password](#postgresql-password)
+4. (Optional) Add [ingress parameters](#ingress-parameters)
+
+### Postgresql password?
+Put below into your `values.override.yaml`
+```yaml
 postgresql:
   secret:
-    password: cvat_postgresql
-    postgres_password: cvat_postgresql_postgres
-    replication_password: cvat_postgresql_replica
-```
-Or, if you know how to work with k8s - you could create your own secret and use it here:
+    password: <insert_password>
+    postgres_password: <insert_postgres_password>
+    replication_password: <insert_replication_password>
 ```
+Or create your own secret and use it with:
+```yaml
 postgresql:
    global:
      postgresql:
-       existingSecret: cvat-postgres-secret
+       existingSecret: <secret>
+```
+
+### Ingress parameters
+Paste below parameters to `values.override.yaml`
+```yaml
+ingress:
+  enabled: true
+  annotations:
+    kubernetes.io/ingress.class: nginx
+    kubernetes.io/tls-acme: "true"
+    ingress.kubernetes.io/ssl-redirect: "true"
+    nginx.ingress.kubernetes.io/use-regex: "true"
+    nginx.ingress.kubernetes.io/secure-backends: "true"
+    nginx.ingress.kubernetes.io/proxy-body-size: "0"
+    nginx.ingress.kubernetes.io/proxy-send-timeout: "120"
+    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
+    cert-manager.io/cluster-issuer: <issuer_name>
+  hosts:
+    - host: <your_domain>
+      paths:
+        - path: "/api/.*|git/.*|tensorflow/.*|auto_annotation/.*|analytics/.*|static/.*|admin|admin/.*|documentation/.*|dextr/.*|reid/.*"
+          service:
+            name: <release_name>-backend-service
+            port: 8080
+        - path: "/"
+          pathType: "Prefix"
+          service:
+            name: <release_name>-frontend-service
+            port: 80
+
+  tls:
+    - hosts:
+        - <your_domain>
+      secretName: ingress-tls-cvat
 ```
-## How to describe ingress:
+
+## Deployment
+Make sure you are using correct kubernetes context. You can check it with `kubectl config current-context`.
+
+Execute following command from repo root directory
+### With overrides:
+```helm upgrade -n <desired_namespace> <release_name> -i --create-namespace ./helm-chart -f ./helm-chart/values.yaml  -f ./helm-chart/values.override.yaml```
+
+### Without overrides:
+```helm upgrade -n <desired_namespace> <release_name> -i --create-namespace ./helm-chart -f ./helm-chart/values.yaml```
+
+## Post-deployment configuration
+
+1. Create [super user](#how-to-create-superuser)
+
+### How to create superuser?
+```sh
+HELM_RELEASE_NAMESPACE="<desired_namespace>" &&\
+HELM_RELEASE_NAME="<release_name>" &&\
+BACKEND_POD_NAME=$(kubectl get pod --namespace $HELM_RELEASE_NAMESPACE -l tier=backend,app.kubernetes.io/instance=$HELM_RELEASE_NAME -o jsonpath='{.items[0].metadata.name}') &&\
+kubectl exec -it --namespace $HELM_RELEASE_NAMESPACE $BACKEND_POD_NAME -c cvat-backend-app-container -- python manage.py createsuperuser
+```
+
+## FAQ
+
+### What is kubernetes and how it is working?
+See <https://kubernetes.io/>
+### What is helm and how it is working?
+See <https://helm.sh/>
+### How to enable ingress:
   Just set `ingress.enabled:` to `true`, then copy example, uncomment it and change values there
-## How to understand what diff will be inflicted by 'helm upgrade'?
+### How to understand what diff will be inflicted by 'helm upgrade'?
 You can use <https://github.com/databus23/helm-diff#install> for that
-## I want to use my own postgresql/redis with your chart.
+### I want to use my own postgresql/redis with your chart.
 Just set `postgresql.enabled` or `redis.enabled` to `false`, as described below.
 Then - put your instance params to "external" field
-## I want to override some settings in values.yaml.
+### I want to override some settings in values.yaml.
 Just create file `values.override.yaml` and place your changes here, using same structure as in `values.yaml`.
 Then reference it in helm update/install command using `-f` flag
-## Why you used external charts to provide redis and postgres?
-Because they definitely know what they do better then we are, so we are getting more quality and less support
-## What is kubernetes and how it is working?
-See <https://kubernetes.io/>
-## What is helm and how it is working?
-See <https://helm.sh/>
+### Why you used external charts to provide redis and postgres?
+Because they definitely know what they do better then we are, so we are getting more quality and less support

helm-chart/values.yaml

@@ -2,7 +2,6 @@
 # This is a YAML-formatted file.
 # Declare variables to be passed into your templates.
 
-
 imagePullSecrets: []
 nameOverride: ""
 fullnameOverride: ""
@@ -31,8 +30,8 @@ cvat:
     #         - e2e-az1
     #         - e2e-az2
     envs:
-        ALLOWED_HOSTS: "*"
-        DJANGO_MODWSGI_EXTRA_ARGS: ""
+      ALLOWED_HOSTS: "*"
+      DJANGO_MODWSGI_EXTRA_ARGS: ""
     additionalEnv: []
     # Example:
     #  - name: volume-from-secret
@@ -56,8 +55,8 @@ cvat:
           protocol: TCP
           name: http
     defaultStorage:
-        enabled: true
-        size: 20Gi
+      enabled: true
+      size: 20Gi
   frontend:
     replicas: 1
     image: openvino/cvat_ui
@@ -110,7 +109,7 @@ postgresql:
     user: postgres
     password: postgres
     dbname: cvat
- # If not external following config will be applied by default
+  # If not external following config will be applied by default
   global:
     postgresql:
       existingSecret: cvat-postgres-secret
@@ -129,7 +128,7 @@ redis:
   #See https://github.com/bitnami/charts/blob/master/bitnami/redis/ for more info
   enabled: true
   external:
-      host: 127.0.0.1
+    host: 127.0.0.1
   usePassword: false
   cluster:
     enabled: false
@@ -146,21 +145,21 @@ ingress:
 #        nginx.ingress.kubernetes.io/proxy-body-size: "0"
 #        nginx.ingress.kubernetes.io/proxy-send-timeout: "120"
 #        nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
-#        cert-manager.io/cluster-issuer: example.issuer.name
+#        cert-manager.io/cluster-issuer: <issuer_name>
 #    hosts:
-#        - host: cvat.example.com
+#        - host: <your domain>
 #          paths:
 #              - path: "/api/.*|git/.*|tensorflow/.*|auto_annotation/.*|analytics/.*|static/.*|admin|admin/.*|documentation/.*|dextr/.*|reid/.*"
 #                service:
-#                    name: cvt-test-backend-service
+#                    name: <release_name>-backend-service
 #                    port: 8080
 #              - path : "/"
 #                pathType: "Prefix"
 #                service:
-#                    name: cvt-test-frontend-service
+#                    name: <release_name>-frontend-service
 #                    port: 80
 #
 #    tls:
 #        - hosts:
-#              - cvat.example.com
+#              - <your domain>
 #          secretName: ingress-tls-cvat