Version: V3.2

Environment Migration Overview

This section describes how devices are moved from one Capture environment to another without reconfiguring or physically touching the device.

The typical reasons to migrate:

moving from an older Capture Cloud production environment to the current one
moving from Capture Cloud to a customer-owned environment (for example your own Azure tenant)

Two environments, one procedure

Migration always spans two environments: the source, where the devices are today, and the target, where they are going. Prepare and verify the target first, then switch devices over one at a time — see the runbook.

The idea: the source environment becomes a proxy

Instead of asking every device to change its endpoint, credentials, and configuration at once, the source environment's Data API is extended to act as a migration proxy.

Each device carries a Migration target that decides where its incoming data goes:

Migration target	What happens to incoming data	What the device gets back
OldOnly (default)	Written to the source environment only. Nothing is forwarded.	The source environment's normal response.
Both	Written to the source environment and forwarded to the target environment, concurrently.	The source environment's response. Forwarding problems never affect it.
NewOnly	Forwarded to the target environment only. The source pipeline is skipped entirely — no time-series write, no blob offload, no message-bus publish.	The target environment's response, relayed verbatim.

Because the device keeps posting to the same URL with the same credentials, migration becomes a switch you flip per device — and can un-flip.

                            SOURCE ENVIRONMENT
                 ┌──────────────────────────────────────┐
                 │                                      │
  Edge gateway   │   Migration      ┌───────────────┐   │
   or sender ────┼──▶  target?  ──▶ │ Local pipeline│   │
                 │       │          │ TSDB / blob   │   │
 POST data to    │       │          │ / message bus │   │
 the unchanged   │       │          └───────────────┘   │
 endpoint        │       │            ▲   ▲             │
                 │       │   OldOnly ─┘   └─ Both       │
                 │       │                              │
                 │       └── Both / NewOnly ──▶ Proxy ──┼──┐
                 └──────────────────────────────────────┘  │
                                                           │
                        TARGET ENVIRONMENT                 │
                 ┌─────────────────────────────────────┐   │
                 │  AuthServer  ◀── 1. log in as the ──┼───┤
                 │      │           device             │   │
                 │      ▼                              │   │
                 │  Data API    ◀── 2. forward the ────┼───┘
                 │                  raw request with   │
                 │                  the target's token │
                 └─────────────────────────────────────┘

What is forwarded, exactly

The proxy is deliberately dumb — it relays the request rather than re-encoding it.

Data inserts only. POST ingest requests are proxied. Reads are not (see the warning below).
The raw body, byte for byte. No payload transformation, no re-compression. Compressed and binary payloads pass through untouched.
The full path and query string, including parameters such as ?Database=…&Retention=….
A restricted set of headers: AuthVersion, DataVersion, DataType, Content-Type and Content-Encoding. Everything else is stripped, and Host is replaced with the target's, so no internal infrastructure headers of the source environment can leak into your environment.

Authentication is re-established, not relayed

The device's original credential is not forwarded. The target environment cannot validate a credential minted by the source environment, and those credentials must never leak into a customer-owned environment.

Instead, the proxy logs in on the target environment's AuthServer as the device and forwards the request with the token that environment issued itself:

The proxy posts the device's username (its Activation UID) and password to the configured Forwarding auth endpoint.
The returned token is cached per device until shortly before it expires (60 seconds of margin).
The forwarded request carries Authorization: Bearer <target-environment token>.
If the target answers 401, the proxy discards the cached token, logs in again once, and retries.

This is why credentials must match

The device must already exist in the target environment with the same Activation UID and the same password. Provisioning it is a prerequisite, not something the migration performs for you — see Prepare the target environment.

Failure behaviour

Forwarding is protected by a circuit breaker per target endpoint, so a target environment having a bad day can never slow down or break the source environment.

After 5 consecutive forwarding failures the circuit opens and forwarding is skipped outright — no waiting, no retries.
After 60 seconds it probes again and closes automatically once the target recovers.
The forwarding HTTP client times out after 30 seconds.
Breakers are isolated per forwarding endpoint URL, so one customer's outage does not affect forwarding for anyone else.

What this means per mode:

Both — forwarding failures are logged and swallowed. The local write and the device's response are unaffected. This is the safe mode: you can leave a device here indefinitely.
NewOnly — there is no local fallback. If the forward cannot be completed (circuit open, timeout, network error) the device receives HTTP 503, and edge gateways apply their normal retry and buffering behaviour.

Reads stay on the source environment

Only inserts are proxied. Data queries continue to be answered by the source environment regardless of migration target. A device on NewOnly therefore writes exclusively to the target environment, while dashboards, reports and API reads on the source environment stop seeing new data for it.

Plan the switch to NewOnly together with repointing the device and its data consumers to the target environment. During Both, both environments answer reads correctly.

How quickly a change takes effect

Changing a migration target is not instantaneous — routing is cached to keep the high-volume ingest path fast.

Device authentication	Propagation
Token-based login (normal edge gateways)	Within about 2 minutes (routing cache TTL, default 120 s).
API token (external connections)	On the device's next request — the cached validation entry is invalidated immediately when the setting changes.

Requests made by users and administrators are never migrated; they always behave as OldOnly.

Scope

Covered

Per-device routing of data inserts between two environments
Dual-write during the transition, with verification before cutover
A separate target endpoint per company, including customer-owned environments

Not covered

Bulk operations — migration targets are set per device
Migration of historical data already stored in the source environment
Migration of configurations, UNS models, dashboards, reports or alerts
Data reads (see the warning above)
Blob offload while a device is on NewOnly
Automated rollback (rollback is manual: set the target back to Both or OldOnly)

Follow the Device Migration runbook for the step-by-step procedure.

The idea: the source environment becomes a proxy​

What is forwarded, exactly​

Authentication is re-established, not relayed​

Failure behaviour​

How quickly a change takes effect​

Scope​

Next​