Add parameter store docs and added examples for secrets manager

ceb10n · Jul 20, 2024 · 3d6fbb3 · 3d6fbb3
1 parent 3d7ad46
commit 3d6fbb3
Show file tree

Hide file tree

Showing 10 changed files with 220 additions and 19 deletions.
diff --git a/docs/configuration/parameter-store.md b/docs/configuration/parameter-store.md
@@ -0,0 +1,50 @@
+# :fontawesome-brands-aws:{ .aws } Parameter Store
+
+You can use `pydantic-settings-aws` to create your settings with data located in [Systems Manager: Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html).
+
+!!! info "Parameter Store content"
+    The content of the the parameter store **must** be a `string`.
+
+## :fontawesome-solid-screwdriver-wrench: SettingsConfigDict options
+
+There is no required setting that you must especify.
+
+### :fontawesome-solid-toolbox: Settings for boto3 client usage
+
+| Option                  | Required?                          | Description                                                                   |
+| :---------------------- | :--------------------------------- | :---------------------------------------------------------------------------- |
+| `ssm_client`            | :fontawesome-solid-xmark: optional | An existing boto3 client for Parameter Store if you already have one          |
+| `aws_region`            | :fontawesome-solid-xmark: optional | The region your Parameter Store lives. Used only if you don't inform a client |
+| `aws_profile`           | :fontawesome-solid-xmark: optional | An existing aws configured profile. Used only if you don't inform a client    |
+| `aws_access_key_id`     | :fontawesome-solid-xmark: optional | A valid Access Key Id. Used only if you don't inform a client                 |
+| `aws_secret_access_key` | :fontawesome-solid-xmark: optional | A valid Secret Access Key Id. Used only if you don't inform a client          |
+| `aws_session_token`     | :fontawesome-solid-xmark: optional | A valid Session Token. Used only if you don't inform a client                 |
+
+## :fontawesome-solid-tags: Configure your Parameter Store with Annotated
+
+You can declare your settings without any annotated field. In case you this, `pydantic-settings-aws` will look for a parater store with the same name as your field.
+
+### :fontawesome-solid-quote-right: Specify the name of the parameter
+
+In case all your parameters are in the same AWS account and region, you can just annotate you field with a string:
+
+```py linenums="1"
+class MongoDBSettings(ParameterStoreBaseSettings):
+    model_config = SettingsConfigDict(
+        ssm_client=my_ssm_client
+    )
+
+    server_host: Annotated[str, "/databases/mongodb/host"]
+```
+
+### :fontawesome-regular-comments: Multiple regions and accounts
+
+If you need to work with multiple accounts and/or regions, you can create a client for each account:
+
+```py linenums="1"
+class MongoDBSettings(ParameterStoreBaseSettings):
+
+    prod_host: Annotated[str, {"ssm": "/prod/databases/mongodb/host", "ssm_client": prod_client}]
+    release_host: Annotated[str, {"ssm": "/release/databases/mongodb/host", "ssm_client": release_client}]
+    development_host: Annotated[str, {"ssm": "/development/databases/mongodb/host", "ssm_client": development_client}]
+```
diff --git a/docs/configuration/secrets-manager.md b/docs/configuration/secrets-manager.md
@@ -0,0 +1,29 @@
+# :fontawesome-brands-aws:{ .aws } Secrets Manager
+
+You can use `pydantic-settings-aws` to create your settings with data located in AWS Secrets Manager.
+
+!!! info "Secrets Manager content"
+    The content of the Secrets Manager **must** be a valid JSON.
+
+## :fontawesome-solid-screwdriver-wrench: SettingsConfigDict options
+
+There is only one required setting that you must especify: `secrets_name`.
+
+### :fontawesome-solid-toolbox: Settings for boto3 client usage
+
+| Option                  | Required?                                         | Description                                                                   |
+| :---------------------- | :------------------------------------------------ | :---------------------------------------------------------------------------- |
+| `secrets_client`        | :fontawesome-solid-xmark: optional                | An existing boto3 client for Secrets Manager if you already have one          |
+| `aws_region`            | :fontawesome-solid-xmark: optional                | The region your Secrets Manager lives. Used only if you don't inform a client |
+| `aws_profile`           | :fontawesome-solid-xmark: optional                | An existing aws configured profile. Used only if you don't inform a client    |
+| `aws_access_key_id`     | :fontawesome-solid-xmark: optional                | A valid Access Key Id. Used only if you don't inform a client                 |
+| `aws_secret_access_key` | :fontawesome-solid-xmark: optional                | A valid Secret Access Key Id. Used only if you don't inform a client          |
+| `aws_session_token`     | :fontawesome-solid-xmark: optional                | A valid Session Token. Used only if you don't inform a client                 |
+
+### :fontawesome-solid-user-secret: Settings for Secrets Manager
+
+| Option            | Required?                                         | Description                      |
+| :---------------- | :------------------------------------------------ | :------------------------------- |
+| `secrets_name`    | :fontawesome-solid-triangle-exclamation: required | The name of your Secrets Manager |
+| `secrets_version` | :fontawesome-solid-xmark: optional                | The version of your secret       |
+| `secrets_stage`   | :fontawesome-solid-xmark: optional                | The stage of your secret         |
diff --git a/docs/examples/parameter-store.md b/docs/examples/parameter-store.md
@@ -0,0 +1,56 @@
+# :fontawesome-brands-aws:{ .aws } Parameter Store
+
+When working with `ParameterStoreBaseSettings`, you can work with parameters living in the same account and region, or with multiple accounts / regions.
+
+
+## :fontawesome-solid-chart-simple: Simplest way
+
+The simplest way you can work with `ParameterStoreBaseSettings` is to leaving it all to boto3 and create your fields with the same name as your parameters:
+
+```py linenums="1"
+class ParameterStoreSettings(ParameterStoreBaseSettings):
+    # no SettingsConfigDict
+
+    mongodb_host: str
+    mongodb_db_name: str
+```
+
+In this case, `pydantic-settings-aws` will leave to boto3 to try to identify how he can connect to AWS, and then will look for the parameters with name `mongodb_host` and `mongodb_db_name`.
+
+!!! warning "We don't shadow pydantic and boto3 errors"
+    In the above case, if for some reason mongodb_host is `None`, it will raise a pydantic's `ValidationError`.
+
+
+## :fontawesome-solid-quote-right: Specifying the name of the parameter
+
+For almost all cases, your parameter's name will be different from your field name.
+
+To deal with these cases, you must use `Annotated` and add the name of your parameter:
+
+```py linenums="1"
+class DynamoDBSettings(ParameterStoreBaseSettings):
+    model_config = SettingsConfigDict(
+        ssm_client=my_ssm_client
+    )
+
+    db_name: Annotated[str, "/databases/dynamodb/payments/dbname"]
+```
+
+## :fontawesome-solid-viruses: Multiple accounts and regions
+
+If you need to work with multiple accounts or regions, you can use `Annotated` and specify a `dict`:
+
+```py
+{
+    "ssm": "parameter name",
+    "ssm_client": my_boto3_client
+}
+```
+
+```py linenums="1"
+class MongoDBSettings(ParameterStoreBaseSettings):
+
+    prod_host: Annotated[str, {"ssm": "/prod/databases/mongodb/host", "ssm_client": prod_client}]
+    release_host: Annotated[str, {"ssm": "/release/databases/mongodb/host", "ssm_client": release_client}]
+    development_host: Annotated[str, {"ssm": "/development/databases/mongodb/host", "ssm_client": development_client}]
+```
diff --git a/docs/examples/secrets-manager.md b/docs/examples/secrets-manager.md
@@ -1,29 +1,14 @@
 # :fontawesome-brands-aws:{ .aws } Secrets Manager
 
