From bc0b686cda244fa6d182b9bfaf6fa6d04abcea6d Mon Sep 17 00:00:00 2001 From: Timo Furrer <tfurrer@gitlab.com> Date: Tue, 16 Jan 2024 10:56:00 +0100 Subject: [PATCH] Add README --- CONTRIBUTING.md | 3 ++ README.md | 97 +++++++++++++++++++++++++++++++++++-- templates/full-pipeline.yml | 8 ++- 3 files changed, 104 insertions(+), 4 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5a920c7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing + +Please read about CI/CD components and best practices at: https://docs.gitlab.com/ee/ci/components diff --git a/README.md b/README.md index 87d2224..e5b38f6 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,96 @@ -# WIP: OpenTofu +# OpenTofu CI/CD component -This OpenTofu CI/CD component is still work in progress. +> **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. -See https://gitlab.com/groups/gitlab-org/-/epics/12401 +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> +``` + +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 + +--- + +# ... 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 +``` + +## 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. diff --git a/templates/full-pipeline.yml b/templates/full-pipeline.yml index 9a936a5..ad60cd9 100644 --- a/templates/full-pipeline.yml +++ b/templates/full-pipeline.yml @@ -18,6 +18,12 @@ spec: description: 'Defines the cleanup stage' # Versions + # This version is only required, because we cannot access the context of the component, + # see https://gitlab.com/gitlab-org/gitlab/-/issues/438275 + version: + default: 'latest' + description: 'Version of this component' + opentofu_version: default: '1.6.0' options: @@ -30,7 +36,7 @@ spec: # FIXME: This should reference the component tag that is used. # Currently, blocked by https://gitlab.com/gitlab-org/gitlab/-/issues/438275 # default: '$CI_REGISTRY/components/opentofu/gitlab-opentofu:$[[ inputs.opentofu_version ]]' - default: '$CI_REGISTRY/components/opentofu/gitlab-opentofu:latest' + default: '$CI_REGISTRY/components/opentofu/gitlab-opentofu:$[[ inputs.version ]]-opentofu$[[ inputs.opentofu_version ]]' description: 'Image name of the gitlab-opentofu image' # Configuration -- GitLab