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

> Author, review and promote Cloud Adapter configuration without repeating catalog mappings.

A configuration file is the durable description of one Cloud Adapter installation. It records the cloud direction, shared target coordinates, deployment settings and the exceptional service configuration that must exist before startup.

It is deliberately compact. You do not need to list every origin service or repeat every compatible origin-to-backend mapping from the service catalog.

## The compact configuration model

For an AWS-origin installation in Google Cloud, the core file is:

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

This file means:

* expose AWS APIs that have a compatible Google Cloud backend in the service catalog;
* use `acme-adapters-prod` and `us-central1` as shared target coordinates;
* select the only compatible backend automatically when one exists;
* let an origin resource-creation request select among multiple compatible backends where the public directed profile provides a selector;
* keep `svcs` empty unless a service needs an actual override or a pre-provisioned dependency.

It does **not** mean that all AWS APIs are supported, that all operations in an exposed API are supported, or that credentials live in this file.

## Field reference

| Field | Meaning | Review question |
| - | - | - |
| `schemaVersion` | Configuration contract understood by the runtime | Does the installed adapter release support this version? |
| `origin` | Cloud API family presented to applications | Does it match the SDKs and tools the workload uses? |
| `target` | Cloud whose compatible backends may be selected | Does it match the deployment and data-residency decision? |
| `targetConfig` | Shared, non-secret target coordinates | Are the project, subscription, resource group and region correct for this environment? |
| `svcs` | Sparse service-specific overrides and prerequisite bindings | Does each entry exist for a concrete reason, rather than restating the catalog? |
| Secret references | Names of secret-backed values resolved by the deployment | Is each reference present, narrowly accessible and free of literal secret material? |

> [!NOTE]
>
> Use the fields documented for the installed release. Do not copy an internal or older configuration shape that declares every service-to-backend pair. Current origin-and-target configuration derives normal mappings from the catalog.

## When `svcs` should be empty

Leave `svcs` empty when all of the following are true:

* the installation's `origin` and `target` identify the required direction;
* the catalog provides a compatible backend for the origin service;
* the backend does not require a service-specific resource or secret to exist before startup;
* resource-level backend selection, if needed, is carried by the origin create request;
* installation-wide target coordinates are sufficient.

S3 to Google Cloud Storage is the canonical example. The installation selects AWS and Google Cloud, and the runtime identity supplies access to Cloud Storage. There is no value in an empty S3 row that merely repeats the catalog edge.

## When to add a service entry

Add a sparse service entry when the adapter cannot become ready from the installation settings alone. The common case is pre-provisioned state.

For example, an SQS implementation backed by Cloud SQL needs a PostgreSQL database and a secret-backed connection binding before it can serve queue operations. Its service entry records only the exceptional inputs. It does not turn `svcs` back into a list of enabled APIs.

A service entry should answer:

1. Which origin service needs additional configuration?
2. Which resource was provisioned for it, and who owns that resource?
3. Which non-secret coordinates can be stored directly?
4. Which secret keys must be resolved at runtime?
5. What health check proves the dependency is usable?
6. What happens to the service and its data when that dependency changes?

If an entry cannot answer one of those questions, it is probably incomplete.

## S3 to Google Cloud Storage file

Use the compact cloud-direction file for the normal S3 to Cloud Storage case:

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

Keep the surrounding deployment record with it:

| Decision | Example production value | Why it is separate from the JSON |
| - | - | - |
| Adapter runtime identity | `cloud-adapter-prod@acme-adapters-prod.iam.gserviceaccount.com` | Identity is attached by the deployment platform, not stored as a key in the file. |
| Allowed target buckets | `acme-orders`, `acme-reports` | Permissions belong in Google Cloud IAM and can be audited independently. |
| Origin-facing bucket names | `orders`, `reports` | These are application-facing resource names and may differ from native names. |
| Client endpoint | `https://s3.adapter.prod.internal` | The application configures this after the endpoint is healthy. |
| Verification identity | `adapter-verifier@acme-adapters-prod.iam.gserviceaccount.com` | A separate read-only observer checks native state. |

