website: Initial docs about the APT/Yum repositories

The HashiCorp engineering services team has set up APT and Yum
repositories as alternative installation methods for various HashiCorp
products, now including Terraform.

We don't really have a great place to talk about these in our current
website structure. There is a longer-term plan to revamp the downloads
page to include other options, but we are already getting lots of
questions about how to use these repositories and so my goal here is to
publish at least a first pass of documentation, linked from the Downloads
page sidebar as a placeholder for now, so we'll have somewhere to refer to
when answering such questions.

My intent is that even once we have a revamped Downloads page that
mentions these options more clearly, we'll still need to link out to
another page to talk about various details, and so the two new URLs this
creates would be the home of that content, even if we rewrite the specific
prose here to work better in the context of the new Downloads page.

website/docs/cli/install/apt.html.md

@@ -0,0 +1,134 @@
+---
+layout: "downloads"
+page_title: "APT Packages for Debian and Ubuntu"
+sidebar_current: "docs-cli-install-apt"
+description: |-
+  The HashiCorp APT repositories contain distribution-specific Terraform packages for both Debian and Ubuntu systems.
+---
+
+# APT Packages for Debian and Ubuntu
+
+The primary distribution packages for Terraform are `.zip` archives containing
+single executable files that you can extract anywhere on your system. However,
+for easier integration with configuration management tools and other systematic
+system configuration strategies, we also offer package repositories for
+Debian and Ubuntu systems, which allow you to install Terraform using the
+`apt install` command or any other APT frontend.
+
+If you are instead using Red Hat Enterprise Linux, CentOS, or Fedora, you
+might prefer to [install Terraform from our Yum repositories](yum.html).
+
+-> **Note:** The APT repositories discussed on this page are generic HashiCorp
+repositories that contain packages for a variety of different HashiCorp
+products, rather than just Terraform. Adding these repositories to your
+system will, by default, therefore make a number of other non-Terraform
+packages available for installation. That might then mask some packages that
+are available for some HashiCorp products in the main Debian and Ubuntu
+package repositories.
+
+## Repository Configuration
+
+The Terraform packages are signed using a private key controlled by HashiCorp,
+so in most situations the first step would be to configure your system to trust
+that HashiCorp key for package authentication. For example:
+
+```bash
+curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
+```
+
+After registering the key, you can add the official HashiCorp repository to
+your system:
+
+```bash
+sudo apt-add-repository "deb [arch=$(dpkg --print-architecture)] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
+```
+
+The above command line uses the following sub-shell commands:
+
+* `dpkg --print-architecture` to determine your system's primary APT
+  architecture/ABI, such as `amd64`.
+* `lsb_release -cs` to find the distribution release codename for your current
+  system, such as `buster`, `groovy`, or `sid`.
+
+`apt-add-repository` usually automatically runs `apt update` as part of its
+work in order to fetch the new package indices, but if it does not then you
+will need to so manually before the packages will be available.
+
+To install Terraform from the new repository:
+
+```bash
+sudo apt install terraform
+```
+
+## Supported Architectures
+
+The HashiCorp APT server currently has packages only for the `amd64`
+architecture, which is also sometimes known as `x86_64`.
+
+There are no official packages available for other architectures, such as
+`arm64`. If you wish to use Terraform on a non-`amd64` system,
+[download a normal release `.zip` file](/downloads.html) instead.
+
+## Supported Debian and Ubuntu Releases
+
+The HashiCorp APT server currently contains release repositories for the
+following distribution releases:
+
+* Debian 8 (`jessie`)
+* Debian 9 (`stretch`)
+* Debian 10 (`buster`)
+* Ubuntu 16.04 (`xenial`)
+* Ubuntu 18.04 (`bionic`)
+* Ubuntu 19.10 (`eoam`)
+* Ubuntu 20.04 (`focal`)
+* Ubuntu 20.10 (`groovy`)
+
+No repositories are available for other Debian or Ubuntu versions or for
+any other APT-based Linux distributions. If you add the repository using
+the above commands on other systems then `apt update` will report the
+repository index as missing.
+
+Terraform executables are statically linked and so they depend only on the
+Linux system call interface, not on any system libraries. Because of that,
+you may be able to use one of the above release codenames when adding a
+repository to your system, even if that codename doesn't match your current
+distribution release.
+
+Over time we will change the set of supported distributions, including both
+adding support for new releases and ceasing to publish new Terraform versions
+under older releases.
+
+## Choosing Terraform Versions
+
+The HashiCorp APT repositories contain multiple versions of Terraform, but
+because the packages are all named `terraform` it is impossible to install
+more than one version at a time, and `apt install` will default to selecting
+the latest version.
+
+It's often necessary to match your Terraform version with what a particular
+configuration is currently expecting. You can use the following command to
+see which versions are currently available in the repository index:
+
+```bash
+apt policy terraform
+```
+
+There may be multiple package releases for a particular Terraform version if
+we need to publish an updated package for any reason. In that case, the
+subsequent releases will have an additional suffix, like `0.13.4-2`. In these
+cases the Terraform executable inside the package should be unchanged, but its
+metadata and other contents may be different.
+
+You can select a specific version to install by including it in the
+`apt install` command line, as follows:
+
+```bash
+sudo apt install terraform==0.14.0
+```
+
+If your workflow requires using multiple versions of Terraform at the same
+time, for example when working through a gradual upgrade where not all
+of your configurations are upgraded yet, we recommend that you use the
+official release `.zip` files instead of the APT packages, so you can install
+multiple versions at once and then select which to use for each command you
+run.

