> ## 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 Service Adapters Work
A **service adapter** lets your application use an equivalent service in your customer's environment. You define your application and its infrastructure once. Tensor9 BYOC adapts that infrastructure to each customer's cloud and, where supported, handles the API differences so your application can keep its existing client libraries.
The [Service Catalog](/byoc/service-adapters/catalog) describes the service mappings available for each target cloud. Your application can, for example, manage a database through the RDS API while sending SQL queries directly to the target PostgreSQL server. A VPC adapter handles network-management calls; the customer's cloud handles the application's network traffic.
Choose the cloud your application is written for, then look for your customer's cloud in the target columns. Adaptation has a direction: support for SQS on Azure Service Bus does not imply support for moving a Service Bus application to AWS. Each service page explains its target services, supported operations and differences that affect applications.
## Adaptation Tiers
An adaptation tier describes how much of a service Tensor9 BYOC takes on when your application runs in your customer's cloud. It covers the infrastructure Tensor9 BYOC provisions in the customer's environment and whether a service adapter answers your application's origin-cloud API calls at runtime.
Tiers apply per service, so you choose service by service how far to adapt. The [Service Catalog](/byoc/service-adapters/catalog) lists the tiers available for each mapping, and your application's own API calls determine which of them it needs.
| Tier | What Tensor9 BYOC provides | How the application uses it |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Max** | Equivalent infrastructure plus an adapter for supported cloud API calls. | Existing cloud clients send those calls to the adapter. Native protocols and application traffic can still go directly to the target service. |
| **Infrastructure only** | Native cloud resources defined in Terraform you own and manage. The resources run in your customer's environment. | The application uses the target service's native API or protocol. Tensor9 BYOC does not answer its origin-cloud API calls at runtime. |
Where both tiers are available, Infrastructure only is an option for applications that do not need the runtime adapter. For example, a PostgreSQL application can connect directly to Cloud SQL after Tensor9 BYOC updates its endpoint. If it also calls the RDS API to create or modify databases, it needs Max support for those operations.
S3 illustrates a different case. Even when the target supports the S3 protocol, an AWS client signs requests for AWS. The adapter directs those requests to the target and signs them with the customer's credentials. Protocol compatibility alone does not remove this runtime dependency.
When the origin and target clouds are the same, the stack runs natively.
## A stack's tier depends on its services and API calls
Your stack requires the highest tier needed by any of its services. Consider an application with these requirements on Google Cloud:
| Requirement | Adaptation | Required tier |
| ---------------------------------------------------- | ----------------------------------------- | ------------------- |
| Deploy Kubernetes workloads to a provisioned cluster | EKS infrastructure becomes GKE | Infrastructure only |
| Query a provisioned PostgreSQL database | RDS infrastructure becomes Cloud SQL | Infrastructure only |
| Resolve names in a provisioned DNS zone | Route 53 infrastructure becomes Cloud DNS | Infrastructure only |
| Publish notifications through the SNS API | The adapter publishes to Pub/Sub | Max |
This stack requires Max for SNS. Adding runtime EKS or RDS management calls also requires their Max adapters; the first two rows describe workloads that only use the provisioned cluster or database.
You can reduce the required tier by removing or replacing a service that needs Max. An optional alerting topic may be a reasonable tradeoff; a database central to the application may not be. Changes to the origin stack affect every customer deployment, so assess that choice for the whole application.
Declaring IAM roles and policies does not by itself require Max. At Infrastructure only, Tensor9 BYOC translates them into the target cloud's permissions at build time. Those permissions can be broader than the original AWS policies. See [AWS IAM](/byoc/service-adapters/aws/security-identity/aws-iam) for the differences between native permission translation and runtime authorization.
To see what your own stack does before deploying it, compile it: [`tensor9 compile`](/byoc/cli/reference#compile)
bundles your Terraform, compiles it for a target, and reports every issue by severity without provisioning
anything. A service with no equivalent on the target, or an IAM construct that cannot be adapted, is reported
as Blocking there rather than at release time. It writes the same issues to `/.tensor9/compile.json`, so a CI
job can fail on them.
Send us your origin stack and target cloud, and we will report its tier and the services that determine it. Selecting a tier yourself and previewing the resulting deployment is **(private beta)**.
## How Tensor9 BYOC adapters work
A service adapter is a small server that runs inside your customer's appliance, in their cloud account or private environment. There is one adapter per service your application uses: a DynamoDB adapter, an S3 adapter, and so on. Each one serves the origin cloud's API for that service alone. Tensor9 BYOC points your application's SDK at the adapter, so those calls reach it inside the appliance instead of the origin cloud, with no change to your code. The adapter authenticates supported origin-cloud requests, translates them into target operations and returns the response format the client expects.
For an S3 request on Google Cloud, the objects live in the customer's Cloud Storage bucket. For an adapter built on a database, the database stores the service's records in a schema managed by the adapter. The service page explains which resources hold the data and who operates them.
Management operations can take time. An adapter may record a requested change, create or update native resources, and report progress through subsequent API reads. The service's operation table describes which calls are supported and where the target behaves differently.
Supported API-compatible mappings keep the application's existing client libraries. Some mappings require a different client or offer only part of the origin service's behavior; their pages state those differences. The adaptation tier describes the runtime components involved, not a guarantee that every operation is equivalent.
At Max, cloud API calls depend on the adapter as well as the backing service. That does not put every database query or network packet through the adapter. Each service's architecture explains the request paths it handles.
## Tune an adaptation
Some service mappings accept tuning tags on origin API requests. These tags express supported target-native choices without replacing your application's origin API. Accepted fields and update behavior depend on the service and target; a create-time tag is not automatically a per-request override.
Use a test appliance matching the relevant customer form factor, verify the resulting target settings and measure the workload before adopting a change. See [Tuning Service Adapters](/byoc/service-adapters/tuning/overview) for the shared mechanism and examples.
## Debug an adapter request
Capture the origin operation, selected backend, deployed version, error and response identifiers. Diagnostic headers can help correlate a request or describe a specific failure's effects, but a missing header does not prove that nothing was written.
The [debugging guide](/byoc/service-adapters/debugging/overview) explains response headers, safe test-appliance reproductions and bounded investigations with coding agents.
## Behavior under load
An adapted call keeps its API. It does not inherit the origin service's behavior, and the differences that
matter appear under load rather than in a first test: consistency models, transaction isolation, index
requirements, rate limits, message-size ceilings and what happens to a hot key.
Each service page states these where they diverge, in two places:
* **How the targets compare** puts each capability against every target, one row at a time. Read consistency,
durability, transaction scope, index types and hard limits are rows here.
* **Limitations**, inside each target's section, covers what the comparison table cannot hold in a cell: the
concurrency behavior, the operations that decline and why, and the workload shapes to size before you
adopt.
The [DynamoDB](/byoc/service-adapters/aws/databases-storage/dynamodb) page is the fullest example.
Its Firestore section records that reads are always strongly consistent, which is stronger than DynamoDB's
eventually-consistent global secondary indexes, and that an undeclared index returns a validation error
rather than falling back to a table scan. Neither is visible from the operation list.
Not every page is written to that depth. A page carrying a **How the targets compare** table has these rows;
a page without one has not been written to that depth yet, which is not a statement that nothing diverges
for that service. Ask us about a service whose page is thin and you need the answer for.
### What the adapter costs
Where a service has been benchmarked, its page carries what the adapter itself adds to a request, separately
from what the backing store costs, under **What the adapter adds** in that target's section.
Measured today: [DynamoDB to Cloud Spanner](/byoc/service-adapters/aws/databases-storage/dynamodb#what-the-adapter-adds),
where the adapter's own work is 0.089 ms p50 against a 4.029 ms Spanner round trip. Those two numbers are
not the whole read: the same measurement spends about 1.24 ms on HTTP framing, the driver and the loopback
hop, which exists because the call now goes to an adapter. Translating a call is nearly free; reaching the
adapter is not. The figure is also one operation shape at concurrency 1, so read it as the in-path cost of
translation rather than as throughput guidance, and take the throughput and tail-latency numbers from the
same page's benchmark section.
No other edge has a published adapter-overhead figure yet, and there is no published guidance on sizing an
adapter's CPU and memory inside your appliance. Both are open, and both are worth asking us about if you are
planning a high-throughput workload.
## Find an adaptation
Compare service mappings, adaptation tiers and target clouds.
The [Service Catalog](/byoc/service-adapters/catalog#services-we-do-not-adapt-yet) also lists services we do not adapt yet. If a mapping you need is absent, [tell us about your use case](https://www.tensor9.com/contact/).
## Terms used here
* **[Origin stack](/byoc/fundamentals/origin-stacks)**: the infrastructure configuration your application starts with, such as Terraform, CloudFormation, Helm or Docker Compose.
* **[Appliance](/byoc/fundamentals/appliances)**: the system Tensor9 BYOC deploys into the customer's cloud or private environment.
* **Service adapter**: the runtime component that answers supported origin-cloud API calls, one per service, running beside your application in the customer's environment.
* **Customer**: the organization hosting your software in its own infrastructure.
* **Vendor**: you, the software vendor defining the application, its origin stack and the target environments you offer to customers.
## Related topics
* [Deployments](/byoc/fundamentals/deployments): how compilation uses service adapters
* [Form factors](/byoc/fundamentals/key-concepts#form-factor): which services an environment can provide
* [Appliances](/byoc/fundamentals/appliances): what gets deployed into the customer's environment
* [How Tensor9 BYOC works](/byoc/fundamentals/how-tensor9-works): how Tensor9 BYOC prepares and deploys an application
