Switch docs to Sphinx

.gitignore

@@ -19,3 +19,4 @@ ansible-lint.xml
 output
 .stestr
 .tox
+doc/build

Earthfile

@@ -116,22 +116,3 @@ image-sync:
   WORKDIR /src
   COPY . /src
   RUN --secret GITHUB_TOKEN go run ./cmd/atmosphere-ci image repo sync ${project}
-
-mkdocs-image:
-  FROM ghcr.io/squidfunk/mkdocs-material:9.5.4
-  RUN pip install \
-    mkdocs-literate-nav
-  SAVE IMAGE mkdocs
-
-mkdocs-serve:
-  LOCALLY
-  WITH DOCKER --load=+mkdocs-image
-    RUN docker run --rm -p 8000:8000 -v ${PWD}:/docs mkdocs
-  END
-
-mkdocs-build:
-  FROM +mkdocs-image
-  COPY . /docs
-  RUN mkdocs build
-  RUN --push --secret GITHUB_TOKEN git remote set-url origin https://x-access-token:${GITHUB_TOKEN}@github.com/vexxhost/atmosphere.git
-  RUN --push mkdocs gh-deploy --force

Jenkinsfile

@@ -81,16 +81,6 @@ pipeline {
             }
           }
         }
-
-        stage('docs') {
-          agent {
-            label 'earthly-2c-4g'
-          }
-
-          steps {
-            sh 'earthly +mkdocs-build'
-          }
-        }
       }
     }
 

README.md

