diff --git a/.gitlab/README.md.template b/.gitlab/README.md.template index d31b349cc6fdbed5cfc2e09a1e60cab0e7e6b3f2..c41963f738418a4c4d99cea66a6944a0f5f9f80c 100644 --- a/.gitlab/README.md.template +++ b/.gitlab/README.md.template @@ -23,6 +23,10 @@ Read more: **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 @@ -69,6 +73,26 @@ include: 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, @@ -195,6 +219,26 @@ include: 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. + +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. + ## Contributing See the [CONTRIBUTING.md](CONTRIBUTING.md) guide. diff --git a/README.md b/README.md index 9dba3feb5cfef744148f1060ca6d57ae49490169..876ae94d665b34386f0f22ba9fc57e9ecfe08d33 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,10 @@ Read more: **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 @@ -71,6 +75,26 @@ include: 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, @@ -214,6 +238,26 @@ include: 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. + +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. + ## Contributing See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.