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