From f0acc4a13a5547abc77ff18966c951ba658657f2 Mon Sep 17 00:00:00 2001 From: Kyle Finley Date: Fri, 3 Apr 2020 20:13:29 -0700 Subject: [PATCH] update formatting of cdk docs (#218) * update formatting of cdk docs * add missing period --- .vscode/settings.json | 2 + docs/source/cdk/advanced_features.rst | 46 ++++++++ docs/source/cdk/configuration.rst | 51 ++++++++ docs/source/cdk/directory_structure.rst | 61 ++++++++++ docs/source/index.rst | 24 ++++ docs/source/module_configuration/cdk.rst | 128 --------------------- docs/source/module_configuration/index.rst | 1 - 7 files changed, 184 insertions(+), 129 deletions(-) create mode 100644 docs/source/cdk/advanced_features.rst create mode 100644 docs/source/cdk/configuration.rst create mode 100644 docs/source/cdk/directory_structure.rst delete mode 100644 docs/source/module_configuration/cdk.rst diff --git a/.vscode/settings.json b/.vscode/settings.json index c30c79f51..9e8f8c7b8 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -31,6 +31,8 @@ "forcerm", "kwarg", "lambci", + "mycdkmodule", + "myothercdkmodule", "nondockerizepip", "rxref", "stubbers" diff --git a/docs/source/cdk/advanced_features.rst b/docs/source/cdk/advanced_features.rst new file mode 100644 index 000000000..af79edcd5 --- /dev/null +++ b/docs/source/cdk/advanced_features.rst @@ -0,0 +1,46 @@ +################# +Advanced Features +################# + +Advanced features and detailed information for using CDK with Runway. + + +*********** +Build Steps +*********** + +Build steps (e.g. for compiling TypeScript) can be specified in the module options. +These steps will be run before each diff, deploy, or destroy. + +.. rubric:: Example +.. code-block:: yaml + + --- + deployments: + - modules: + - path: mycdkmodule.cdk + environments: + dev: true + options: + build_steps: + - npx tsc + + +**************** +Disabling NPM CI +**************** + +At the start of each module execution, Runway will execute ``npm ci`` to ensure +the CDK is installed in the project (so Runway can execute it via +``npx cdk``. This can be disabled (e.g. for use when the ``node_modules`` +directory is pre-compiled) via the ``skip_npm_ci`` module option: + +.. rubric:: Example +.. code-block:: yaml + + --- + deployments: + - modules: + - path: mycdkmodule.cdk + options: + skip_npm_ci: true diff --git a/docs/source/cdk/configuration.rst b/docs/source/cdk/configuration.rst new file mode 100644 index 000000000..d05efeec3 --- /dev/null +++ b/docs/source/cdk/configuration.rst @@ -0,0 +1,51 @@ +############# +Configuration +############# + +Standard `CDK `__ rules apply but, we have some added prerequisites, recommendations, and caveats. + + +************* +Prerequisites +************* + +- `npm installed on the system `__ +- CDK must be a dev dependency of the module (e.g. ``npm install --save-dev aws-cdk``) + +We strongly recommend you commit the package-lock.json that is generated after running ``npm install``. + + +************ +Environments +************ + +Unlike some other module types, CDK does not have file that can be used to configure an environment. +It can only be configured using the ``environments`` option of a deployment and/or module (see :ref:`Runway Config File ` for details). + + +Runway Config +============= + +.. rubric:: Top-level +.. code-block:: yaml + + --- + deployments: + - modules: + - path: mycdkmodule.cdl + environments: + dev: true + prod: true + - modules: + - path: myothercdkmodule.cdk + environments: + dev: true + prod: true + +.. rubric:: In Module Directory +.. code-block:: yaml + + --- + environments: + dev: true + prod: true diff --git a/docs/source/cdk/directory_structure.rst b/docs/source/cdk/directory_structure.rst new file mode 100644 index 000000000..c193f5f91 --- /dev/null +++ b/docs/source/cdk/directory_structure.rst @@ -0,0 +1,61 @@ +################### +Directory Structure +################### + +Example directory structures for a CDK module. + + +********** +C# Example +********** + +.. code-block:: + + . + ├── add-project.hook.d.ts + ├── cdk.json + ├── package.json + ├── package-lock.json + └── src + ├── HelloCdk + │ ├── HelloCdk.csproj + │ ├── HelloConstruct.cs + │ ├── HelloStack.cs + │ └── Program.cs + └── HelloCdk.sln + + +************** +Python Example +************** + +.. code-block:: + + . + ├── Pipfile + ├── Pipfile.lock + ├── app.py + ├── cdk.json + ├── hello + │ ├── __init__.py + │ ├── hello_construct.py + │ └── hello_stack.py + ├── package.json + └── package-lock.json + + +****************** +TypeScript Example +****************** + +.. code-block:: + + . + ├── bin + │ └── sample.ts + ├── cdk.json + ├── lib + │ └── sample-stack.ts + ├── package.json + ├── package.json + └── tsconfig.json diff --git a/docs/source/index.rst b/docs/source/index.rst index eb1a52a67..eb746b2a2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -37,6 +37,30 @@ Very simple configuration to: Module Configuration ******************** + +.. _mod-cdk: + +AWS Cloud Development Kit (CDK) +=============================== + +The CDK module type is deployed using the `AWS Cloud Development Kit (CDK) `__. +Runway uses `system installed npm `__ to install the CDK per-module. +This means that the CDK must be included as a dev dependency in the **package.json** of the module. + +- `Configuration `__ +- `Directory Structure `__ +- `Advanced Features `__ + +.. toctree:: + :caption: AWS Cloud Development Kit (CDK) + :maxdepth: 2 + :hidden: + + cdk/configuration + cdk/directory_structure + cdk/advanced_features + + CloudFormation & Troposphere ============================ diff --git a/docs/source/module_configuration/cdk.rst b/docs/source/module_configuration/cdk.rst deleted file mode 100644 index 4b2165c61..000000000 --- a/docs/source/module_configuration/cdk.rst +++ /dev/null @@ -1,128 +0,0 @@ -.. _Lookups: ../lookups.html - -.. _mod-cdk: - -CDK -=== - -Standard `AWS CDK -`_ rules apply, with the following recommendations/caveats: - -A ``package.json`` file is required, specifying the aws-cdk dependency. E.g.:: - - { - "name": "mymodulename", - "version": "1.0.0", - "description": "My CDK module", - "main": "index.js", - "dependencies": { - "@aws-cdk/cdk": "^0.9.2", - "@types/node": "^10.10.1" - }, - "devDependencies": { - "aws-cdk": "^0.9.2", - "typescript": "^3.0.3" - } - "author": "My Org", - "license": "Apache-2.0" - } - -We strongly recommend you commit the package-lock.json that is generated after running ``npm install`` - - -Build Steps ------------ - -Build steps (e.g. for compiling TypeScript) can be specified in the module options. These steps will be run before each diff, deploy, or destroy. -:: - - deployments: - - modules: - - path: mycdkmodule - environments: - dev: true - options: - build_steps: - - npx tsc - - -Environment Configs -------------------- - -Environments can be specified via deployment and/or module options. Each example below shows the explicit CDK ``ACCOUNT/REGION`` environment mapping; -these can be alternately be specified with a simple boolean (e.g. ``dev: true``). - - -Top-level Runway Config -~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --- - - deployments: - - modules: - - path: mycdkmodule - environments: - # CDK environment values can be specified in 3 forms: - # Opt 1 - A yaml mapping, in which case each key:val pair will be provided as context options - # dev: - # route_53_zone_id: Z3P5QSUBK4POTI - # Opt 2 - A string, in which case the explicit CDK ``ACCOUNT/REGION`` environment will be verified - # dev: 987654321098/us-west-2 - # Opt 3 - Booleans, in which case the module will always be deployed in the given environment - # dev: true - -and/or: -:: - - --- - - deployments: - - environments: - # CDK environment values can be specified in 3 forms: - # Opt 1 - A yaml mapping, in which case each key:val pair will be provided as context options - # dev: - # route_53_zone_id: Z3P5QSUBK4POTI - # Opt 2 - A string, in which case the explicit CDK ``ACCOUNT/REGION`` environment will be verified - # dev: 987654321098/us-west-2 - # Opt 3 - Booleans, in which case the module will always be deployed in the given environment - # dev: true - modules: - - mycdkmodule - - -In Module Directory -~~~~~~~~~~~~~~~~~~~ - -.. important:: `Lookups`_ are not supported in this file. - -:: - - --- - environments: - # CDK environment values can be specified in 3 forms: - # Opt 1 - A yaml mapping, in which case each key:val pair will be provided as context options - # dev: - # route_53_zone_id: Z3P5QSUBK4POTI - # Opt 2 - A string, in which case the explicit CDK ``ACCOUNT/REGION`` environment will be verified - # dev: 987654321098/us-west-2 - # Opt 3 - Booleans, in which case the module will always be deployed in the given environment - # dev: true - -(in ``runway.module.yml``) - -Disabling NPM CI ----------------- -At the start of each module execution, Runway will execute ``npm ci`` to ensure -the CDK is installed in the project (so Runway can execute it via -``npx cdk``. This can be disabled (e.g. for use when the ``node_modules`` -directory is pre-compiled) via the ``skip_npm_ci`` module option: -:: - - --- - deployments: - - modules: - - path: mycdkproject.cdk - options: - skip_npm_ci: true diff --git a/docs/source/module_configuration/index.rst b/docs/source/module_configuration/index.rst index 040d6ed1f..d60ae8383 100644 --- a/docs/source/module_configuration/index.rst +++ b/docs/source/module_configuration/index.rst @@ -7,7 +7,6 @@ Module Configurations :maxdepth: 1 :name: mod-configs - cdk custom kubernetes serverless