|
| 1 | +# Upgrade from v4.x to v5.x |
| 2 | + |
| 3 | +Please consult the `examples` directory for reference example configurations. If you find a bug, please open an issue with supporting configuration to reproduce. |
| 4 | + |
| 5 | +## List of backwards incompatible changes |
| 6 | + |
| 7 | +- Minimum supported Terraform version increased to `v1.3` to support Terraform state `moved` blocks as well as other advanced features |
| 8 | +- The `apigatewayv2_` and `default_apigatewayv2_` prefixes has been removed from the output names |
| 9 | +- When a custom domain is used, the execution endpoint is disabled automatically; this is to ensure that requests are sent via the custom domain |
| 10 | +- For `authorizers`, the `audience` and `issuer` properties are now nested under `jwt_configuration` to better match the upstream API |
| 11 | + |
| 12 | +## Additional changes |
| 13 | + |
| 14 | +- Minimum supported Terraform AWS provider raised to `v5.37.0` to support recent bug fixes in the provider |
| 15 | +- Default values for `api_key_selection_expression`, `route_selection_expression` variables set to `null` (still matches prior value v4.x version but is set as `null` now) |
| 16 | +- The input data structure for `routes` (was `integrations`) has been updated and now uses optional inputs |
| 17 | + |
| 18 | +### Added |
| 19 | + |
| 20 | + - Support for creating a websocket API endpoint |
| 21 | + - Support for creating Route53 alias records for custom domain names w/ support for multiple sub-domains using a wildcard API Gateway custom domain name |
| 22 | + - Support for creating ACM certificate for custom domain |
| 23 | + - Support for automatically deploying the stage when updates have been made (for Websocket, HTTP is always auto-deployed by the API) |
| 24 | + |
| 25 | +### Modified |
| 26 | + |
| 27 | + - Stage access log group settings are now embedded into the `stage_access_log_settings` variable |
| 28 | + - API mapping is created automatically when using a custom domain |
| 29 | + - Default values of 500 and 1000 have been set for `throttling_burst_limit` and `throttling_rate_limit` respectively to ensure users do not face errors when deploying APIs for the first time and not configuring these |
| 30 | + - Default values for the log group name (`"/aws/apigateway/${var.name}/${var.stage_name}"`) and retention period (`30`) have been provided for the stage access logs log group |
| 31 | + |
| 32 | +### Removed |
| 33 | + |
| 34 | + - None |
| 35 | + |
| 36 | +### Variable and output changes |
| 37 | + |
| 38 | +1. Removed variables: |
| 39 | + |
| 40 | + - `create_api_gateway` |
| 41 | + - `create_default_stage_api_mapping` |
| 42 | + - `create_default_stage_access_log_group` -> replaced by `create_log_group` set within `stage_access_log_settings` |
| 43 | + - `default_stage_access_log_*` -> replaced by setting values within `stage_access_log_settings` |
| 44 | + - `create_vpc_link` |
| 45 | + - `default_stage_access_log_destination_arn` |
| 46 | + - `domain_name_tags` |
| 47 | + |
| 48 | +2. Renamed variables: |
| 49 | + |
| 50 | + - `integrations` -> `routes` |
| 51 | + - `create_default_stage` -> `create_stage` |
| 52 | + - `create_api_domain_name` -> `create_domain_name` |
| 53 | + - `default_route_settings` -> `stage_default_route_settings` |
| 54 | + - `default_stage_tags` -> `stage_tags` |
| 55 | + |
| 56 | +3. Added variables: |
| 57 | + |
| 58 | + - `create_domain_name` |
| 59 | + - `create_domain_records` |
| 60 | + - `subdomains` |
| 61 | + - `create_certificate` |
| 62 | + - `stage_access_log_settings` |
| 63 | + - `stage_client_certificate_id` |
| 64 | + - `stage_description` |
| 65 | + - `stage_name` |
| 66 | + - `stage_variables` |
| 67 | + - `deploy_stage` |
| 68 | + |
| 69 | +4. Removed outputs: |
| 70 | + |
| 71 | + - `default_apigatewayv2_stage_domain_name` |
| 72 | + - `aws_apigatewayv2_api_mapping` |
| 73 | + - `apigatewayv2_vpc_link_id` -> replaced by `vpc_links` |
| 74 | + - `apigatewayv2_vpc_link_arn` -> replaced by `vpc_links` |
| 75 | + - `apigatewayv2_authorizer_id` -> replaced by `authorizers` |
| 76 | + |
| 77 | +5. Renamed outputs: |
| 78 | + |
| 79 | + - `apigatewayv2_api_` -> prefix replaced with `api_` |
| 80 | + - `default_apigatewayv2_stage_` prefix replaced with `stage_` |
| 81 | + - `apigatewayv2_domain_` prefix replaced with `domain_` |
| 82 | + |
| 83 | +6. Added outputs: |
| 84 | + |
| 85 | + - `acm_certificate_arn` |
| 86 | + - `integrations` |
| 87 | + - `routes` |
| 88 | + - `stage_access_logs_cloudwatch_log_group_name` |
| 89 | + - `stage_access_logs_cloudwatch_log_group_arn` |
| 90 | + |
| 91 | +## Upgrade Migrations |
| 92 | + |
| 93 | +### Diff of Before (v4.0) vs After (v5.0) |
| 94 | + |
| 95 | +```diff |
| 96 | + module "apigateway_v2" { |
| 97 | + source = "terraform-aws-modules/apigateway-v2/aws" |
| 98 | +- version = "~> 4.0" |
| 99 | ++ version = "~> 5.0" |
| 100 | + |
| 101 | +- create_default_stage_access_log_group = true |
| 102 | +- default_stage_access_log_format = "$context.identity.sourceIp" |
| 103 | ++ stage_access_log_settings = { |
| 104 | ++ create_log_group = true |
| 105 | ++ format = "$context.identity.sourceIp" |
| 106 | ++ } |
| 107 | + |
| 108 | + authorizers = { |
| 109 | + "cognito" = { |
| 110 | + authorizer_type = "JWT" |
| 111 | + identity_sources = "$request.header.Authorization" |
| 112 | + name = "cognito" |
| 113 | + |
| 114 | +- audience = ["d6a38afd-45d6-4874-d1aa-3c5c558aqcc2"] |
| 115 | +- issuer = "https://${aws_cognito_user_pool.this.endpoint}" |
| 116 | + jwt_configuration = { |
| 117 | ++ audience = ["d6a38afd-45d6-4874-d1aa-3c5c558aqcc2"] |
| 118 | ++ issuer = "https://${aws_cognito_user_pool.this.endpoint}" |
| 119 | + } |
| 120 | + } |
| 121 | + } |
| 122 | + |
| 123 | +- integrations = { |
| 124 | ++ routes = { |
| 125 | + "POST /start-step-function" = { |
| 126 | +- integration_type = "AWS_PROXY" |
| 127 | +- integration_subtype = "StepFunctions-StartExecution" |
| 128 | +- credentials_arn = module.step_function.role_arn |
| 129 | + |
| 130 | +- request_parameters = jsonencode({ |
| 131 | +- StateMachineArn = module.step_function.state_machine_arn |
| 132 | +- }) |
| 133 | + |
| 134 | +- payload_format_version = "1.0" |
| 135 | +- timeout_milliseconds = 12000 |
| 136 | + |
| 137 | ++ integration = { |
| 138 | ++ type = "AWS_PROXY" |
| 139 | ++ subtype = "StepFunctions-StartExecution" |
| 140 | ++ credentials_arn = module.step_function.role_arn |
| 141 | + |
| 142 | ++ request_parameters = { |
| 143 | ++ StateMachineArn = module.step_function.state_machine_arn |
| 144 | ++ } |
| 145 | + |
| 146 | ++ payload_format_version = "1.0" |
| 147 | ++ timeout_milliseconds = 12000 |
| 148 | ++ } |
| 149 | + } |
| 150 | + |
| 151 | + "GET /some-route-with-authorizer-and-scope" = { |
| 152 | +- lambda_arn = module.lambda_function.lambda_function_arn |
| 153 | +- payload_format_version = "2.0" |
| 154 | +- authorization_type = "JWT" |
| 155 | +- authorizer_key = "cognito" |
| 156 | +- authorization_scopes = "tf/something.relevant.read,tf/something.relevant.write" |
| 157 | + |
| 158 | ++ authorization_type = "JWT" |
| 159 | ++ authorizer_key = "cognito" |
| 160 | ++ authorization_scopes = ["tf/something.relevant.read", "tf/something.relevant.write"] |
| 161 | + |
| 162 | ++ integration = { |
| 163 | ++ uri = module.lambda_function.lambda_function_arn |
| 164 | ++ payload_format_version = "2.0" |
| 165 | ++ } |
| 166 | + } |
| 167 | + |
| 168 | + "$default" = { |
| 169 | +- lambda_arn = module.lambda_function.lambda_function_arn |
| 170 | +- tls_config = jsonencode({ |
| 171 | +- server_name_to_verify = local.domain_name |
| 172 | +- }) |
| 173 | + |
| 174 | +- response_parameters = jsonencode([ |
| 175 | +- { |
| 176 | +- status_code = 500 |
| 177 | +- mappings = { |
| 178 | +- "append:header.header1" = "$context.requestId" |
| 179 | +- "overwrite:statuscode" = "403" |
| 180 | +- } |
| 181 | +- }, |
| 182 | +- { |
| 183 | +- status_code = 404 |
| 184 | +- mappings = { |
| 185 | +- "append:header.error" = "$stageVariables.environmentId" |
| 186 | +- } |
| 187 | +- } |
| 188 | +- ]) |
| 189 | + |
| 190 | ++ integration = { |
| 191 | ++ uri = module.lambda_function.lambda_function_arn |
| 192 | ++ tls_config = jsonencode({ |
| 193 | ++ server_name_to_verify = local.domain_name |
| 194 | ++ }) |
| 195 | + |
| 196 | ++ response_parameters = [ |
| 197 | ++ { |
| 198 | ++ status_code = 500 |
| 199 | ++ mappings = { |
| 200 | ++ "append:header.header1" = "$context.requestId" |
| 201 | ++ "overwrite:statuscode" = "403" |
| 202 | ++ } |
| 203 | ++ }, |
| 204 | ++ { |
| 205 | ++ status_code = 404 |
| 206 | ++ mappings = { |
| 207 | ++ "append:header.error" = "$stageVariables.environmentId" |
| 208 | ++ } |
| 209 | ++ } |
| 210 | ++ ] |
| 211 | ++ } |
| 212 | + } |
| 213 | + } |
| 214 | +} |
| 215 | +``` |
0 commit comments