k8s deployment doc

docs/administration/backup.md

@@ -6,9 +6,31 @@ Persistent data of squest are:
 - media folder (used to store images)
 
 An integrated backup solution based on [django-dbbackup](https://django-dbbackup.readthedocs.io/en/master/) is 
-available. Once enabled, backups are placed in the `/app/backup` folder of the `celery-beat` container.
+available. Once enabled, backups are placed in the `/app/backup` folder of one of the django based container.
 
-## Execute a backup manually
+!!! note
+
+    Get more info on dbrestore and mediarestore command arguments on the 
+    [official doc](https://django-dbbackup.readthedocs.io/en/master/commands.html#).
+
+## Using Docker compose
+
+### Enable automatic backup
+
+Enable automatic backup by updating your environment configuration file `docker/environment_variables/squest.env`:
+```bash
+BACKUP_ENABLED=True
+```
+
+By default, backup is performed every day at 1 AM.
+
+!!! note
+
+    Follow the full [configuration documentation](../configuration/squest_settings.md) to know all available flags
+    for the backup service.
+
+
+### Execute a backup manually
 
 Execute the command below against the celery-beat container:
 ```bash
@@ -57,22 +79,7 @@ Output example:
 In this example, data are placed in the mount point `/var/lib/docker/volumes/squest_backup/_data` on the host. 
 Files in this path need to be placed in a safe place.
 
-## Enable automatic backup
-
-Enable automatic backup by updating your environment configuration file `docker/environment_variables/squest.env`:
-```bash
-BACKUP_ENABLED=True
-```
-
-By default, backup is performed every day at 1 AM.
-
-!!! note
-
-    Follow the full [configuration documentation](../configuration/squest_settings.md) to know all available flags
-    for the backup service.
-
-
-## Restore
+### Restore
 
 Start Squest services like for the initial deployment
 ```bash
@@ -100,7 +107,65 @@ docker-compose exec celery-beat python manage.py dbrestore
 docker-compose exec celery-beat python manage.py mediarestore 
 ```
 
-!!! note
+## Using Kubernetes
 
-    Get more info on dbrestore and mediarestore command arguments on the 
-    [official doc](https://django-dbbackup.readthedocs.io/en/master/commands.html#).
+### Enable automatic backup
+
+Enable the backup in `squest.yml` inventory:
+```yaml
+squest_django:
+  backup: 
+    enabled: true
+    crontab: "0 1 * * *"
+```
+
+Run the deployment playbook
+```bash
+ansible-playbook -v -i inventory deploy.yml --tags backup
+```
+
+### Externalize backup via SSH
+
+This feature is optional. By default, the backup cronjob will place backup file into a PVC. Depending on your K8S environment, you might want to externalize them.
+If you want to push those files into an external ssh server you can use the integrated rsync solution.
+
+```yaml
+squest_django:
+  externalize_backup_via_rsync:  # rsync backup files into and external server
+    enabled: true
+    crontab: "30 1 * * *"
+    private_ssh_key: "{{ lookup('file', '/path/to/id_ed25519_squest_k8s_dev') + '\n' }}"
+    ssh_user: "squest_k8s_dev"
+    ssh_server: "remote.server.ssh.net"
+    remote_path: "/backup/squest_k8s_dev/"
+```
+
+### Execute a backup manually
+
+Run the `backup.yml` playbook
+```bash
+ansible-playbook -v -i inventory backup.yml
+```
+
+This command will execute a job in K8S that add a backup of the database and media files into a PVC.
+
+### Restore
+
+To restore Squest. First, deploy the app like for the first deployment using the playbook.
+
+Once Squest is available, copy backup files into django pod
+```bash
+kubectl -n squest cp ~/path/to/db-2023-12-06-182115.dump django-54b69fbb48-wrt9j:/app/backup
+kubectl -n squest cp ~/path/to/media-2023-12-06-182117.tar django-54b69fbb48-wrt9j:/app/backup
+```
+
+Check backup is listed
+```bash
+kubectl -n squest exec -it django-54b69fbb48-wrt9j python manage.py listbackups
+```
+
+Restore by passing backup file name
+```bash
+kubectl -n squest exec -it django-54b69fbb48-wrt9j -- python manage.py dbrestore --database default -i db-2023-12-06-182115.dump
+kubectl -n squest exec -it django-54b69fbb48-wrt9j -- python manage.py mediarestore -i media-2023-12-06-182117.tar
+```

docs/administration/upgrade.md

@@ -4,12 +4,14 @@ This documentation aims at explaining how to perform an upgrade of squest on new
 
 !!! note
 
-    Read the changelog of the version before performing any update to know what are the breaking changes or specific requirements of the new release.
+    Read the changelog and release note of the version before performing any update to know what are the breaking changes or specific requirements of the new release.
 
 !!! note
 
     We recommend performing a manual backup before any upgrade. See the dedicated [backup doc](backup.md)
 
+## Using Docker compose
+
 Stop all containers that use the Squest image
 ```bash
 docker-compose kill django celery-worker celery-beat
@@ -31,3 +33,23 @@ Start back containers
 ```bash
 docker-compose start django celery-worker celery-beat
 ```
+
+## Using Kubernetes
+
+Change the Squest image version in the inventory
+```yaml
+squest_django:
+  image: quay.io/hewlettpackardenterprise/squest:<version>
+```
+
+Run the update playbook
+```bash
+ansible-playbook -v -i inventory update.yml
+```
+
+The playbook will:
+
+- Redirect the traffic to maintenance page
+- Rollout Django containers with the new image
+- Execute database migration
+- Restore traffic to Squest once the app is back available

docs/configuration/squest_settings.md

@@ -3,7 +3,9 @@
 Default settings are configured to provide a testing/development environment. For a production setup it is recommended
 to adjust them following your target environment.
 
-The configuration is loaded from environment variables file placed in the folder `docker/environment_variables`.
+When using docker-compose, the configuration is loaded from environment variables file placed in the folder `docker/environment_variables`.
+
+When using Kubernetes, the configuration need to be placed in the `squest.yml` inventory file in the variable `squest_django/env`.
 
 ## Database
 
@@ -359,4 +361,3 @@ Redis hostname.
 **Default:** `6379`
 
 Redis port.
-

docs/getting_started.md

@@ -1,29 +1,4 @@
 
-Pre-requisites:
-
-- docker
-- docker-compose
-- Instance of Red Hat Ansible Automation Platform or AWX
-
-## Deploy Squest
-
-The current deployment is based on Docker Compose. To run the application, execute the `docker-compose.yml` file:
-```bash
-docker-compose up
-```
-
-Then connect with your web browser to [http://127.0.0.1:8080](http://127.0.0.1:8080)
-The default admin account is `admin // admin`
-
-The default export the port 8080. If you want to use the standard HTTP port 80, update the 
-file `docker-compose.override.yml`.
-```yaml
-services:
-  nginx:
-    ports:
-      - "80:8080"
-```
-
 ## Connect Squest to your controller
 
 The first step consist into adding a **backend controller** (RHAAP/AWX).

docs/configuration/tls.md → docs/installation/docker-compose.md

@@ -1,13 +1,36 @@
-# TLS
+# Docker Compose deployment
 
-This section explains how to add TLS support on Squest.
+## Deploy Squest app
+
+The docker-compose based deployment is a good way to easily and quickly test Squest. This way of deploying is also stable enough to be used in production.
+
+To run the Squest application, execute the `docker-compose.yml` file:
+```bash
+docker-compose up
+```
+
+Then connect with your web browser to [http://127.0.0.1:8080](http://127.0.0.1:8080)
+The default admin account is `admin // admin`
+
+The default export the port 8080. If you want to use the standard HTTP port 80, update the 
+file `docker-compose.override.yml`.
+```yaml
+services:
+  nginx:
+    ports:
+      - "80:8080"
+```
+
+## TLS
+
+This section explains how to add TLS support on Squest when using docker-compose based deployment.
 
 The TLS endpoint is managed by a reverse proxy on top of the default web server.
 This is not the only way to handle this part. Many tools like Nginx, Apache or Traefik could be used, and you are free 
 to use the one you want instead of this proposed configuration.
 The only recommendation we have is to keep the default nginx web server as main http entrypoint.
 
-## TLS using Caddy
+### Using Caddy
 
 [Caddy](https://caddyserver.com/) is a powerful webserver written in Go which provide a 
 [reverse proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#reverse-proxy) feature.

docs/installation/kubernetes.md

@@ -0,0 +1,92 @@
+# Kubernetes deployment
+
+!!!warning
+
+    This deployment is still a beta feature. Feel free to send pull requests to enhance the deployment or give us feedback though Gitter chat or GitHub discutions.
+
+## Pre-requisites
+
+The Kubernetes deployment is wrapped by Ansible. The code has been tested with Ansible version `2.15.5`.
+
+Install Ansible dependencies:
+
+```bash
+ansible-galaxy collection install kubernetes.core
+```
+
+Install Python dependencies:
+```bash
+pip3 install kubernetes
+```
+
+## Ansible inventory
+
+An example inventory file is present in `k8s/inventory/group_vars/all/squest.yml`.
+
+For a minimal installation  you need to at least provide information concerning your Kubernetes environment
+```yaml
+k8s_kubeconfig_path: "/path/to/kubeconfig"
+k8s_cluster_fqdn: "k8s.domain.local"
+squest_namespace: "squest"
+k8s_storage_class: "thin"
+```
+
+## Deploy Squest using Ansible
+
+Run the `deploy` playbook against your inventory config file:
+
+```bash
+cd k8s
+ansible-playbook -v -i inventory deploy.yml
+```
+
+**Tags:**
+
+| Name        | Description                                 |
+|-------------|---------------------------------------------|
+| namespace   | Create the Squest namespace                 |
+| utils       | Install CRD utils (certmanager, Prometheus) |
+| db          | Deploy mariadb CRDs, operator and server    |
+| rabbitmq    | Deploy rabbitmq CRDs, operator and service  |
+| redis       | Deploy redis CRDs, operator and service     |
+| django      | Deploy Squest application                   |
+| celery      | Deploy Celery components (worker and beat)  |
+| maintenance | Deploy nginx maintenance pod                |
+| backup      | Deploy backup cron jobs                     |
+
+
+!!! note
+
+    By default, the deployment uses **nginx ingress controller** to configure the Squest external access on `squest.{{ k8s_cluster_fqdn }}`.
+
+## Configuration
+
+### Squest config
+
+The [Squest configuration](../configuration/squest_settings.md) is injected as environment variables. The environment is placed in `squest.yml` as `env` flag like the following:
+```yaml
+squest_django:
+  env:
+    TZ: "Europe/Paris"
+    DB_HOST: "mariadb"
+    DB_PORT: "3306"
+    REDIS_CACHE_HOST: "rfrm-redis"
+    DEBUG: "true"
+    DB_USER: "{{ squest_db.user }}"
+    DB_PASSWORD: "{{ squest_db.password }}"
+    WAIT_HOSTS: "mariadb:3306,rabbitmq:5672"
+```
+
+### Use your own ingress
+
+By default, the playbook will configure an ingress that point to `squest.{{ k8s_cluster_fqdn }}` based on the [nginx ingress controller](https://docs.nginx.com/nginx-ingress-controller/).
+
+To expose the Squest URL by using your own ingress controller, you can either update `annotations` (when the target controller can be managed by annotations) or disable the default ingress to declare then your ingress rules on your own.
+
+To disable the default ingress configuration, in the `squest.yml` inventory file:
+```yaml
+squest_django:
+  image: "quay.io/hewlettpackardenterprise/squest:latest"
+  ingress:
+    enabled: false
+```