65ad73fe03
We've removed the main documentation pages for the backends that are removed in Terraform v1.3, but we'll leave a small callout note so that the backend names are still reachable through our search index once the v1.3 docs are the active version. The primary goal here is to help folks who have inherited configurations using older versions of Terraform to learn about features they see in those configurations, so the main thing here is the link to the older release docs which include those. However, this is also a good opportunity to link to the upgrade guide content which describes some possible migration paths away from these removed backends. |
||
|---|---|---|
| .. | ||
| data | ||
| docs | ||
| img/docs | ||
| layouts | ||
| scripts | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| vercel.json | ||
Terraform Documentation
This directory contains the portions of the Terraform website that pertain to the core functionality, excluding providers and the overall configuration.
The website uses the files in this directory in conjunction with
the terraform-website repository. The terraform-website repository brings all of the documentation together and contains the scripts for testing and building the entire site.
Suggesting Changes
You can submit an issue with documentation requests or submit a pull request with suggested changes.
Click Edit this page at the bottom of any Terraform website page to go directly to the associated markdown file in GitHub.
Modifying Sidebar Navigation
You must update the the sidebar navigation when you add or delete documentation .mdx files. If you do not update the navigation, the website deploy preview fails.
To update the sidebar navigation, you must edit the appropriate nav-data.json file. This repository contains the sidebar navigation files for the following documentation sets:
- Terraform Language:
language-nav-data.json - Terraform CLI:
cli-nav-data.json - Introduction to Terraform:
intro-nav-data.json
For more details about how to update the sidebar navigation, refer to Editing Navigation Sidebars in the terraform-website repository.
Adding Redirects
You must add a redirect when you move, rename, or delete documentation pages. Refer to https://github.com/hashicorp/terraform-website#redirects for details.
Previewing Changes
You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the terraform-website repository, allowing you to preview the entire Terraform documentation site.
Set Up Local Environment
-
Install Go or create a
~/godirectory manually. -
Open terminal and set
GOPATHas an environment variable:Bash:
export $GOPATH=~/go(bash)Zsh:
echo -n 'export GOPATH=~/go' >> ~/.zshrc -
Restart your terminal or command line session.
Launch Site Locally
- Navigate into your local
terraformtop-level directory and runmake website. - Open
http://localhost:3000in your web browser. While the preview is running, you can edit pages and Next.js automatically rebuilds them. - Press
ctrl-Cin your terminal to stop the server and end the preview.
Deploying Changes
Merging a PR to main queues up documentation changes for the next minor product release. Your changes are not immediately available on the website.
The website generates versioned documentation by pointing to the HEAD of the release branch for that version. For example, the v1.2.x documentation on the website points to the HEAD of the v1.2 release branch in the terraform repository. To update existing documentation versions, you must also backport your changes to that release branch. Backported changes become live on the site within one hour.
Backporting
Important: Editing old versions (not latest) should be rare. We backport to old versions when there is an egregious error. Egregious errors include inaccuracies that could cause security vulnerabilities or extreme inconvenience for users.
Backporting involves cherry-picking commits to one or more release branches within a docs repository. You can backport (cherry-pick) commits to a version branch by adding the associated backport label to your pull request. For example, if you need to add a security warning to the v1.1 documentation, you must add the 1.1-backport label. When you merge a pull request with one or more backport labels, GitHub Actions opens a backport PR to cherry-pick your changes to the associated release branches. You must manually merge the backport PR to finish backporting the changes.
To make your changes available on the latest docs version:
-
Add the backport label for the latest version.
-
Merge the pull request. GitHub Actions autogenerates a backport pull request, linked to the original.
-
Merge the auto-generated backport pull request.
You can review and merge your own backport pull request without waiting for another review if the changes in the backport pull request are effectively equivalent to the original. You can make minor adjustments to resolve merge conflicts, but you should not merge a backport PR that contains major content or functionality changes from the original, approved pull request. If you are not sure whether it is okay to merge a backport pull request, post a comment on the original pull request to discuss with the team.