From 43565bcb3a2f47e53ee6984e0229b0c9086191ac Mon Sep 17 00:00:00 2001 From: Andrey Zhavoronkov Date: Tue, 20 Sep 2022 12:38:27 +0300 Subject: [PATCH] moved README Helm file to documentation (#4977) --- helm-chart/README.md | 231 +---------------- .../docs/administration/advanced/analytics.md | 2 +- .../administration/advanced/backup_guide.md | 2 +- .../advanced/iam_system_roles.md | 3 +- .../installation_automatic_annotation.md | 2 +- .../advanced/k8s_deployment_with_helm.md | 240 ++++++++++++++++++ .../en/docs/administration/advanced/ldap.md | 2 +- .../advanced/mounting_cloud_storages.md | 2 +- .../administration/advanced/upgrade_guide.md | 2 +- 9 files changed, 249 insertions(+), 237 deletions(-) create mode 100644 site/content/en/docs/administration/advanced/k8s_deployment_with_helm.md diff --git a/helm-chart/README.md b/helm-chart/README.md index a0148314..a6d13f37 100644 --- a/helm-chart/README.md +++ b/helm-chart/README.md @@ -1,231 +1,2 @@ -# 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) - - [(Optional) Enable Auto annotation feature](#optional-enable-auto-annotation-feature) - - [(Optional) Enable Analytics](#optional-enable-analytics) - - [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 setup Minikube?](#how-to-setup-minikube) - - [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. If you do not already have a cluster, - you can create one by using [Minikube](https://github.com/kubernetes/minikube/). [How to setup Minikube](#how-to-setup-minikube). -1. Installed [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) -1. Installed [Helm](https://helm.sh/). -1. Installed [dependencies](#installing-dependencies) - -### Installing dependencies -To install and/or update run: -```shell -helm dependency update -``` - -### Optional steps -1. Ingress configuration for the Traefik ingress controller is enabled by default. - - Note for Minikube use: - - because the Traefik creates its main service with `Loadbalanser` type, - which involve the assignment of externalIP by Cloud, what never happens on Minikube, - you need to explicitly set the externalIP address for the traefic service. - Add the following to `values.override.yaml` file: - ```yaml - traefik: - service: - externalIPs: - - "your minikube IP (can be obtained with `minicube ip` command)" - ``` - - Also ensure that your CVAT ingress appears on your hosts file (/etc/hosts). - You can do this by running this command: - `cvat.local` is default domainname, you can override it via `values.override.yaml`. - ```shell - echo "$(minikube ip) cvat.local" | sudo tee -a /etc/hosts - ``` - -## Configuration -1. Create `values.override.yaml` file inside `helm-chart` directory. -1. Fill `values.override.yaml` with new parameters for chart. -1. Override [postgresql password](#postgresql-password) -1. Create a rules.tar.gz archive containing all OPA rules inside this `helm-chart` directory. - ```shell - find ../cvat/apps/iam/rules -name "*.rego" -and ! -name '*test*' -exec basename {} \; | tar -czf rules.tar.gz -C ../cvat/apps/iam/rules/ -T - - ``` - -### Postgresql password? -Put below into your `values.override.yaml` -```yaml -postgresql: - secret: - password: - postgres_password: - replication_password: -``` -Or create your own secret and use it with: -```yaml -postgresql: - global: - postgresql: - existingSecret: -``` - -### (Optional) Enable Auto annotation feature - -Before starting, ensure that the following prerequisites are met: -- The Nuclio [CLI (nuctl)](https://nuclio.io/docs/latest/reference/nuctl/nuctl/) is installed. - To install the CLI, simply [download](https://github.com/nuclio/nuclio/releases) - the appropriate CLI version to your installation machine. - -1. Set `nuclio.enabled: true` in your `values.override.yaml` -1. Run `helm dependency update` in `helm-chart` directory -1. Because Nuclio functions are images that need to be pushed and pulled to/from the registry, - you need to configure credentials to pull from your preferable registry with the following settings: - Options: - - `values.override.yaml` file: - ```yaml - registry: - loginUrl: someurl - credentials: - username: someuser - password: somepass - ``` - - Or you can create a secret with credentials as described in the [guide](https://nuclio.io/docs/latest/setup/k8s/running-in-production-k8s/#the-preferred-deployment-method) - and set `registry.secretName=your-registry-credentials-secret-name` in the `values.override.yaml` file. - - - In the case of using Minikube, you can run a local unsecured registry with minikube add-ons: - ```shell - minikube addons enable registry - minikube addons enable registry-aliases - ``` - Before Docker container images can be pushed to your newly created unsecure registry, - you need to add its address (`$(minikube ip):5000`) to the list of unsecure registries to - instruct Docker to accept working against it: - follow the instructions in the [Docker documentation](https://docs.docker.com/registry/insecure/#deploy-a-plain-http-registry) - - You might also need to log into your registry account (docker login) - on the installation machine before running the deployment command. - -1. Create cvat project: - ```shell - nuctl --namespace create project cvat - ``` -1. Finaly deploy the fuction, i.e.: - - using minikube registry: - ```shell - nuctl deploy --project-name cvat --path serverless/tensorflow/faster_rcnn_inception_v2_coco/nuclio --registry $(minikube ip):5000 --run-registry registry.minikube - ``` - - using Docker hub: - ```shell - nuctl deploy --project-name cvat --path serverless/tensorflow/faster_rcnn_inception_v2_coco/nuclio --registry docker.io/your_username - ``` - -### (Optional) Enable Analytics - -1. Set `analytics.enabled: true` in your `values.override.yaml` -1. Run `helm dependency update` in `helm-chart` directory -1. Since custom images are required here, you will need to create them yourself - and push them to your preferred docker registry. - You might also need to log into your registry account (docker login) - on the installation machine before running the push command. - How to set up local registry when using Minikube see [previous section](#how_to_enable_auto_annotation_feature) - - - Let's build custom elasticsearch, logstash and kibana images with the following command - ```shell - docker-compose -f docker-compose.yml -f components/analytics/docker-compose.analytics.yml build - ``` - - - Tag images: - ```shell - docker tag cvat_kibana:latest /cvat_kibana:latest - docker tag cvat_elasticsearch:latest /cvat_elasticsearch:latest - docker tag cvat_logstash:latest /cvat_logstash:latest - ``` - - - Push to registry - ```shell - docker push /cvat_kibana:latest - docker push /cvat_elasticsearch:latest - docker push /cvat_logstash:latest - ``` - - - Add corresponding settings into `values.override.yaml`, i.e. for minikube registry: - ```yaml - logstash: - image: "registry.minikube/cvat_logstash" - imageTag: "latest" - - elasticsearch: - image: "registry.minikube/cvat_elasticsearch" - imageTag: "latest" - - kibana: - image: "registry.minikube/cvat_kibana" - imageTag: "latest" - ``` - - - Deploy - ```shell - helm upgrade --namespace --install ./helm-chart -f ./helm-chart/values.yaml -f values.override.yaml - ``` - -## Deployment -Make sure you are using correct kubernetes context. You can check it with `kubectl config current-context`. - -> **Warning:** The k8s service name of Open Policy Agent is fixed to opa by default. -> This is done to be compatible with CVAT 2.0 but limits this helm chart to a single release per namespace. -> The OPA url currently can´t be set as an environment variable. -> As soon as this is possible you can set cvat.opa.composeCompatibleServiceName -> to false in your value.override.yaml and configure the opa url as additional env. - -Execute following command from repo root directory -### With overrides: -```helm upgrade -n -i --create-namespace ./helm-chart -f ./helm-chart/values.yaml -f ./helm-chart/values.override.yaml``` - -### Without overrides: -```helm upgrade -n -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="" &&\ -HELM_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 -### What is helm and how it is working? -See -### How to setup Minikube -1. Please follow the official Minikube installation [guide](https://minikube.sigs.k8s.io/docs/start/) -1. ```shell - minikube start --addons registry,registry-aliases - ``` -### How to understand what diff will be inflicted by 'helm upgrade'? -You can use for that -### 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. -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 +[See for details](https://https://opencv.github.io/cvat/docs/administration/advanced/k8s_deployment_with_helm/) diff --git a/site/content/en/docs/administration/advanced/analytics.md b/site/content/en/docs/administration/advanced/analytics.md index 576a63f5..92a8dc2e 100644 --- a/site/content/en/docs/administration/advanced/analytics.md +++ b/site/content/en/docs/administration/advanced/analytics.md @@ -4,7 +4,7 @@ title: 'Installation Analytics' linkTitle: 'Installation Analytics' -weight: 2 +weight: 20 description: 'Instructions for deployment and customization of Analytics. This section on [GitHub](https://github.com/cvat-ai/cvat/tree/develop/components/analytics).' --- diff --git a/site/content/en/docs/administration/advanced/backup_guide.md b/site/content/en/docs/administration/advanced/backup_guide.md index af5230ed..3b5cad6f 100644 --- a/site/content/en/docs/administration/advanced/backup_guide.md +++ b/site/content/en/docs/administration/advanced/backup_guide.md @@ -1,7 +1,7 @@ --- title: 'Backup guide' linkTitle: 'Backup guide' -weight: 11 +weight: 50 description: 'Instructions on how to backup CVAT data with Docker.' --- diff --git a/site/content/en/docs/administration/advanced/iam_system_roles.md b/site/content/en/docs/administration/advanced/iam_system_roles.md index 11cefdb7..17cd5d79 100644 --- a/site/content/en/docs/administration/advanced/iam_system_roles.md +++ b/site/content/en/docs/administration/advanced/iam_system_roles.md @@ -1,9 +1,10 @@ --- title: 'IAM: system roles' linkTitle: 'system roles' -weight: 22 +weight: 70 --- ## System roles +TBD diff --git a/site/content/en/docs/administration/advanced/installation_automatic_annotation.md b/site/content/en/docs/administration/advanced/installation_automatic_annotation.md index 38e7c94a..8e0bed35 100644 --- a/site/content/en/docs/administration/advanced/installation_automatic_annotation.md +++ b/site/content/en/docs/administration/advanced/installation_automatic_annotation.md @@ -4,7 +4,7 @@ title: 'Semi-automatic and Automatic Annotation' linkTitle: 'Installation Auto Annotation' -weight: 5 +weight: 10 description: 'Information about the installation of components needed for semi-automatic and automatic annotation.' --- diff --git a/site/content/en/docs/administration/advanced/k8s_deployment_with_helm.md b/site/content/en/docs/administration/advanced/k8s_deployment_with_helm.md new file mode 100644 index 00000000..5b777311 --- /dev/null +++ b/site/content/en/docs/administration/advanced/k8s_deployment_with_helm.md @@ -0,0 +1,240 @@ +--- + +title: 'CVAT deployment on Kubernetes with Helm' +linkTitle: 'CVAT deployment on Kubernetes with Helm' +weight: 1 +description: 'Instructions for deploying CVAT on a Kubernetes cluster.' + +--- + + + + +- [Prerequisites](#prerequisites) + - [Installing dependencies](#installing-dependencies) + - [Optional steps](#optional-steps) +- [Configuration](#configuration) + - [Postgresql password?](#postgresql-password) + - [(Optional) Enable Auto annotation feature](#optional-enable-auto-annotation-feature) + - [(Optional) Enable Analytics](#optional-enable-analytics) +- [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 setup Minikube](#how-to-setup-minikube) + - [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. If you do not already have a cluster, + you can create one by using [Minikube](https://github.com/kubernetes/minikube/). [How to setup Minikube](#how-to-setup-minikube). +1. Installed [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) +1. Installed [Helm](https://helm.sh/). +1. Installed [dependencies](#installing-dependencies) + +### Installing dependencies +To install and/or update run: +```shell +helm dependency update +``` + +### Optional steps +1. Ingress configuration for the Traefik ingress controller is enabled by default. + + Note for Minikube use: + - because the Traefik creates its main service with `Loadbalanser` type, + which involve the assignment of externalIP by Cloud, what never happens on Minikube, + you need to explicitly set the externalIP address for the traefic service. + Add the following to `values.override.yaml` file: + ```yaml + traefik: + service: + externalIPs: + - "your minikube IP (can be obtained with `minicube ip` command)" + ``` + - Also ensure that your CVAT ingress appears on your hosts file (/etc/hosts). + You can do this by running this command: + `cvat.local` is default domainname, you can override it via `values.override.yaml`. + ```shell + echo "$(minikube ip) cvat.local" | sudo tee -a /etc/hosts + ``` + +## Configuration +1. Create `values.override.yaml` file inside `helm-chart` directory. +1. Fill `values.override.yaml` with new parameters for chart. +1. Override [postgresql password](#postgresql-password) +1. Create a rules.tar.gz archive containing all OPA rules inside this `helm-chart` directory. + ```shell + find ../cvat/apps/iam/rules -name "*.rego" -and ! -name '*test*' -exec basename {} \; | tar -czf rules.tar.gz -C ../cvat/apps/iam/rules/ -T - + ``` + +### Postgresql password? +Put below into your `values.override.yaml` +```yaml +postgresql: + secret: + password: + postgres_password: + replication_password: +``` +Or create your own secret and use it with: +```yaml +postgresql: + global: + postgresql: + existingSecret: +``` + +### (Optional) Enable Auto annotation feature + +Before starting, ensure that the following prerequisites are met: +- The Nuclio [CLI (nuctl)](https://nuclio.io/docs/latest/reference/nuctl/nuctl/) is installed. + To install the CLI, simply [download](https://github.com/nuclio/nuclio/releases) + the appropriate CLI version to your installation machine. + +1. Set `nuclio.enabled: true` in your `values.override.yaml` +1. Run `helm dependency update` in `helm-chart` directory +1. Because Nuclio functions are images that need to be pushed and pulled to/from the registry, + you need to configure credentials to pull from your preferable registry with the following settings: + Options: + - `values.override.yaml` file: + ```yaml + registry: + loginUrl: someurl + credentials: + username: someuser + password: somepass + ``` + - Or you can create a secret with credentials as described in the [guide](https://nuclio.io/docs/latest/setup/k8s/running-in-production-k8s/#the-preferred-deployment-method) + and set `registry.secretName=your-registry-credentials-secret-name` in the `values.override.yaml` file. + + - In the case of using Minikube, you can run a local unsecured registry with minikube add-ons: + ```shell + minikube addons enable registry + minikube addons enable registry-aliases + ``` + Before Docker container images can be pushed to your newly created unsecure registry, + you need to add its address (`$(minikube ip):5000`) to the list of unsecure registries to + instruct Docker to accept working against it: + follow the instructions in the [Docker documentation](https://docs.docker.com/registry/insecure/#deploy-a-plain-http-registry) + + You might also need to log into your registry account (docker login) + on the installation machine before running the deployment command. + +1. Create cvat project: + ```shell + nuctl --namespace create project cvat + ``` +1. Finaly deploy the fuction, i.e.: + - using minikube registry: + ```shell + nuctl deploy --project-name cvat --path serverless/tensorflow/faster_rcnn_inception_v2_coco/nuclio --registry $(minikube ip):5000 --run-registry registry.minikube + ``` + - using Docker hub: + ```shell + nuctl deploy --project-name cvat --path serverless/tensorflow/faster_rcnn_inception_v2_coco/nuclio --registry docker.io/your_username + ``` + +### (Optional) Enable Analytics + +1. Set `analytics.enabled: true` in your `values.override.yaml` +1. Run `helm dependency update` in `helm-chart` directory +1. Since custom images are required here, you will need to create them yourself + and push them to your preferred docker registry. + You might also need to log into your registry account (docker login) + on the installation machine before running the push command. + How to set up local registry when using Minikube see [previous section](#how_to_enable_auto_annotation_feature) + + - Let's build custom elasticsearch, logstash and kibana images with the following command + ```shell + docker-compose -f docker-compose.yml -f components/analytics/docker-compose.analytics.yml build + ``` + + - Tag images: + ```shell + docker tag cvat_kibana:latest /cvat_kibana:latest + docker tag cvat_elasticsearch:latest /cvat_elasticsearch:latest + docker tag cvat_logstash:latest /cvat_logstash:latest + ``` + + - Push to registry + ```shell + docker push /cvat_kibana:latest + docker push /cvat_elasticsearch:latest + docker push /cvat_logstash:latest + ``` + + - Add corresponding settings into `values.override.yaml`, i.e. for minikube registry: + ```yaml + logstash: + image: "registry.minikube/cvat_logstash" + imageTag: "latest" + + elasticsearch: + image: "registry.minikube/cvat_elasticsearch" + imageTag: "latest" + + kibana: + image: "registry.minikube/cvat_kibana" + imageTag: "latest" + ``` + + - Deploy + ```shell + helm upgrade --namespace --install ./helm-chart -f ./helm-chart/values.yaml -f values.override.yaml + ``` + +## Deployment +Make sure you are using correct kubernetes context. You can check it with `kubectl config current-context`. + +> **Warning:** The k8s service name of Open Policy Agent is fixed to opa by default. +> This is done to be compatible with CVAT 2.0 but limits this helm chart to a single release per namespace. +> The OPA url currently can´t be set as an environment variable. +> As soon as this is possible you can set cvat.opa.composeCompatibleServiceName +> to false in your value.override.yaml and configure the opa url as additional env. + +Execute following command from repo root directory +### With overrides: +```helm upgrade -n -i --create-namespace ./helm-chart -f ./helm-chart/values.yaml -f ./helm-chart/values.override.yaml``` + +### Without overrides: +```helm upgrade -n -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="" &&\ +HELM_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 +### What is helm and how it is working? +See +### How to setup Minikube +1. Please follow the official Minikube installation [guide](https://minikube.sigs.k8s.io/docs/start/) +1. ```shell + minikube start --addons registry,registry-aliases + ``` +### How to understand what diff will be inflicted by 'helm upgrade'? +You can use for that +### 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. +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 diff --git a/site/content/en/docs/administration/advanced/ldap.md b/site/content/en/docs/administration/advanced/ldap.md index 0e8024e1..783f1a6f 100644 --- a/site/content/en/docs/administration/advanced/ldap.md +++ b/site/content/en/docs/administration/advanced/ldap.md @@ -4,7 +4,7 @@ title: 'LDAP Backed Authentication' linkTitle: 'LDAP Login' -weight: 5 +weight: 40 description: 'Allow users to login with credentials from a central source' --- diff --git a/site/content/en/docs/administration/advanced/mounting_cloud_storages.md b/site/content/en/docs/administration/advanced/mounting_cloud_storages.md index 7f97463b..2ed712e1 100644 --- a/site/content/en/docs/administration/advanced/mounting_cloud_storages.md +++ b/site/content/en/docs/administration/advanced/mounting_cloud_storages.md @@ -1,7 +1,7 @@ --- title: 'Mounting cloud storage' linkTitle: 'Mounting cloud storage' -weight: 10 +weight: 30 description: 'Instructions on how to mount AWS S3 bucket, Microsoft Azure container or Google Drive as a filesystem.' --- diff --git a/site/content/en/docs/administration/advanced/upgrade_guide.md b/site/content/en/docs/administration/advanced/upgrade_guide.md index ee75c754..ba7e1746 100644 --- a/site/content/en/docs/administration/advanced/upgrade_guide.md +++ b/site/content/en/docs/administration/advanced/upgrade_guide.md @@ -1,7 +1,7 @@ --- title: 'Upgrade guide' linkTitle: 'Upgrade guide' -weight: 11 +weight: 60 description: 'Instructions for upgrading CVAT deployed with docker compose' ---