> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Examples

> Configure and verify S3 to Google Cloud Storage and DynamoDB to provisioned Azure Cosmos DB.

These examples connect installation configuration, client endpoint configuration, resource-level choices and native target verification. Each example uses a disposable resource and checks the result through both the origin API and the target cloud.

<Warning>
  Use dedicated test resources. Do not run these commands against a production bucket, table, database or Cosmos DB account without an approved test and cleanup plan.
</Warning>

## S3 to Google Cloud Storage

This example keeps the S3 API at the application boundary and stores object bytes in Google Cloud Storage.

### What belongs in each layer

| Layer            | Value                                                               |
| ---------------- | ------------------------------------------------------------------- |
| Installation     | `origin: aws`, `target: gcp`, Google Cloud project and location     |
| Catalog mapping  | S3 to Google Cloud Storage, derived automatically                   |
| Runtime identity | Google identity allowed to access the target test bucket            |
| Application      | S3-specific endpoint pointing to Cloud Adapter                      |
| Verification     | `gcloud storage` using a separate read-only identity where possible |

There is no service row whose only purpose is to say S3 maps to Cloud Storage.

### 1. Write the installation configuration

```json theme={null}
{
  "schemaVersion": 4,
  "origin": "aws",
  "target": "gcp",
  "targetConfig": {
    "GCP_PROJECT": "acme-adapters-dev",
    "GCP_LOCATION": "us-central1"
  }
}
```

