Merge pull request #236 from stakater/improve-docs

improve templates and add concepts

content/architecture/architecture.md

@@ -1,4 +1,4 @@
-# MTO Architecture
+# Architecture
 
 The Multi-Tenant Operator (MTO) is a comprehensive system designed to manage multi-tenancy in Kubernetes environments. Following is the architecture of the MTO:
 

content/architecture/concepts.md

@@ -0,0 +1,31 @@
+# Concepts
+
+Here are the key concepts of Multi-Tenant Operator (MTO):
+
+## Tenant
+
+A **Tenant** represents a logical grouping of namespaces, users, and resources within a Kubernetes cluster, enabling isolated environments for teams or projects. It defines access controls, resource quotas, and namespace configurations specific to each tenant.
+
+## Quota
+
+The **Quota** enforces resource limits for tenants, such as CPU, memory, and storage, ensuring fair allocation. It also defines minimum and maximum resource usage per pod or container within tenant namespaces.
+
+## Template
+
+A **Template** is a reusable blueprint in Multi-Tenant Operator (MTO) that defines configurations for Kubernetes resources. It supports raw manifests, Helm charts, or resource mappings, enabling standardization and automation across multiple tenants.
+
+## Template Instance (TI)
+
+A **Template Instance** is a concrete implementation of a **Template**, created with specific parameters tailored for a particular tenant or use case. It generates actual Kubernetes resources based on the defined template.
+
+## Template Group Instance (TGI)
+
+A **Template Group Instance** works on a particular set of namespaces based on the mentioned labels, taking **Template** as a reference for the resources to be deployed. It simplifies managing multiple interdependent resources for complex tenant setups.
+
+## Extensions
+
+**Extensions** enhance MTO functionality by integrating external services like ArgoCD. They allow seamless configuration of AppProjects for tenants, extending multi-tenant workflows.
+
+## Resource Supervisor
+
+The **Resource Supervisor** manages the hibernation of deployments and stateful sets, enabling scaling down during user defined schedule or by manual trigger, optimizing resource utilization and reducing costs.

content/crds-api-reference/template.md

@@ -1,24 +1,34 @@
 # Template
 
-## Cluster scoped resource
+Templates are used to initialize Namespaces, share common resources across namespaces, and map secrets/configmaps from one namespace to other namespaces.
+
+They can contain pre-defined parameters such as `${namespace}`/`${tenant}`.
+
+Also, you can define custom variables in `Template`, `TemplateInstance` and `TemplateGroupInstance`. The parameters defined in `Templates` are overwritten the values defined in `TemplateInstance` and `TemplateGroupInstance`.
+
+## Specification
+
+`Template` Custom Resource (CR) supports three key methods for defining and managing resources: `manifests`, `helm`, and `resource mapping`. Let’s dive into each method, their differences, and their use cases:
+
+### 1. Manifests
+
+This approach uses raw Kubernetes manifests (YAML files) that specify resources directly in the template.
+
+#### How It Works
+
+* The template includes the actual YAML specifications of resources like `Deployment`, `Service`, `ConfigMap`, etc.
+* These manifests are applied as-is or with minor parameter substitutions (e.g., dynamically populated `{tenant}` and `{namespace}` variables wherever added or user defined parameters).
+
+#### Use Cases
+
+* Best for straightforward and simple resources where you don't need advanced templating logic or dependency management.
+* Ideal when the resource definitions are static or have minimal customization needs.
+
+#### Example
 
 ```yaml
 apiVersion: tenantoperator.stakater.com/v1alpha1
 kind: Template
-metadata:
-  name: redis
-resources:
-  helm:
-    releaseName: redis
-    chart:
-      repository:
-        name: redis
-        repoUrl: https://charts.bitnami.com/bitnami
-    values: |
-      redisPort: 6379
----
-apiVersion: tenantoperator.stakater.com/v1alpha1
-kind: Template
 metadata:
   name: networkpolicy
 parameters:
@@ -59,35 +69,68 @@ resources:
           ports:
           - protocol: TCP
             port: 5978
----
+```
+
+### 2. Helm
+
+This method integrates Helm charts into the template, allowing you to leverage Helm's templating capabilities and package management.
+
+#### How It Works
+
+* The `Template` references a Helm chart.
+* Values for the Helm chart can be passed by the `values` field.
+* The Helm chart generates the necessary Kubernetes resources dynamically at runtime.
+
+#### Use Cases
+
+* Best for complex resource setups with interdependencies (e.g., a microservice with a Deployment, Service, Ingress, and Configmap).
+* Useful for resources requiring advanced templating logic or modular packaging.
+* Great for managing third-party tools or applications (e.g., deploying Prometheus, Keycloak, or databases).
+
+#### Example
+
+```yaml
 apiVersion: tenantoperator.stakater.com/v1alpha1
 kind: Template
 metadata:
-  name: resource-mapping
+  name: redis
 resources:
-  resourceMappings:
-    secrets:
-      - name: secret-s1
-        namespace: namespace-n1
-    configMaps:
-      - name: configmap-c1
-        namespace: namespace-n2
+  helm:
+    releaseName: redis
+    chart:
+      repository:
+        name: redis
+        repoUrl: https://charts.bitnami.com/bitnami
+    values: |
+      redisPort: 6379
 ```
 
