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

# Adapter Configuration

> Configure a Cloud Adapter deployment, its service mappings and the clients that use it.

> [!NOTE]
>
> Before running a `tensor9` command, [install the CLI, set `T9_API_KEY`, and verify your customer account](https://docs.tensor9.com/cloud-adapter-early-access/getting-started/install-and-authenticate). Online commands are authenticated and their adapter detail is limited to mappings your account is entitled to use.

Cloud Adapter configuration answers three different questions:

1. **What runs here?** The installation selects an origin cloud, a target environment, a deployment shape and target-cloud coordinates.
2. **What needs to be prepared?** Most supported origin services use their compatible target backend automatically. A service-specific block is needed when a mapping requires resources to be provisioned or bound before the adapter starts.
3. **Which application calls use the adapter?** The application points the relevant native SDK client at the Cloud Adapter endpoint. Other service clients keep their existing endpoints.

Keep those layers separate. A target region belongs to the installation. A pre-provisioned Cloud SQL database belongs to the service that uses it. A Cosmos DB capacity choice belongs to one DynamoDB table. `AWS_ENDPOINT_URL_S3` belongs to the application process.

## Configuration at a glance

| Layer | Typical settings | Scope | Example |
| - | - | - | - |
| Installation | Origin cloud, target cloud, target project or subscription, region, deployment shape, networking | One Cloud Adapter installation | AWS origin APIs in Google Cloud project `acme-adapters-prod` |
| Runtime identity | Target-cloud principal, secret references, workload identity, allowed target resources | One installation or adapter runtime | A Google service account allowed to read and write Cloud Storage |
| Pre-provisioned service | Backend resources and bindings that must exist before the service starts | Only services that need them | An SQS adapter bound to a provisioned Cloud SQL database |
| Resource selection | Backend selector and supported target-native tuning | One created resource | A table with an explicit target capacity choice |
| Client routing | Service-specific endpoint, region and origin-side credentials | One application process or SDK client | `AWS_ENDPOINT_URL_S3=https://adapter.example.internal` |

The [service catalog](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/catalog.md) is the source for available mappings and service names. A catalog check belongs at the beginning of configuration, not after an installation has been provisioned.

## Start with the workload

Inventory what the application actually calls before choosing a target environment. Record the origin service, operations, resource names, request features and operational expectations.

For an S3 workload, this includes more than “uses S3.” Capture object CRUD, listing and pagination, multipart upload, conditional requests, metadata, checksums, versioning, lifecycle configuration, presigned URLs and retry behavior. Then compare that list with the [S3 target profile](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/databases-storage/s3.md).

For DynamoDB, capture key schemas, secondary indexes, conditional expressions, transactions, streams, TTL, item sizes, hot partitions, table creation behavior and capacity assumptions. Compare the result with the [DynamoDB target profile](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/databases-storage/dynamodb-table.md).

> [!WARNING]
>
> A listed backend does not promise the complete origin service. Support is directional, operation-specific and sometimes conditional. Read the public profile for the exact directed pair; authenticate and use `tensor9 explain` to inspect the mapping available to your account before configuring production traffic.

## Declare the cloud direction once

Current Cloud Adapter configuration selects an origin API family and a target cloud. It does not require a hand-written origin-to-backend row for every service. Cloud Adapter uses the service catalog to expose origin APIs with compatible target backends.

This compact example selects AWS as the origin and Google Cloud as the target:

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

The important consequence is that a normal S3 to Cloud Storage installation does not need an extra row that repeats `aws::1.0.0::s3` and `google::1.0.0::gcs`. The cloud direction and catalog already establish that relationship.

`targetConfig` contains shared target coordinates. It is not a credential map. Authentication comes from the runtime identity supplied to the deployment. Do not put a service-account key in `targetConfig`.

## Add service configuration only when it has work to do

A service-specific entry is a sparse override, not an allowlist of enabled APIs. Add one when that service needs configuration beyond the installation-wide cloud direction, especially when its backend must be provisioned or bound before startup.

Examples include:

* a queue adapter that needs a pre-provisioned PostgreSQL database and a secret reference for its DSN;
* a service that needs an existing namespace, key ring or shared coordination store;
* a mapping with a service-specific network or identity binding;
* a resource family whose infrastructure must exist before the origin API can create logical resources inside it.

Do not add empty service entries just to restate catalog mappings. They increase review noise without changing behavior.

### Automatic mapping: S3 to Google Cloud Storage

For S3 backed by Google Cloud Storage, the installation supplies the Google Cloud project and location, and the runtime receives a Google identity with narrowly scoped storage permissions. The application continues to send S3 requests.

The local equivalent shows the same selection directly:

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

Then route only S3 in the application process:

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

This does not redirect DynamoDB, STS or another AWS client. Read the complete [S3 to Cloud Storage configuration example](https://docs.tensor9.com/cloud-adapter-early-access/configuration/examples.md#s3-to-google-cloud-storage).

### Pre-provisioned mapping: SQS to Cloud SQL

An SQS mapping backed by Cloud SQL needs a database before it can serve queue operations. That prerequisite belongs in a sparse SQS service configuration together with a secret reference for the database connection. It is a real reason to add a service-specific block.

Keep the DSN out of the configuration file. The non-secret configuration should name the secret reference and describe the database ownership, backup, connection and migration expectations. The deployment resolves the secret into the adapter runtime.

This differs from S3 to Cloud Storage: object requests can address native storage directly through the selected target identity, while the PostgreSQL-backed queue implementation depends on provisioned shared state before its endpoint is ready.

### Resource-level choices

When several target backends are valid for a created resource, the origin request can carry a supported
backend choice and target-native capacity settings. These choices belong to that resource rather than the
installation as a whole. Read the public directed profile for exact directive names, accepted values and
scope. Authenticate and use `tensor9 explain` to confirm the mapping available to your account before creating production resources.

## Route one client or one service

Prefer the native SDK or tool's service-specific endpoint control. This keeps the change narrow and visible.

For AWS clients, configure the endpoint process-wide for one service:

```bash theme={null}
export AWS_ENDPOINT_URL_S3="$T9_CLOUD_ADAPTER_ENDPOINT"
```

Or set the endpoint on one SDK client:

```python theme={null}
import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://adapter.example.internal",
    region_name="us-east-1",
)
```

Use a client-level endpoint when one process must compare adapted and origin-native behavior or when only one client should use the adapter. Use the service-specific environment variable when every client for that service in the process should use the same route.

Do not replace a general AWS endpoint or DNS setting when only S3 should be adapted. Broad endpoint changes can accidentally send credential discovery, STS or an unsupported service to the adapter.

## Separate the identities

| Identity | Used for | Keep it scoped to |
| - | - | - |
| Origin-facing identity | Authentication and authorization of the application's origin-shaped request | The origin operations and resources the application may use |
| Target runtime identity | Native calls from Cloud Adapter to the selected backend | The target resources and operations required by the mapping |
| Verification identity | Independent inspection during testing and incident response | Read-only access where possible |

Do not use the verification identity as the adapter runtime identity. Independent verification is useful because it observes the target through a separate path.

Keep secret values out of configuration files, command lines, screenshots, reviews and support transcripts. Use the secret-reference mechanism for the installed deployment shape. Commit only redacted configuration and the names of required secret references.

## Treat changes as transitions

A valid new file is not necessarily a safe update. Classify every change before applying it:

| Change | Typical impact | Required review |
| - | - | - |
| Add a pre-provisioned service | New stateful resources, secret bindings and permissions | Ownership, backup, network path and bounded smoke test |
| Change a target identity | Requests begin using a different principal | Permission diff, secret rotation and rollback |
| Change region or project | Resources may resolve to a different target | Data location, naming, network and migration review |
| Change backend | Persistent data may not follow | Explicit migration and cutover plan |
| Change capacity tuning | Cost, throttling and latency can change | Native setting verification and representative load test |
| Change client endpoint | Traffic moves between implementations | Staged rollout, origin-shaped error checks and rollback |

The [provisioned deployment workflow](https://docs.tensor9.com/cloud-adapter-early-access/deployment/provisioned.md) validates supported updates and coordinates runtime changes. Editing a file does not move data, rotate an identity or prove that the new endpoint is healthy.

## Validate in four views

For every meaningful configuration change, collect evidence from four views:

1. **Configuration:** the reviewed file or guided summary names the intended origin, target and required service prerequisites.
2. **Origin API:** the normal SDK or tool receives the expected origin-shaped response.
3. **Target service:** a native read confirms the expected resource and effective settings.
4. **Adapter explanation:** [Explain](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain.md) identifies the selected mapping and relevant translation without exposing secrets.

One view cannot substitute for the others. A valid file does not prove deployment. A successful S3 response does not prove the object landed in the expected bucket. An explanation receipt does not prove a write committed.

## Review configuration with the included agents

Ask the included [Support Agents](https://docs.tensor9.com/cloud-adapter-early-access/support/agents.md) to explain the selected mapping, assessment issues or effective service roster. Supply the exact configuration revision and reviewed evidence. A configuration assessment does not establish live health, target placement or workload capacity; retain the four-view verification above.

For a configuration change, use [Bounded Work and Approval](https://docs.tensor9.com/cloud-adapter-early-access/operations/bounded-work.md) to identify its owner, precise effects, rollback and verification. An agent's suggested edit remains a proposal until accepted through the authoritative configuration workflow.

## Choose a setup path

Use [configuration files](https://docs.tensor9.com/cloud-adapter-early-access/configuration/files.md) when the configuration must be reviewed, promoted across environments or generated by automation. Use [guided configuration](https://docs.tensor9.com/cloud-adapter-early-access/configuration/guided-setup.md) when you want the terminal to enumerate supported choices and produce the same reviewable file.

Both paths should end with the same artifact, validation and deployment review. Continue to [worked configuration examples](https://docs.tensor9.com/cloud-adapter-early-access/configuration/examples.md) for S3 to Cloud Storage and DynamoDB to provisioned Cosmos DB.


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