Before applying it, review [S3 on Google Cloud](/cloud-adapter/service-catalog/aws/databases-storage/s3#on-google-cloud). Confirm that the application operations, multipart behavior, metadata, checksums and error paths are covered.

### 2. Confirm target access

Use the native verification identity to confirm that the target bucket exists:

```bash theme={null}
export TARGET_BUCKET="acme-adapter-smoke-gcs"
gcloud storage buckets describe "gs://$TARGET_BUCKET"
```

This proves only that the verification path can see the bucket. The adapter runtime identity is configured separately and should have only the permissions required by the mapping.

### 3. Start a local adapter or use the installed endpoint

For a local configuration check, start the directed mapping:

```bash theme={null}
tensor9 adapt svc run \
  --origin aws::1.0.0::s3 \
  --backend google::1.0.0::gcs
```

Copy the listening endpoint printed by the command:

```bash theme={null}
export T9_CLOUD_ADAPTER_ENDPOINT="<endpoint printed by tensor9>"
```

The explicit `--backend` is a property of this single-service local command. A provisioned origin-and-target installation derives the same normal mapping from the catalog.

### 4. Route only S3

Set the AWS SDK's service-specific endpoint for the current process:

```bash theme={null}
export AWS_ENDPOINT_URL_S3="$T9_CLOUD_ADAPTER_ENDPOINT"
export AWS_REGION="us-east-1"
export AWS_REQUEST_CHECKSUM_CALCULATION="WHEN_REQUIRED"
```

Or construct one Python client with an explicit endpoint:

```python theme={null}
import os
import boto3

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["T9_CLOUD_ADAPTER_ENDPOINT"],
    region_name="us-east-1",
)
```

Do not set a general AWS endpoint. STS, DynamoDB and other clients should keep their own routes.

### 5. Write one object

Choose an origin-facing bucket name, a disposable key and a small body:

```bash theme={null}
export ORIGIN_BUCKET="adapter-smoke-test"
export TEST_KEY="configuration/s3-gcs-$(date +%s).txt"
printf 'configured S3 to Cloud Storage\n' > /tmp/t9-s3-gcs.txt

aws s3api put-object \
  --bucket "$ORIGIN_BUCKET" \
  --key "$TEST_KEY" \
  --body /tmp/t9-s3-gcs.txt \
  --content-type text/plain \
  --metadata configuration-example=s3-gcs
```

If you did not set `AWS_ENDPOINT_URL_S3`, pass `--endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT"` to each AWS CLI command instead.

### 6. Verify both interfaces

Read through S3:

```bash theme={null}
aws s3api head-object \
  --bucket "$ORIGIN_BUCKET" \
  --key "$TEST_KEY"

aws s3api get-object \
  --bucket "$ORIGIN_BUCKET" \
  --key "$TEST_KEY" \
  /tmp/t9-s3-origin.txt
```

Read the native object:

```bash theme={null}
gcloud storage objects describe "gs://$TARGET_BUCKET/$TEST_KEY"
gcloud storage cat "gs://$TARGET_BUCKET/$TEST_KEY" > /tmp/t9-s3-target.txt

cmp /tmp/t9-s3-gcs.txt /tmp/t9-s3-origin.txt
cmp /tmp/t9-s3-gcs.txt /tmp/t9-s3-target.txt
```

The S3 ETag and Cloud Storage generation are different identifiers. Compare bytes and the application-visible metadata instead of assuming those identifiers are interchangeable.

### 7. Clean up the test object

```bash theme={null}
aws s3api delete-object \
  --bucket "$ORIGIN_BUCKET" \
  --key "$TEST_KEY"

gcloud storage objects describe "gs://$TARGET_BUCKET/$TEST_KEY"
```

The native describe should report that the current object is no longer readable. A target with versioning or soft delete can retain recoverable data, so inspect those settings before treating deletion as physical erasure.

### What this proves

This bounded test proves that the selected client can reach the adapter, the tested S3 operations are served by the selected mapping, and the expected object bytes appear in the target bucket. It does not prove compatibility for untested S3 operations, migrate existing objects or validate production throughput.

## DynamoDB to provisioned Azure Cosmos DB

This example creates an `orders` table through the DynamoDB API, selects the provisioned Cosmos DB mapping and gives the target container an autoscale maximum of 40,000 RU/s.

### What belongs in each layer

| Layer            | Value                                                                              |
| ---------------- | ---------------------------------------------------------------------------------- |
| Installation     | `origin: aws`, `target: azure`, subscription, resource group and location          |
| Runtime identity | Azure identity permitted to use the configured Cosmos DB account and database      |
| Resource request | Provisioned Cosmos DB backend selector, key schema and autoscale maximum           |
| Application      | DynamoDB-specific endpoint pointing to Cloud Adapter                               |
| Verification     | DynamoDB `DescribeTable` plus native Cosmos DB container and throughput inspection |

The capacity choice belongs to the table. It is not a global installation setting.

### 1. Write the installation configuration

```json theme={null}
{
  "schemaVersion": 4,
  "origin": "aws",
  "target": "azure",
  "targetConfig": {
    "AZURE_SUBSCRIPTION_ID": "00000000-0000-0000-0000-000000000000",
    "AZURE_RESOURCE_GROUP": "rg-cloud-adapter-dev",
    "AZURE_LOCATION": "eastus2"
  }
}
```

Review [DynamoDB on provisioned Cosmos DB](/cloud-adapter/service-catalog/aws/databases-storage/dynamodb-table#azure-cosmos-db-provisioned). Pay particular attention to numeric precision, transaction scope, index planning, stream ownership and table lifecycle.

### 2. Set endpoint and native target values

```bash theme={null}
export T9_CLOUD_ADAPTER_ENDPOINT="https://dynamodb.adapter.dev.internal"
export AWS_ENDPOINT_URL_DYNAMODB="$T9_CLOUD_ADAPTER_ENDPOINT"
export AWS_REGION="us-east-1"

export AZURE_RESOURCE_GROUP="rg-cloud-adapter-dev"
export COSMOS_ACCOUNT="acme-adapter-dev"
export COSMOS_DATABASE="cloud-adapter"
export COSMOS_CONTAINER="orders"
```

`AWS_ENDPOINT_URL_DYNAMODB` affects DynamoDB clients in this process. It does not redirect S3 or STS.

### 3. Build a complete `CreateTable` request

```json theme={null}
{
  "TableName": "orders",
  "AttributeDefinitions": [
    {
      "AttributeName": "tenant_id",
      "AttributeType": "S"
    },
    {
      "AttributeName": "order_id",
      "AttributeType": "S"
    }
  ],
  "KeySchema": [
    {
      "AttributeName": "tenant_id",
      "KeyType": "HASH"
    },
    {
      "AttributeName": "order_id",
      "KeyType": "RANGE"
    }
  ],
  "BillingMode": "PAY_PER_REQUEST",
  "Tags": [
    {
      "Key": "t9:backend",
      "Value": "azure::1.0.0::cosmosdb::provisioned"
    },
    {
      "Key": "t9:tuning:container.properties.options.autoscaleSettings.maxThroughput",
      "Value": "40000"
    },
    {
      "Key": "environment",
      "Value": "development"
    }
  ]
}
```

Save it as `create-orders-table.json`.

`BillingMode` remains part of the DynamoDB-facing description. The tuning tag controls the effective Cosmos DB autoscale maximum. A later DynamoDB `UpdateTable` does not automatically resize the Cosmos container.

40,000 RU/s is an example. Choose a supported value for the target region and workload. The documented tuning field accepts a minimum of 1,000 RU/s in 1,000-RU/s increments.

### 4. Create the table through DynamoDB

```bash theme={null}
aws dynamodb create-table \
  --cli-input-json file://create-orders-table.json
```

Keep the command timestamp and response. Table creation can return before every target-side action is ready, so poll the origin API instead of assuming the first response is final:

```bash theme={null}
aws dynamodb wait table-exists --table-name orders
aws dynamodb describe-table --table-name orders
```

### 5. Verify the Cosmos DB container and size

Inspect the target container:

```bash theme={null}
az cosmosdb sql container show \
  --account-name "$COSMOS_ACCOUNT" \
  --database-name "$COSMOS_DATABASE" \
  --name "$COSMOS_CONTAINER" \
  --resource-group "$AZURE_RESOURCE_GROUP"
```

Read its effective autoscale maximum:

```bash theme={null}
az cosmosdb sql container throughput show \
  --account-name "$COSMOS_ACCOUNT" \
  --database-name "$COSMOS_DATABASE" \
  --name "$COSMOS_CONTAINER" \
  --resource-group "$AZURE_RESOURCE_GROUP" \
  --query resource.autoscaleSettings.maxThroughput \
  --output tsv
```

Expect `40000`. If the container exists but the throughput differs, preserve the create response and use [Explain](/cloud-adapter/debugging/explain) before changing capacity.

### 6. Exercise the key schema

Write one disposable item:

```bash theme={null}
aws dynamodb put-item \
  --table-name orders \
  --item '{
    "tenant_id": {"S": "tenant-smoke"},
    "order_id": {"S": "order-001"},
    "status": {"S": "configured"},
    "total_cents": {"N": "1250"}
  }'
```

Read it back through DynamoDB:

```bash theme={null}
aws dynamodb get-item \
  --table-name orders \
  --key '{
    "tenant_id": {"S": "tenant-smoke"},
    "order_id": {"S": "order-001"}
  }' \
  --consistent-read
```

This verifies one point write and strongly consistent point read through the origin API. It does not test conditional writes, queries, transactions, secondary indexes, streams or sustained throughput.

### 7. Measure before accepting the capacity

Run a representative workload and record:

* request rate and item-size distribution;
* consumed RUs and throttled requests;
* p50, p95 and p99 latency at the application;
* partition-key distribution;
* adapter CPU, memory and target-call latency;
* Cosmos DB cost at the selected maximum;
* retries and origin-shaped errors.

Do not infer production capacity from a successful `PutItem`. The autoscale maximum defines a cost and throttling envelope, not a performance guarantee.

### 8. Clean up deliberately

Delete the test item first:

```bash theme={null}
aws dynamodb delete-item \
  --table-name orders \
  --key '{
    "tenant_id": {"S": "tenant-smoke"},
    "order_id": {"S": "order-001"}
  }'
```

Delete the table only if this example created a dedicated disposable table and the resource owner approved deletion:

```bash theme={null}
aws dynamodb delete-table --table-name orders
```

Logical `DeleteTable` and native physical cleanup are separate in this mapping. Confirm target state and billing through Azure rather than assuming the DynamoDB response deleted the Cosmos DB account or shared database.

### What this proves

This test proves that the table request selected the provisioned Cosmos DB mapping, the key schema was accepted, the effective autoscale maximum matches the tuning tag, and one item can round-trip through the DynamoDB API. It does not prove compatibility for every expression, transaction, index or stream behavior.

## Promote a tested configuration

Before moving either example beyond development:

1. save the reviewed installation file without secrets;
2. record the exact service profile and adapter version tested;
3. replace disposable identities with dedicated least-privilege runtime identities;
4. repeat the operation matrix the application actually uses;
5. establish native backup, recovery, quota and alerting procedures;
6. document endpoint rollout and rollback;
7. retain a redacted [Explain](/cloud-adapter/debugging/explain) example for the service;
8. test cleanup and uncertain-write recovery.

Use [configuration files](/cloud-adapter/configuration/files) for review and promotion rules, and [Tuning Your Adapters](/cloud-adapter/tuning/overview) before adding any other target-native directive.