Allow self-hosting of custom site-specific user and operator documentation

.gitlab-ci.yml.sample

@@ -277,6 +277,8 @@ deploy_production:
         - environments/site/**/*
         - environments/site-ha/**/*
         - environments/production/**/*
+        # Uncomment when using custom self-hosted docs
+        # - docs/
       when: manual
   environment:
     name: production

bin/port-forward

@@ -46,18 +46,6 @@ case "$1" in
     service="azimuth-caas-operator-ara"
     remote_port="8000"
     ;;
-  awx)
-    name="AWX"
-    namespace="azimuth"
-    service="awx-service"
-    remote_port="80"
-    ;;
-  consul)
-    name="Consul"
-    namespace="azimuth"
-    service="consul-ui"
-    remote_port="80"
-    ;;
   grafana)
     name="Grafana"
     namespace="monitoring-system"
@@ -76,6 +64,12 @@ case "$1" in
     service="zenith-server-registrar"
     remote_port="80"
     ;;
+  azimuth-api)
+    name="Azimuth API"
+    namespace="azimuth"
+    service="azimuth-api"
+    remote_port="80"
+    ;;
   *)
     echo "Unrecognised service: $1" 1>&2
     exit 1

docs/configuration/16-local-customisations.md

@@ -1,25 +1,78 @@
 # Local customisations
 
-Azimuth allows a few site-specific customisations to be made to the user interface, if required.
+Azimuth allows a few site-specific customisations to be made, if required.
 
-## Documentation link
+## User and Operator Documentation
 