-You can use `pydantic-settings-aws` to create your settings with data located in AWS Secrets Manager.
+For more information about all the options and settings, refer to [Configuring Secrets Manager](../configuration/secrets-manager.md)
 
-!!! info "Secrets Manager content"
-    The content of the Secrets Manager **must** be a valid JSON.
-
-## :fontawesome-brands-aws:{ .aws } Secrets Manager options
-
-There is only one required setting that you must especify: `secrets_name`.
-
-### SettingsConfigDict options
-
-| Option         | Required?                                      |
-| :------------- | :--------------------------------------------- |
-| `secrets_name` | :fontawesome-solid-triangle-exclamation: required    |
-| `PUT`          | :material-check-all: Update resource           |
-| `DELETE`       | :material-close:     Delete resource           |
-
-## Using your boto3 client
+## :fontawesome-solid-toolbox: Using your boto3 client
 
 You can use an already created `boto3 client`.
 
 All you need to do is to add `secrets_client` to your `SettingsConfigDict`.
 
-```py title="user_settings.py" linenums="1"
+```py linenums="1"
 import boto3
 from pydantic_settings_aws import SecretsManagerBaseSettings
 
@@ -54,3 +39,76 @@ You can just create your settings, and everything will be allright:
 ```python
 settings = AWSSecretsSettings()
 ```