website/docs/cli/install/yum.html.md

@@ -0,0 +1,121 @@
+---
+layout: "downloads"
+page_title: "Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux"
+sidebar_current: "docs-cli-install-yum"
+description: |-
+  The HashiCorp Yum repositories contain distribution-specific Terraform packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems.
+---
+
+# Yum/DNF Packages for RHEL, CentOS, and Fedora
+
+The primary distribution packages for Terraform are `.zip` archives containing
+single executable files that you can extract anywhere on your system. However,
+for easier integration with configuration management tools and other systematic
+system configuration strategies, we also offer package repositories for
+RedHat Enterprise Linux, Fedora, and Amazon Linux systems, which allow you to
+install Terraform using the `yum install` or `dnf install` commands.
+
+If you are instead using Debian or Ubuntu, you
+might prefer to [install Terraform from our APT repositories](apt.html).
+
+-> **Note:** The Yum repositories discussed on this page are generic HashiCorp
+repositories that contain packages for a variety of different HashiCorp
+products, rather than just Terraform. Adding these repositories to your
+system will, by default, therefore make a number of other non-Terraform
+packages available for installation. That might then mask the packages that are
+available for some HashiCorp products in the main distribution repositories.
+
+## Repository Configuration
+
+Before adding a repository you must determine which distribution you are using.
+The following command lines refer to a placeholder variable `$release` which
+you must replace with the appropriate value from the following list:
+
+* Red Hat Enterprise Linux: `RHEL`
+* Fedora: `fedora`
+* Amazon Linux: `AmazonLinux`
+
+If you are using a Yum-based distribution, add the repository using
+`yum-config-manager` as follows:
+
+```bash
+sudo yum install -y yum-utils
+sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo
+```
+
+If you are using a DNF-based distribution, add the repository using
+`dnf config-manager` as follows:
+
+```bash
+sudo dnf install -y dnf-plugins-core
+sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/$release/hashicorp.repo
+```
+
+In both cases, the Terraform package name is `terraform`. For example:
+
+```bash
+yum install terraform
+```
+
+## Supported Architectures
+
+The HashiCorp Yum/DNF server currently has packages only for the `x86_64`
+architecture, which is also sometimes known as `amd64`.
+
+There are no official packages available for other architectures, such as
+`aarch64`. If you wish to use Terraform on a non-`x86_64` system,
+[download a normal release `.zip` file](/downloads.html) instead.
+
+## Supported Distribution Releases
+
+The HashiCorp Yum server currently contains release repositories for the
+following distribution releases:
+
+* AmazonLinux 2
+* Fedora 29
+* Fedora 30
+* Fedora 31
+* Fedora 32
+* Fedora 33
+* RHEL 7 (and CentOS 7)
+* RHEL 8 (and CentOS 8)
+
+No repositories are available for other versions of these distributions or for
+any other RPM-based Linux distributions. If you add the repository using
+the above commands on other systems then you will see a 404 Not Found error.
+
+Over time we will change the set of supported distributions, including both
+adding support for new releases and ceasing to publish new Terraform versions
+under older releases.
+
+## Choosing Terraform Versions
+
+The HashiCorp Yum repositories contain multiple versions of Terraform, but
+because the packages are all named `terraform` it is impossible to install
+more than one version at a time, and `yum install` or `dnf install` will
+default to selecting the latest version.
+
+It's often necessary to match your Terraform version with what a particular
+configuration is currently expecting. You can use the following command to
+see which versions are currently available in the repository index:
+
+```bash
+yum --showduplicate list terraform
+```
+
+You can select a specific version to install by including it in the
+`yum install` command line, as follows:
+
+```bash
+yum install terraform-0.14.0-2.x86_64
+```
+
+If you are using a DNF-based distribution, similar use `dnf` instead of `yum`
+when following the above steps.
+
+If your workflow requires using multiple versions of Terraform at the same
+time, for example when working through a gradual upgrade where not all
+of your configurations are upgraded yet, we recommend that you use the
+official release `.zip` files instead of the Yum packages, so you can install
+multiple versions at once and then select which to use for each command you
+run.

website/layouts/downloads.erb

@@ -7,6 +7,14 @@
         <a href="/downloads.html">Download Terraform</a>
       </li>
 
+      <li<%= sidebar_current("docs-cli-install-apt") %>>
+        <a href="/docs/cli/install/apt.html">Debian/Ubuntu APT Packages</a>
+      </li>
+
+      <li<%= sidebar_current("docs-cli-install-yum") %>>
+        <a href="/docs/cli/install/yum.html">RHEL/Fedora Yum Packages</a>
+      </li>
+
       <li<%= sidebar_current("upgrade-guides") %>>
         <a href="/upgrade-guides/index.html">Upgrade Guides</a>
       </li>