@@ -9,137 +9,6 @@ community:
   on the Kubernetes Slack. If you are new to Kubernetes Slack workspace,
   [Join the Kubernetes Slack workspace](https://slack.kubernetes.io/) first.
 
-## Quick Start
-
-The quick start intends to provide the most near-production experience possible,
-as it is architected purely towards production-only environments. In order to
-get a quick production-ready experience of Atmosphere, you will need access to
-an OpenStack cloud.
-
-The quick start is powered by Molecule and it is used in continuous integration
-running against the VEXXHOST public cloud so that would be an easy target to
-use to try it out.
-
-You will need the following quotas set up in your cloud account:
-
-* 8 instances
-* 32 cores
-* 128GB RAM
-* 360GB storage
-
-These resources will be used to create a total of 8 instances broken up as
-follows:
-
-* 3 Controller nodes
-* 3 Ceph OSD nodes
-* 2 Compute nodes
-
-First of all, you'll have to make sure you clone the repository locally to your
-system with `git` by running the following command:
-
-```shell
-git clone https://github.com/vexxhost/atmosphere
-```
-
-You will need `poetry` installed on your operating system.  You will need to make
-sure that you have the appropriate OpenStack environment variables set (such
-as `OS_CLOUD` or `OS_AUTH_URL`, etc.).  You can also use the following
-environment variables to tweak the behaviour of the Heat stack that is created:
-
-* `ATMOSPHERE_STACK_NAME`: The name of the Heat stack to be created (defaults to
-  `atmosphere`).
-
-* `ATMOSPHERE_PUBLIC_NETWORK`: The name of the public network to attach floating
-  IPs from (defaults to `public`).
-
-* `ATMOSPHERE_IMAGE`: The name or UUID of the image to be used for deploying the
-  instances (defaults to `Ubuntu 20.04.3 LTS (x86_64) [2021-10-04]`).
-
-* `ATMOSPHERE_INSTANCE_TYPE`(Deprecated): The instance type used to deploy all of the
-  different instances.(It doesn't have its own default value.)
-  This has been deprecated from v1.4.0. You can configure the instance type per a
-  machine role using `ATMOSPHERE_CONTROLLER_INSTANCE_TYPE`,
-  `ATMOSPHERE_COMPUTE_INSTANCE_TYPE`, and `ATMOSPHERE_STORAGE_INSTANCE_TYPE`
-  variables. For backwards compatibility, if variables specific to the machine roles
-  are not set and `ATMOSPHERE_INSTANCE_TYPE` is set, `ATMOSPHERE_INSTANCE_TYPE` value
-  is used.
-
-* `ATMOSPHERE_CONTROLLER_INSTANCE_TYPE`: The instance type used to deploy controller
-  instances (defaults to `v3-standard-16`).
-
-* `ATMOSPHERE_COMPUTE_INSTANCE_TYPE`: The instance type used to deploy compute
-  instances (defaults to `v3-standard-4`).
-
-* `ATMOSPHERE_STORAGE_INSTANCE_TYPE`: The instance type used to deploy storage
-  instances (defaults to `v3-standard-4`).
-
-* `ATMOSPHERE_NAMESERVERS`: A comma-separated list of nameservers to be used for
-  the instances (defaults to `1.1.1.1`).
-
-* `ATMOSPHERE_USERNAME`: The username what is used to login into the instances (
-  defaults to `ubuntu`).
-
-* `ATMOSPHERE_DNS_SUFFIX_NAME`: The DNS domainname that is used for the API and
-  Horizon. (defaults to `nip.io`).
-
-* `ATMOSPHERE_ACME_SERVER`: The ACME server, currenly this is from LetsEncrypt,
-  with StepCA from SmallStep it is possible to run a internal ACME server.
-  The CA of that ACME server should be present in the instance image.
-
-* `ATMOSPHERE_ANSIBLE_VARS_PATH`: The path for ansible group_vars and host_vars.
-  This to build a multinode development cluster with own configs, that are not
-  generated by molecule. This way you can test your configs before you bring
-  them to production.
-
-Once you're ready to get started, you can run the following command to install
-poetry dependencies:
-
-```shell
-poetry install
-```
-
-Then you can run the following command to build the Heat stack :
-
-```shell
-poetry run molecule converge
-```
-
-This will create a Heat stack with the name `atmosphere` and start deploying
-the cloud.  Once it's complete, you can login to any of the systems by using
-the `login` sub-command.  For exampel, to login to the first controller node,
-you can run the following:
-
-```shell
-poetry run molecule login -h ctl1
-```
-
-In all the controllers, you will find an `openrc` file location inside the
-`root` account home directory, as well as the OpenStack client installed there
-as well.  You can use it by running the following after logging in:
-
-```shell
-source /root/openrc
-openstack server list
-```
-
-The Kubernetes administrator configuration will also be available on all of the
-control plane nodes, you can simply use it by running `kubectl` commands on
-any of the controllers as `root`:
-
-```shell
-kubectl get nodes -owide
-```
-
-Once you're done with your environment and you need to tear it down, you can
-use the `destroy` sub-command:
-
-```shell
-poetry run molecule destroy
-```
-
-For more information about the different commands used by Molecule, you can
-refer to the Molecule documentation.
-
 ## Contributing
 
 You'll need to make sure that you have [`pre-commit`](https://pre-commit.com)

doc/requirements.txt

@@ -0,0 +1,5 @@
+dunamai
+furo
+sphinx
+sphinx-autobuild
+sphinx-copybutton

doc/source/admin/index.rst

@@ -0,0 +1,19 @@
+Administrator Documentation
+===========================
+
+This section is designed to equip system administrators with the knowledge and
+tools necessary for the effective management and operation of the Atmosphere
+deployment. It offers comprehensive guides and resources across various aspects
+of system administration, including troubleshooting, maintenance, and more.
+
+Intended for administrators tasked with the setup and ongoing management of
+Atmosphere, this documentation aims to provide clear and practical
+information to ensure stable and efficient operation of the system.
+
+.. toctree::
+   :maxdepth: 2
+
+   integration
+   monitoring
+   maintenance
+   troubleshooting

doc/source/admin/integration.rst

@@ -0,0 +1,77 @@
+#################
+Integration Guide
+#################
+
+This section provides detailed instructions on integrating external systems
+and services with Atmosphere, enhancing functionality and streamlining workflows.
+
+********
+Keycloak
+********
+
+Keycloak serves as a comprehensive identity and access management solution,
+facilitating the integration of various identity providers for centralized user
+authentication and authorization. By leveraging federated identity, Keycloak enables
+seamless Single Sign-On (SSO) capabilities across a suite of applications, enhancing
+the user experience and bolstering security measures.
+
+Identity Providers
+==================
+
+Incorporating identity providers into Keycloak allows users to authenticate via trusted
+external sources. This federated authentication scheme simplifies the login process by
+using existing credentials, whether from enterprise directories like LDAP or other
+identity services.
+
+Azure AD
+--------
+
+Azure AD is recognized for its extensive adoption and integration within the enterprise
+ecosystem, offers a secure and familiar authentication method for countless users.
+
+You can begin the integration process by creating an application registration in Azure AD
+and configuring the necessary settings in Keycloak. The following steps outline the
+procedure:
+
+1. Sign in to the Azure portal and access the **Azure Active Directory** service.
+2. Navigate to **App registrations** and click **New registration**.
+3. Fill in the application name, select the account types it will serve, and
+   specify a **Redirect URI**.
+
+At this point, you'll need to grab the **Redirect URI** from the Keycloak client settings
+using the following steps:
+
+1. Log into the Keycloak admin console using your administrator credentials.
+2. Switch to the ``atmosphere`` realm where you'll be configuring Azure AD.
+3. In the **Identity Providers** section, select **Add provider** and choose **Microsoft**.
+4. Keycloak will generate a **Redirect URI** which you will use in the Azure AD
+   application registration process to ensure that authentication responses are
+   correctly routed.
+
+At this point, you'll be able to finalize the Azure AD application registration by
+following these remaining steps:
+
+1. Return to the Azure AD application registration page and input the Redirect
+   URI from Keycloak.
+2. After the application is registered, navigate to **Certificates & secrets**
+   to create a client secret.
+3. Record the **Client ID** and **Client Secret** provided, as they will be
+   needed to configure Keycloak.
+
+At this point, you're ready to configure Keycloak with the Azure AD settings:
+
+1. In the Keycloak admin console, navigate back to the `atmosphere` realm's
+   **Identity Providers** section.
+2. For the Microsoft provider configuration, enter the **Client ID** and
+   **Client Secret** obtained from Azure AD.
+3. Adjust any additional settings according to your requirements, such as the
+   default scopes, mappers, and other provider-specific configurations.
+4. Save your changes to finalize the integration.
+
+By integrating Azure AD with Keycloak, you enable users to authenticate with
+their corporate credentials across all applications that are secured by
+Keycloak. This provides a consistent and secure user experience, leveraging
+the robust features of Azure AD within the flexible framework of Keycloak.
+
+For a deeper dive into the Azure AD configuration within Keycloak, consult the
+`Keycloak Microsoft Identity Provider documentation <https://www.keycloak.org/docs/latest/server_admin/#_microsoft>`_.

doc/source/admin/maintenance.rst

@@ -0,0 +1,31 @@
+#################
+Maintenance Guide
+#################
+
+This guide provides instructions for regular maintenance tasks necessary to
+ensure the smooth and secure operation of the system.
+
+*********************
+Renewing Certificates
+*********************
+
+The certificates used by the Kubernetes cluster are valid for one year.  They
+are automatically renewed when the cluster is upgraded to a new version of
+Kubernetes.  However, if you are running the same version of Kubernetes for
+more than a year, you will need to manually renew the certificates.
+
+To renew the certificates, run the following command on each one of your
+control plane nodes:
+
+.. code-block:: console
+
+    $ sudo kubeadm certs renew all
+
+Once the certificates have been renewed, you will need to restart the
+Kubernetes control plane components to pick up the new certificates.  You need
+to do this on each one of your control plane nodes by running the following
+command one at a time on each node:
+
+.. code-block:: console
+
+    $ ps auxf | egrep '(kube-(apiserver|controller-manager|scheduler)|etcd)' | awk '{ print $2 }' | xargs sudo kill