From 35a63aa2d5c4d2e6d1c8ddee9f75e250813958ef Mon Sep 17 00:00:00 2001 From: Ryan Ahearn Date: Tue, 3 Dec 2024 11:22:36 -0500 Subject: [PATCH] Add UPGRADING.md documentation for moving to v2 --- README.md | 14 +++--- SECURITY.md | 1 + UPGRADING.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 127 insertions(+), 7 deletions(-) create mode 100644 UPGRADING.md diff --git a/README.md b/README.md index 67d54bf..aabbd51 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Creates an RDS database based on the `rds_plan_name` variable and outputs the `i ``` module "database" { - source = "github.com/GSA-TTS/terraform-cloudgov//database?ref=v2.0.0-beta.1" + source = "github.com/GSA-TTS/terraform-cloudgov//database?ref=v2.0.0" cf_space_id = data.cloudfoundry_space.app_space.id name = "database_name" @@ -31,7 +31,7 @@ Creates a Elasticache redis instance and outputs the `instance_id` for use elsew ``` module "redis" { - source = "github.com/GSA-TTS/terraform-cloudgov//redis?ref=v2.0.0-beta.1" + source = "github.com/GSA-TTS/terraform-cloudgov//redis?ref=v2.0.0" cf_space_id = data.cloudfoundry_space.app_space.id name = "redis_name" @@ -52,7 +52,7 @@ Creates an s3 bucket and outputs the `bucket_id` for use elsewhere. ``` module "s3" { - source = "github.com/GSA-TTS/terraform-cloudgov//s3?ref=v2.0.0-beta.1" + source = "github.com/GSA-TTS/terraform-cloudgov//s3?ref=v2.0.0" cf_space_id = data.cloudfoundry_space.app_space.id name = "${local.app_name}-s3-${local.env}" @@ -76,7 +76,7 @@ Note that the domain must be created in cloud.gov by an OrgManager before this m ``` module "domain" { - source = "github.com/GSA-TTS/terraform-cloudgov//domain?ref=v2.0.0-beta.1" + source = "github.com/GSA-TTS/terraform-cloudgov//domain?ref=v2.0.0" cf_org_name = local.cf_org_name cf_space = data.cloudfoundry_space.app_space @@ -98,7 +98,7 @@ Notes: ``` module "clamav" { - source = "github.com/GSA-TTS/terraform-cloudgov//clamav?ref=v2.0.0-beta.1" + source = "github.com/GSA-TTS/terraform-cloudgov//clamav?ref=v2.0.0" cf_org_name = local.cf_org_name cf_space_name = local.cf_space_name @@ -125,7 +125,7 @@ Creates a new cloud.gov space, such as when creating an egress space, and output ``` module "egress_space" { - source = "github.com/GSA-TTS/terraform-cloudgov//cg_space?ref=v2.0.0-beta.1" + source = "github.com/GSA-TTS/terraform-cloudgov//cg_space?ref=v2.0.0" cf_org_name = local.cf_org_name cf_space_name = "${local.cf_space_name}-egress" @@ -153,7 +153,7 @@ Prerequities: ``` module "egress_proxy" { - source = "github.com/GSA-TTS/terraform-cloudgov//egress_proxy?ref=v2.0.0-beta.1" + source = "github.com/GSA-TTS/terraform-cloudgov//egress_proxy?ref=v2.0.0" cf_org_name = local.cf_org_name cf_egress_space = data.cloudfoundry_space.egress_space diff --git a/SECURITY.md b/SECURITY.md index 5289d1d..846f684 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,6 +7,7 @@ Only certain branches are supported with security updates. | Version (branch) | Supported | | ---------------- | --------- | | main | :white_check_mark: | +| v1 | :white_check_mark: | | other | :x: | When using this code or reporting vulnerability please be sure to use supported branches and the most recent release tag. diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 0000000..e40f824 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,119 @@ +# Upgrading from v1 to v2 + +The terraform-cloudgov modules have many backwards-incompatible changes between v1 and v2. These changes are mostly around: + +1. Changing from the [cloudfoundry-community](https://registry.terraform.io/providers/cloudfoundry-community/cloudfoundry/latest/docs) provider to the [cloudfoundry](https://registry.terraform.io/providers/cloudfoundry/cloudfoundry/latest/docs) provider. +1. Changes to inputs and outputs and resources created to better fit with the new provider and as the result of lessons learned over the life of the v1 code base. + +## Using v1 and v2 together + +It is possible to use modules from both v1 and v2 in the same root module, to ease migration (or even remain on v1 for existing resources and use v2 for new ones). We will continue to maintain the v1 branch for awhile with bug-fixes as needed. + +Specify both providers in your root module (here, `cloudfoundry-community` is probably called `cloudfoundry` in your old module): + +``` +terraform { + required_version = "~> 1.0" + required_providers { + cloudfoundry = { + source = "cloudfoundry/cloudfoundry" + version = "1.1.0" + } + + cloudfoundry-community = { + source = "cloudfoundry-community/cloudfoundry" + version = "0.53.1" + } + } +} + +provider "cloudfoundry" { + api_url = "https://api.fr.cloud.gov" + user = var.cf_user + password = var.cf_password +} + +provider "cloudfoundry-community" { + api_url = "https://api.fr.cloud.gov" + user = var.cf_user + password = var.cf_password +} +``` + +The v1 modules should properly select the `cloudfoundry-community` provider, but if they don't you may need to [explicitely set the provider](https://developer.hashicorp.com/terraform/language/modules/develop/providers#passing-providers-explicitly): + +``` +module "database" { + source = "github.com/gsa-tts/terraform-cloudgov//database?ref=v1.1.0" + providers = { + cloudfoundry = cloudfoundry-community + } + + # ... +} +``` + +## Provider Upgrades + +Follow the steps in the [cloudfoundry provider migration guide](https://github.com/cloudfoundry/terraform-provider-cloudfoundry/blob/main/migration-guide/Readme.md) to migrate an existing use of the v1 module to v2. As an example, here are the steps for upgrading a database module: + +1. Update source line to point to v2 module and change `cf_space_name` to `cf_space_id` +1. Verify that `terraform validate` passes +1. Run: `terraform state show module.database.cloudfoundry_service_instance.rds | grep -m 1 id` and copy the ID +1. Run: `terraform state rm module.database.cloudfoundry_service_instance.rds` +1. Run: `terraform import module.database.cloudfoundry_service_instance.rds ID_FROM_STEP_3` +1. Run: `terraform apply` to fill in new computed attributes + +## Module Changes + +### Common Changes + +1. Check the `variables.tf` and `outputs.tf` files for each module for new names of variables and outputs. There should not be any variables or outputs that kept the same name but changed behavior. + +### Egress Proxy + +Egress Proxy no longer sets up network policies between the proxy and client apps, and does not create a User Provided Service Instance to deliver the credentials to the app. It is the developer's responsibility to do those things in the root module to better handle circular dependencies between creating the client app(s) and the proxy. + +To setup the network policy in your root module, add: + +``` +resource "cloudfoundry_network_policy" "egress_policy" { + provider = cloudfoundry-community + policy { + source_app = cloudfoundry_app.client_app.id # assumes you're deploying the client app with terraform + destination_app = module.egress_proxy.app_id + port = module.egress_proxy.https_port + } +} +``` + +To add a UPSI: + +``` +resource "cloudfoundry_service_instance" "egress_proxy_credentials" { + name = "egress-proxy-credentials" + space = module.app_space.space_id + type = "user-provided" + credentials = module.egress_proxy.json_credentials +} +``` + +### Clamav + +Clamav no longer sets up network policies between the clamav app and client apps. It is the developer's responsibility to set this up to better handle circular dependencies between the various apps. + +### cg_space + +Migrating the space roles is a little trickier. Here is a path forward: + +1. Upgrade the space module source to v2 +1. `terraform apply -target=module.space.cloudfoundry_space_users.space_permissions` to remove the old permissions resources. +1. Manually add your terraform user as a SpaceDeveloper and a SpaceManager to the space. + ``` + cf set-space-role CF_USER_GUID ORG SPACE SpaceDeveloper + cf set-space-role CF_USER_GUID ORG SPACE SpaceManager + ``` +1. Ensure that your terraform user is _not_ listed in the terraform as a deployer, manager, or developer +1. `terraform apply` to add new permissions resources. +1. Use `cf unset-space-role` to remove the manual permissions settings or destroy the service account entirely to clean up after yourself. +1. (Optional, if you didn't destroy the service account) Re-add your terraform user to the terraform permissions configuration and have a different deployer apply it (like via CI/CD)