Read [S3 on Google Cloud](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/databases-storage/s3.md#on-google-cloud) before approving the file. The configuration selects the direction; the service profile defines the behavior available in that direction.

## DynamoDB to Azure file and resource configuration

An AWS-origin installation in Azure starts with installation-wide target coordinates:

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

Do not add a service row merely to choose a resource-level backend or capacity. The file selects the
deployment context; supported resource directives select and size an individual resource. Read their exact
names, values, and verification steps in the public directed profile, then confirm entitlement before running the adapter.

## Keep environment files independent

Use a complete file per installation rather than a production file assembled from a long chain of implicit overlays.

```text theme={null}
cloud-adapter/
  development.json
  staging.json
  production.json
  README.md
```

The files may share a generated source, but each reviewed artifact should make its effective origin, target and coordinates obvious. A reviewer should not need shell state or an undocumented merge order to determine where an installation sends data.

Good differences between environments include project or subscription, region, resource names, capacity choices and secret reference names. Avoid changing the basic service semantics between staging and production unless that difference is intentional and tested.

## Keep secrets out of the file

Store references, not values. Never put any of the following in the configuration repository:

* PostgreSQL connection strings;
* cloud access keys or service-account JSON;
* client secrets, bearer tokens or signed URLs;
* private keys or certificate key material;
* captured authorization headers.

For a pre-provisioned service, the file should identify the secret entry that the deployment resolves. The runtime receives the resolved value through the deployment's protected secret channel. A redacted review should still show which service consumes which secret and why.

> [!WARNING]
>
> A value named `POSTGRES_DSN` in a literal configuration map is still a secret, even if the file format accepts strings. Put it in the supported secret-reference map. Renaming a secret does not make it safe to commit.

## Review a file before applying it

**1. Confirm the cloud direction**

Check `origin`, `target` and target coordinates against the intended environment. A wrong project or subscription can produce a valid deployment in the wrong place.

**2. Compare the workload with the catalog**

List the origin services and operations the application uses. Open each service profile for the selected target and record unsupported or conditional behavior.

**3. Remove redundant service rows**

For every `svcs` entry, identify the prerequisite or override it carries. Remove entries that only repeat an automatically derived catalog mapping.

**4. Review pre-provisioned dependencies**

Confirm ownership, region, network reachability, identity, backup, recovery, capacity and secret references for every database or coordination store needed before startup.

**5. Inspect the identity boundary**

Separate the origin-facing caller identity, target runtime identity and native verification identity. Review least-privilege permissions for each.

**6. Diff against the installed configuration**

Review the effective file, not only the edited fragment. Highlight changes to cloud coordinates, service prerequisites, secret references and persistent data paths.

**7. Validate before effects**

Run the installed release's configuration validation and inspect the proposed resources and warnings. A parse success is not a deployment approval.

## Preserve three artifacts

Keep these records for each installation:

1. **Desired configuration:** the reviewed input you intended to apply.
2. **Applied configuration:** the exact validated configuration accepted by the deployment workflow.
3. **Deployment receipt:** the version, resource changes, outcome and endpoint produced by the operation.

They answer different questions. A desired file explains intent. The applied file explains what the runtime accepted. The receipt explains what the operation actually changed.

## Configure the client after the endpoint is ready

The installation file does not automatically redirect an application. After health checks pass, configure only the native client that should use the adapter.

Process-wide S3 route:

```bash theme={null}
export AWS_ENDPOINT_URL_S3="https://s3.adapter.prod.internal"
```

Single Python client:

```python theme={null}
import boto3

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

Keep a rollback that restores the previous endpoint. Do not move production traffic until a bounded request has succeeded through the origin API and been verified through the target's native API.

## Common mistakes

| Mistake | Why it fails | Better choice |
| - | - | - |
| Listing every service-to-backend mapping | It duplicates the catalog and becomes stale | Declare origin and target once; add only sparse prerequisite overrides |
| Putting a backend on every `svcs` row | Current origin-target configuration selects compatible backends from the catalog | Use a resource-level selector documented in the directed profile where supported, or a prerequisite block |
| Storing a DSN in a normal string map | The secret can reach source control, logs or rendered plans | Store a secret reference and resolve it at runtime |
| Treating a valid file as proof of deployment | Validation cannot prove cloud effects or health | Retain the deployment receipt and run a bounded smoke test |
| Changing target coordinates in place | The same logical resource name may now resolve elsewhere | Treat it as a data and traffic migration |
| Redirecting all AWS traffic | Discovery or unsupported services may hit the adapter | Use the service-specific endpoint variable or client option |

Continue to [guided configuration](https://docs.tensor9.com/cloud-adapter-early-access/configuration/guided-setup.md) to produce the same file interactively, or use the [worked examples](https://docs.tensor9.com/cloud-adapter-early-access/configuration/examples.md) to test the resulting route.


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