> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan your data planes

> Decide how many data planes to run and which data tags each one serves before you deploy

export const Alert = ({type, title, children}) => {
  const variant = ["info", "success", "warning", "danger", "note"].includes(type) ? type : "note";
  return <div className={`alert alert--${variant}`}>
      <div className="alert-icon" />
      <div className="alert-content">
        {title && <div className="alert-title">{title}</div>}
        <div className="alert-body">{children}</div>
      </div>
    </div>;
};

Most Hybrid customers run **two data planes**: one serving the `dev` data tag for Edit and Preview, one serving `production` for Production. Decide whether that fits you before you deploy anything.

<Alert type="info" title="Data plane, On-Premise Agent, OPA, and agent are the same thing">
  <ul>
    <li><strong>Data plane</strong> is the name used in these docs.</li>
    <li><strong>On-Premise Agent</strong> or <strong>OPA</strong> is the original name. The admin page that lists your data planes is still <a href="https://app.superblocks.com/opas">app.superblocks.com/opas</a>.</li>
    <li><strong>Agent</strong> is the name in configuration: <code>superblocks\_agent\_tags</code> in Terraform, <code>superblocks.agentTags</code> in Helm, <code>SUPERBLOCKS\_AGENT\_TAGS</code> in Docker.</li>
  </ul>

  <p>
    <strong>Data tags</strong> were previously called <strong>profiles</strong>, and the agent tag format still uses the <code>profile:</code> prefix: <code>profile:production</code> serves the data tag whose key is <code>production</code>.
  </p>
</Alert>

## Environments and data tags

Every Superblocks application moves through three built-in environments:

| Environment    | What happens there                          |
| -------------- | ------------------------------------------- |
| **Edit**       | Developers and Clark build and test the app |
| **Preview**    | Changes are reviewed before going live      |
| **Production** | The published app runs                      |

Environments are fixed. Data tags control which data each one can reach. A **data tag** names a segment of your data; admins create tags on the [Environments](https://app.superblocks.com/environments) page and choose which environments each tag is allowed in. Your account starts with **Development** (key `dev`) and **Production** (key `production`).

A data tag is attached to two things:

1. **Integration configurations.** Each integration can have several configurations (different hosts, credentials, or databases), each linked to one or more data tags.
2. **Data planes.** Each data plane advertises the data tags it serves through its agent tags setting.

When an app runs an API, its environment determines the active data tag. That tag selects both the integration configuration that supplies the credentials and the data plane that executes the code.

```mermaid theme={null}
flowchart LR
  Edit --> DevTag["Data tag: dev"]
  Preview --> DevTag
  Production --> ProdTag["Data tag: production"]
  DevTag --> DevPlane["Development data plane<br/>profile:dev"]
  ProdTag --> ProdPlane["Production data plane<br/>profile:production"]
```

## How data planes match data tags

The agent tags setting is a comma-separated list of `profile:<key>` entries:

* `profile:production` serves one data tag.
* `profile:dev,profile:staging` serves two.
* `profile:*` serves every data tag. It is the default and fine for a first test deployment, but it gives you none of the separation described below and stops working when you enable Superblocks Database.

Two rules follow:

* **Every data tag you use must be served by a data plane.** Hybrid requests never fall back to Superblocks Cloud. If no active data plane serves the active tag, the API fails with `Unable to connect to on-premise agent(s)`.
* **Replicas are not separate data planes.** Three instances behind one load balancer are one data plane with one set of agent tags; that is how you [scale](/enterprise/hybrid-architecture/manage/scaling_and_high_availability). Add a data plane only when you need a different network, account, or set of data tags.

## The recommended setup

| Data plane  | Agent tags           | Serves environments | Runs in                                 |
| ----------- | -------------------- | ------------------- | --------------------------------------- |
| Development | `profile:dev`        | Edit, Preview       | Your pre-production AWS account and VPC |
| Production  | `profile:production` | Production          | Your production AWS account and VPC     |

This puts a hard boundary between the data builders and Clark touch while building and the data your published apps touch. For each integration, then decide:

* **The data source has a pre-production instance** (a staging database, a sandbox tenant of an internal API): create one configuration for `dev` that points at it and one for `production`.
* **The data source has no pre-production instance** (most SaaS tools, data warehouses): one configuration linked to both tags is enough.

### Sharing a third-party configuration between dev and production

Integration configurations are stored in the control plane, not on a data plane, so a configuration linked to both `dev` and `production` is delivered to whichever data plane runs the request. Both data planes reach Salesforce, Jira, or any other SaaS over outbound HTTPS; nothing crosses the account boundary.

A shared configuration is the deliberate exception to "test data never reaches production," so the decision is what builders and Clark can do to that system from Edit and Preview. Three options, from simplest to most isolated:

| Option                                                   | When to use it                                                                                                                          |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| One configuration, both tags                             | Read-mostly integrations, or when the SaaS has no sandbox and you accept that Edit sees live data                                       |
| Two configurations, same instance, scoped user for `dev` | Same tenant, but the `dev` configuration authenticates as a read-only or limited user so building cannot create real tickets or records |
| Two configurations, separate instances                   | The vendor offers a sandbox (Salesforce Sandbox, Jira test site); point `dev` at it                                                     |

The data plane split is the same in every case. Only the credentials attached to each tag differ.

## Next steps

<CardGroup cols={3}>
  <Card title="Reference architectures" icon="sitemap" href="/enterprise/hybrid-architecture/plan/architectures">
    The recommended two-account AWS layout, and when to add more data planes or tags.
  </Card>

  <Card title="Superblocks Database" icon="database" href="/enterprise/hybrid-architecture/plan/superblocks-database">
    How data planes and data tags decide where each app's database lives.
  </Card>

  <Card title="Deploy a data plane" icon="rocket" href="/enterprise/hybrid-architecture/deployment/index">
    Prerequisites and deployment methods for AWS, GCP, Azure, and Kubernetes.
  </Card>
</CardGroup>