WIP: Attempt to add some Azimuth architecture docs into config docs

docs/architecture.md

@@ -0,0 +1,157 @@
+# Azimuth Architecture
+
+These docs look at the Azimuth Architecture from an operator's point of view.
+
+For more details on Azimuth Architecture from a developer point of view, please see the
+[Azimuth Architecture Developer Docs](https://github.com/stackhpc/azimuth/blob/master/docs/architecture.md).
+
+## Azimuth Components
+
+The following sections highlight the key parts of an Azimuth deployment,
+working through them in the order that they are setup by the Ansible automation.
+
+### Config git repository
+
+The desired state is recorded in git.
+Updating involves merging in the latest changes from the
+[azimuth-config reference configuration](https://github.com/stackhpc/azimuth-config).
+
+It is recommmended to use a single git repository
+for all your [Azimuth environments](./environments.md),
+e.g. for both staging and production.
+Similarly, `git-crypt` should be used
+for [encrypting secrets](./repository/secrets.md).
+
+### Control host
+
+This is where Ansible is run. Ideally, this should be from within an ephemeral runner
+created by [GitHub or GitLab automation](./deployment/automation.md). The control host must
+be able to reach the OpenStack public API endpoints for the target cloud.
+
+### Ansible collection
+
+The [azimuth-ops](https://github.com/stackhpc/ansible-collection-azimuth-ops/) Ansible collection
+contains all of the roles and playbooks required to deploy and update Azimuth. The
+[provision](https://github.com/stackhpc/ansible-collection-azimuth-ops/blob/main/playbooks/provision.yml)
+playbook provides the main entry point into the Ansible collection.
+
+### Deployment OpenStack Project
+
+Azimuth management infrastructure is typically run within the OpenStack cloud it is targeting.
+
+To isolate your Azimuth manangement infrastructure from other workloads,
+it is good practice to run Azimuth within a separate dedicated OpenStack project.
+Moreover, production and staging deployments are typically
+given their own separate OpenStack project.
+
+### Seed VM with K3S
+
+This VM is created in the deployment OpenStack project using OpenTofu.
+A light-weight [K3S](https://k3s.io/) cluster is run on the seed node, with all
+K3S data stored in a dedicated Cinder volume mounted at `/var/lib/rancher/`,
+allowing the seed VM to be upgraded or recreated without data loss (as long as the
+Cinder volume is preserved).
+
+For single node deployments, all Azimuth components run on the seed's K3S cluster.
+
+For highly-available (HA) deployments, K3S is instead used to run a
+[Cluster API management cluster](https://cluster-api.sigs.k8s.io/user/concepts#management-cluster).
+which in turn uses [CAPI Helm charts](https://github.com/stackhpc/capi-helm-charts)
+to create a highly-available Kubernetes cluster for hosting the Azimuth management components.
+
+!!! warning
+
+    HA deployments require that [Octavia](https://docs.openstack.org/octavia/latest/index.html)
+    is available on the target cloud to provide load-balancers for Azimuth components.
+
+    For single node deployment, the seed VM is given a floating IP.
+
+### Seed VM OpenTofu state
+
+An [OpenTofu remote state store](./repository/terraform.md) must be configured
+in order to persist the OpenTofu state used to create the Seed VM. This state store is accessed,
+for example, when [accessing the seed VM](https://stackhpc.github.io/azimuth-config/debugging/access-k3s/).
+
+### Azimuth Management Kubernetes Cluster
+
+For HA deployments, we run all Azimuth services in the HA K8s cluster.
+For the single node deployment, we run everything in K3s on the seed VM.
+For simplicity we call this the Azimuth Management Cluster.
+
+For more details about the architecture of the Azimuth services, please see the
+[Azimuth Architecture Developer Docs](https://github.com/stackhpc/azimuth/blob/master/docs/architecture.md).
+
+### CaaS images, templates and workloads
+
+TODO
+
+### Kubernetes images, templates and workloads
+
+TODO
+
+### Kubernetes application templates
+
+TODO
+
+### Zenith
+
+TODO
+
+### Azimuth Ingress and SSL
+
+Most Azimuth traffic goes through a single wildcard DNS entry.
+This includes: ...
+
+TODO
+
+### Azimuth Monitoring and Alerting
+
+TODO
+
+### Workload OpenStack Projects
+
+When a user logs into Azimuth, they select a tenancy.
+This maps to a specific OpenStack Project.
+
+### Azimuth CRDs
+
+Azimuth doesn't have a database, as such.
+
+TODO
+
+
+### Backup and Disaster recovery
+
+TODO
+
+## Authentication and Authorization
+
+Azimuth currently delegates all authentication and authorization to OpenStack.
+
+In many ways, you can consider the Azimuth to be
+a sophisticated OpenStack client,
+similar to Horizon and the OpenStack CLI.
+
+Any user with access to an OpenStack project,
+will see that project listed as a tenancy within Azimuth.
+In addition, people with access to that OpenStack project
+get full access to all platforms created within that tenancy.
+
+We make an assumption that all users with access to the OpenStack
+API can elevate themselves to have "root access" within any VM
+in that OpenStack project. This is a feature of OpenStack's APIs.
+
+There are plans for "managed" tenancies within Azimuth,
+where users do not get "root access".
+This will depend on OpenStack efforts around adding the
+project-reader role into 2024.1 release.
+For more details, please see
+[OpenStack consistent RBAC](https://governance.openstack.org/tc/goals/selected/consistent-and-secure-rbac.html).
+
+### Upstairs and Downstairs
+
+TODO
+
+### Keycloak
+
+TODO

docs/best-practice.md

@@ -1,14 +1,18 @@
-# Best practice for deployments
+# Getting started with production deployment
 
 This document guides you through the process of setting up a production-ready Azimuth
 deployment following recommended best practice.
 
-## Prerequisites
+To quickly try out Azimuth on your OpenStack cloud, you can follow [these instructions](./try.md)
+to get a simple deployment running within a single VM in your OpenStack cloud.
 
-Before proceeding with an Azimuth deployment, you should ensure that the target cloud
-meets the [prerequisites](./configuration/01-prerequisites.md).
+## 1. Check Prerequisites
 
-## OpenStack projects
+Before proceeding with an Azimuth deployment,
+ensure you meet the required
+[prerequisites](./configuration/01-prerequisites.md).
+
+### Create OpenStack projects
 
 Azimuth is usually deployed on the cloud that is being targeted for workloads. It is
 recommended to have three OpenStack projects for a production Azimuth deployment, to contain:
@@ -22,7 +26,7 @@ The production and staging projects must have
 deployment. The required quota in the CI/CD project will depend on the number of
 proposed changes that are open concurrently.
 
-## Repository
+## 2. Create your Azimuth Configuration Git Repository
 
 Before building your Azimuth configuration, you must first
 [set up your configuration repository](./repository/index.md), including initialising
@@ -32,20 +36,9 @@ It is recommended to use a
 [feature branch workflow](./repository/index.md#making-changes-to-your-configuration)
 to make changes to your Azimuth configuration in a controlled way.
 
-## OpenTofu state
+## 3. Define your Environments
 
-Azimuth deployments use [OpenTofu](https://opentofu.org/), an open-source fork of
-[Terraform](https://www.terraform.io/), to manage some parts of the infrastructure.
-
-A [remote state store](./repository/opentofu.md#remote-state) must be configured in
-order to persist the OpenTofu state across playbook executions. If GitLab is being
-used for the Azimuth configuration repository, it is recommended to use
-[GitLab-managed Terraform state](./repository/opentofu.md#gitlab) for this. If not,
-[S3](./repository/opentofu.md#s3) is the preferred approach.
-
-## Environments
-
-An Azimuth configuration repository contains multiple [environments](./environments.md),
+Your Azimuth configuration git repository contains multiple [environments](./environments.md),
 some of which contain common configuration ("mixin" environments), and some of which
 represent a deployment ("concrete" environments).
 
@@ -83,7 +76,49 @@ base --> ha --> site --> site-ha --> production
 
 with only necessary differences configured in each environment, e.g. the ingress base domain, between `staging` and `production`.
 
-## Continuous delivery
+## 4. Populate required group_vars
+
+Before looking to customize your local deployment,
+we recommend you first get a minimal configuration
+up and running.
+
+Above you created the following environments:
+
+* site
+* site-ha
+* aio, staging and production
+
+You now need to populate the required group_vars
+such aio, staging and production environments can be deployed.
+
+When building an environment for the first time,
+it is recommended to follow each configuration documentation page in order,
+beginning with the
+[Deployment method](./configuration/02-deployment-method.md).
+A quick overview of the minimal required parameters can be seen in the
+(example environment)[https://github.com/stackhpc/azimuth-config/tree/devel/environments/example/inventory/group_vars/all].
+
+## 5. Review Production Good Practice
+
+### 5.1. OpenTofu state
+
+Azimuth deployments use [OpenTofu](https://opentofu.org/), an open-source fork of
+[Terraform](https://www.terraform.io/), to manage some parts of the infrastructure.
+
+A [remote state store](./repository/opentofu.md#remote-state) must be configured in
+order to persist the OpenTofu state across playbook executions. If GitLab is being
+used for the Azimuth configuration repository, it is recommended to use
+[GitLab-managed Terraform state](./repository/opentofu.md#gitlab) for this. If not,
+[S3](./repository/opentofu.md#s3) is the preferred approach.
+
+### 5.2. Setup Monitoring Alerts
+
+Ensure you can access your monitoring and alerts are flowing somewhere
+you will notice them.
+
+TODO...
+
+### 5.3. Setup Continuous delivery
 
 A production Azimuth deployment should use [continuous delivery](./deployment/automation.md),
 where changes to the configuration are automatically deployed to the `aio` and `staging`
@@ -103,7 +138,7 @@ A
 [sample GitLab CI/CD configuration](https://github.com/stackhpc/azimuth-config/tree/stable/.gitlab-ci.yml.sample)
 is provided that implements this workflow for GitLab-hosted repositories.
 
-## Disaster recovery
+### 5.4. Backups and Disaster recovery
 
 Azimuth uses [Velero](https://velero.io/) to backup the data that is required to restore an
 Azimuth instance in the event of a catastrophic failure. This functionality is not enabled by
@@ -112,8 +147,10 @@ default, as it requires credentials for an S3 bucket in which the backups will b
 It is recommended that [disaster recovery is enabled](./configuration/15-disaster-recovery.md) for
 a production deployment.
 
-## Configuration
+### 5.5. Do you first upgrade
+
+TODO
+
+## 6. Join the community!
 
-You are now ready to begin adding configuration to your environments. When building an environment
-for the first time, it is recommended to follow each documentation page in order, beginning with
-the [Deployment method](./configuration/02-deployment-method.md).
+TODO

docs/index.md

@@ -1,7 +1,18 @@
 # Azimuth Operator Documentation
 
 This documentation describes how to manage deployments of
-[Azimuth](https://github.com/stackhpc/azimuth), including all the required dependencies.
+[Azimuth](https://github.com/stackhpc/azimuth),
+including all the required dependencies.
+
+## Try Azimuth on your OpenStack cloud
+
+If you have access to a project on an OpenStack cloud, you can try Azimuth!
+You don't need admin level access.
+
+To try out Azimuth on your OpenStack cloud, you can follow [these instructions](./try.md)
+to get a simple deployment running within a single VM in your OpenStack cloud.
+
+## Getting started with a Production Azimuth
 
 Azimuth is deployed using [Ansible](https://www.ansible.com/) with playbooks from the
 [azimuth-ops Ansible collection](https://github.com/stackhpc/ansible-collection-azimuth-ops),
@@ -12,44 +23,16 @@ The `azimuth-config` repository is designed to be forked for a specific site and
 into multiple [environments](#environments). This structure allows common configuration to be
 shared but overridden where required using composition of environments.
 
-## Structure of an Azimuth deployment
-
-A fully-featured Azimuth deployment consists of many components, such as
-[Zenith](https://github.com/stackhpc/zenith), [Cluster API](https://cluster-api.sigs.k8s.io/)
-and the [CaaS operator](https://github.com/stackhpc/azimuth-caas-operator), which
-require a [Kubernetes](https://kubernetes.io/) cluster to run.
-
-However when you consider an Azimuth deployment as a whole, the only _real_ dependency is
-an [OpenStack](https://www.openstack.org/) cloud to target - we can create a Kubernetes
-cluster within an OpenStack project on the target cloud to host our Azimuth deployment.
-This is exactly what the playbooks in the `azimuth-ops` collection will do, when driven by
-a configuration derived from `azimuth-config`.
-
-There are two methods that `azimuth-ops` can use to deploy Azimuth and all of its
-dependencies:
-
-  1. Onto a managed single-node [K3S](https://k3s.io/) cluster in an OpenStack project.
-  2. Onto a managed highly-available Kubernetes cluster in an OpenStack project.
-
-Option 1 is useful for development or demo deployments, but is not suitable for a production
-deployment.
-
-Option 2 is the recommended deployment mechanism for most deployments. In this mode,
-[OpenTofu](https://opentofu.org/), an open-source fork of [Terraform](https://www.terraform.io/),
-is used to provision a single-node K3S cluster that is configured as a
-[Cluster API](https://cluster-api.sigs.k8s.io/) management cluster. Cluster API is then
-used to provision a highly-available Kubernetes cluster in the same OpenStack project
-onto which Azimuth is deployed.
-
-!!! warning
+For a production-ready deployment, you should follow the steps in the
+[getting started documentation](./best-practice.md).
 
-    Option 2 requires that [Octavia](https://docs.openstack.org/octavia/latest/index.html)
-    is available on the target cloud to provide load-balancers for Azimuth components.
+## Understating Azimuth Architecture
 
-## Deploying Azimuth
+If you want to know more about how Azimuth is architected,
+and better understand its security model,
+please read
+[Azimuth Architecture](./architecture.md)
 
-To try out Azimuth on your OpenStack cloud, you can follow [these instructions](./try.md)
-to get a simple single-node deployment.
+## Developing Azimuth
 
-For a production-ready deployment, you should follow the steps in the
-[best practice document](./best-practice.md).
+For a developer setup, please see [developing azimuth](./developing/index.md).

mkdocs.yml

@@ -7,6 +7,7 @@ nav:
   - Home: index.md
   - try.md
   - best-practice.md
+  - architecture.md
   - environments.md
   - Repository:
       - repository/index.md