From e08075fbc95c629fe7659c88794a3fd3eff3e286 Mon Sep 17 00:00:00 2001 From: Kyle Finley Date: Fri, 3 Apr 2020 15:40:13 -0700 Subject: [PATCH 1/2] Initial reformatting --- .vscode/settings.json | 2 + docs/source/index.rst | 21 +++ docs/source/terraform/advanced_features.rst | 164 ++++++++++++++++++ docs/source/terraform/configuration.rst | 33 ++++ docs/source/terraform/directory_structure.rst | 5 + 5 files changed, 225 insertions(+) create mode 100644 docs/source/terraform/advanced_features.rst create mode 100644 docs/source/terraform/configuration.rst create mode 100644 docs/source/terraform/directory_structure.rst diff --git a/.vscode/settings.json b/.vscode/settings.json index 5351f2011..48719f320 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -34,6 +34,8 @@ "lambci", "mycdkmodule", "myothercdkmodule", + "mybucket", + "mytable", "nondockerizepip", "rxref", "stubbers" diff --git a/docs/source/index.rst b/docs/source/index.rst index 8576429a8..d6069c94f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -108,6 +108,27 @@ This means that Serverless must be included as a dev dependency in the **package serverless/advanced_features +.. _mod-tf: + +Terraform +========= + +TBD + +- `Configuration `__ +- `Directory Structure `__ +- `Advanced Features `__ + +.. toctree:: + :caption: Terraform + :maxdepth: 2 + :hidden: + + terraform/configuration + terraform/directory_structure + terraform/advanced_features + + ****************** Indices and tables ****************** diff --git a/docs/source/terraform/advanced_features.rst b/docs/source/terraform/advanced_features.rst new file mode 100644 index 000000000..4d762072f --- /dev/null +++ b/docs/source/terraform/advanced_features.rst @@ -0,0 +1,164 @@ +.. _Runway Config File: runway_config.html + +################# +Advanced Features +################# + +Advanced features and detailed information for using Terraform with Runway. + +.. _tf-backend: + +******* +Backend +******* + +If your Terraform will only ever be used with a single backend, it can be defined inline. + +.. rubric:: main.tf +.. code-block:: + + terraform { + backend "s3" { + region = "us-east-1" + key = "some_unique_identifier_for_my_module" # e.g. contosovpc + bucket = "some_s3_bucket_name" + dynamodb_table = "some_ddb_table_name" + } + } + +However, it's generally preferable to separate the backend configuration out from the rest of the Terraform code. +Choose from one of the following options. + + +Backend Config File +=================== + +Backend config options can be specified in a separate file or multiple files per environment and/or region using one of the following naming schemes. + +- ``backend-ENV-REGION.tfvars`` +- ``backend-ENV.tfvars`` +- ``backend-REGION.tfvars`` +- ``backend.tfvars`` + +.. rubric:: Example +.. code-block:: + + region = "us-east-1" + bucket = "some_s3_bucket_name" + dynamodb_table = "some_ddb_table_name" + +In the above example, where all but the key are defined, the **main.tf** backend definition is reduced to the following. + +.. rubric:: main.tf +.. code-block:: + + terraform { + backend "s3" { + key = "some_unique_identifier_for_my_module" # e.g. contosovpc + } + } + + +runway.yml +========== + +Backend config options can also be specified as a module option in the `Runway Config File`_. +:ref:`Lookups` can be used to provide dynamic values to this option. + +.. rubric:: Module Level +.. code-block:: yaml + + --- + deployments: + - modules: + - path: sampleapp.tf + options: + terraform_backend_config: + bucket: mybucket + dynamodb_table: mytable + region: us-east-1 + +.. rubric:: Deployment Level +.. code-block:: yaml + + --- + deployments: + - modules: + - path: sampleapp-01.tf + - path: sampleapp-02.tf + module_options: # shared between all modules in deployment + terraform_backend_config: + bucket: ${ssm ParamNameHere::region=us-east-1} + dynamodb_table: ${ssm ParamNameHere::region=us-east-1} + region: ${env AWS_REGION} + + +runway.yml From CloudFormation Outputs +====================================== + +A recommended option for managing the state bucket and table is to create +them via CloudFormation (try running ``runway gen-sample cfn`` to get a +template and stack definition for bucket/table stack). To further support this, +backend config options can be looked up directly from CloudFormation +outputs. + +.. rubric:: Module Level +.. code-block:: yaml + + --- + deployments: + - modules: + - path: sampleapp.tf + options: + terraform_backend_config: + region: us-east-1 + terraform_backend_cfn_outputs: + bucket: StackName::OutputName # e.g. common-tf-state::TerraformStateBucketName + dynamodb_table: StackName::OutputName # e.g. common-tf-state::TerraformStateTableName + + +.. rubric:: Deployment Level +.. code-block:: yaml + + --- + deployments: + - modules: + - path: sampleapp-01.tf + - path: sampleapp-02.tf + module_options: # shared between all modules in deployment + terraform_backend_config: + region: us-east-1 + terraform_backend_cfn_outputs: + bucket: StackName::OutputName # e.g. common-tf-state::TerraformStateBucketName + dynamodb_table: StackName::OutputName # e.g. common-tf-state::TerraformLockTableName + + +.. _tf-version: + +******** +Versions +******** + +By specifying the version via a ``.terraform-version`` file in your Terraform directory, or a module +option, Runway will automatically download & use that version for the module. This, alongside +tightly pinning Terraform provider versions, is highly recommended to keep a predictable experience +when deploying your module. + +.. rubric:: .terraform-version +.. code-block:: + + 0.11.6 + +.. rubric:: runway.yml +.. code-block:: yaml + + --- + deployments: + - modules: + - path: sampleapp.tf + options: + terraform_version: + "*": 0.11.13 # applies to all environments + # prod: 0.9.0 # can also be specified for a specific environment + +Without a version specified, Runway will fallback to whatever ``terraform`` it finds first in your PATH. diff --git a/docs/source/terraform/configuration.rst b/docs/source/terraform/configuration.rst new file mode 100644 index 000000000..094d0a50a --- /dev/null +++ b/docs/source/terraform/configuration.rst @@ -0,0 +1,33 @@ +############# +Configuration +############# + + +******* +Options +******* + +Options specific to Terraform Modules. + +**terraform_backend_config (Optional[Dict[str, str]])** + Mapping to configure Terraform backend. See :ref:`Backend ` for more details. + + .. rubric:: Example + .. code-block:: yaml + + options: + terraform_backend_config: + bucket: mybucket + dynamodb_table: mytable + region: us-east-1 + +**terraform_version (Optional[Dict[str, str]])** + Mapping of deploy environment to a Terraform version. See :ref:`Versions ` for more details. + + .. rubric:: Example + .. code-block:: yaml + + options: + terraform_version: + "*": 0.11.13 # applies to all environments + # prod: 0.9.0 # can also be specified for a specific environment diff --git a/docs/source/terraform/directory_structure.rst b/docs/source/terraform/directory_structure.rst new file mode 100644 index 000000000..5eadb7605 --- /dev/null +++ b/docs/source/terraform/directory_structure.rst @@ -0,0 +1,5 @@ +################### +Directory Structure +################### + +Example directory structures for a Terraform module. From 300074b853025266a1e218f4680162ccff4e6b13 Mon Sep 17 00:00:00 2001 From: Kyle Finley Date: Mon, 6 Apr 2020 10:28:06 -0700 Subject: [PATCH 2/2] finish reformatting --- docs/source/index.rst | 4 +- docs/source/module_configuration/index.rst | 1 - .../source/module_configuration/terraform.rst | 303 ------------------ docs/source/terraform/advanced_features.rst | 16 +- docs/source/terraform/configuration.rst | 61 ++++ docs/source/terraform/directory_structure.rst | 13 + 6 files changed, 86 insertions(+), 312 deletions(-) delete mode 100644 docs/source/module_configuration/terraform.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index d6069c94f..8a70745a9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -113,7 +113,9 @@ This means that Serverless must be included as a dev dependency in the **package Terraform ========= -TBD +Runway provides a simple way to run the Terraform versions you want with variable values specific to each environment. +Terraform does not need to be installed prior to using this module type. +Runway maintains a cache of Terraform versions on a system, downloading and installing different versions as needed. - `Configuration `__ - `Directory Structure `__ diff --git a/docs/source/module_configuration/index.rst b/docs/source/module_configuration/index.rst index 836c6d89e..ba7fb34d3 100644 --- a/docs/source/module_configuration/index.rst +++ b/docs/source/module_configuration/index.rst @@ -10,4 +10,3 @@ Module Configurations custom kubernetes staticsite - terraform diff --git a/docs/source/module_configuration/terraform.rst b/docs/source/module_configuration/terraform.rst deleted file mode 100644 index b31c896ec..000000000 --- a/docs/source/module_configuration/terraform.rst +++ /dev/null @@ -1,303 +0,0 @@ -.. _Lookups: lookups.html - -.. _mod-tf: - -Terraform -========= - -Runway provides a simple way to run the Terraform versions you want with -variable values specific to each environment. Perform the following steps to -align your Terraform directory with Runway's requirements & best practices. - - -Part 1: Adding Terraform to Deployment --------------------------------------- - -Start by adding your Terraform directory to your runway.yml's list of modules. - -(Note: to Runway, a module is just a directory in which to run -``terraform apply``, ``serverless deploy``, etc - no relation to Terraform's -concept of modules) - -Directory tree: -:: - - . - ├── runway.yml - └── terraformstuff.tf - └── main.tf - - -runway.yml: -:: - - --- - deployments: - - modules: - - terraformstuff.tf - regions: - - us-east-1 - - -Part 2: Specify the Terraform Version -------------------------------------- - -By specifying the version via a ``.terraform-version`` file in your Terraform directory, or a module -option, Runway will automatically download & use that version for the module. This, alongside -tightly pinning Terraform provider versions, is highly recommended to keep a predictable experience -when deploying your module. - -.terraform-version:: - - 0.11.6 - - -or in runway.yml, either for a single module:: - - --- - deployments: - - modules: - - path: mytfmodule - options: - terraform_version: - "*": 0.11.13 # applies to all environments - # prod: 0.9.0 # can also be specified for a specific environment - - -and/or for a group of modules: -:: - - --- - deployments: - - modules: - - path: mytfmodule - - path: anothermytfmodule - module_options: # shared between all modules in deployment - terraform_version: - "*": 0.11.13 # applies to all environments - # prod: 0.9.0 # can also be specified for a specific environment - - -Without a version specified, Runway will fallback to whatever ``terraform`` -it finds first in your PATH. - - -Part 3: Adding Backend Configuration ------------------------------------- - -Next, configure the backend for your Terraform configuration. If your Terraform -will only ever be used with a single backend, it can be defined inline: - -main.tf: -:: - - terraform { - backend "s3" { - region = "us-east-1" - key = "some_unique_identifier_for_my_module" # e.g. contosovpc - bucket = "some_s3_bucket_name" - dynamodb_table = "some_ddb_table_name" - } - } - -However, it's generally preferable to separate the backend configuration out -from the rest of the Terraform code. Choose from one of the following options. - - -Backend Config in File -~~~~~~~~~~~~~~~~~~~~~~ - -Backend config options can be specified in a separate file or multiple files -per environment and/or region: - -- ``backend-ENV-REGION.tfvars`` -- ``backend-ENV.tfvars`` -- ``backend-REGION.tfvars`` -- ``backend.tfvars`` - -:: - - region = "us-east-1" - bucket = "some_s3_bucket_name" - dynamodb_table = "some_ddb_table_name" - -In the above example, where all but the key are defined, the main.tf backend -definition is reduced to: - -main.tf:: - - terraform { - backend "s3" { - key = "some_unique_identifier_for_my_module" # e.g. contosovpc - } - } - - -Backend Config in runway.yml -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Backend config options can also be specified as a module option in runway.yml: - -Either for a single module:: - - --- - deployments: - - modules: - - path: mytfmodule - options: - terraform_backend_config: - bucket: mybucket - region: us-east-1 - dynamodb_table: mytable - -and/or for a group of modules: -:: - - --- - deployments: - - modules: - - path: mytfmodule - - path: anothermytfmodule - module_options: # shared between all modules in deployment - terraform_backend_config: - bucket: mybucket - region: us-east-1 - dynamodb_table: mytable - - -Backend CloudFormation Outputs in runway.yml -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A recommended option for managing the state bucket and table is to create -them via CloudFormation (try running ``runway gen-sample cfn`` to get a -template and stack definition for bucket/table stack). To further support this, -backend config options can be looked up directly from CloudFormation -outputs. - -Either for a single module:: - - --- - deployments: - - modules: - - path: mytfmodule - options: - terraform_backend_config: - region: us-east-1 - terraform_backend_cfn_outputs: - bucket: StackName::OutputName # e.g. common-tf-state::TerraformStateBucketName - dynamodb_table: StackName::OutputName # e.g. common-tf-state::TerraformStateTableName - - -and/or for a group of modules: -:: - - --- - deployments: - - modules: - - path: mytfmodule - - path: anothermytfmodule - module_options: # shared between all modules in deployment - terraform_backend_config: - region: us-east-1 - terraform_backend_cfn_outputs: - bucket: StackName::OutputName # e.g. common-tf-state::TerraformStateBucketName - dynamodb_table: StackName::OutputName # e.g. common-tf-state::TerraformLockTableName - - -Backend SSM Parameters in runway.yml -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Similar to the CloudFormation lookup, backend config options can be looked up -directly from SSM Parameters. - -Either for a single module:: - - --- - deployments: - - modules: - - path: mytfmodule - options: - terraform_backend_config: - region: us-east-1 - bucket: ${ssm ParamNameHere::region=us-east-1} - dynamodb_table: ${ssm ParamNameHere::region=us-east-1} - - -and/or for a group of modules: -:: - - --- - deployments: - - modules: - - path: mytfmodule - - path: anothermytfmodule - module_options: # shared between all modules in deployment - terraform_backend_config: - region: us-east-1 - bucket: ${ssm ParamNameHere::region=us-east-1} - dynamodb_table: ${ssm ParamNameHere::region=us-east-1} - - -Part 4: Variable Values ------------------------ - -Finally, define your per-environment variables using one or both of the following options. - - -Values in Variable Definitions Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Standard Terraform `tfvars -`_ -files can be used, exactly as one normally would with ``terraform apply -var-file``. -Runway will automatically detect them when named like ``ENV-REGION.tfvars`` or ``ENV.tfvars``. - -E.g. ``common-us-east-1.tfvars``:: - - region = "us-east-1" - image_id = "ami-abc123" - - -Values in runway.yml -~~~~~~~~~~~~~~~~~~~~ - -Variable values can also be specified as parameter values in runway.yml. It -is recommended to use `Lookups`_ in the ``parameters`` section to -assist in selecting the appropriate values for the deploy environment and/or -region being deployed to but, this is not a requirement if the value will -remain the same. - -:: - - --- - - deployments: - - modules: - - path: mytfmodule - parameters: - region: ${env AWS_REGION} - image_id: ${var image_id.${env AWS_REGION}} - mylist: - - item1 - - item2 - mymap: - key1: value1 - key2: value1 - -and/or -:: - - --- - - deployments: - - parameters: - region: ${env AWS_REGION} - image_id: ${var image_id.${env AWS_REGION}} - mylist: - - item1 - - item2 - mymap: - key1: value1 - key2: value1 - modules: - - mytfmodule diff --git a/docs/source/terraform/advanced_features.rst b/docs/source/terraform/advanced_features.rst index 4d762072f..4f544d95f 100644 --- a/docs/source/terraform/advanced_features.rst +++ b/docs/source/terraform/advanced_features.rst @@ -8,9 +8,9 @@ Advanced features and detailed information for using Terraform with Runway. .. _tf-backend: -******* -Backend -******* +********************* +Backend Configuration +********************* If your Terraform will only ever be used with a single backend, it can be defined inline. @@ -133,13 +133,15 @@ outputs. dynamodb_table: StackName::OutputName # e.g. common-tf-state::TerraformLockTableName +--- + .. _tf-version: -******** -Versions -******** +****************** +Version Management +****************** -By specifying the version via a ``.terraform-version`` file in your Terraform directory, or a module +By specifying which version of Terraform to use via a ``.terraform-version`` file in your module directory, or a module option, Runway will automatically download & use that version for the module. This, alongside tightly pinning Terraform provider versions, is highly recommended to keep a predictable experience when deploying your module. diff --git a/docs/source/terraform/configuration.rst b/docs/source/terraform/configuration.rst index 094d0a50a..2a6176fe2 100644 --- a/docs/source/terraform/configuration.rst +++ b/docs/source/terraform/configuration.rst @@ -31,3 +31,64 @@ Options specific to Terraform Modules. terraform_version: "*": 0.11.13 # applies to all environments # prod: 0.9.0 # can also be specified for a specific environment + + +********* +Variables +********* + +Variables can be defined per-environment using one or both of the following options. + +tfvars +====== + +Standard Terraform `tfvars +`__ +files can be used, exactly as one normally would with ``terraform apply -var-file``. +Runway will automatically detect them when named like ``ENV-REGION.tfvars`` or ``ENV.tfvars``. + +.. rubric:: Example + +Contests of a file named **common-us-east-1.tfvars** + +.. code-block:: + + region = "us-east-1" + image_id = "ami-abc123" + + +runway.yml +========== + +Variable values can also be specified as parameter values in runway.yml. It +is recommended to use `Lookups`_ in the ``parameters`` section to +assist in selecting the appropriate values for the deploy environment and/or +region being deployed to but, this is not a requirement if the value will +remain the same. + +.. code-block:: yaml + + --- + deployments: + - modules: + - path: sampleapp-01.tf + parameters: + region: ${env AWS_REGION} + image_id: ${var image_id.${env AWS_REGION}} + mylist: + - item1 + - item2 + mymap: + key1: value1 + key2: value1 + - modules: + - path: sampleapp-02.tf + parameters: + region: ${env AWS_REGION} + image_id: ${var image_id.${env AWS_REGION}} + mylist: + - item1 + - item2 + mymap: + key1: value1 + key2: value1 diff --git a/docs/source/terraform/directory_structure.rst b/docs/source/terraform/directory_structure.rst index 5eadb7605..a2d292132 100644 --- a/docs/source/terraform/directory_structure.rst +++ b/docs/source/terraform/directory_structure.rst @@ -3,3 +3,16 @@ Directory Structure ################### Example directory structures for a Terraform module. + + +******* +Example +******* + +.. code-block:: + + . + ├── .terraform-version + ├── backend-us-east-1.tfvars + ├── dev-us-east-1.tfvars + └── main.tf