Configuration Files

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:

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

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:

Which origin service needs additional configuration?
Which resource was provisioned for it, and who owns that resource?
Which non-secret coordinates can be stored directly?
Which secret keys must be resolved at runtime?
What health check proves the dependency is usable?
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:

{
  "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	`[email protected]`	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	`[email protected]`	A separate read-only observer checks native state.

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

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

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.

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

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.

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.

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.

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.

Inspect the identity boundary

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

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.

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:

Desired configuration: the reviewed input you intended to apply.
Applied configuration: the exact validated configuration accepted by the deployment workflow.
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:

export AWS_ENDPOINT_URL_S3="https://s3.adapter.prod.internal"

Single Python client:

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 to produce the same file interactively, or use the worked examples to test the resulting route.

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

Configuration Files

The compact configuration model

Field reference

When `svcs` should be empty

When to add a service entry

S3 to Google Cloud Storage file

DynamoDB to Azure file and resource configuration

Keep environment files independent

Keep secrets out of the file

Review a file before applying it

Preserve three artifacts

Configure the client after the endpoint is ready

Common mistakes

​The compact configuration model

​Field reference

​When svcs should be empty

​When to add a service entry

​S3 to Google Cloud Storage file

​DynamoDB to Azure file and resource configuration

​Keep environment files independent

​Keep secrets out of the file

​Review a file before applying it

​Preserve three artifacts

​Configure the client after the endpoint is ready

​Common mistakes

The compact configuration model

Field reference

When `svcs` should be empty

When to add a service entry

S3 to Google Cloud Storage file

DynamoDB to Azure file and resource configuration

Keep environment files independent

Keep secrets out of the file

Review a file before applying it

Preserve three artifacts

Configure the client after the endpoint is ready

Common mistakes