-Templates are used to initialize Namespaces, share common resources across namespaces, and map secrets/configmaps from one namespace to other namespaces.
+### 3. Resource Mapping
 
-* They either contain one or more Kubernetes manifests, a reference to secrets/configmaps, or a Helm chart.
-* They are being tracked by TemplateInstances in each Namespace they are applied to.
-* They can contain pre-defined parameters such as ${namespace}/${tenant} or user-defined ${MY_PARAMETER} that can be specified within an TemplateInstance.
+This approach maps secrets and configmaps from one tenant's namespace to another tenant's namespace, or within a tenant's namespace.
 
-Also, you can define custom variables in `Template` and `TemplateInstance` . The parameters defined in `TemplateInstance` are overwritten the values defined in `Template` .
+#### How It Works
 
-Manifest Templates: The easiest option to define a Template is by specifying an array of Kubernetes manifests which should be applied when the Template is being instantiated.
+* The template contains mappings to pre-existing resources (secrets and configmaps only).
 
-Helm Chart Templates: Instead of manifests, a Template can specify a Helm chart that will be installed (using Helm template) when the Template is being instantiated.
+#### Use Cases
 
-Resource Mapping Templates: A template can be used to map secrets and configmaps from one tenant's namespace to another tenant's namespace, or within a tenant's namespace.
+* Ideal for maintaining consistency across shared resources without duplicating definitions.
+* Best when resources already exist.
 
-## Mandatory and Optional Templates
+#### Example
 
-Templates can either be mandatory or optional. By default, all Templates are optional. Cluster Admins can make Templates mandatory by adding them to the `spec.templateInstances` array within the Tenant configuration. All Templates listed in `spec.templateInstances` will always be instantiated within every `Namespace` that is created for the respective Tenant.
+```yaml
+apiVersion: tenantoperator.stakater.com/v1alpha1
+kind: Template
+metadata:
+  name: resource-mapping
+resources:
+  resourceMappings:
+    secrets:
+      - name: secret-s1
+        namespace: namespace-n1
+    configMaps:
+      - name: configmap-c1
+        namespace: namespace-n2
+```

content/installation/aws-eks.md

@@ -1,6 +1,6 @@
 # On EKS
 
-This document covers how to link Multi Tenant Operator with an [Amazon EKS (Elastic Kubernetes Service)](https://aws.amazon.com/eks/) cluster.
+This document covers how to deploy Multi Tenant Operator with an [Amazon EKS (Elastic Kubernetes Service)](https://aws.amazon.com/eks/) cluster.
 
 ## Prerequisites
 

content/installation/azure-aks.md

@@ -1,6 +1,6 @@
 # On AKS
 
-This document covers how to link Multi Tenant Operator with an [AKS (Azure Kubernetes Service)](https://azure.microsoft.com/en-us/products/kubernetes-service/) cluster.
+This document covers how to deploy Multi Tenant Operator with an [AKS (Azure Kubernetes Service)](https://azure.microsoft.com/en-us/products/kubernetes-service/) cluster.
 
 ## Prerequisites
 

theme_override/mkdocs.yml

@@ -31,6 +31,7 @@ nav:
       - installation/helm.md
   - Architecture:
      - architecture/architecture.md
+     - architecture/concepts.md     
   - pricing.md
   - Tutorials:
       - Configuring Tenants: