Merge pull request #29 from ceb10n/docs/awssettingssource

Add docs to AWSBaseSettings

docs/configuration/aws.md

@@ -0,0 +1,68 @@
+# :fontawesome-brands-aws:{ .aws } AWSBaseSettings
+
+You can use `pydantic-settings-aws` to create your settings with data located both in [Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) and [Secrets Manager](https://aws.amazon.com/secrets-manager/).
+
+## :fontawesome-solid-screwdriver-wrench: SettingsConfigDict options
+
+You need to inform at least the Secrets Manager name, if you are using it as a data source.
+
+!!! tip "Parameter Store Settings"
+    If you are not using secrets manager as a data source, check [ParameterStoreBaseSettings](parameter-store.md).
+
+### :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          |
+| `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 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: Define which service you field is using with Annotated
+
+When you are using `AWSBaseSettings` you need to add at least a `dict` with the AWS service you are using.
+
+```py linenums="1"
+class MongoDBSettings(AWSBaseSettings):
+    model_config = SettingsConfigDict(
+        secrets_client=my_secrets_client,
+        secrets_name="myservice/mongodb",
+        ssm_client=my_ssm_client
+    )
+
+    username: Annotated[str, {"service": "secrets"}]
+    password: Annotated[str, {"service": "secrets"}]
+    server_host: Annotated[str, {"service": "ssm", "ssm": "/databases/mongodb/host"}]
+    server_port: Annotated[str, {"service": "ssm", "ssm": "/databases/mongodb/port"}]
+```
+
+### :fontawesome-solid-list: Single Secrets, multiple parameter store
+
+At the moment you can only have one Secrets Manager source, but multiple parameter store.
+
+```py linenums="1"
+class MongoDBSettings(AWSBaseSettings):
+    model_config = SettingsConfigDict(
+        secrets_client=my_secrets_client,
+        secrets_name="myservice/mongodb"
+    )
+
+    username: Annotated[str, {"service": "secrets"}] # will use SettingsConfigDict
+    password: Annotated[str, {"service": "secrets"}] # will use SettingsConfigDict
+    host: Annotated[str, {"ssm": "/dev/virginia/databases/mongodb/host", "ssm_client": dev_virginia_client}] # will use dev_virginia_client
+    port: Annotated[str, {"ssm": "/dev/saopaulo/databases/mongodb/host", "ssm_client": dev_saopaulo_client}] # will use dev_saopaulo_client
+```
+
+## :fontawesome-solid-quote-right: Settings Order
+
+First, `AWSBaseSettings` will try to load your data from either Parameter Store or Secrets Manager.
+
+If it can't find a value, `AWSBaseSettings` will still try to get your information from Environment, dotenv files and secret files.
+
+* AWS SSM and Secrets Manager
+* Environment variables
+* dotenv files
+* secret files

docs/examples/aws.md

@@ -0,0 +1,28 @@
+# :fontawesome-brands-aws:{ .aws } Parameter Store
+
+When working with `AWSBaseSettings`, you can work with multiple parameters living in the same account and region, or with multiple accounts / regions.
+
+The only restriction if for Secrets Manager. You can only use one *secret / client / account / region* at a time.
+
+
+## :fontawesome-solid-chart-simple: Simplest way
+
+The only required setting is your secret's name. All other configurations you can leave to boto3 to deal.
+
+```py linenums="1"
+class ParameterStoreSettings(AWSBaseSettings):
+    model_config = SettingsConfigDict(
+        secrets_name="my/secret"
+    )
+
+    username: Annotated[str, {"service": "secrets"}]
+    password: Annotated[str, {"service": "secrets"}]
+    mongodb_host: Annotated[str, {"service": "ssm", "ssm": "/mysystem/mongodb/host"}]
+    mongodb_db_name: Annotated[str, {"service": "ssm"}] # will look for a parameter named mongodb_db_name
+    environment: str # not related to aws. If you have an environment named ENVIRONMENT, it will work as if you were using BaseSettings
+```
+
+In this case, `pydantic-settings-aws` will leave to boto3 to try to identify how he can connect to AWS.
+
+!!! warning "We don't shadow pydantic and boto3 errors"
+    In the above case, if for some reason any field is `None`, it will raise a pydantic's `ValidationError`.

mkdocs.yml

@@ -54,9 +54,11 @@ markdown_extensions:
 nav:
   - Pydantic Settings AWS Docs: index.md
   - Configuration:
+    - AWS: configuration/aws.md
     - Parameter Store: configuration/parameter-store.md
     - Secrets Manager: configuration/secrets-manager.md
   - Examples:
+    - AWS: examples/aws.md
     - Parameter Store: examples/parameter-store.md
     - Secrets Manager: examples/secrets-manager.md
   - Reference: reference.md