Adapter Configuration

Before running a tensor9 command, install the CLI, set T9_API_KEY, and verify your customer account. 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:

What runs here? The installation selects an origin cloud, a target environment, a deployment shape and target-cloud coordinates.
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.
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 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. 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.

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:

{
  "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:

tensor9 adapt svc run \
  --origin aws::1.0.0::s3 \
  --backend google::1.0.0::gcs

Then route only S3 in the application process:

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.

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:

export AWS_ENDPOINT_URL_S3="$T9_CLOUD_ADAPTER_ENDPOINT"

Or set the endpoint on one SDK client:

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 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:

Configuration: the reviewed file or guided summary names the intended origin, target and required service prerequisites.
Origin API: the normal SDK or tool receives the expected origin-shaped response.
Target service: a native read confirms the expected resource and effective settings.
Adapter explanation: Explain 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.

Choose a setup path

Use configuration files when the configuration must be reviewed, promoted across environments or generated by automation. Use guided configuration 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 for S3 to Cloud Storage and DynamoDB to provisioned Cosmos DB.

Tensor9 Cloud Adapter

How It Works

Getting Started

Configuration

Deployment

Support

Amazon Web Services

Google Cloud

Microsoft Azure

Making Trade-offs

Tuning

Debugging

Testing

Guides

Reference

Adapter Configuration

Configuration at a glance

Start with the workload

Declare the cloud direction once

Add service configuration only when it has work to do

Automatic mapping: S3 to Google Cloud Storage

Pre-provisioned mapping: SQS to Cloud SQL

Resource-level choices

Route one client or one service

Separate the identities

Treat changes as transitions

Validate in four views

Choose a setup path

​Configuration at a glance

​Start with the workload

​Declare the cloud direction once

​Add service configuration only when it has work to do

​Automatic mapping: S3 to Google Cloud Storage

​Pre-provisioned mapping: SQS to Cloud SQL

​Resource-level choices

​Route one client or one service

​Separate the identities

​Treat changes as transitions

​Validate in four views

​Choose a setup path

Configuration at a glance

Start with the workload

Declare the cloud direction once

Add service configuration only when it has work to do

Automatic mapping: S3 to Google Cloud Storage

Pre-provisioned mapping: SQS to Cloud SQL

Resource-level choices

Route one client or one service

Separate the identities

Treat changes as transitions

Validate in four views

Choose a setup path