diff --git a/.gitlab-ci.yml.sample b/.gitlab-ci.yml.sample index 819ab8b5..c82767e9 100644 --- a/.gitlab-ci.yml.sample +++ b/.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 diff --git a/bin/port-forward b/bin/port-forward index 65a2d1d0..99ea690b 100755 --- a/bin/port-forward +++ b/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 diff --git a/docs/configuration/16-local-customisations.md b/docs/configuration/16-local-customisations.md index b8e1bce7..7412139a 100644 --- a/docs/configuration/16-local-customisations.md +++ b/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:// +mkdocs_operator_docs_branch: +mkdocs_user_docs_repo: https:// +mkdocs_user_docs_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: | + +``` + +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. `git@github.com: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. + + + + +## 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: ⇧ Shift + ⌘ Command + R diff --git a/docs/repository/index.md b/docs/repository/index.md index 1b73e8b0..0b6cf658 100644 --- a/docs/repository/index.md +++ b/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 diff --git a/docs/repository/secrets.md b/docs/repository/secrets.md index 30664d5b..d6cb1460 100644 --- a/docs/repository/secrets.md +++ b/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 diff --git a/docs/site-example/index.md b/docs/site-example/index.md new file mode 100644 index 00000000..fc9baa2b --- /dev/null +++ b/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._ diff --git a/docs/site-example/quickstart.md b/docs/site-example/quickstart.md new file mode 100644 index 00000000..f7215a66 --- /dev/null +++ b/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._ diff --git a/environments/base/inventory/group_vars/all.yml b/environments/base/inventory/group_vars/all.yml index 72f0cf3d..4cb7ca75 100644 --- a/environments/base/inventory/group_vars/all.yml +++ b/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 }}" diff --git a/mkdocs.yml b/mkdocs.yml index 61715db5..aaab5255 100644 --- a/mkdocs.yml +++ b/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 diff --git a/requirements.yml b/requirements.yml index 7fd9d133..3f905c02 100644 --- a/requirements.yml +++ b/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