diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b95a2ea6e..8fd78ec5a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,6 +4,12 @@ on: push: branches: - main + workflow_dispatch: {} + +permissions: + id-token: write + contents: write + pages: write jobs: docs: @@ -12,6 +18,7 @@ jobs: concurrency: group: on-docs-build runs-on: ubuntu-latest + environment: Docs steps: - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c with: @@ -32,29 +39,46 @@ jobs: with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@e1e17a757e536f70e52b5a12b2e8d1d1c60e04ef + with: + aws-region: us-east-1 + role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }} + - name: Deploy Docs + run: | + aws s3 sync \ + dist \ + s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-dotnet/ apidocs: # Force Github action to run only a single job at a time (based on the group name) # This is to prevent "race-condition" in publishing a new version of doc to `gh-pages` concurrency: group: on-docs-build runs-on: ubuntu-latest + environment: Docs steps: - uses: actions/checkout@v3 - name: Setup .NET 6.0 uses: actions/setup-dotnet@607fce577a46308457984d59e4954e075820f10a with: dotnet-version: 6.0.405 - - name: Install solution dependencies - run: | - dotnet new tool-manifest - dotnet tool install docfx - - name: Create API docs - run: | - dotnet docfx apidocs/docfx.json + - uses: nikeee/docfx-action@b9c2cf92e3b4aa06878a1410833a8828b4bdcd26 #1.0.0 + name: Build Documentation + with: + args: apidocs/docfx.json - name: Release API docs to latest uses: peaceiris/actions-gh-pages@bd8c6b06eba6b3d25d72b7a1767993c0aeee42e7 # v3.9.2 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./apidocs/_site - keep_files: true destination_dir: api + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@e1e17a757e536f70e52b5a12b2e8d1d1c60e04ef + with: + aws-region: us-east-1 + role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }} + - name: Deploy Docs + run: | + aws s3 sync \ + apidocs/_site \ + s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-dotnet/api/ diff --git a/.github/workflows/on_push_docs.yml b/.github/workflows/on_push_docs.yml deleted file mode 100644 index d46879ca6..000000000 --- a/.github/workflows/on_push_docs.yml +++ /dev/null @@ -1,35 +0,0 @@ -name: Docs - -on: - push: - branches: - - develop - paths: - - "docs/**" - - "mkdocs.yml" - - "examples/**" - -jobs: - changelog: - permissions: - contents: write - uses: ./.github/workflows/reusable_publish_changelog.yml - - release-docs: - needs: changelog - permissions: - contents: write - pages: write - uses: ./.github/workflows/reusable_publish_docs.yml - with: - version: develop - alias: stage -# Maintenance: Only necessary in repo migration -# - name: Create redirect from old docs -# run: | -# git checkout gh-pages -# test -f 404.html && echo "Redirect already set" && exit 0 -# git checkout develop -- 404.html -# git add 404.html -# git commit -m "chore: set docs redirect" --no-verify -# git push origin gh-pages -f diff --git a/.github/workflows/reusable_publish_docs.yml b/.github/workflows/reusable_publish_docs.yml index 822ce867d..d2744eaff 100644 --- a/.github/workflows/reusable_publish_docs.yml +++ b/.github/workflows/reusable_publish_docs.yml @@ -22,6 +22,7 @@ on: type: boolean permissions: + id-token: write contents: write pages: write @@ -32,6 +33,7 @@ jobs: concurrency: group: on-docs-rebuild runs-on: ubuntu-latest + environment: Docs steps: - uses: actions/checkout@v3 with: @@ -82,6 +84,17 @@ jobs: keep_files: true destination_dir: latest/api + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@e1e17a757e536f70e52b5a12b2e8d1d1c60e04ef + with: + aws-region: us-east-1 + role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }} + - name: Deploy Docs + run: | + aws s3 sync \ + dist \ + s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-dotnet/ + apidocs: # Force Github action to run only a single job at a time (based on the group name) @@ -89,6 +102,7 @@ jobs: concurrency: group: on-docs-build runs-on: macos-latest + environment: Docs steps: - uses: actions/checkout@v3 with: @@ -103,4 +117,14 @@ jobs: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./apidocs/_site keep_files: true - destination_dir: api \ No newline at end of file + destination_dir: api + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@e1e17a757e536f70e52b5a12b2e8d1d1c60e04ef + with: + aws-region: us-east-1 + role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }} + - name: Deploy Docs + run: | + aws s3 sync \ + apidocs/_site \ + s3://${{ secrets.AWS_DOCS_BUCKET }}/lambda-dotnet/api/ \ No newline at end of file diff --git a/apidocs/docfx.json b/apidocs/docfx.json index d3be77747..490abbcc2 100644 --- a/apidocs/docfx.json +++ b/apidocs/docfx.json @@ -3,11 +3,8 @@ { "src": [ { - "files": [ - "**/*.csproj" - ], - "src": "../libraries/src/", - "force": true + "files": ["**/*.csproj"], + "src": "../libraries/src/" } ], "dest": "api", @@ -21,23 +18,16 @@ "build": { "content": [ { - "files": ["api/**.yml", "api/index.md"] + "files": ["api/**"] }, { - "files": ["toc.yml", "*.md"] + "files": ["toc.yml", "*.md"], + "exclude": ["_site/**", "**/bin/**", "**/obj/**", "**/[Tt]ests/**"] } ], "resource": [ { - "files": [ - "images/**" - ] - } - ], - "overwrite": [ - { - "files": ["apidoc/**.md"], - "exclude": ["obj/**", "_site/**"] + "files": ["images/**"] } ], "dest": "_site", @@ -60,4 +50,4 @@ "cleanupCacheHistory": false, "disableGitFeatures": false } -} \ No newline at end of file +} diff --git a/docs/utilities/parameters.md b/docs/utilities/parameters.md index d138af0d0..44aecb64b 100644 --- a/docs/utilities/parameters.md +++ b/docs/utilities/parameters.md @@ -28,13 +28,14 @@ Powertools are available as NuGet packages. You can install the packages from [N This utility requires additional permissions to work as expected. See the table below: -Provider | Function/Method | IAM Permission -------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- -SSM Parameter Store | `SsmProvider.Get(string)` `SsmProvider.Get(string)` | `ssm:GetParameter` -SSM Parameter Store | `SsmProvider.GetMultiple(string)` `SsmProvider.GetMultiple(string)` | `ssm:GetParametersByPath` -Secrets Manager | `SecretsProvider.Get(string)` `SecretsProvider.Get(string)` | `secretsmanager:GetSecretValue` -DynamoDB | `DynamoDBProvider.Get(string)` `DynamoDBProvider.Get(string)` | `dynamodb:GetItem` -DynamoDB | `DynamoDBProvider.GetMultiple(string)` `DynamoDBProvider.GetMultiple(string)` | `dynamodb:Query` +| Provider | Function/Method | IAM Permission | +| ------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------- | +| SSM Parameter Store | `SsmProvider.Get(string)` `SsmProvider.Get(string)` | `ssm:GetParameter` | +| SSM Parameter Store | `SsmProvider.GetMultiple(string)` `SsmProvider.GetMultiple(string)` | `ssm:GetParametersByPath` | +| SSM Parameter Store | If using **`WithDecryption()`** option | You must add an additional permission `kms:Decrypt` | +| Secrets Manager | `SecretsProvider.Get(string)` `SecretsProvider.Get(string)` | `secretsmanager:GetSecretValue` | +| DynamoDB | `DynamoDBProvider.Get(string)` `DynamoDBProvider.Get(string)` | `dynamodb:GetItem` | +| DynamoDB | `DynamoDBProvider.GetMultiple(string)` `DynamoDBProvider.GetMultiple(string)` | `dynamodb:Query` | ## SSM Parameter Store @@ -138,10 +139,12 @@ in order to get data from other regions or use specific credentials. The AWS Systems Manager Parameter Store provider supports two additional arguments for the `Get()` and `GetMultiple()` methods: -| Option | Default | Description | -|---------------|---------|-------------| -| **WithDecryption()** | `False` | Will automatically decrypt the parameter. | -| **Recursive()** | `False` | For `GetMultiple()` only, will fetch all parameter values recursively based on a path prefix. | +| Option | Default | Description | +| -------------------- | ------- | --------------------------------------------------------------------------------------------- | +| **WithDecryption()** | `False` | Will automatically decrypt the parameter. | +| **Recursive()** | `False` | For `GetMultiple()` only, will fetch all parameter values recursively based on a path prefix. | + +You can create `SecureString` parameters, which are parameters that have a plaintext parameter name and an encrypted parameter value. If you don't use the `WithDecryption()` option, you will get an encrypted value. Read [here](https://docs.aws.amazon.com/kms/latest/developerguide/services-parameter-store.html) about best practices using KMS to secure your parameters. **Example:** @@ -350,8 +353,8 @@ DynamoDB provider can be customized at initialization to match your table struct | -------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------- | | **table_name** | **Yes** | *(N/A)* | Name of the DynamoDB table containing the parameter values. | | **key_attr** | No | `id` | Hash key for the DynamoDB table. | -| **sort_attr** | No | `sk` | Range key for the DynamoDB table. You don't need to set this if you don't use the `GetMultiple()` method. | -| **value_attr** | No | `value` | Name of the attribute containing the parameter value. +| **sort_attr** | No | `sk` | Range key for the DynamoDB table. You don't need to set this if you don't use the `GetMultiple()` method. | +| **value_attr** | No | `value` | Name of the attribute containing the parameter value. | === "DynamoDBProvider" diff --git a/libraries/src/AWS.Lambda.Powertools.Parameters/AWS.Lambda.Powertools.Parameters.csproj b/libraries/src/AWS.Lambda.Powertools.Parameters/AWS.Lambda.Powertools.Parameters.csproj index 66d0c52a4..0b0161f35 100644 --- a/libraries/src/AWS.Lambda.Powertools.Parameters/AWS.Lambda.Powertools.Parameters.csproj +++ b/libraries/src/AWS.Lambda.Powertools.Parameters/AWS.Lambda.Powertools.Parameters.csproj @@ -4,17 +4,45 @@ net6.0 enable enable + default + AWS.Lambda.Powertools.Parameters + 0.0.1 + Amazon Web Services + Amazon.com, Inc + AWS Lambda Powertools for .NET + AWS Lambda Powertools for .NET - Parameters package. + Copyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved. + https://github.com/awslabs/aws-lambda-powertools-dotnet + Apache-2.0 + AWS;Amazon;Lambda;Powertools + README.md + https://sdk-for-net.amazonwebservices.com/images/AWSLogo128x128.png + AWSLogo128x128.png + true + AWS.Lambda.Powertools.Parameters + AWS.Lambda.Powertools.Parameters + + true + + + + + + - - - - + - + + + + + + + diff --git a/mkdocs.yml b/mkdocs.yml index 0ecd77ba5..f96608374 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,6 +63,7 @@ markdown_extensions: - pymdownx.snippets: base_path: "." check_paths: true + restrict_base_path: false - meta - toc: permalink: true diff --git a/poetry.lock b/poetry.lock index 7c0c05aea..66ac82b91 100644 --- a/poetry.lock +++ b/poetry.lock @@ -321,18 +321,19 @@ plugins = ["importlib-metadata"] [[package]] name = "pymdown-extensions" -version = "9.9" +version = "10.0" description = "Extension pack for Python Markdown." category = "main" optional = false python-versions = ">=3.7" files = [ - {file = "pymdown_extensions-9.9-py3-none-any.whl", hash = "sha256:ac698c15265680db5eb13cd4342abfcde2079ac01e5486028f47a1b41547b859"}, - {file = "pymdown_extensions-9.9.tar.gz", hash = "sha256:0f8fb7b74a37a61cc34e90b2c91865458b713ec774894ffad64353a5fce85cfc"}, + {file = "pymdown_extensions-10.0-py3-none-any.whl", hash = "sha256:e6cbe8ace7d8feda30bc4fd6a21a073893a9a0e90c373e92d69ce5b653051f55"}, + {file = "pymdown_extensions-10.0.tar.gz", hash = "sha256:9a77955e63528c2ee98073a1fb3207c1a45607bc74a34ef21acd098f46c3aa8a"}, ] [package.dependencies] markdown = ">=3.2" +pyyaml = "*" [[package]] name = "python-dateutil"