Ignition 8.3 scale-out deployment starts with a repository commit, passes through a deployment pipeline, and terminates at one selected Gateway configuration. The central design decision is whether a difference describes an environment or identifies a Gateway. Treat environment differences as deployment-mode candidates; treat different device inventories as instance configuration unless a tested instance-profile pattern provides the required isolation.
Where Does the Deployment Request Travel?
Follow the configuration from authoring to runtime before choosing a repository layout. An engineer commits shared automation, projects, tags, UDTs, scripts, and device definitions. The pipeline selects an environment and target Gateway, transfers or mounts the applicable files, activates the selected configuration, and then checks the running Gateway.
| Path element | Selection it must make | Reading to capture | Failure indication |
|---|---|---|---|
| Git repository | Commit and configuration subtree | Commit identifier and changed paths | Unrelated Gateway configuration appears in the change set |
| Deployment pipeline | Environment and Gateway identity | Resolved target, source path, and variables | One environment label selects several asymmetric targets without an instance discriminator |
| Network path | Destination address and service | Resolved address, configured port, and connection result | The job cannot reach the intended Gateway or reaches another instance |
| Gateway filesystem/configuration layer | Base files plus applicable overrides | Rendered file set or configuration diff | Files from another Gateway are present or required files are absent |
| Runtime services | Active device and database endpoints | Gateway status, connection state, and diagnostic messages | The deployment completes but runtime connections point to the wrong endpoints |
The pipeline must answer two independent questions: which environment is being deployed, and which Gateway receives it. A single TEST or PROD selector answers only the first. In the described topology, five production backends and two test backends have different device connections, so Gateway identity must remain explicit somewhere in the path.
Does the Physical Path Reach the Intended Gateway?
Layer one first. Repository design cannot correct a pipeline that resolves the wrong address, mounts the wrong directory, or cannot reach the configuration service. Before investigating modes, run the deployment job's normal connectivity check from its execution context and record the actual destination rather than the human-readable job name.
- Resolve the target Gateway name to an address from the pipeline runner.
- Compare that address with the deployment inventory for the selected instance.
- Test the configured management or configuration service port. Read the port from the Gateway or pipeline configuration; no port value is specified here.
- Record the connection timeout and retry settings from the job definition. A transport timeout is a path problem, not a deployment-mode problem.
- Confirm that any mounted repository path maps to the intended Gateway and instance subtree.
| Symptom | Likely stopping point | Next reading |
|---|---|---|
| Connection timeout | Name resolution, routing, firewall, or service listener | Resolved address and port reachability from the runner |
| Deployment succeeds on the wrong Gateway | Pipeline target selection | Resolved target identifier and destination address |
| Correct Gateway receives another instance's devices | Repository subtree or mode selection | Rendered configuration and selected profile |
| Shared scripts update but local devices do not | Composition or path filtering | Changed paths, included paths, and activation result |
| Files look correct but connections fail | Runtime endpoint substitution or credentials | Effective endpoint values and Gateway diagnostics |
Is Each Difference Environmental or Instance-Specific?
Take an inventory diff between two Gateways that perform the same role. Classify each changed field before selecting a mechanism.
| Difference | Classification | Preferred control point |
|---|---|---|
| Same logical connection with a test endpoint instead of a production endpoint | Environment-specific | Deployment mode or external variable, according to the supported configuration field |
| Different device inventory because each backend owns different equipment | Instance-specific | Gateway-specific configuration selected by the pipeline |
| Identical global logic and scripts | Shared | Common repository path deployed to all applicable backends |
| Frontend Perspective resources | Gateway-role-specific | Frontend path or frontend repository boundary |
| Credentials or values that must not be committed | Secret or runtime-specific | Approved external secret or environment mechanism |
Use a direct decision rule: if two Gateways would still differ after both were placed in the same environment, the difference is instance-specific. Backend A and Backend B retain different device connections in production, so PROD alone cannot select the correct inventory. Conversely, a single logical backend promoted from test to production can use a deployment mode for differences caused by that promotion.
This classification also exposes the risk in creating seven modes named prod-backend-1 through prod-backend-5 and test-backend-1 through test-backend-2. Those names combine environment and identity into one selector. The pattern can work when each profile is complete and the active profile is controlled, but every new Gateway or environment multiplies the profiles and review paths.
Which Git Boundary Keeps Changes Atomic?
A monorepo is the simpler default when the same team owns the shared automation and Gateway configurations. It lets one commit update a UDT, its scripts, related tags, and the consuming project together. Separate repositories for tag definitions, UDTs, a global project, scripting, and Perspective split a single functional change across commit histories and require explicit version coordination.
Repository boundaries should follow independent ownership, release cadence, or access control—not file type alone. A practical layout can retain shared backend content once, give each backend its own configuration subtree, and isolate frontend resources by role. The pipeline then composes shared content with exactly one target-specific subtree.
| Layout | Useful when | Main control required |
|---|---|---|
| One monorepo | One organization controls coordinated frontend and backend releases | Path ownership, validation, and target-aware pipelines |
| Monorepo per Gateway role | Frontend and backend ownership or release cadence differs | Versioned interface between shared resources |
| Many file-type repositories | Access or release independence outweighs coordination cost | Dependency versions and an orchestrated release manifest |
Do not duplicate common scripts into all seven instance directories. Keep shared content in one path and make the pipeline fail when a target has no matching instance configuration or when more than one instance subtree is selected.
Can Hierarchical Deployment Modes Represent the Topology?
The proposed hierarchy is Core, then an environment mode, then a Gateway mode. Do not base production composition on presumed inheritance. Prove the actual merge behavior with a controlled configuration containing one shared object, one environment override, one instance-only object, and one deliberate conflict.
- Create an isolated test configuration with uniquely named values at the shared, environment, and instance layers.
- Activate each candidate mode and export or inspect the effective configuration.
- Record whether objects merge, replace, or disappear when a layer omits them.
- Introduce a conflicting field and record which layer wins.
- Restart or reload through the same mechanism used by production and repeat the reading.
If the effective result cannot be predicted from one documented selection rule, move instance selection into the pipeline. A pipeline can select the common backend path plus one Gateway-specific path without requiring nested mode semantics.
An alternate pattern keeps entire device configurations inside instance-specific modes. It supports editing multiple configurations from one development Gateway and committing them together. Its acceptance test is isolation: activating one profile must never retain devices from another profile, and switching profiles must produce a reviewable full diff. The issue reported for additional folders is maintainability rather than a demonstrated runtime performance limit.
Where Should OS Environment Variables Enter the Path?
Use OS environment variables for values that genuinely vary outside the repository, such as network or database endpoints, only where the target configuration field supports the intended substitution mechanism. Keep configuration structure in Git and inject values at deployment or startup. A variable must not decide which unrelated device inventory belongs to a Gateway unless the pipeline validates the resulting selection.
| Setting | Git should contain | Runtime source may contain | Verification reading |
|---|---|---|---|
| Device inventory | Named devices and instance ownership | Endpoint values when supported | Active devices match the target manifest |
| Database connection | Logical connection definition | Host, database, or secret values as permitted by the configuration mechanism | Effective endpoint and connection state |
| Shared scripts | Complete versioned source | No instance selection logic unless explicitly required | Deployed commit matches the pipeline record |
| Credentials | Reference or placeholder, not the secret | Approved secret store or protected runtime variable | Connection succeeds without exposing the value in logs |
Detect unset, empty, or unexpected variables before activation. Log variable names and resolved target identities, but never log secret values. After activation, read the effective endpoint from the Gateway configuration or status interface; a successful file transfer does not prove that substitution occurred.
How Should the Resolving Deployment Branch Run?
For this asymmetric topology, use one versioned source of truth, separate shared content from instance configuration, and make the pipeline select both environment and Gateway identity. Deployment modes can still represent environment differences for Gateways fulfilling the same role. An instance-profile approach remains valid only after the isolation and merge tests pass.
- Inventory all five production and two test backends. Assign each device connection to exactly one Gateway configuration unless the architecture intentionally duplicates it.
- Move common logic, scripts, tags, and UDTs into shared repository paths. Keep each distinct device inventory in a target-specific path or a fully isolated instance profile.
- Configure the pipeline with separate environment and Gateway selectors. Reject unknown targets and ambiguous matches.
- Resolve OS environment variables and protected values before activation. Stop the job when a required value is absent.
- Capture the commit identifier, target address, selected shared path, selected instance path or profile, and configuration diff.
- Deploy first to the intended test backend and inspect the effective configuration, device list, database destinations, scripts, and project resources.
- Promote the same commit through the production pipeline while changing only the authorized environment and instance inputs.
- Read back the running Gateway configuration and compare it with the target manifest. Confirm that no device from another backend is present, every expected connection reports its runtime state, and the recorded commit matches the deployed files.
FAQ
Can I use one Ignition 8.3 monorepo for all Gateways?
Yes. Keep shared automation in common paths and give each asymmetric backend a distinct configuration path; require the pipeline to select exactly one target configuration.
Can I create one deployment mode per backend Gateway?
Yes, if each mode has tested isolation and deterministic composition. Seven instance modes have no stated performance limit here, but combining environment and identity increases review and maintenance work.
Does a TEST or PROD mode select the correct device inventory?
No when Gateways in the same environment own different devices. Add an explicit Gateway selector in the pipeline or use a verified instance profile containing the complete local device configuration.
Can I verify a deployment from the Git commit alone?
No. Read back the active Gateway configuration, compare its devices and endpoints with the target manifest, check each connection state, and confirm the running files match the recorded commit.