~> I am aware of issues trying to deploy resources using Terraform v1.5.7. If possible please try use Terraform v1.6.1 or above, as it appear changes in Terraform resolve the issue. See #35 for more details
This module allows you to deploy multiple next.js websites using a multi zone architecture. This uses Open Next lambda, S3 and CloudFront.
This module supports three deployment options:
Independent Zones
Note: If you use tools like Terragrunt or CDKTF, you can use the Single Zone module to deploy each zone into its own terraform state
Shared Distribution
Shared Distribution and Bucket
The following are optional:
- Route 53 (A and AAAA records)
- WAF
- Staging Distribution
- Warmer function
- Image Optimization function
- Tag to Path Mapping DB
See the module documentation section below for more info.
Note: This module uses multiple bash scripts to delete data, upload data and mutate resources outside of Terraform. This prevents Terraform from removing resources when they have changed and allows the staging distribution functionality to work correctly.
You must have bash and the AWS CLI available, the CLI must be configured to use the same credentials or environment variables as the default AWS provider for this functionality to work correctly.
If you need to destroy the Terraform resources, it is recommended that you enable force_destroy
on the website bucket to delete the assets in the bucket when running a Terraform destory.
This module supports CloudFront continuous deployment. See the continuous deployment docs for instructions on how to leverage this capability.
See the backend server deployment docs for instructions to see the options.
For infomation on managing custom domains see the domain-config documentation
Below is the documentation for the Terraform module, outlining the providers, modules and resources required to deploy the website. The documentation includes the inputs that can be supplied (including any defaults) and what is outputted from the module.
By default, the module will zip all the necessary open-next artefacts as part of a Terraform deployment. To facilitate this, the .open-next folders need to be stored locally.
You can also choose to upload the artefacts to S3 and pass the reference in.
Note: the logic to automatically inject environment variables for lambda@edge functions will not run if you choose this option
Alternatively you can create the zip using your own tooling and supply the path to the zip file and the hash (SHA256 hash of the file encoded using Base64).
You must configure the AWS providers five times because some organizations use different accounts or roles for IAM, DNS, etc. The module has been designed to cater for these requirements. The server function is a separate provider to allow your backend resources to be deployed to a region, i.e. eu-west-1, and deploy the server function to another region, i.e. us-east-1, for lambda@edge. The global
provider region should be set to us-east-1 to allow the auth-function, WAF, etc. to be configured correctly.
Below is an example setup.
provider "aws" {}
provider "aws" {
alias = "server_function"
}
provider "aws" {
alias = "iam"
}
provider "aws" {
alias = "dns"
}
provider "aws" {
alias = "global"
region = "us-east-1"
}
Name | Version |
---|---|
terraform | >= 1.4.0 |
archive | >= 2.3.0 |
aws | >= 5.46.0 |
local | >= 2.4.0 |
Name | Version |
---|---|
aws | 5.46.0 |
Name | Source | Version |
---|---|---|
public_resources | ../tf-aws-open-next-public-resources | n/a |
website_zone | ../tf-aws-open-next-zone | n/a |
Name | Type |
---|---|
aws_lambda_permission.function_url_permission | resource |
aws_s3_bucket.shared_bucket | resource |
aws_s3_bucket_policy.shared_bucket_policy | resource |
aws_s3_bucket_policy.shared_distribution_bucket_policy | resource |
aws_region.current | data source |
Name | Description | Type | Default | Required |
---|---|---|---|---|
additional_server_functions | Default configutation for all additional server functions with the ability to override the configuration per function. This feature requires open next v3. By default, the module will create a new zip from the server function code on disk. However, you can override this by supplying a zip file containing the lambda code with either a local reference or a reference to the zip in an S3 bucket. Possible values for backend_deployment_type: - REGIONAL_LAMBDA_WITH_AUTH_LAMBDA - REGIONAL_LAMBDA_WITH_OAC - REGIONAL_LAMBDA_WITH_OAC_AND_ANY_PRINCIPAL - REGIONAL_LAMBDA See https://github.com/RJPearson94/terraform-aws-open-next/blob/v3.1.0/docs/backend-server-deployments.md for a complete breakdown of the different backend options. NOTE: This can be overridden for each zone |
object({ |
{} |
no |
aliases | The production and staging aliases to use. This can be overridden for each zone | object({ |
null |
no |
behaviours | Override the default behaviour config. When the deployment is set to 'INDEPENDENT_ZONES' this can be overridden for each zone. If deployment is 'SHARED_DISTRIBUTION' or 'SHARED_DISTRIBUTION_AND_BUCKET' this configuration is used | object({ |
{} |
no |
cache_control_immutable_assets_regex | Regex to set public,max-age=31536000,immutable on immutable resources. This can be overridden for each zone | string |
"^.*(\\.next)$" |
no |
cloudwatch_log | The default cloudwatch log group configuration. This can be overridden for each zone and each function"" Possible values for deployment: - PER_FUNCTION (default) - SHARED_PER_ZONE - USE_EXISTING When deployment is set to SHARED_PER_ZONE or USE_EXISTING , name is mandatory.For SHARED_PER_ZONE , the name will include the aws/lambda namespace and the supplied prefix and suffixFor USE_EXISTING , the name will represent the log group name (including prefix) |
object({ |
{} |
no |
content_types | The MIME type mapping and default for artefacts generated by Open Next. This can be overridden for each zone | object({ |
{} |
no |
continuous_deployment | Configuration for continuous deployment config for CloudFront When the deployment is set to 'INDEPENDENT_ZONES' this can be overridden for each zone. If continuous deployment is enabled, updates to the origins, ordered_cache_behaviors and default_cache_behaviors are ignored See https://github.com/RJPearson94/terraform-aws-open-next/blob/v3.1.0/docs/continuous-deployments.md for a complete breakdown of how to use continuous deployment. |
object({ |
{} |
no |
custom_error_responses | Allow custom error responses to be set on the distributions When the deployment is set to 'INDEPENDENT_ZONES' this can be overridden for each zone. If deployment is 'SHARED_DISTRIBUTION' or 'SHARED_DISTRIBUTION_AND_BUCKET' this configuration is used. If the deployment is 'SHARED_DISTRIBUTION', the files are saved into the root zone bucket. If the deployment is 'SHARED_DISTRIBUTION_AND_BUCKET' the files are saved in the shared bucket NOTE: These custom error pages only apply to response codes from the origins. To configure custom error responses for status codes returned by WAF, please configure the custom error responses in WAF. |
list(object({ |
[] |
no |
deployment | The deployment model for the multi zone website The possible values are: - INDEPENDENT_ZONES - SHARED_DISTRIBUTION - SHARED_DISTRIBUTION_AND_BUCKET See https://github.com/RJPearson94/terraform-aws-open-next/tree/v3.1.0?tab=readme-ov-file#deployment-options for a complete breakdown of the different deployment options. |
string |
n/a | yes |
distribution | Configuration for the CloudFront distribution. When the deployment is set to 'INDEPENDENT_ZONES' this can be overridden for each zone. If deployment is 'SHARED_DISTRIBUTION' or 'SHARED_DISTRIBUTION_AND_BUCKET' this configuration is used Possible values for deployment are: - NONE - CREATE The module has a local copy of the x-forwarded host CloudFront function code by default. The code can be seen at https://github.com/RJPearson94/terraform-aws-open-next/blob/v3.1.0/modules/tf-aws-open-next-public-resources/code/xForwardedHost.js (open next v2) and https://github.com/RJPearson94/terraform-aws-open-next/blob/v3.1.0/modules/tf-aws-open-next-public-resources/code/cloudfrontFunctionOpenNextV3.js (open next v3). This code can be overridden by passing in the javascript function as a string to the code argument under the x_forwarded_host_function object. An example can be seen below.x_forwarded_host_function = {The auth function is deployed if the server function backend_deployment_type is set to EDGE_LAMBDA. The module has a local copy of the auth function code, which will be deployed by default. The code can be seen at https://github.com/RJPearson94/terraform-aws-open-next/blob/v3.1.0/modules/tf-aws-open-next-public-resources/code/auth/index.js. You can override this to supplying a zip file containing the lambda code with either a local reference or a reference to the zip in an S3 bucket. Possible values for the auth_function deployment are: - NONE - USE_EXISTING - CREATE - DETACH The auth function arn is mandatory when deployment is set to USE_EXISTING .When migrating from using the auth function to either public cloud functions or to using OAC, you should set the deployment on the auth_function to CREATE, then apply the changes. Then, you can set deployment to false in a subsequent change to clean up the function. If you run the server function as a lambda@edge, you should increase the deletion timeout to 2 hours 120m . As the lambda service needs to wait for the replicas to be removed, this often exceeds the default 10-minute deletion timeout. This extended timeout allows Terraform to poll for longer and should help mitigate Terraform failures; an example Terraform configuration can be seen below.auth_function = {As lambda@edge doesn't support environment variables, the environment variables are injected into the source code before the zip is generated. NOTE: If the lambda function code is supplied as a zip or via an S3 reference, this code modification will not occur Terraform does not manage cloudwatch log groups for the auth function; the lambda service creates the log group when the function runs in each region. CloudFront supports Origin Access Control (OAC) for lambda URLs. The possible values for the deployment options are: - NONE - CREATE NOTE: If the server function or image optimisation function backend deployment types use OAC, then the OAC will be created. As there is a limit on the number of cache policies associated with an AWS account, you can either configure the module to create the cache policy or use an existing one. The possible values for the cache policy deployment are: - USE_EXISTING - CREATE If cache policy deployment is set to USE_EXISTING , then ID, is a required field.WARNING: The distribution is fundamental to the architecture, and the module is optional to facilitate sharing a distribution for multi-zone deployments and to support edge cases not supported by the module. With that said, it is not recommended to supply a distribution. |
object({ |
{} |
no |
domain_config | Configuration for CloudFront distribution domain When the deployment is set to 'INDEPENDENT_ZONES' this can be overridden for each zone. If deployment is 'SHARED_DISTRIBUTION' or 'SHARED_DISTRIBUTION_AND_BUCKET' this configuration is used See https://github.com/RJPearson94/terraform-aws-open-next/blob/v3.1.0/docs/domain-config.md for a complete breakdown of the different domain configuration options. |
object({ |
null |
no |
edge_functions | Default configutation for all edge functions with the ability to override the configuration per edge function By default, the module will create a new zip from the edge function code on disk. However, you can override this by supplying a zip file containing the lambda code with either a local reference or a reference to the zip in an S3 bucket. This feature requires open next v3. NOTE: Terraform does not manage cloudwatch log groups; instead, the lambda service creates the log group when the function runs in each region. The module OPEN_NEXT_ORIGIN environment variable for each edge function, as per the open next documentation for middleware. You have the ability to remove this environment variable by setting the include_open_next_origin_env_variable to false or override this value by setting an environment variable with the same name via the additional_environment_variables attribute.You should increase the deletion timeout to 2 hours 120m . As the lambda service needs to wait for the replicas to be removed, this often exceeds the default 10-minute deletion timeout. This extended timeout allows Terraform to poll for longer and should help mitigate Terraform failures; an example Terraform configuration can be seen below.timeouts = {As lambda@edge doesn't support environment variables, the environment variables are injected into the source code before the zip is generated. NOTE: If the lambda function code is supplied as a zip or via an S3 reference, this code modification will not occur NOTE: This can be overridden for each zone |
object({ |
{} |
no |
function_architecture | The default instruction set architecture for the lambda functions. This can be overridden for each zone and each function | string |
"arm64" |
no |
iam | The default IAM configuration. This can be overridden for each zone and each function |