Newer
Older
<!-- This document is generated by `make docs` from `.gitlab/README.md` -->
> The `src/gitlab-tofu.sh` script is still merely a copy from [`gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images).
> Therefore, lots of things in this script and in the templates are still Terraform-related and haven't
> been changed to their OpenTofu equivalents.
> Have a look at the [Migrating from the Terraform CI/CD templates](#migrating-from-the-terraform-cicd-templates)
section when migrating from Terraform CI/CD templates.
This project is home to the **OpenTofu CI/CD component** and it's related assets,
like the `gitlab-tofu` wrapper script and OCI images containing that script
together with an OpenTofu version.
Read more:
- [CI/CD components](https://docs.gitlab.com/ee/ci/components)
- [Development guide for GitLab CI/CD components](https://docs.gitlab.com/ee/development/cicd/components)
- [CI/CD Catalog](https://docs.gitlab.com/ee/ci/components/index.html#cicd-catalog)
**Note**: Please make sure to use a released version of this CI/CD component.
You find all releases on the [Releases Overview Page](https://gitlab.com/components/opentofu/-/releases).
♻️ **Migrating from the Terraform CI/CD templates?** Check **[this](#migrating-from-the-terraform-cicd-templates)** out.
[[_TOC_]]
## Usage
```yaml
include:
- component: gitlab.com/components/opentofu/full-pipeline@<VERSION>
inputs:
# The version must currently be specified explicitly as an input,
# to find the correctly associated images. # This can be removed
# once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
version: <VERSION>
opentofu_version: <OPENTOFU_VERSION>
stages: [validate, build, deploy, cleanup]
---
# ... or without the destroy jobs:
include:
- component: gitlab.com/components/opentofu/validate-plan-apply@<VERSION>
inputs:
# The version must currently be specified explicitly as an input,
# to find the correctly associated images. # This can be removed
# once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
version: <VERSION>
opentofu_version: <OPENTOFU_VERSION>
stages: [validate, build, deploy]
- component: gitlab.com/components/opentofu/full-pipeline@0.10.0
inputs:
# The version must currently be specified explicitly as an input,
# to find the correctly associated images. # This can be removed
# once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
stages: [validate, build, deploy, cleanup]
# ... in case you absolutely know what you are doing and are
# aware that this may introduce breaking changes, you may use the latest release:
- component: gitlab.com/components/opentofu/full-pipeline@~latest
inputs:
# The version must currently be specified explicitly as an input,
# to find the correctly associated images. # This can be removed
# once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
stages: [validate, build, deploy, cleanup]
Or import all jobs as hidden templates ready to be extended:
```yaml
include:
- component: gitlab.com/components/opentofu/job-templates@<VERSION>
inputs:
# The version must currently be specified explicitly as an input,
# to find the correctly associated images. # This can be removed
# once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
version: <VERSION>
opentofu_version: <OPENTOFU_VERSION>
stages: [...]
fmt:
extends: [.opentofu:fmt]
...
```
### Opinionated Templates
This component repository also provides some templates that may often be used,
for example one that only runs validation (`fmt` and `validate`), plan and an apply,
but no destructive actions.
- [`validate-plan`](templates/validate-plan.yml)
- [`validate-plan-apply`](templates/validate-plan-apply.yml)
### Job Templates
Instead of including the `full-pipeline` or another opinionated template,
it's also possible to include individual jobs
and compose your own pipeline, for example, to just run the `fmt` job you can do:
```yaml
include:
- component: gitlab.com/components/opentofu/fmt@<VERSON>
inputs:
# The version must currently be specified explicitly as an input,
# to find the correctly associated images. # This can be removed
# once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
Or you can also include the `job-templates` template, that will include
all available OpenTofu jobs as hidden job templates prefixed with `.opentofu:`.
Those are especially useful when you want to minimize your includes and
you want to extend the jobs:
```yaml
include:
- component: gitlab.com/components/opentofu/job-templates@<VERSON>
inputs:
# The version must currently be specified explicitly as an input,
# to find the correctly associated images. # This can be removed
# once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
version: <VERSION>
opentofu_version: 1.6.1
plan:
extends: [.opentofu:plan]
parallel:
matrix:
- TF_ROOT: test/
- TF_ROOT: prod/
```
Have a look at the [`full-pipeline`](templates/full-pipeline.yml) for how it's constructed.
The following job components exist:
- [`fmt`](templates/fmt.yml)
- [`validate`](templates/validate.yml)
- [`plan`](templates/plan.yml)
- [`apply`](templates/apply.yml)
- [`destroy`](templates/destroy.yml)
- [`delete-state`](templates/delete-state.yml)
Have a look at the individual template spec to learn about the available inputs.
### Inputs
| Name | Default | Description |
| ---- | ------- | ----------- |
| `stage_validate` | `validate` | Defines the validate stage. This stage includes the `fmt` and `validate` jobs. |
| `stage_build` | `build` | Defines the build stage. This stage includes the `plan` job. |
| `stage_deploy` | `deploy` | Defines the deploy stage. This stage includes the `apply` job. |
| `stage_cleanup` | `cleanup` | Defines the cleanup stage. This stage includes the `destroy` and `delete-state` jobs. |
| `version` | `latest` | Version of this component. Has to be the same as the one in the component include entry. |
| `opentofu_version` | `1.6.1` | OpenTofu version that should be used. Must be one of `1.6.1`, `1.6.0`, `1.6.0-rc1`. |
| `root_dir` | `${CI_PROJECT_DIR}` | Root directory for the OpenTofu project. |
| `state_name` | `default` | Remote OpenTofu state name. |
| `auto_apply` | `false` | Whether the apply job is manual or automatically run. |
| `auto_destroy` | `false` | Whether the destroy job is manual or automatically run. |
### Available OpenTofu Versions
The following OpenTofu versions are available with this component via the `opentofu_version` input:
- [`1.6.1`](https://github.com/opentofu/opentofu/releases/tag/v1.6.1)
- [`1.6.0`](https://github.com/opentofu/opentofu/releases/tag/v1.6.0)
- [`1.6.0-rc1`](https://github.com/opentofu/opentofu/releases/tag/v1.6.0-rc1)
### Variables
(🚧 *This section is work in progress*)
Have a look at the [`src/gitlab-tofu.sh`](src/gitlab-tofu.sh) script and how the `TF_`-prefixed
variables are being used. You may set them according to your needs.
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
## Releases & Versioning
This project currently releases tagged commits.
An overview of releases can be found on the [Releases page](https://gitlab.com/components/opentofu/-/releases).
Each release is accessible in the [CI/CD Catalog](https://gitlab.com/explore/catalog).
### Component Versions
The component release versions follow [Semantic Versioning 2.0.0](https://semver.org/).
### Image Versions
This project releases multiple OCI image variants that can be used with the component.
The intention is that the images used in a component have the same version and or not mixed.
Due to the limitations described in https://gitlab.com/gitlab-org/gitlab/-/issues/438275
it's currently required to provide the component version in the `component` include field
and as the `version` input. Check out the [Usage](#Usage) section for examples.
Each component release deploys the following images:
- `registry.gitlab.com/components/opentofu/gitlab-opentofu:<VERSION>-opentofu<OPENTOFU_VERSION>`
- `registry.gitlab.com/components/opentofu/gitlab-opentofu:<VERSION>-opentofu`
- Includes the latest stable OpenTofu version at the time of releasing the component
- `registry.gitlab.com/components/opentofu/gitlab-opentofu:<VERSION>`
- Includes the latest stable OpenTofu version at the time of releasing the component
In the above examples `<VERSION>` references the component version and `<OPENTOFU_VERSION>`
an OpenTofu release, from [here](https://github.com/opentofu/opentofu/releases).
*Note: unfortunately, these image versions are not SemVer compatible,
because `-` indicates a prerelease (which they are not in this case).
However, we cannot use the alternative `+` which would indicate build metadata
as we'd like.
See https://github.com/distribution/distribution/issues/1201*
## Usage on self-managed
GitLab CI/CD components are not yet distributed and available on self-managed GitLab instances.
(see details [here](https://gitlab.com/gitlab-org/gitlab/-/issues/415638)).
It's also not possible to just include CI/CD components across instance, thus an include like
`- component: gitlab.com/components/opentofu/full-pipeline@~latest` won't work from a
self-managed instance.
However, you could mirror this project from GitLab.com onto any self-managed instance using
a [repository pull mirror](https://docs.gitlab.com/ee/user/project/repository/mirror/pull.html).
and then use the component as you would from GitLab.com, but change the domain, like so:
```yaml
include:
- component: gitlab.example.com/components/opentofu/full-pipeline@<VERSION>
inputs:
...
```
This example assumes your GitLab instance is hosted on `gitlab.example.com` and this component
project is mirrored in the `components/opentofu` project.
## Migrating from the Terraform CI/CD templates
When migrating from the GitLab Terraform CI/CD templates you can use the following migration rules:
- Used `Terraform.gitlab-ci.yml` -> Migrate to `validate-plan-apply`.
- Used `Terraform/Base.gitlab-ci.yml` -> Migrate to `job-templates`.
- Migrate the `.terraform:` job prefix to `.opentofu:`.
- Used the `kics-iac-sast` job -> Additionally include the `Jobs/SAST-IaC.latest.gitlab-ci.yml` template.
- Migrate the following job names:
- `build` -> `plan`
- `deploy` -> `apply`
- Migrate the `TF_ROOT` variable to the `root_dir` input.
- Although the `TF_ROOT` variable is still used and maybe overwritten after the import on individual jobs.
- Migrate the `TF_STATE_NAME` variable to the `state_name` input.
- Although the `TF_STATE_NAME` variable is still used and maybe overwritten after the import on individual jobs.
- Migrate the `TF_AUTO_DEPLOY` variable to the `auto_apply` input.
- Used other variables -> Use the same variables with this component.
The same rules apply for the `latest` templates.
We also recommend to check out the [Usage](#Usage) section for more details about the available templates and inputs.
### OpenTofu component `inputs` vs. Terraform template `variables`
This OpenTofu CI/CD component makes use of [`inputs`](https://docs.gitlab.com/ee/ci/yaml/#specinputs)
whereas the Terraform CI/CD templates used [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables).
We recommend that you use the `inputs` with the OpenTofu component where available and required.
However, if needed you may overwrite the jobs and set the `variables` you like.
## Contributing
See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.