From 37f37b7ffeb5a2b3465c69c68461f8269b16891d Mon Sep 17 00:00:00 2001 From: Jake Skipper Date: Wed, 8 Nov 2023 16:23:52 +0000 Subject: [PATCH 1/2] Addition of upgrade info --- .vscode/cspell.json | 6 +- docs/Makefile | 13 ++- docs/source/index.rst | 1 + docs/source/upgrades.rst | 166 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 181 insertions(+), 5 deletions(-) create mode 100644 docs/source/upgrades.rst diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 6ae5d0ce6..d06031501 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -213,6 +213,10 @@ "autodetected", "addoption", "domparator", - "Fakhreddine" + "Fakhreddine", + "SPHINXAUTOBUILD", + "autobuild", + "SPHINXAUTOBUILDPORT", + "ssmstore" ] } diff --git a/docs/Makefile b/docs/Makefile index fce09adc0..da43b8a7f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,7 +1,9 @@ -SPHINXOPTS = -SPHINXBUILD = poetry run sphinx-build -SOURCEDIR = source -BUILDDIR = build +SPHINXOPTS = +SPHINXBUILD = poetry run sphinx-build +SPHINXAUTOBUILD ?= poetry run sphinx-autobuild +SPHINXAUTOBUILDPORT = 9997 +SOURCEDIR = source +BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: @@ -17,6 +19,9 @@ clean: docs: clean html +preview: + @$(SPHINXAUTOBUILD) --port $(SPHINXAUTOBUILDPORT) "$(SOURCEDIR)" "$(BUILDDIR)" $(O) + open: @open build/html/index.html diff --git a/docs/source/index.rst b/docs/source/index.rst index 5b9caee85..aea642802 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,7 @@ Runway is a lightweight wrapper around infrastructure deployment (e.g. CloudForm :hidden: installation + upgrades getting_started quickstart/index commands diff --git a/docs/source/upgrades.rst b/docs/source/upgrades.rst new file mode 100644 index 000000000..91e46ab56 --- /dev/null +++ b/docs/source/upgrades.rst @@ -0,0 +1,166 @@ +.. _upgrades: + +######## +Upgrades +######## + +.. contents:: + :depth: 4 + +During a Runway upgrade (especially coming from a :code:`0.x` version) you may required to make changes to your configuration or modules. This page will describe common issues when upgrading and how to resolve them. + +******************************* +Updating the Runway Config File +******************************* + +You may need to update your Runway config file structure depending on how old of a Runway version you are upgrading from. Some config keys have changed in spelling, may make use of :code:`_` instead of :code:`-`, or have different functionality altogether. For example, compare this old config file: + +.. code-block:: yaml + + deployments: + - modules: + - module-1.cfn + - module-2.cfn + - module-3.cfn + regions: + - us-east-1 + account-id: + prod: 123412341234 + assume-role: + post_deploy_env_revert: true + prod: arn:aws:iam::123412341234:role/my-deployment-role + environments: + prod-ops: + namespace: my-account + environment: prod + +To this newer version: + +.. code-block:: yaml + + variables: + account_id: + prod: 123412341234 + assume_role: + prod: arn:aws:iam::123412341234:role/my-deployment-role + parameters: + prod: + namespace: my-account + environment: prod + + deployments: + - modules: + - module-1.cfn + - module-2.cfn + - module-3.cfn + regions: + - us-east-1 + account_id: ${var account_id.${env DEPLOY_ENVIRONMENT}} + assume_role: + arn: ${var assume_role.${env DEPLOY_ENVIRONMENT}} + post_deploy_env_revert: true + environments: + prod: true + parameters: ${var parameters.${env DEPLOY_ENVIRONMENT}} + +In the above example, we've taken advantage of Runway's :code:`variables` key and we dynamically reference it based on our :code:`DEPLOY_ENVIRONMENT`. We also updated :code:`account-id` and :code:`assume-role` to :code:`account_id` and :code:`assume_role`. + +Runway is very flexible about how you can structure your config, the above is only an example of one way to adjust it. Just keep in mind while upgrading that if you receive errors as soon as you start a :code:`runway` command, it is likely due to a config file error or no longer supported directive. + +******************************** +Migration from Stacker to CFNgin +******************************** + +Older versions of Runway used Stacker, which was then forked and included into the Runway project as CFNgin. This causes a few concerns while migrating older deployments. + +------------------------------ +Update References to Stacker +------------------------------ + +See :doc:`cfngin/migrating` for info on converting your older Stacker modules into CFNgin compatible versions. + +------------------------------- +Migration of Stacker Blueprints +------------------------------- + +In some environments, you may see usage of Stacker "Blueprints". These are Python scripts leveraging Troposphere to generate CloudFormation templates programmatically. While these can be incredibly powerful, they also come with a Python experience dependency and are prone to breaking due to AWS or Runway changes. In older deployments if the blueprint contains references to :code:`stacker` it will also need to be updated to use the new :code:`cfngin` library after a Runway upgrade, as described in :doc:`cfngin/migrating`. + +In most cases it is easiest to: + +1. Navigate to the AWS CloudFormation Console, +2. find the stack that was deployed using the blueprint, +3. copy its CloudFormation template data (optionally converting it to YAML on the way); and, +4. convert the deployment in Runway to use that static template so you can eliminate the blueprint. + +This process leaves you with a much more simple to manage static template. + +------------------------------------ +A Note on Tagging in Stacker Modules +------------------------------------ + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +stacker_namespace / cfngin_namespace tag +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If a Stacker/CFNgin deployment doesn't have a :code:`tags` key defined, a default value is used: + +Stacker:: + + stacker_namespace: ${namespace} + +CFNgin:: + + cfngin_namespace: ${namespace} + +Because of this if you are upgrading a Stacker module without the :code:`tags` key defined, you'll see Runway attempting to adjust the tags on every resource in the module. This is because it is updating the default :code:`stacker_namespace` tag to a :code:`cfngin_namespace` tag. If you'd like to prevent this behavior, you can add a :code:`tags` key as follows:: + + tags: + stacker_namespace: ${namespace} + +The above usage will cause CFNgin to keep the old :code:`stacker_namespace` tag with its original value, eliminating the need for changes to tags on resources. + +^^^^^^^^^^^^^^^^^^^^ +Int to String Errors +^^^^^^^^^^^^^^^^^^^^ + +When defining a :code:`tags` key directly onto a CFNgin stack definition (not the top level :code:`tags` key in the CFNgin config file), you may see an error regarding using an :code:`int` instead of a :code:`string`. For instance: + +.. code-block:: yaml + + # This may return a "must be of type string" error + my-stack-definition: + template_path: ./my-templates/my-cloudformation-template.yaml + tags: + CostCenter: 1234 + +This can be resolved by enclosing your numerical value in quotes: + +.. code-block:: yaml + + # This may return a "must be of type string" error + my-stack-definition: + template_path: ./my-templates/my-cloudformation-template.yaml + tags: + CostCenter: "1234" + +****************** +Updates to Lookups +****************** + +Some lookup usage may have changed slightly. Here's some examples: + +.. code-block:: yaml + + # This generates a deprecation warning in newer Runway versions + VpcId: ${rxref vpc::VpcId} + + # This is the new usage + VpcId: ${rxref vpc.VpcId} + +.. code-block:: yaml + + # This generates an unknown lookup error + SlackUrl: ${ssmstore us-east-1@/devops/slack_hook} + + # This is the new usage + SlackUrl: ${ssm /devops/slack_hook} From 3a83d9ee4f368871e3cca1244872d47a904dd380 Mon Sep 17 00:00:00 2001 From: Jake Skipper Date: Wed, 8 Nov 2023 16:30:54 +0000 Subject: [PATCH 2/2] Typo --- docs/source/upgrades.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/upgrades.rst b/docs/source/upgrades.rst index 91e46ab56..2ad3aeb30 100644 --- a/docs/source/upgrades.rst +++ b/docs/source/upgrades.rst @@ -30,7 +30,7 @@ You may need to update your Runway config file structure depending on how old of post_deploy_env_revert: true prod: arn:aws:iam::123412341234:role/my-deployment-role environments: - prod-ops: + prod: namespace: my-account environment: prod