@@ -105,6 +105,7 @@ that you might use in your hook scripts (as env. variables) and Ansible playbook
*`environment_type`: the current deployment environment type (`review`, `integration`, `staging` or `production`)
*`environment_name`: a generated application name to use for the current deployment environment (ex: `myapp-review-fix-bug-12` or `myapp-staging`) - _details below_
*`environment_namespace`: the sluggified namespace when using [multiple environments](#multiple-environments-support)(empty otherwise)
*`ssh_public_key_file`: the path of the private key file (if an appropriate `$ANSIBLE_xxx_PUBLIC_KEY` variable is set)
*`ssh_private_key_file`: the path of the public key file (if an appropriate `$ANSIBLE_xxx_PRIVATE_KEY` variable is set)
@@ -203,6 +204,43 @@ The **static way** can be implemented simply by setting the appropriate configur
To implement the **dynamic way**, your deployment script shall simply generate a `environment_url.txt` file in the working directory, containing only
the dynamically generated url. When detected by the template, it will use it as the newly deployed environment url.
### Multiple environments support
The Ansible template allows deploying multiple environments in parallel. Use cases of this include:
- monorepo, where a single Git repository might host several separate deployable components or apps,
- multi-instances deployment of the same application.
This feature can be enabled using the [parallel matrix jobs](https://docs.gitlab.com/ee/ci/yaml/#parallelmatrix)
pattern at the `.ansible-env-base` job level (this is the top parent job of all deployment jobs).
Environments namespacing is ensured by the `ANSIBLE_ENVIRONMENT_NAMESPACE` variable (must start with a slash `/`).
Here is the example of the `.gitlab-ci.yml` file for a project deploying both a frontend and a backend applications:
```yaml
.ansible-env-base:
parallel:
matrix:
-ANSIBLE_ENVIRONMENT_NAMESPACE:"/front"
# Ansible playbook and inventory for frontend
ENV_PLAYBOOK_FILE:"front-playbook.yml"
-ANSIBLE_ENVIRONMENT_NAMESPACE:"/back"
# Ansible playbook and inventory for backend
ENV_PLAYBOOK_FILE:"back-playbook.yml"
# ⚠ on_stop must be unset when defining parallel:matrix environments
The above configuration will deploy 2 environments on each pipeline:
- on feature branches: `review/front/$CI_COMMIT_REF_NAME` and `review/back/$CI_COMMIT_REF_NAME`
- on the integration branch: `integration/front` and `integration/back`
- on the production branch: `staging/front` and `staging/back` (and finally `production/front` and `production/back`)
### Deployment output variables
Each deployment job produces _output variables_ that are propagated to downstream jobs (using [dotenv artifacts](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsdotenv)):
@@ -215,6 +253,16 @@ Those variables may be freely used in downstream jobs (for instance to run accep
You may also add and propagate your own custom variables, by pushing them to the `ansible.env` file in your [deployment script](#deployment-and-cleanup-scripts).
> [!important]
> If [multiple environments](#multiple-environments-support) are configured, the output variables are prefixed with a
> sluggified value of the `ANSIBLE_ENVIRONMENT_NAMESPACE` variable (stripped of punctuation characters and converted to lowercase):
>
> * `<namespace_slug>_environment_type`: set to the type of environment (`review`, `integration`, `staging` or `production`),
> * `<namespace_slug>_environment_name`: the application name (see below),
> * `<namespace_slug>_environment_url`: set to the environment URL (whether determined statically or dynamically).
>
> The output dotenv file will be `ansible.env.<namespace_slug>` instead, and the dynamic variable `${environment_namespace}` can be used in your hook scripts and Ansible playbooks to access the contextual value of `<namespace_slug>`.
### Ansible commands overrides
Instead of creating hook scripts, you can also override and/or decorate the Ansible commands
@@ -268,6 +316,7 @@ This template can be configured with the following **environment variables**:
| `environment-namespace` / `ANSIBLE_ENVIRONMENT_NAMESPACE` | Extra [GitLab environments](https://docs.gitlab.com/ci/environments/) namespace _(only required when deploying [multiple environments](#multiple-environments-support))_<br/>:warning: must start with a slash `/` | _none_ |
| :lock: `ANSIBLE_VAULT_PASSWORD` | The Ansible vault password used to decrypt vars. | **has to be defined in gitlab secret if used** |
| :lock: `ANSIBLE_PRIVATE_KEY` | The Ansible SSH private key to use in all stages (can be overridden per env) | **has to be defined in gitlab secret if used** |
| `public-key` / `ANSIBLE_PUBLIC_KEY` | The Ansible SSH public key associated to the private key to be use in all stages (can be overridden per env) | **has to be defined if used** |
"description":"The default environments url _(only define for static environment URLs declaration)_\n\n_supports late variable expansion (ex: `https://%{environment_name}.acme.com`)_"
},
{
"name":"ANSIBLE_ENVIRONMENT_NAMESPACE",
"description":"Extra [GitLab environments](https://docs.gitlab.com/ci/environments/) namespace _(only required when deploying multiple environments)_\n\n:warning: must start with a slash `/`",
"advanced":true
},
{
"name":"ANSIBLE_VAULT_PASSWORD",
"description":"The Ansible vault password used to decrypt vars",
