> ## 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.

# How Cloud Adapter Works

> Follow an origin API request through a service adapter to its backend.

**Your existing cloud client talks to Cloud Adapter as though it were talking to its origin cloud service.** Point the origin CLI or SDK at the adapter endpoint; you still make S3, DynamoDB or other documented origin-API calls. The service adapter accepts a supported request, calls its configured target service with the target identity, and returns a response in the origin API's format. The target service (not the origin cloud) holds the application data.

![An application sends an origin-cloud API request through Tensor9 Cloud Adapter to a native target service and receives an origin-shaped response.](https://mintcdn.com/tensor9/ufP2gYsEkScmc1Bt/images/cloud-adapter-early-access/diagrams/cloud-adapter-how-it-works-light.svg?fit=max\&auto=format\&n=ufP2gYsEkScmc1Bt\&q=85\&s=141d60aa3a9b68341aca1622c212ac57)

## Example: S3 to Google Cloud Storage

Suppose an application uses `PutObject` to write `report.pdf` to an S3 bucket named `media`. Cloud Adapter handles that request as follows:

The AWS CLI can make the same call by changing its endpoint:

```bash theme={null}
aws s3api put-object --bucket media --key report.pdf --body ./report.pdf \
  --endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT"
```

1. The AWS CLI or application's S3 client sends an **S3 API** request with the bucket name, object key, bytes and metadata to the adapter endpoint, not to Amazon S3.
2. The S3 service adapter translates the S3 request to a Google Cloud Storage request.
3. The adapter calls the **GCS API** with the target identity configured for the deployment.
4. Cloud Storage writes the object to `gs://media/report.pdf`.
5. The adapter returns an S3 success response and ETag. The AWS CLI or S3 SDK receives the response format it expects.

![An application sends an S3 PutObject request through Tensor9 Cloud Adapter, which translates it to a Google Cloud Storage request, writes the object, and returns an S3 response.](https://mintcdn.com/tensor9/ufP2gYsEkScmc1Bt/images/cloud-adapter-early-access/diagrams/cloud-adapter-how-it-works-s3-gcs-light.svg?fit=max\&auto=format\&n=ufP2gYsEkScmc1Bt\&q=85\&s=904d0f2949dc9c5ed4e5b0b4c1f11900)

Object bodies remain in Cloud Storage. Cloud Adapter keeps bucket configuration separately so S3 bucket operations can retain their requested state and apply supported settings to the target bucket. `GetObject`, `HeadObject`, `ListObjectsV2`, multipart upload and other operations each have their own published behavior.

[See the S3 to Google Cloud Storage service profile →](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/databases-storage/s3.md#on-google-cloud)

## Example: DynamoDB to Azure Cosmos DB

A database request requires more adaptation than an object write. Consider this conditional update to an item in the `orders` table:

```text theme={null}
Key:                 customerId=C-42, orderId=O-1042
UpdateExpression:    SET #status = :shipped
ConditionExpression: #status = :open
```

This is still a DynamoDB API call. For a simpler read of the same item, the AWS CLI can be pointed at the adapter too:

```bash theme={null}
aws dynamodb get-item --table-name orders \
  --key '{"customerId":{"S":"C-42"},"orderId":{"S":"O-1042"}}' \
  --endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT"
```

The CLI speaks DynamoDB; it does not need Azure credentials or a Cosmos DB client. A conditional `UpdateItem` takes a more involved path:

1. The DynamoDB SDK sends the operation, typed attributes, update expression and condition to the adapter's **DynamoDB API** endpoint.
2. The DynamoDB service adapter parses the request and identifies the logical table and partition route.
3. It preserves the DynamoDB item types and maps the requested behavior to Cosmos DB.
4. Because this request uses a conditional `SET`, the adapter runs a partition-scoped stored procedure that reads the item, evaluates the condition, applies the update and checks the resulting item size atomically.
5. The adapter calls the **Azure Cosmos DB API**, which commits the document update. A concurrent write conflict remains retryable rather than appearing as a failed DynamoDB condition.
6. The adapter returns DynamoDB attributes, status or a DynamoDB-shaped conditional error.

![A conditional DynamoDB UpdateItem request passes through Tensor9 Cloud Adapter, which parses the DynamoDB request, maps the logical table and key, executes an atomic Azure Cosmos DB write, and returns a DynamoDB response.](https://mintcdn.com/tensor9/ufP2gYsEkScmc1Bt/images/cloud-adapter-early-access/diagrams/cloud-adapter-how-it-works-dynamodb-cosmos-light.svg?fit=max\&auto=format\&n=ufP2gYsEkScmc1Bt\&q=85\&s=f0a9e1452e2c52d861c7e58f7fa319a8)

Other request shapes take different paths. Eligible conditional removals can use native PATCH. Requests involving a local secondary index, a complex expression or an old image on condition failure can use an ETag-guarded read-modify-write. The same service profile defines how reads, queries, secondary indexes, streams, TTL and table operations behave. It also identifies important boundaries, including numeric precision, pagination and DynamoDB multi-item transactions.

[See the DynamoDB to Azure Cosmos DB service profile →](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/databases-storage/dynamodb-table.md)

The origin client and the backend use different credentials and authorization systems. Configuring a target-cloud credential does not establish who may call the adapter. Review both sides before exposing an endpoint.

For an AWS CLI process, `AWS_ENDPOINT_URL_S3` routes S3 commands and `AWS_ENDPOINT_URL_DYNAMODB` routes DynamoDB commands to the adapter without adding `--endpoint-url` to each command. Use service-specific settings so an unrelated AWS call is not redirected by accident. The [AWS CLI guide](https://docs.tensor9.com/cloud-adapter-early-access/guides/aws-cli.md) shows endpoint setup and verification.

## Compatibility is specific

An adapter can support one operation without supporting every feature or option of that operation. Check the service reference for required configuration, supported operations and known differences.

Adaptation also has a direction. An S3-to-Cloud Storage mapping does not imply that a Cloud Storage client can use S3 through the same adapter. Nor does one successful request establish all the behavior your application depends on.

## Management APIs and data planes are different

Cloud Adapter handles supported calls to an origin cloud API. It does not automatically proxy every protocol that a target service exposes. An S3 management request and an application's native database connection are different paths and may have different identities, endpoints and consistency behavior.

| Path | What the adapter can establish | What still needs its own design |
| - | - | - |
| Origin cloud management API | Request translation, target operation and origin-shaped response for published operations | Operation coverage, authorization and target limits |
| Native data-plane protocol | Only what the selected service mapping explicitly includes | Direct endpoint, network path, credentials and protocol compatibility |
| Infrastructure tool | The tool's API calls, where its endpoint can be configured | Local synthesis, state handling and tool-specific retries |

This is why the [Guides](https://docs.tensor9.com/cloud-adapter-early-access/guides/index.md) begin with API clients and infrastructure tools rather than promising that every application protocol is proxied.

Native application traffic does not always pass through a service adapter. For example, adapting an infrastructure-management API is different from proxying every database query or network packet. The request path depends on the service and mapping.

## Service adapters and cloud adapters

A **service adapter** covers a specific origin service and backend. A **cloud adapter** groups service adapters for a particular origin-to-target cloud direction. You can start with a single service and add others as your workload requires them.

The [deployment model](https://docs.tensor9.com/cloud-adapter-early-access/deployment/overview.md) supports a single process and a provisioned installation. The deployment choice does not change the meaning of a service mapping.

## See what the adapter is doing

[Tuning tags](https://docs.tensor9.com/cloud-adapter-early-access/tuning/overview.md) let supported origin requests supply target-native choices. [Diagnostic response headers](https://docs.tensor9.com/cloud-adapter-early-access/debugging/response-headers.md) help interpret a response. [`tensor9 explain`](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain) describes the selected profile or a covered request's adapter decisions without requiring you to infer them from implementation details.

Choose the mode deliberately: a hypothetical explanation does not apply the target operation, while `ExecuteAndExplain` does. A receipt identifies the resulting report; it does not by itself establish success, authorization or side effects. The [worked adapter investigations](https://docs.tensor9.com/cloud-adapter-early-access/debugging/worked-examples.md) show how to combine the report with the origin response and native target observations for S3 to Cloud Storage and more complex mappings.

Cloud Adapter includes [Support Agents](https://docs.tensor9.com/cloud-adapter-early-access/support/agents.md) to help interpret that evidence. Give the agent the selected mapping, native result, report revision and independent target observation, then ask one concrete question. Keep any follow-up read or change within its permitted scope. Use [Operations with Agents](https://docs.tensor9.com/cloud-adapter-early-access/operations/overview.md) to coordinate the resulting task and verify its outcome; the agent's interpretation does not replace the original API result or approve a resource change.

Begin with [key concepts](https://docs.tensor9.com/cloud-adapter-early-access/key-concepts.md), or [evaluate an adapter](https://docs.tensor9.com/cloud-adapter-early-access/getting-started/overview.md) against your application's operations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.