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

# Guided Configuration

> Generate and review Cloud Adapter configuration in the terminal.

Guided configuration asks the same questions represented in a [configuration file](https://docs.tensor9.com/cloud-adapter-early-access/configuration/files.md), validates each answer and writes a reusable file. It is useful when you are configuring a cloud direction for the first time or want the terminal to enumerate available choices from the service catalog.

It does not create a separate configuration format, and it does not require an AI agent.

## Prepare before starting

Bring these decisions to the guided flow:

| Decision | What to know |
| - | - |
| Origin cloud | The SDK and API family the application already uses |
| Target cloud | Where the adapter and target services will run |
| Target coordinates | Project or subscription, resource group, region and network |
| Workload surface | Origin services, operations and resource features the application depends on |
| Runtime identity | The target-cloud principal the adapter will use |
| Existing resources | Buckets, databases, namespaces and key rings that may be reused |
| Pre-provisioned dependencies | Databases or coordination stores that must exist before an adapter can start |
| Secret references | Names and keys of secrets, never the secret values themselves |
| Verification path | A native tool and preferably read-only identity for checking target state |

Do not begin by choosing a backend name from memory. Begin with the origin service and open its catalog page for the selected target.

## Run the guided flow

**1. Choose the origin and target clouds**

Select the API family the application uses and the environment where Cloud Adapter will run. The generated file records this once rather than declaring every service mapping individually.

For the S3 example, choose **AWS** as the origin and **Google Cloud** as the target. For the DynamoDB example, choose **AWS** and **Microsoft Azure**.

**2. Enter shared target coordinates**

Supply the project or subscription, region and any target-wide resource group or network selection. Review these values character by character. A valid but incorrect project is still an incorrect deployment.

These are non-secret coordinates. Let the deployment use its standard cloud identity mechanism instead of pasting a key into the terminal.

**3. Review the discovered API surface**

The guided flow resolves services from the origin-to-target catalog. It should show which origin APIs have compatible target backends and which do not.

Do not add empty service entries for the discovered mappings. For every API your application uses, read the public directed profile to check the behavior your workload needs. Authenticate and use `tensor9 explain` when checking the direction available to your account.

**4. Configure pre-provisioned services**

Answer additional questions only for services that require resources or bindings before startup. Supply database coordinates, namespaces and secret references where the selected mapping documents them.

For example, an SQS adapter backed by Cloud SQL needs a provisioned PostgreSQL database and a protected DSN binding. S3 backed by Cloud Storage normally does not need an equivalent service-specific declaration.

**5. Review resource-level choices**

Identify choices that belong to an origin resource request rather than the installation file. A DynamoDB table's provisioned Cosmos DB selection and autoscale maximum belong to `CreateTable` tags, so record the intended values in the review without turning them into installation-wide defaults.

**6. Review identity and network access**

Confirm the origin-facing identity, target runtime identity and verification identity separately. Check the endpoint's intended callers, TLS name, ingress policy and path to each target dependency.

**7. Inspect the generated file**

Read the final JSON before proceeding. Confirm that the cloud direction appears once, service entries are sparse, secret references contain no values and target coordinates identify the intended environment.

**8. Save without applying**

Store the generated file where it can be reviewed. Saving the file does not provision resources or change a running adapter.

## Example: AWS to Google Cloud

For an installation that will serve S3 through Google Cloud Storage, the guided answers should reduce to a compact file like this:

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

The review summary should also identify, outside the file:

* the runtime service account;
* the target test bucket and allowed storage operations;
* the internal endpoint name and callers allowed to reach it;
* the origin-facing bucket name used by the test;
* the native verification identity and cleanup owner.

There should be no empty S3 service row. The AWS-to-Google-Cloud direction and service catalog already identify Cloud Storage as a compatible S3 backend.

After saving the file, use the [S3 to Cloud Storage worked example](https://docs.tensor9.com/cloud-adapter-early-access/configuration/examples.md#s3-to-google-cloud-storage) to verify one object lifecycle.

## Example: AWS to Azure with DynamoDB

For DynamoDB backed by provisioned Cosmos DB, the guided installation answers identify the Azure environment:

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

Table-specific backend and capacity decisions remain with the resource-creation request. The guided flow
must use the exact directive names and accepted values in the public profile for the directed adapter.
Confirm entitlement, regional availability and workload measurements before approving a production
capacity choice.

## Read the generated summary as a reviewer

The summary should make these differences visible:

| Question | Installation answer | Resource or service answer |
| - | - | - |
| Where does this run? | Google Cloud project or Azure subscription, region and network | Not repeated per ordinary mapping |
| Which origin APIs may be exposed? | Derived from the origin, target and service catalog | Service page limits still apply |
| Which backend serves a resource? | Automatic when only one compatible choice exists | Documented resource-level selector when several choices exist |
| Which state must already exist? | Listed as a deployment prerequisite | Sparse service entry and secret reference for the affected service |
| How large is a Cosmos container? | Not an installation-wide default | Mapping-specific tuning tag on `CreateTable` |
| Where does the application send calls? | Endpoint produced by the deployment | Native client endpoint configuration after health succeeds |

If the generated summary lists dozens of service rows that carry no configuration, stop and check whether an older configuration shape is being used.

## Existing resources need explicit ownership

When the guided flow offers an existing resource, record:

* its full native identifier;
* who owns deletion, backup, restore and capacity;
* whether the adapter may create logical resources inside it;
* whether it already contains data;
* which identity can access it;
* how the mapping separates this installation from other tenants or environments.

Selecting an existing database is not permission to replace it, migrate its contents or relax its access policy.

## Handle validation failures

| Failure | What to check |
| - | - |
| No compatible backend | Confirm the origin service name and target; then read the service catalog rather than forcing a row |
| Ambiguous resource backend | Select a documented backend on the origin create request |
| Missing pre-provisioned resource | Provision or bind the required database, namespace or coordination store before continuing |
| Secret value detected | Remove it and enter a supported secret reference instead |
| Region or project mismatch | Correct the target coordinates before any cloud effects |
| Existing resource conflict | Confirm ownership and use a distinct resource or an explicit migration plan |
| Unsupported configuration transition | Keep the running configuration unchanged and plan the required migration |

Validation errors should remain visible in the generated review. Do not convert a blocked service to an unrelated backend merely to produce a file.

## Keep the generated file

Preserve the generated file as the input to deployment and later [configuration transitions](https://docs.tensor9.com/cloud-adapter-early-access/configuration/overview.md#treat-changes-as-transitions). Commit the non-secret file after review, retain the exact applied version and keep the deployment receipt beside the release record.

The file-based and guided paths must converge on the same validation rules. You can generate interactively once, then promote reviewed environment-specific files through automation.

## Verify after deployment

The guided flow ends at configuration. Deployment and traffic verification are separate steps:

1. provision the installation and its declared prerequisites;
2. confirm runtime health and endpoint TLS;
3. route only the test service client to the endpoint;
4. run one bounded origin request;
5. inspect the target natively;
6. use [Explain](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain.md) when the mapping or error source is unclear;
7. clean up only the test resource.

Continue to [worked configuration examples](https://docs.tensor9.com/cloud-adapter-early-access/configuration/examples.md) for complete S3 and DynamoDB flows.


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