From 42c523e6a290a7c8ebc1ea4acfcdce296fb68915 Mon Sep 17 00:00:00 2001 From: Dalton Hubble Date: Tue, 27 Nov 2018 00:08:51 -0800 Subject: [PATCH] Recommend switch from ~/.terraformrc to 3rd-party plugin dir * Switch tutorials from using ~/.terraformrc to using the 3rd-party plugin directory so 3rd-party plugins can be pinned * Continue to show using terraform-provider-ct v0.2.2. Updating to a newer version is only safe once all managed clusters are v1.12.2 or higher --- CHANGES.md | 3 ++ docs/architecture/concepts.md | 2 +- docs/cl/aws.md | 16 ++++----- docs/cl/azure.md | 16 ++++----- docs/cl/bare-metal.md | 21 +++++------ docs/cl/digital-ocean.md | 16 ++++----- docs/cl/google-cloud.md | 16 ++++----- docs/topics/maintenance.md | 67 +++++++++++++++++++++++++++++++++++ 8 files changed, 104 insertions(+), 53 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index aeb03402..7b9d2faf 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -16,6 +16,9 @@ Notable changes between versions. * Enable CoreDNS `loop` and `loadbalance` plugins ([#340](https://github.com/poseidon/typhoon/pull/340)) * Fix pod-checkpointer log noise and checkpointable pods detection ([#346](https://github.com/poseidon/typhoon/pull/346)) * Use kubernetes-incubator/bootkube v0.14.0 +* [Recommend](https://typhoon.psdn.io/topics/maintenance/#terraform-plugins-directory) switching from `~/.terraformrc` to the Terraform [third-party plugins](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins) directory `~/.terraform.d/plugins/`. + * Allows pinning `terraform-provider-ct` and `terraform-provider-matchbox` versions + * Improves safety of later plugin version migrations #### Azure diff --git a/docs/architecture/concepts.md b/docs/architecture/concepts.md index d42416ef..255ab02f 100644 --- a/docs/architecture/concepts.md +++ b/docs/architecture/concepts.md @@ -69,7 +69,7 @@ Module versioning ensures `terraform get --update` only fetches the desired vers Maintain Terraform configs for "live" infrastructure in a versioned repository. Seek to organize configs to reflect resources that should be managed together in a `terraform apply` invocation. -You may choose to organize resources all together, by team, by project, or some other scheme. Here's an example that manages four clusters together: +You may choose to organize resources all together, by team, by project, or some other scheme. Here's an example that manages clusters together: ```sh .git/ diff --git a/docs/cl/aws.md b/docs/cl/aws.md index f8455dcf..f97d3234 100644 --- a/docs/cl/aws.md +++ b/docs/cl/aws.md @@ -21,20 +21,12 @@ $ terraform version Terraform v0.11.7 ``` -Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system. +Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system to `~/.terraform.d/plugins/`, noting the final name. ```sh wget https://github.com/coreos/terraform-provider-ct/releases/download/v0.2.1/terraform-provider-ct-v0.2.1-linux-amd64.tar.gz tar xzf terraform-provider-ct-v0.2.1-linux-amd64.tar.gz -sudo mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct /usr/local/bin/ -``` - -Add the plugin to your `~/.terraformrc`. - -``` -providers { - ct = "/usr/local/bin/terraform-provider-ct" -} +mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct ~/.terraform.d/plugins/terraform-provider-ct_v0.2.1 ``` Read [concepts](/architecture/concepts/) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`). @@ -64,6 +56,10 @@ provider "aws" { shared_credentials_file = "/home/user/.config/aws/credentials" } +provider "ct" { + version = "0.2.1" +} + provider "local" { version = "~> 1.0" alias = "default" diff --git a/docs/cl/azure.md b/docs/cl/azure.md index 7e68dc9f..4f43ef18 100644 --- a/docs/cl/azure.md +++ b/docs/cl/azure.md @@ -24,20 +24,12 @@ $ terraform version Terraform v0.11.7 ``` -Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system. +Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system to `~/.terraform.d/plugins/`, noting the final name. ```sh wget https://github.com/coreos/terraform-provider-ct/releases/download/v0.2.1/terraform-provider-ct-v0.2.1-linux-amd64.tar.gz tar xzf terraform-provider-ct-v0.2.1-linux-amd64.tar.gz -sudo mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct /usr/local/bin/ -``` - -Add the plugin to your `~/.terraformrc`. - -``` -providers { - ct = "/usr/local/bin/terraform-provider-ct" -} +mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct ~/.terraform.d/plugins/terraform-provider-ct_v0.2.1 ``` Read [concepts](/architecture/concepts/) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`). @@ -62,6 +54,10 @@ provider "azurerm" { alias = "default" } +provider "ct" { + version = "0.2.1" +} + provider "local" { version = "~> 1.0" alias = "default" diff --git a/docs/cl/bare-metal.md b/docs/cl/bare-metal.md index 2b209e2f..1742bb7f 100644 --- a/docs/cl/bare-metal.md +++ b/docs/cl/bare-metal.md @@ -113,28 +113,20 @@ $ terraform version Terraform v0.11.7 ``` -Add the [terraform-provider-matchbox](https://github.com/coreos/terraform-provider-matchbox) plugin binary for your system. +Add the [terraform-provider-matchbox](https://github.com/coreos/terraform-provider-matchbox) plugin binary for your system to `~/.terraform.d/plugins/`, noting the final name. ```sh wget https://github.com/coreos/terraform-provider-matchbox/releases/download/v0.2.2/terraform-provider-matchbox-v0.2.2-linux-amd64.tar.gz tar xzf terraform-provider-matchbox-v0.2.2-linux-amd64.tar.gz -sudo mv terraform-provider-matchbox-v0.2.2-linux-amd64/terraform-provider-matchbox /usr/local/bin/ +mv terraform-provider-matchbox-v0.2.2-linux-amd64/terraform-provider-matchbox ~/.terraform.d/plugins/terraform-provider-matchbox_v0.2.2 ``` -Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system. +Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system to `~/.terraform.d/plugins/`, noting the final name. ```sh wget https://github.com/coreos/terraform-provider-ct/releases/download/v0.2.1/terraform-provider-ct-v0.2.1-linux-amd64.tar.gz tar xzf terraform-provider-ct-v0.2.1-linux-amd64.tar.gz -sudo mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct /usr/local/bin/ -``` - -Add the plugin to your `~/.terraformrc`. - -``` -providers { - matchbox = "/usr/local/bin/terraform-provider-matchbox" -} +mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct ~/.terraform.d/plugins/terraform-provider-ct_v0.2.1 ``` Read [concepts](/architecture/concepts/) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`). @@ -149,12 +141,17 @@ Configure the Matchbox provider to use your Matchbox API endpoint and client cer ```tf provider "matchbox" { + version = "0.2.2" endpoint = "matchbox.example.com:8081" client_cert = "${file("~/.config/matchbox/client.crt")}" client_key = "${file("~/.config/matchbox/client.key")}" ca = "${file("~/.config/matchbox/ca.crt")}" } +provider "ct" { + version = "0.2.1" +} + provider "local" { version = "~> 1.0" alias = "default" diff --git a/docs/cl/digital-ocean.md b/docs/cl/digital-ocean.md index 835fee0e..a2cc0b66 100644 --- a/docs/cl/digital-ocean.md +++ b/docs/cl/digital-ocean.md @@ -21,20 +21,12 @@ $ terraform version Terraform v0.11.7 ``` -Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system. +Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system to `~/.terraform.d/plugins/`, noting the final name. ```sh wget https://github.com/coreos/terraform-provider-ct/releases/download/v0.2.1/terraform-provider-ct-v0.2.1-linux-amd64.tar.gz tar xzf terraform-provider-ct-v0.2.1-linux-amd64.tar.gz -sudo mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct /usr/local/bin/ -``` - -Add the plugin to your `~/.terraformrc`. - -``` -providers { - ct = "/usr/local/bin/terraform-provider-ct" -} +mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct ~/.terraform.d/plugins/terraform-provider-ct_v0.2.1 ``` Read [concepts](/architecture/concepts/) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`). @@ -63,6 +55,10 @@ provider "digitalocean" { alias = "default" } +provider "ct" { + version = "0.2.1" +} + provider "local" { version = "~> 1.0" alias = "default" diff --git a/docs/cl/google-cloud.md b/docs/cl/google-cloud.md index ec44650e..de901639 100644 --- a/docs/cl/google-cloud.md +++ b/docs/cl/google-cloud.md @@ -21,20 +21,12 @@ $ terraform version Terraform v0.11.7 ``` -Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system. +Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system to `~/.terraform.d/plugins/`, noting the final name. ```sh wget https://github.com/coreos/terraform-provider-ct/releases/download/v0.2.1/terraform-provider-ct-v0.2.1-linux-amd64.tar.gz tar xzf terraform-provider-ct-v0.2.1-linux-amd64.tar.gz -sudo mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct /usr/local/bin/ -``` - -Add the plugin to your `~/.terraformrc`. - -``` -providers { - ct = "/usr/local/bin/terraform-provider-ct" -} +mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct ~/.terraform.d/plugins/terraform-provider-ct_v0.2.1 ``` Read [concepts](/architecture/concepts/) to learn about Terraform, modules, and organizing resources. Change to your infrastructure repository (e.g. `infra`). @@ -65,6 +57,10 @@ provider "google" { region = "us-central1" } +provider "ct" { + version = "0.2.1" +} + provider "local" { version = "~> 1.0" alias = "default" diff --git a/docs/topics/maintenance.md b/docs/topics/maintenance.md index 313610b7..c3b738c2 100644 --- a/docs/topics/maintenance.md +++ b/docs/topics/maintenance.md @@ -126,3 +126,70 @@ Typhoon supports multi-controller clusters, so it is possible to upgrade a clust !!! warning Typhoon does not support or document node replacement as an upgrade strategy. It limits Typhoon's ability to make infrastructure and architectural changes between tagged releases. + +### Terraform Plugins Directory + +Use the Terraform 3rd-party [plugin directory](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins) `~/.terraform.d/plugins` to keep versioned copies of the `terraform-provider-ct` and `terraform-provider-matchbox` plugins. The plugin directory replaces the `~/.terraformrc` file to allow 3rd party plugins to be defined and versioned independently (rather than globally). + +``` +# ~/.terraformrc (DEPRECATED) +providers { + ct = "/usr/local/bin/terraform-provider-ct" + matchbox = "/usr/local/bin/terraform-provider-matchbox" +} +``` + +Migrate to using the Terraform plugin directory. Move `~/.terraformrc` to a backup location. + +``` +mv ~/.terraformrc ~/.terraform-backup +``` + +Add the [terraform-provider-ct](https://github.com/coreos/terraform-provider-ct) plugin binary for your system to `~/.terraform.d/plugins/`. Download the **same version** of `terraform-provider-ct` you were using with `~/.terraformrc`, updating only be done as a followup and is **only** safe for v1.12.2+ clusters! + +```sh +wget https://github.com/coreos/terraform-provider-ct/releases/download/v0.2.1/terraform-provider-ct-v0.2.1-linux-amd64.tar.gz +tar xzf terraform-provider-ct-v0.2.1-linux-amd64.tar.gz +mv terraform-provider-ct-v0.2.1-linux-amd64/terraform-provider-ct ~/.terraform.d/plugins/terraform-provider-ct_v0.2.1 +``` + +If you use bare-metal, add the [terraform-provider-matchbox](https://github.com/coreos/terraform-provider-matchbox) plugin binary for your system to `~/.terraform.d/plugins/`, noting the versioned name. + +```sh +wget https://github.com/coreos/terraform-provider-matchbox/releases/download/v0.2.2/terraform-provider-matchbox-v0.2.2-linux-amd64.tar.gz +tar xzf terraform-provider-matchbox-v0.2.2-linux-amd64.tar.gz +mv terraform-provider-matchbox-v0.2.2-linux-amd64/terraform-provider-matchbox ~/.terraform.d/plugins/terraform-provider-matchbox_v0.2.2 +``` + +Binary names are versioned. This enables the ability to upgrade different plugins and have clusters pin different versions. + +``` +$ tree ~/.terraform.d/ +/home/user/.terraform.d/ +└── plugins + ├── terraform-provider-ct_v0.2.1 + └── terraform-provider-matchbox_v0.2.2 +``` + +In each Terraform working directory, set the version of each provider. + +``` +# providers.tf + +provider "matchbox" { + version = "0.2.2" + ... +} + +provider "ct" { + version = "0.2.1" +} +``` + +Run `terraform init` to ensure plugin version requirements are met. Verify `terraform plan` does not produce a diff, since the plugin versions should be the same as previously. + +``` +$ terraform init +$ terraform plan +``` +