-The Azimuth UI includes a documentation link in the navigation bar at the top of the page.
-By default, this link points to the
-[generic Azimuth user documentation](https://azimuth-cloud.github.io/azimuth-user-docs/) that
-covers usage of the reference appliances.
+As part of the standard Azimuth deployment procedure, a copy of the generic user and operator
+documentation sites are published on separate subdomains of the Azimuth ingress URL. For an Azimuth
+instance hosted at `portal.azimuth.example.com`, the documentation can be accessed at
+`user.docs.azimuth.example.com` and `admin.docs.azimuth.example.com` respectively. The operator
+documentation is protected by the same username and password as the
+[admin dashboards](../configuration/14-monitoring.md#accessing-web-interfaces).
 
-However it is recommended to change this link to point at local documentation that is specific
-to your site, where possible. This documentation can include additional information, e.g.
-how to get an account to use with Azimuth, which is out-of-scope for the generic documentation.
+### Site-specific documentation
 
-To change the documentation link, use the following variable:
+The default configuration for the user and operator documentation will build a local copy
+of the [upstream documentation](https://github.com/azimuth-cloud/azimuth-config/tree/stable/docs);
+however, the following configuration can be used to instead build the documentation from a
+downstream azimuth-config repository:
 
 ```yaml  title="environments/my-site/inventory/group_vars/all/variables.yml"
-azimuth_documentation_url: https://docs.example.org/azimuth
+mkdocs_operator_docs_repo: https://<your-github-or-gitlab-repo>
+mkdocs_operator_docs_branch: <optional-non-default-branch>
+mkdocs_user_docs_repo: https://<your-github-or-gitlab-repo>
+mkdocs_user_docs_branch: <optional-non-default-branch>
 ```
 
-## Theming
+This allows Azimuth operators to build up their own set of internal documentation pages specific to
+their Azimuth deployment. A set of
+[example files](https://github.com/azimuth-cloud/azimuth-config/tree/stable/docs/site-example/)
+are provided as part of the upstream repository as a starting point for structuring your site-specific
+operator documentation. You will also need to uncomment (or add your own items to) the relevant `nav`
+entries in your local [mkdocs.yml](https://github.com/azimuth-cloud/azimuth-config/tree/stable/mkdocs.yml)
+file. For more information on how to customise your local documentation see the official
+[MkDocs website](https://www.mkdocs.org).
+
+!!! tip
+
+    In order to minimise the potential for merge conflicts when synchronising the latest upstream changes
+    into a downstream azimuth-config repository, it is recommended that any site specific docs are placed
+    in a separate set of files / folders under the `docs` directory. An example structure is provided
+    [here](https://github.com/azimuth-cloud/azimuth-config/tree/stable/docs/site-example/).
+
+If the downstream configuration is hosted in a private repository, then SSH-based authentication
+must be used to allow the documentation build process *read-only* access to the repository. To set
+up this authentication, an SSH keypair must first be created using (a command similar to):
+
+```sh
+ssh-keygen -t ed25519 -f azimuth-docs-key -N "" -C "-- Azimuth config repository deploy key"
+```
+
+The generated private key should then be stored as an encrypted secret inside the environment's
+`secrets.yml` file:
+
+```yaml  title="environments/my-site/inventory/group_vars/all/secrets.yml"
+mkdocs_deploy_ssh_private_key: |
+  <private-key>
+```
+
+and the public key must be added to the config repository as a 'deploy key' (see relevant
+[GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys)
+or [GitLab](https://docs.gitlab.com/ee/user/project/deploy_keys/) docs for more details).
+
+Finally, the target repository URL(s) should be updated to use an SSH-based git remote address e.g. `[email protected]:my-org/azimuth-config` instead of `https://github.com/my-org/azimuth-config`.
+
+!!! tip
+
+    The documentation publishing feature works by checking out a local copy of the repository inside a Kubernetes
+    init container and then running `mkdocs`. To debug authentication or build issues, start by checking the logs
+    of the relevant `operator_docs` or `user_docs` init container on the Azimuth management cluster.
+
+<!-- TODO: Think about how to refresh docs when docs change but mkdocs Helm release values don't. -->
+<!-- When working with site-specific documentation for deployments managed via GitLab [CI/CD](../deployment/automation.md) it is also advisable to edit the `.gitlab-ci.yml` workflow file to include the `docs/` directory in the list of watched files for the production deployment job (i.e. the `changes` list in the `deploy_production` section). This ensures that any changes made to site-specific documentation will be automatically incorporated into the published documentation pages. -->
+
+## User Interface Theming
 
 The Azimuth UI is built using the [Bootstrap frontend toolkit](https://getbootstrap.com/),
 which provides a grid system and several built-in components.
@@ -41,7 +94,7 @@ azimuth_theme_bootstrap_css_url: https://bootswatch.com/5/zephyr/bootstrap.css
 ```
 !!! tip
 
-    In order for the theming changes to take effect you may need to do a hard refresh of 
+    In order for the theming changes to take effect you may need to do a hard refresh of
     the page due to the aggressive nature of CSS caching.
 
     Mac: <kbd>⇧ Shift</kbd> + <kbd>⌘ Command</kbd> + <kbd>R</kbd>

docs/repository/index.md

@@ -100,6 +100,12 @@ changes to `main`. These changes can then be reviewed before being merged to `ma
 If you have automated deployments, the branch may even get a dynamic environment created
 for it where the result of the changes can be verified before the merge takes place.
 
+## Documenting your configuration
+
+See [local customisations](../configuration/16-local-customisations.md#site-specific-documentation) for
+information on how to create and publish site-specific operator documentation as part of your Azimuth
+deployment.
+
 ## Upgrading to a new Azimuth release
 
 When a new Azimuth release becomes available, you will need to synchronise the changes

docs/repository/secrets.md

@@ -98,7 +98,7 @@ explicit in the repository who has access.
 A full discussion of the use of GPG is beyond the scope of this documentation, including
 the generation of keys, as it differs substantially depending on your operating system.
 
-To add a GPG key to your repository, use the following command:
+To add a _signed_ GPG key to your repository, use the following command:
 
 ```sh
 git-crypt add-gpg-user USER_ID

docs/site-example/index.md

@@ -0,0 +1,5 @@
+# **_example-cloud_** Azimuth Operator Documentation
+
+_Add any site-specific operator documentation such as information about custom applications
+in the Azimuth app catalog or other important information that Azimuth operators should be
+aware of._

docs/site-example/quickstart.md

@@ -0,0 +1,40 @@
+# Operator Quickstart
+
+This is an operator quickstart guide for the **_example-cloud_** Azimuth deployment.
+
+## Getting started
+
+To start working with the **_example-cloud_** Azimuth deployment a new operator first must be
+granted access to the configuration repository's [encrypted secrets](../repository/secrets.md).
+The recommended way to do so is using [GPG keys](../repository/secrets.md#granting-access-to-others).
+
+The **_example-cloud_** Azimuth configuration is managed via CI/CD, meaning that the correct process for
+applying configuration changes is to create a pull request into the **_example-cloud_** azimuth-config
+repository and have it reviewed by another team member. Once the change has been approved, merging the
+pull request will trigger an automatic deployment of the updated configuration to the Azimuth staging
+environment. Once a change has been deployed and tested in staging, the equivalent CI job for deploying
+the change to the production Azimuth environment should be triggered manually by an operator via the
+**_GitLab-or-GitHub_** UI.
+
+## Useful links
+
+The **_example-cloud_** Azimuth includes a useful set of monitoring dashboards and tools for operators.
+A general overview of the available tools can be found
+[here](https://azimuth-config.readthedocs.io/en/stable/configuration/14-monitoring/) and the
+_example-cloud_ instances can be accessed using the following links:
+
+- _Insert list of links to Grafana, Alert Manager etc._
+
+For an introduction to the available configuration options within an Azimuth deployment, see
+[here](https://azimuth-config.readthedocs.io/en/stable/configuration/).
+
+## Custom **_example-cloud_** Azimuth Apps
+
+_Optional: Describe any custom site-specific Azimuth apps here and link to the relevant configuration
+sections in the downstream azimuth-config repository._
+
+## Notable **_example-cloud_** configuration
+
+_Optional: Desribe any important ways in which this downstream configuration differs from the upstream Azimuth
+defaults, e.g. custom networking or storage integrations or explicitly enabled or disabled experimental
+features._

environments/base/inventory/group_vars/all.yml

@@ -94,6 +94,10 @@ ingress_ara_subdomain: ara
 ingress_helm_dashboard_subdomain: helm
 # The subdomain that should be used for the Kubernetes dashboard
 ingress_kubernetes_dashboard_subdomain: kubernetes
+# The subdomain that should be used for the operator docs
+ingress_operator_docs_subdomain: admin-guide
+# The subdomain that should be used for the user docs
+ingress_user_docs_subdomain: user-guide
 
 # Annotations for Azimuth ingress resources
 ingress_annotations:
@@ -205,3 +209,6 @@ capi_cluster_addons_openstack_loadbalancer_provider: >-
   {{- openstack_loadbalancer_provider }}
 azimuth_capi_operator_capi_helm_openstack_loadbalancer_provider: >-
   {{- openstack_loadbalancer_provider }}
+
+# The URL for the user documentation link in the Azimuth UI
+azimuth_documentation_url: "{{ 'https' if ingress_tls_enabled else 'http' }}://{{ ingress_user_docs_subdomain }}.{{ ingress_base_domain }}"

mkdocs.yml

@@ -2,6 +2,8 @@ site_name: Azimuth Operator Documentation
 repo_url: https://github.com/azimuth-cloud/azimuth-config
 copyright: Copyright © StackHPC 2022
 edit_uri: ''
+# TODO: Make separate standalone CAPI docs
+# docs_dir: docs/azimuth
 
 nav:
   - Home: index.md
@@ -48,6 +50,9 @@ nav:
       - debugging/caas.md
   - Developing:
       - developing/index.md
+#   - example-cloud Azimuth Operators:
+#       - site-example/index.md
+#       - site-example/quickstart.md
 
 theme:
   name: material

requirements.yml

@@ -3,7 +3,7 @@
 collections:
   - name: https://github.com/azimuth-cloud/ansible-collection-azimuth-ops.git
     type: git
-    version: 0.13.2
+    version: feat/mkdocs # 0.13.2
   # For local development
   # - type: dir
   #   source: ../ansible-collection-azimuth-ops