+
+## :fontawesome-solid-toolbox: Getting specific version and stage of the secret
+
+```py linenums="1"
+from pydantic_settings_aws import SecretsManagerBaseSettings
+
+class AWSSecretsSettings(SecretsManagerBaseSettings):
+    model_config = SettingsConfigDict(
+        secrets_name="my/secret",
+        secrets_version="2",
+        secrets_stage="AWSCURRENT"
+    )
+
+    username: str
+    password: str
+```
+
+## :fontawesome-solid-id-card: With AWS profile name
+
+```py linenums="1"
+from pydantic_settings_aws import SecretsManagerBaseSettings
+
+class AWSSecretsSettings(SecretsManagerBaseSettings):
+    model_config = SettingsConfigDict(
+        secrets_name="my/secret",
+        aws_profile="DEV",
+        aws_region="sa-east-1"
+    )
+
+    username: str
+    password: str
+```
+
+## :fontawesome-solid-gears: With access key
+
+```py linenums="1"
+from pydantic_settings_aws import SecretsManagerBaseSettings
+
+class AWSSecretsSettings(SecretsManagerBaseSettings):
+    model_config = SettingsConfigDict(
+        secrets_name="my/secret",
+        aws_region="us-east-1",
+        aws_access_key_id="my_aws_access_key_id",
+        aws_secret_access_key="my_aws_secret_access_key",
+        aws_session_token="my_aws_session_token"
+    )
+
+    username: str
+    password: str
+```
+
+
+## :fontawesome-solid-gears: With IAM Identity Center (SSO)
+
+Just login with sso:
+
+```shell
+aws sso login --profile DEV
+```
+
+And then you can leave all empty:
+
+```py linenums="1"
+from pydantic_settings_aws import SecretsManagerBaseSettings
+
+class AWSSecretsSettings(SecretsManagerBaseSettings):
+    model_config = SettingsConfigDict(
+        secrets_name="my/secret"
+    )
+
+    username: str
+    password: str
+```
diff --git a/docs/explanation.md b/docs/explanation.md
diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md
diff --git a/docs/reference.md b/docs/reference.md
@@ -1,2 +1,5 @@
 
+!!! warning "🚧 Work in Progress"
+    This page is a work in progress.
+
 ::: pydantic_settings_aws.settings.SecretsManagerBaseSettings
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -5,4 +5,3 @@
 .yellow {
     color: #fffec0
 }
-
diff --git a/docs/tutorials.md b/docs/tutorials.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -24,6 +24,8 @@ theme:
     - search.highlight
     - search.share
     - search.suggest
+  palette:
+    primary: orange
 
 plugins:
   - mkdocstrings
@@ -51,7 +53,11 @@ markdown_extensions:
 
 nav:
   - Pydantic Settings AWS Docs: index.md
+  - Configuration:
+    - Parameter Store: configuration/parameter-store.md
+    - Secrets Manager: configuration/secrets-manager.md
   - Examples:
+    - Parameter Store: examples/parameter-store.md
     - Secrets Manager: examples/secrets-manager.md
   - Reference: reference.md