Skip to content

Commit 41b6862

Browse files
JohnGarbuttJohnGarbutt
authored
Reorder production deployment docs (azimuth-cloud#126)
* Reorder production deployment docs * Add a note about ensuring monitoring is setup. * updated to match review comments * Update best-practice.md * Update best-practice.md
1 parent 8714311 commit 41b6862

File tree

2 files changed

+63
-39
lines changed

2 files changed

+63
-39
lines changed

‎docs/best-practice.md‎

Lines changed: 55 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,8 @@
1-
# Best practice for deployments
1+
# Best practice for production deployments
22

33
This document guides you through the process of setting up a production-ready Azimuth
44
deployment following recommended best practice.
55

6-
## Prerequisites
7-
8-
Before proceeding with an Azimuth deployment, you should ensure that the target cloud
9-
meets the [prerequisites](./configuration/01-prerequisites.md).
10-
11-
## OpenStack projects
12-
13-
Azimuth is usually deployed on the cloud that is being targeted for workloads. It is
14-
recommended to have three OpenStack projects for a production Azimuth deployment, to contain:
15-
16-
* A highly-available (HA) production deployment, e.g. `azimuth-production`
17-
* A HA staging deployment, e.g. `azimuth-staging`
18-
* All-in-one (AIO) deployments for validating changes, e.g. `azimuth-cicd`
19-
20-
The production and staging projects must have
21-
[sufficient quota](./configuration/01-prerequisites.md#prerequisites) for a HA Azimuth
22-
deployment. The required quota in the CI/CD project will depend on the number of
23-
proposed changes that are open concurrently.
24-
256
## Repository
267

278
Before building your Azimuth configuration, you must first
@@ -32,17 +13,6 @@ It is recommended to use a
3213
[feature branch workflow](./repository/index.md#making-changes-to-your-configuration)
3314
to make changes to your Azimuth configuration in a controlled way.
3415

35-
## OpenTofu state
36-
37-
Azimuth deployments use [OpenTofu](https://opentofu.org/), an open-source fork of
38-
[Terraform](https://www.terraform.io/), to manage some parts of the infrastructure.
39-
40-
A [remote state store](./repository/opentofu.md#remote-state) must be configured in
41-
order to persist the OpenTofu state across playbook executions. If GitLab is being
42-
used for the Azimuth configuration repository, it is recommended to use
43-
[GitLab-managed Terraform state](./repository/opentofu.md#gitlab) for this. If not,
44-
[S3](./repository/opentofu.md#s3) is the preferred approach.
45-
4616
## Environments
4717

4818
An Azimuth configuration repository contains multiple [environments](./environments.md),
@@ -83,6 +53,47 @@ base --> ha --> site --> site-ha --> production
8353

8454
with only necessary differences configured in each environment, e.g. the ingress base domain, between `staging` and `production`.
8555

56+
## OpenStack projects
57+
58+
Azimuth is usually deployed on the cloud that is being targeted for workloads. It is
59+
recommended to have three OpenStack projects for a production Azimuth deployment, to contain:
60+
61+
* A highly-available (HA) production deployment, e.g. `azimuth-production`
62+
* A HA staging deployment, e.g. `azimuth-staging`
63+
* All-in-one (AIO) deployments for validating changes, e.g. `azimuth-cicd`
64+
65+
The production and staging projects must have
66+
[sufficient quota](./configuration/01-prerequisites.md#prerequisites) for a HA Azimuth
67+
deployment. The required quota in the CI/CD project will depend on the number of
68+
proposed changes that are open concurrently.
69+
70+
Users that login to Azimuth will see a list of the OpenStack projects
71+
they can access. Any OpenStack project can be used to deploy Azimuth
72+
workloads, as long as the networking requirements have been met.
73+
Azimuth creates application credentials to be able to create the
74+
user workloads using the appropriate automation.
75+
76+
## Deployment Prerequisites
77+
78+
Before proceeding with an Azimuth [deployment](./deployment/index.md),
79+
you should ensure that you can fulfil
80+
[all the prerequisites](./configuration/01-prerequisites.md).
81+
82+
The prerequisites include verifying that the target cloud has the required features available,
83+
generating OpenStack application credentials
84+
and ensuring that the required DNS records and TLS certificates are available.
85+
86+
## OpenTofu state
87+
88+
Azimuth deployments use [OpenTofu](https://opentofu.org/), an open-source fork of
89+
[Terraform](https://www.terraform.io/), to manage some parts of the infrastructure.
90+
91+
A [remote state store](./repository/opentofu.md#remote-state) must be configured in
92+
order to persist the OpenTofu state across playbook executions. If GitLab is being
93+
used for the Azimuth configuration repository, it is recommended to use
94+
[GitLab-managed Terraform state](./repository/opentofu.md#gitlab) for this. If not,
95+
[S3](./repository/opentofu.md#s3) is the preferred approach.
96+
8697
## Continuous delivery
8798

8899
A production Azimuth deployment should use [continuous delivery](./deployment/automation.md),
@@ -103,6 +114,15 @@ A
103114
[sample GitLab CI/CD configuration](https://github.com/stackhpc/azimuth-config/tree/stable/.gitlab-ci.yml.sample)
104115
is provided that implements this workflow for GitLab-hosted repositories.
105116

117+
## Monitoring
118+
119+
Before going into production, be sure you can
120+
[access the monitoring](./debugging/access-monitoring.md).
121+
122+
Also ensure you have
123+
[configured alert manager](./configuration/14-monitoring.md)
124+
such that you will notice any alerts on staging and production.
125+
106126
## Disaster recovery
107127

108128
Azimuth uses [Velero](https://velero.io/) to backup the data that is required to restore an
@@ -117,3 +137,7 @@ a production deployment.
117137
You are now ready to begin adding configuration to your environments. When building an environment
118138
for the first time, it is recommended to follow each documentation page in order, beginning with
119139
the [Deployment method](./configuration/02-deployment-method.md).
140+
141+
!!! tip
142+
143+
Remember to share as much configuration as possible between all your [environments](./environments.md)!

‎docs/index.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
This documentation describes how to manage deployments of
44
[Azimuth](https://github.com/stackhpc/azimuth), including all the required dependencies.
55

6+
## Deploying Azimuth
7+
68
Azimuth is deployed using [Ansible](https://www.ansible.com/) with playbooks from the
79
[azimuth-ops Ansible collection](https://github.com/stackhpc/ansible-collection-azimuth-ops),
810
driven by configuration derived from the
@@ -12,6 +14,12 @@ The `azimuth-config` repository is designed to be forked for a specific site and
1214
into multiple [environments](#environments). This structure allows common configuration to be
1315
shared but overridden where required using composition of environments.
1416

17+
To try out Azimuth on your OpenStack cloud, you can follow [these instructions](./try.md)
18+
to get a simple single-node deployment.
19+
20+
For a production-ready deployment, you should follow the steps in the
21+
[best practice document](./best-practice.md).
22+
1523
## Structure of an Azimuth deployment
1624

1725
A fully-featured Azimuth deployment consists of many components, such as
@@ -45,11 +53,3 @@ onto which Azimuth is deployed.
4553

4654
Option 2 requires that [Octavia](https://docs.openstack.org/octavia/latest/index.html)
4755
is available on the target cloud to provide load-balancers for Azimuth components.
48-
49-
## Deploying Azimuth
50-
51-
To try out Azimuth on your OpenStack cloud, you can follow [these instructions](./try.md)
52-
to get a simple single-node deployment.
53-
54-
For a production-ready deployment, you should follow the steps in the
55-
[best practice document](./best-practice.md).

0 commit comments

Comments
 (0)