<!-- This document is generated by `make docs` from `.gitlab/README.md` -->

# OpenTofu CI/CD Component

> 🚧 **NOTE** 🚧
> 
> 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]
```

A concrete example may look like this:

```yaml
# Using version `0.10.0`:
include:
  - 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.
      version: 0.10.0
      opentofu_version: 1.6.1

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:
include:
  - 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.
      version: latest
      opentofu_version: 1.6.1

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.
      version: <VERSION>
      opentofu_version: 1.6.1
      root_dir: tofu/
```

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.


## 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.