Skip to content
Snippets Groups Projects
Unverified Commit d07aab8f authored by Timo Furrer's avatar Timo Furrer
Browse files

Generate README

parent 8ad03715
Branches
Tags
No related merge requests found
......@@ -64,6 +64,16 @@ gitlab-opentofu-image:build:
--push
.
check-readme:
stage: test
needs: []
image: alpine:latest
before_script:
- apk add coreutils make git
script:
- make docs
- git diff --exit-code
container_scanning:
extends: .opentofu-versions
needs: ['gitlab-opentofu-image:build']
......
# OpenTofu CI/CD component
> 🚨 🚧 **NOTE** 🚧 🚨
>
> This component is **work in progress**, where inputs, template names and the entire interface in general may
> change at any time until version 1.0.0 is reached. From where on this CI/CD component will be versioned using [semver 2.0](https://semver.org/).
> The progress of implementing such a version can be tracked in https://gitlab.com/groups/gitlab-org/-/epics/12401.
>
> 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.
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)
## 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, test, build, deploy, cleanup]
```
A concrete example may look like this:
```yaml
# Using `latest`
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.0
stages: [validate, test, build, deploy, cleanup]
---
# ... or using `0.0.0-alpha1`:
include:
- component: gitlab.com/components/opentofu/full-pipeline@0.0.0-alpha1
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.0.0-alpha1
opentofu_version: 1.6.0
stages: [validate, test, build, deploy, cleanup]
```
### Inputs
| Name | Default | Description |
| ---- | ------- | ----------- |
<INPUTS>
## 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*
## Contributing
See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.
......@@ -2,6 +2,11 @@
Please read about CI/CD components and best practices at: https://docs.gitlab.com/ee/ci/components
## README
The [`README.md`](README.md) file is generated using `make docs` (see [`Makefile`](Makefile))
from [`.gitlab/README.md`](.gitlab/README.md).
## Upgrade OpenTofu versions
When adding new OpenTofu versions the following places need to be updated:
......
docs:
csplit -sf readme -n 1 .gitlab/README.md '/<INPUTS>/'
yq '.spec.inputs | .[] | "| `" + key + "` | `" + .default + "` | " + .description + " |"' templates/full-pipeline.yml > readme_inputs.md
echo '<!-- This document is generated by `make docs` from `.gitlab/README.md` -->\n' > README.md
cat readme0 >> README.md
cat readme_inputs.md >> README.md
tail -n+2 readme1 >> README.md
rm -f readme0 readme1 readme_inputs.md
<!-- This document is generated by `make docs` from `.gitlab/README.md` -->
# OpenTofu CI/CD component
> 🚨 🚧 **NOTE** 🚧 🚨
......@@ -65,6 +67,23 @@ include:
stages: [validate, test, build, deploy, cleanup]
```
### Inputs
| Name | Default | Description |
| ---- | ------- | ----------- |
| `stage_validate` | `validate` | Defines the validate stage |
| `stage_test` | `test` | Defines the test stage |
| `stage_build` | `build` | Defines the build stage |
| `stage_deploy` | `deploy` | Defines the deploy stage |
| `stage_cleanup` | `cleanup` | Defines the cleanup stage |
| `version` | `latest` | Version of this component |
| `opentofu_version` | `1.6.0` | Released version of upstream OpenTofu |
| `gitlab_opentofu_image` | `$CI_REGISTRY/components/opentofu/gitlab-opentofu:$[[ inputs.version ]]-opentofu$[[ inputs.opentofu_version ]]` | Image name of the gitlab-opentofu image |
| `root_dir` | `${CI_PROJECT_DIR}` | Root directory for the OpenTofu project |
| `state_name` | `default` | 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 |
## Releases & Versioning
This project currently releases tagged commits.
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment