Merge pull request #752 from awslabs/release/5.0.1

Release/5.0.1

.github/workflows/check-documentation-build.yml

@@ -0,0 +1,56 @@
+name: Documentation Check
+
+on:
+  push:
+    branches: 
+      - "main"
+    paths:
+      - "docs/**"
+      - ".readthedocs.yaml"
+      - "setup.py"
+      - "VERSION"
+      - ".github/workflows/check-documentation-build.yml"
+
+  pull_request:
+    branches:
+      - "main"
+      - "stable"
+    paths:
+      - "docs/**"
+      - ".readthedocs.yaml"
+      - "setup.py"
+      - "VERSION"
+      - ".github/workflows/check-documentation-build.yml"
+
+  # Allows this workflow to be run manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install yq
+        run: sudo snap install yq
+      - name: Get Python Version
+        id: get-version
+        run: |
+            python_version=$(cat .readthedocs.yaml | yq ".build.tools.python")
+            echo python-version=$python_version >> $GITHUB_OUTPUT
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '${{ steps.get-version.outputs.python-version }}'
+      - name: Update pip
+        run: pip install --upgrade pip
+      - name: Install Requirements for building docs
+        run: pip install -r docs/requirements-docs.txt
+      - name: Install SeedFarmer
+        run: pip install -e .
+      - name: Sphinx Build
+        working-directory: ./docs/
+        run: make html

CHANGELOG.md

@@ -11,6 +11,21 @@ This project adheres to [Semantic Versioning](http://semver.org/) and [Keep a Ch
 
 ### Fixes
 
+## v5.0.1 (2024-12-02)
+
+### New 
+
+### Changes
+
+- Adds `seedfarmer --version` to validate package without running explicit command
+- Added ability to disable env replacement in module parameters
+- Updating bootstrap docs with minimum permissions
+- Update manifest example module versions
+- Update session manager to pass toolchain role region to sts
+
+### Fixes
+- allow nested modules in archives pulled over HTTPS (ref issue/749)
+
 ## v5.0.0 (2024-08-16)
 
 ### New

README.md

@@ -1,5 +1,9 @@
 # Seed-Farmer
 
+[![PyPi](https://img.shields.io/pypi/v/seed-farmer)](https://pypi.org/project/seed-farmer/)
+[![Python Version](https://img.shields.io/pypi/pyversions/seed-farmer.svg)](https://pypi.org/project/seed-farmer/)
+[![License](https://img.shields.io/pypi/l/seed-farmer)](https://github.com/awslabs/seed-farmer/blob/main/LICENSE)
+
 Seed-Farmer (seedfarmer) is an opensource orchestration tool that works with AWS CodeSeeder (see [github](https://github.com/awslabs/aws-codeseeder) or [docs](https://aws-codeseeder.readthedocs.io/en/latest/)) and acts as an orchestration tool modeled after [GitOps deployments](https://www.gitops.tech/).  It has a CommandLine Interface (CLI) based in Python. 
 
 Please see our [SeedFarmer Documentation](https://seed-farmer.readthedocs.io/en/latest/).

VERSION

@@ -1 +1 @@
-5.0.0
+5.0.1

docs/requirements-docs.in

@@ -1,5 +1,5 @@
-sphinx-autoapi==3.2.1
-sphinx-rtd-theme==2.0.0
+sphinx-autoapi==3.4.0
+sphinx-rtd-theme==3.0.2
 sphinxcontrib-applehelp==2.0.0
 sphinxcontrib-devhelp==2.0.0
 sphinxcontrib-htmlhelp==2.1.0
@@ -14,4 +14,4 @@ PyYAML==6.0.2
 urllib3~=1.26.19
 wheel==0.44.0
 typing-extensions==4.12.2
-certifi~=2024.7.4
+certifi~=2024.8.30

docs/requirements-docs.txt

@@ -10,7 +10,7 @@ astroid==2.15.5
     # via sphinx-autoapi
 babel==2.12.1
     # via sphinx
-certifi==2024.7.4
+certifi==2024.8.30
     # via
     #   -r docs/requirements-docs.in
     #   requests
@@ -70,11 +70,11 @@ sphinx==7.1.2
     #   sphinx-click
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
-sphinx-autoapi==3.2.1
+sphinx-autoapi==3.4.0
     # via -r docs/requirements-docs.in
 sphinx-click==6.0.0
     # via -r docs/requirements-docs.in
-sphinx-rtd-theme==2.0.0
+sphinx-rtd-theme==3.0.2
     # via -r docs/requirements-docs.in
 sphinxcontrib-applehelp==2.0.0
     # via
@@ -104,6 +104,8 @@ sphinxcontrib-serializinghtml==2.0.0
     # via
     #   -r docs/requirements-docs.in
     #   sphinx
+stdlib-list==0.10.0
+    # via sphinx-autoapi
 typing-extensions==4.12.2
     # via
     #   -r docs/requirements-docs.in

docs/source/bootstrapping.md

@@ -86,3 +86,42 @@ The qualifier post-pends a 6 chars alpha-numeric string to the deployment role a
 
 ## Prepping the Account / Region
 `seedfarmer` leverages the AWS CDKv2.  This must be bootstrapped in each account/region combination to be used of each target account.
+
+## Minimum Permissions Required for Bootstrap
+The following policy outlines the minimum required IAM permissions in order to execute `seedfarmer bootstrap ..` against a toolchain/target account. **Note**: The project name `exampleproj` is used in this policy as an example. This would need to be changed to the project name in `seedfarmer.yaml`.
+
+```
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "VisualEditor0",
+            "Effect": "Allow",
+            "Action": [
+                "cloudformation:CreateChangeSet",
+                "cloudformation:DescribeChangeSet",
+                "cloudformation:ExecuteChangeSet",
+                "cloudformation:DescribeStacks"
+            ],
+            "Resource": [
+                "arn:aws:iam:::role/seedfarmer-*-toolchain-role",
+                "arn:aws:cloudformation:*:*:stack/seedfarmer-exampleproj-toolchain-role/*",
+                "arn:aws:cloudformation:*:*:stack/seedfarmer-exampleproj-deployment-role/*"
+            ]
+        },
+        {
+            "Sid": "VisualEditor1",
+            "Effect": "Allow",
+            "Action": [
+                "iam:GetRole",
+                "iam:DeleteRolePolicy",
+                "iam:TagRole",
+                "iam:CreateRole",
+                "iam:DeleteRole",
+                "iam:PutRolePolicy"
+            ],
+            "Resource": "*"
+        }
+    ]
+}
+```

docs/source/manifests.md

@@ -91,7 +91,7 @@ targetAccountMappings:
   - THIS CANNOT BE USED WITH `name`
 - **toolchainRegion** :the designated region that the `toolchain` is created in
 - **forceDependencyRedeploy**: this is a boolean that tells seedfarmer to redeploy ALL dependency modules (see [Force Dependency Redeploy](force-redeploy)) - Default is `False`
-- **archiveSecret**: name of a secret in SecretsManager that contains the credentials to access a private HTTPS archive for the modules
+- **archiveSecret**: name of a secret in SecretsManager that contains the credentials to access a private HTTPS archive for the modules  (see [Archive Secret](archivesecret))
   - secret name must follow the `*-archive-credentials*` naming pattern
   - the secret value must be a JSON with the `username` and `password` values
 - **groups** : the relative path to the [`module manifests`](module_manifest) that define each module in the group.  This sequential order is preserved in deployment, and reversed in destroy.
@@ -330,7 +330,7 @@ When using this feature, any change to these file(s) (modifying, add to manifest
 ## Universal Environment Variable Replacement in Manifests
 As of the release of `seed-farmer==3.5.0`, we have added support for dynamic replacement of values with environment variables in manifests.  This does not replace any pre-existing functionality.  This also is limited to only manifests (`deployment_manifest` and `module_manifest`).  Things like the `deployspec` and the `modulestack` are NOT included in this functionality.  We strongly recommend using hard-coded values in manifests or leveraging the facilities already in place, but we have added this feature based on feedback from experienced users.
 
-Any string within your manifests that has a designated pattern will automatically be resolved.  If you have an environment variable named `SOMEKEY` that is defined, you can reference it in your manifests via wrapping it in `${}` --> for example `${SOMEKEY}`.   
+Any string within your manifests that has a designated pattern will automatically be resolved.  If you have an environment variable named `SOMEKEY` that is defined, you can reference it in your manifests via wrapping it in `${}` --> for example `${SOMEKEY}`. Additionally, it is possible to disable environment variable replacement in module input parameters using `disableEnvVarResolution: True` for cases such as when input parameter is a script.
 
 The following is a valid manifest:
 
@@ -356,6 +356,12 @@ parameters:
   - name: vpc-id
     valueFrom:
       secretsManager: ${SOMEKEY}
+  - name: param-no-env-resolution
+    disableEnvVarResolution: True
+    value:
+      - |
+        export VAR=test
+        echo "${VAR}"
 ```
 This can be applied to all values in the manifest.  We do not recommend using this in the `name` field of manifests as any value that is referenced by downstream manifests MUST align.  For example, in the following:
 
@@ -525,7 +531,7 @@ This would result in the creation of an `_auth` entry in npm config (`.npmrc`) w
 npm config set //the-mirror-dns/npm/:_auth="mybase64encodedssltoken"
 ```
 
-
+(archivesecret)=
 ### Archive Secret
 
 If using an archive store that is not public or needs an authentication scheme, the `archiveSecret` provides a means to set a username / password, so that the archived modules can be downloaded.
@@ -557,6 +563,14 @@ The content of the AWS SecretsManager secret must be a JSON containing two value
 },
 ```
 
+The archive secret would then need to be referenced in the deployment manifest:
+
+```yaml
+...
+archiveSecret: example-archive-credentials-modules
+...
+```
+
 (parameters)=
 ## Parameters
 

docs/source/upgrades.md

@@ -92,7 +92,7 @@ Seedkits must be upgraded if **both** of the following is true.
 To upgrade:
 1. Update your version of `aws-codeseeder` via
     ```bash
-    pip install --upgrade codeseeder==1.1.0
+    pip install --upgrade aws-codeseeder==1.1.0
      ```
 2. Run seedfarmer with the `--update-seedkit` flag set
     ```bash

examples/exampleproject/manifests-isolated/examples/optional-modules-2.yaml

@@ -6,12 +6,14 @@
 #     value: true
 # ---
 name: buckets
-path: git::https://github.com/awslabs/idf-modules.git//modules/storage/buckets/?ref=release/1.2.0&depth=1
+path: git::https://github.com/awslabs/idf-modules.git//modules/storage/buckets/?ref=release/1.12.0&depth=1
 targetAccount: secondary
 targetRegion: us-west-2
 parameters:
   - name: encryption-type
     value: SSE
+  - name: retention-type
+    value: DESTROY
   - name: vpc-id
     valueFrom:
       parameterValue: vpcId

examples/exampleproject/manifests-isolated/examples/optional-modules.yaml

@@ -6,11 +6,13 @@
 #     value: true
 # ---
 name: buckets
-path: git::https://github.com/awslabs/idf-modules.git//modules/storage/buckets/?ref=release/1.2.0&depth=1
+path: git::https://github.com/awslabs/idf-modules.git//modules/storage/buckets/?ref=release/1.12.0&depth=1
 targetAccount: primary
 targetRegion: us-east-2
 parameters:
   - name: encryption-type
     value: SSE
+  - name: retention-type
+    value: DESTROY
   - name: some-name
     value: other

examples/exampleproject/manifests/examples/optional-modules.yaml

@@ -1,11 +1,13 @@
 name: networking
-path: git::https://github.com/awslabs/idf-modules.git//modules/network/basic-cdk/?ref=release/1.2.0&depth=1
+path: git::https://github.com/awslabs/idf-modules.git//modules/network/basic-cdk/?ref=release/1.12.0&depth=1
 parameters:
   - name: internet-accessible
     value: true
 ---
 name: buckets
-path: git::https://github.com/awslabs/idf-modules.git//modules/storage/buckets/?ref=release/1.2.0&depth=1
+path: git::https://github.com/awslabs/idf-modules.git//modules/storage/buckets/?ref=release/1.12.0&depth=1
 parameters:
   - name: encryption-type
-    value: SSE
+    value: SSE
+  - name: retention-type
+    value: DESTROY

pyproject.toml

@@ -70,6 +70,7 @@ markers = [
     "mgmt_metadata_support: marks all `mgmt_metadata_support` tests",
     "mgmt_build_info: marks all `mgmt_build_info` tests",
     "mgmt_git_support: marks all `mgmt_git_support` tests",
+    "mgmt_git_release:  marks all `mgmt_git_release` tests",
     "mgmt_archive_support: marks all `mgmt_archive_support` tests",
     "service: marks all `services` tests",
     "projectpolicy: marks all `projectpolicy` tests",

requirements-dev.in

@@ -1,20 +1,23 @@
-awscli~=1.33.41
-certifi~=2024.7.4
+-c requirements.txt
+
+awscli~=1.34.29
+certifi~=2024.8.30
 check-manifest~=0.48
 mypy~=1.11
 pip-tools~=7.4.1
-pydot~=3.0.1
+pydot~=3.0.2
 pyroma~=4.0
-pytest~=8.3.2
+pytest~=8.3.3
 pytest-cov~=5.0.0
 pytest-mock~=3.14.0
 pytest-ordering~=0.6
-ruff~=0.5.7
+ruff~=0.6.9
 twine~=5.1.1
 types-PyYAML~=6.0.12
 types-requests~=2.31.0.6
-types-setuptools~=71.1.0
+types-setuptools~=75.1.0
 wheel~=0.44.0
-moto[s3,sts,iam,codebuild,secretsmanager,ssm]~=5.0.12
+boto3-stubs[codebuild,iam,s3,secretsmanager,ssm,sts]~=1.35.34
+moto[s3,sts,iam,codebuild,secretsmanager,ssm]~=5.0.16
 requests~=2.32.3
-werkzeug~=3.0.3
+werkzeug~=3.0.4