docs: update guides (#1049)

.docs/content/0.armonik/0.index.md

@@ -1 +1,17 @@
 # ArmoniK
+
+ArmoniK is a high throughput compute grid project using Kubernetes. 
+
+It provides a reference architecture that can be used to build and adapt a modern high throughput compute solution on-premise or using Cloud services, allowing users to submit high volumes of short and long-running tasks and scaling environments dynamically.
+
+::alert{type="info"}
+This project is an Open Source ([Apache 2.0 License](https://github.com/aneoconsulting/ArmoniK/blob/main/LICENSE)).
+::
+
+## When should I use ArmoniK
+
+ArmoniK should be used when the following criteria are met:
+
+1. A high task throughput is required (from 250 to 10,000+ tasks per second).
+2. The tasks are loosely coupled.
+3. Variable workloads (tasks with heterogeneous execution times) are expected and the solution needs to dynamically scale with the load.

.docs/content/2.guide/1.how-to/_dir.yml

@@ -0,0 +1,2 @@
+title: How to
+navigation.icon: ph:question-duotone

.docs/content/2.guide/authentication-configuration-guide.md → .docs/content/2.guide/1.how-to/how-to-configure-authentication.md

@@ -1,14 +1,14 @@
-# **ArmoniK Authentication Configuration Guide**
+# How to configure authentication?
 
 This guide aims to present the setup of the authentication framework within ArmoniK.
 
-## **What authentication means in ArmoniK**
+## What authentication means in ArmoniK
 
 Authentication in ArmoniK is about security. Without authentication, anyone with access to the gRPC endpoints can send requests to it, potentially running undesirable workloads. 
 
 ArmoniK uses client certificates to authenticate users. Authentication allows users who have the right certificates to send requests to the different endpoints. Different certificates can grant different permissions, based on a User-Role-Permission system.
 
-## **Authentication options in ArmoniK**
+## Authentication options in ArmoniK
 
 It is possible to setup the authentication in different ways when deploying ArmoniK:
 
@@ -18,7 +18,7 @@ It is possible to setup the authentication in different ways when deploying Armo
 - **Ingress + Control plane authentication**: Only users with valid client certificates can send requests to the endpoints. Two users are created by default, one with access to all endpoints and requests and one with access only to the monitoring endpoints and requests. These certificates are generated by the ArmoniK deployment (See [How to setup authentication using default certificates](#how-to-setup-authentication-using-default-certificates)).
 - **Ingress + Control plane authentication, custom CA**: Only the users with valid client certificates can send requests to the endpoints. Users, roles and permissions are setup manually. Certificates are **not generated** by the deployment scripts, meaning the client certificate authority must be provided during deployment and user certificates are not automatically generated (See [How to setup your own certificates for authentication](#how-to-setup-your-own-certificates-for-authentication) for details).
 
-## **Authentication options features table**
+## Authentication options features table
 |               Authentication Option               | No client certificate | Method access restriction | Autogenerated Certificates | Custom roles | Custom certificates |
 |:-------------------------------------------------:|:---------------------:|:-------------------------:|:--------------------------:|:------------:|:-------------------:|
 |                 No authentication                 |          ✔️           |           ❌             |             ❌             |      ❌     |         ❌          |
@@ -27,7 +27,7 @@ It is possible to setup the authentication in different ways when deploying Armo
 |      Ingress + Control plane authentication       |          ❌           |           ✔️             |             ✔️             |      ❌     |         ❌          |
 | Ingress + Control plane authentication, custom CA |          ❌           |           ✔️             |             ❌             |      ✔️     |         ✔️          |
 
-# **Deployment configuration**
+# Deployment configuration
 
 For each of the following configuration, the required parameters in your [```armonik/parameters.tfvars```](https://github.com/aneoconsulting/ArmoniK/blob/main/infrastructure/quick-deploy/localhost/armonik/parameters.tfvars) to specify are:
 
@@ -38,10 +38,10 @@ For each of the following configuration, the required parameters in your [```arm
 - ```authentication.require_authorization```: Controls whether the control plane checks for user permissions. If used it needs the ```authentication.require_authentication``` to be true.
 - ```authentication.authentication_datafile```: Empty if the default generated certificates will be used, otherwise is a path to a json configuration file (See [How to create a Json authentication configuration file](#how-to-create-a-json-authentication-configuration-file))
 
-## **How to setup a deployment without authentication**
+## How to setup a deployment without authentication
 
 | Configuration parameter                      |    Value    |
-|:---------------------------------------------|:-----------:|
+|---------------------------------------------|-----------|
 | ```ingress.mTLS```                           | ```false``` |
 | ```ingress.generate_client_cert```           | ```false``` |
 | ```ingress.custom_client_ca_file```          |  ```""```   |
@@ -51,10 +51,10 @@ For each of the following configuration, the required parameters in your [```arm
 
 Using this configuration, anyone with access to the endpoints can send any request.
 
-## **How to setup mTLS authentication using a default certificate authority and a single user certificate**
+## How to setup mTLS authentication using a default certificate authority and a single user certificate
 
 | Configuration parameter                      |    Value    |
-|:---------------------------------------------|:-----------:|
+|---------------------------------------------|-----------|
 | ```ingress.mTLS```                           | ```true```  |
 | ```ingress.generate_client_cert```           | ```false``` |
 | ```ingress.custom_client_ca_file```          |  ```""```   |
@@ -64,9 +64,9 @@ Using this configuration, anyone with access to the endpoints can send any reque
 
 Using this configuration, a default client certificate will be generated. Anyone can access the endpoints using this certificate. Since this certificate will be put in the database by default, the parameter ```authentication.require_authentication``` can be set to true or false. The default client certificate created is ```infrastructure/quick-deploy/localhost/armonik/generated/certificates/ingress/client.submitter.crt```
 
-## **How to setup mTLS authentication using a custom certificate authority**
+## How to setup mTLS authentication using a custom certificate authority
 | Configuration parameter                      |    Value    |
-|:---------------------------------------------|:-----------:|
+|---------------------------------------------|-----------|
 | ```ingress.mTLS```                           | ```true``` |
 | ```ingress.generate_client_cert```           | ```false``` |
 | ```ingress.custom_client_ca_file```          |  ```Path to client ca.pem```   |
@@ -76,9 +76,9 @@ Using this configuration, a default client certificate will be generated. Anyone
 
 Using this configuration, the specified ```ca.pem``` will be used to authenticate user certificates. The client certificates **are not generated** by the deployment.
 
-## **How to setup authentication using default certificates**
+## How to setup authentication using default certificates
 | Configuration parameter                      |    Value    |
-|:---------------------------------------------|:-----------:|
+|---------------------------------------------|-----------|
 | ```ingress.mTLS```                           | ```true```  |
 | ```ingress.generate_client_cert```           | ```true```  |
 | ```ingress.custom_client_ca_file```          |  ```""```   |
@@ -88,10 +88,10 @@ Using this configuration, the specified ```ca.pem``` will be used to authenticat
 
 Default certificates are generated alongside the automatically generated client certificate authority. In this case, two certificates are generated in the ```infrastructure/quick-deploy/localhost/armonik/generated/certificates/ingress``` folder : ```client.submitter.crt``` which corresponds to a user with all permissions, and ```client.monitoring.crt``` which corresponds to a user with only monitoring permissions. You can modify the default users and roles created by modifying the module file [armonik/authentication-roles-default.tf](https://github.com/aneoconsulting/ArmoniK/blob/main/infrastructure/modules/armonik/authentication-roles-default.tf).
 
-## **How to setup your own certificates for authentication**
+## How to setup your own certificates for authentication
 
 | Configuration parameter                      |    Value    |
-|:---------------------------------------------|:-----------:|
+|---------------------------------------------|-----------|
 | ```ingress.mTLS```                           | ```true```  |
 | ```ingress.generate_client_cert```           | ```false``` |
 | ```ingress.custom_client_ca_file```          |  ```Path to client ca.pem```   |
@@ -101,7 +101,7 @@ Default certificates are generated alongside the automatically generated client
 
 Using this configuration, the specified ```ca.pem``` will be used to authenticate the user certificates. The client certificates are **not generated** by the deployment. Each certificate is attributed to a specific user with specific roles. Each role has specific permissions, allowing or denying the user access to specific endpoints. For each certificate, the user and role need to be described in the given json configuration file (See [How to create a Json authentication configuration file](#how-to-create-a-json-authentication-configuration-file)). 
 
-### **How to create a Json authentication configuration file**
+### How to create a Json authentication configuration file
 
 The Json authentication configuration file must have the following format (note that the format is **case sensitive**):
 
@@ -137,7 +137,7 @@ The resulting configuration is stored in the MongoDB database. If the database i
 kubectl -n armonik get job authentication-in-database -o json | jq "del(.spec.selector)" | jq "del(.spec.template.metadata.labels)" | kubectl -n armonik replace --force -f -
 ```
 
-### **Json authentication configuration example**
+### Json authentication configuration example
 
 The following json is an example defining two users, with their own different roles. The role ```Submitter``` does have all the permissions on every current endpoints. The role ```Monitoring``` does have all permissions related to monitoring duties, but cannot start or stop tasks or sessions. Each user has its own certificate.
 
@@ -215,4 +215,4 @@ The following json is an example defining two users, with their own different ro
     }
   ],
 }
-```
+```

.docs/content/2.guide/Partitionning.md → .docs/content/2.guide/1.how-to/how-to-configure-partitions.md

@@ -1,10 +1,8 @@
-<!-- TODO: rename and reorganize -->
-
-# **ArmoniK Partitioning Configuration Guide**
+# How to configure partitions?
 
 This guide aims to present the setup and usage of the partitions within ArmoniK.
 
-## **What partitioning means in ArmoniK**
+## What partitioning means in ArmoniK
 
 Partitions are sets of pods with their own configuration, their own task queue and their own scaling rules. Partitioning is useful in the following use-cases (non-exhaustive):
 
@@ -14,7 +12,7 @@ Partitions are sets of pods with their own configuration, their own task queue a
 
 
 
-## **How to setup the partitioning in terraform**
+## How to setup the partitioning in terraform
 
 
 To install and configure the partioning there are some modifications to implement in the deployment scripts.  With the implementation in the 2.9 version, the partioning is static. That means, that the partitions have to be defined and deployed at the same time than the ArmoniK infrastructure and cannot be changed without a redeployment and a new modification of the parameters files.
@@ -135,7 +133,7 @@ compute_plane = {
 }
 ```
 
-## **Use a partition when submitting tasks with UnifiedAPI**
+## Use a partition when submitting tasks with UnifiedAPI
 
 The partition to use is defined when creating the session, by setting the default `TaskOptions` of the session. The partition must exist, otherwise an error is raised.
 
@@ -164,9 +162,11 @@ Service = ServiceFactory.CreateService(Props, loggerFactory);
 
 If you set the `PartitionId` to empty (`""`), the default partition will be used.
 
-**Warning:** It is an error to set the `PartitionId` to `null`.
+::alert{type="warning"}
+It is an error to set the `PartitionId` to `null`.
+::
 
-## **Use a partition when submitting tasks with native gRPC API**
+## Use a partition when submitting tasks with native gRPC API
 
 In order to use partitions with the native gRPC API, you must specify at the session creation the partitions that will be used by the tasks of this session. This is done with the field `PartitionIds` which is the list of the partitions available to the tasks. You can set it to an empty list or a list containing only a single empty string to use the default partition during the session. You can also define the default partition to be used by the tasks of the session in the `defaultTaskOption`. An empty `DefaultTaskOption.PartitionId` is replaced by the default partition of the *cluster*. If a partition does not exist, an error is raised.
 
@@ -199,4 +199,6 @@ var createTaskReply = await submitterClient.CreateTasksAsync(
 );
 ```
 
-**Warning:** It is an error to set the `PartitionId` to `null`.
+::alert{type="warning"}
+It is an error to set the `PartitionId` to `null`.
+::

.docs/content/2.guide/using-seq.md → .docs/content/2.guide/1.how-to/how-to-configure-seq.md

@@ -1,13 +1,11 @@
-<!-- TODO: reorganize -->
+# How to configure SEQ?
 
-# Configure Seq
-
-If you want to access outside your kubernetes cluster, you have to configure seq to make it accessible from outside.
+If you want to access outside your Kubernetes cluster, you have to configure Seq to make it accessible from outside.
 To do so, you have to set this service (`seq_web` in [seq.tf](../old/armonik-deployments/armonik/modules/armonik-components/seq.tf#L92) ) as `LoadBalancer` instead of `ClusterIP`.
 
 Then, redeploy.
 
-# Connexion
+## Connexion
 
 When you perform the command:
 ```bash
@@ -21,15 +19,15 @@ If you enabled the authentication of seq, the default credentials are the follow
 
 You can then change the password in `settings` -> `system`.
 
-# Useful requests
+## Useful requests
 
 The application name for the control plane is `ArmoniK.Control`. (Application = 'ArmoniK.Control')
 The application name for the polling agent is `ArmoniK.Compute.PollingAgent`. (Application = 'ArmoniK.Compute.PollingAgent')
 The application name for the worker is `ArmoniK.Compute.Worker`. (Application = 'ArmoniK.Compute.Worker')
 
-# Troubleshoot
+## Troubleshoot
 
-If you use docker as the kubernetes backend, you should configure the logging driver of docker to `json-file`.
+If you use docker as the Kubernetes backend, you should configure the logging driver of docker to `json-file`.
 Otherwise, the logs will remain empty (fluent-bit will not be able to fetch logs).
 
 https://docs.docker.com/config/containers/logging/configure/#configure-the-default-logging-driver

.docs/content/2.guide/image-versions.md → .docs/content/2.guide/default-images.md

@@ -1,3 +1,6 @@
+<!-- TODO: need have a new title -->
+<!-- TODO: need to create a page where the all in one deployment is explain -->
+
 # Default images
 
 The all-in-one terraform deployments support to omit the image names and tags in the tfvars.
@@ -12,7 +15,7 @@ For third-party images, the default tag of an image is defined in [`image_tags`]
 You are still be able to specify custom image names and/or image tags in your tfvars if you want, without needing to modify [`versions.tfvars.json`](../versions.tfvars.json).
 If you try to use an image name that is not listed in [`versions.tfvars.json`](../versions.tfvars.json), you are required to also specify a tag for this image.
 
-# Examples
+## Examples
 
 All the examples are for the all-in-one local deployment for mongodb, with the following default versions:
 ```json
@@ -42,7 +45,7 @@ All the examples are for the all-in-one local deployment for mongodb, with the f
 
 Specifying the image and its version within the tfvars (ex: [`parameters.tfvars`](../infrastructure/quick-deploy/aws/all/parameters.tfvars))
 
-## Use the default image and tag:
+### Use the default image and tag:
 ```terraform
 mongodb = {
 }
@@ -56,7 +59,7 @@ control_plane = {
 - control_plane: `dockerhubaneo/armonik_control:0.8.3`
 
 
-## Use the default image with a custom tag:
+### Use the default image with a custom tag:
 ```terraform
 mongodb = {
   image_tag = "6.0"
@@ -71,7 +74,7 @@ control_plane = {
 - mongodb: `mongo:6.0`
 - control_plane: `dockerhubaneo/armonik_control:0.8.0`
 
-## Use a custom image:
+### Use a custom image:
 ```terraform
 mongodb = {
   image_name = "custom_registry/mongo"
@@ -88,7 +91,7 @@ control_plane = {
 - mongodb: `custom_registry/mongo:6.0`
 - control_plane: `custom_registry/custom_armonik_control:0.8.3`
 
-## Special case of the workers
+### Special case of the workers
 
 There is no default image for the workers, but you can still omit the tag if the image is listed in [`versions.tfvars.json`](../versions.tfvars.json):
 

.docs/content/2.guide/Happy-Flow-Diagram-Sequence.md → .docs/content/2.guide/happy-flow-diagram-sequence.md

@@ -1,3 +1,5 @@
+# Happy Flow Diagram Sequence
+
 <Mermaid>
 sequenceDiagram
     #title ArmoniK Happy Flow Sequence