Gateway Deployment Modes
💡Have feedback for this page? Let us know on the IA Forum.
Gateway Deployment Modes allow you to configure different running environments for your Gateway. This can be useful in cases where you want to use your Gateway in different capacities, such as in a production or development environment.
Collections​
Collections can be considered as any grouping of Gateway resources. Deployment modes are the same thing, with the added caveat that they are user-created and user-defined. Thus, all deployment modes are collections, but not all collections are deployment modes.
It is important to understand the various collection levels when working with deployment modes so you know what resources will be inherited and which can be modified, as deployment modes take initial elements and resources from parent collections. At the top level is the system collection. Ignition will use this built-in collection to inject any required configurations into a Gateway instance. Any resources within the system collection, such as is the MariaDB JDBC driver, are immutable. However, you can still override a system resource to create a resource definition for your deployment mode.
Next is the external collection. The resources within the external collection cannot be modified through the Gateway but instead through the external file system within Ignition's data directory. These resources are read-only within the Gateway because the external collection is intended to be a place for centrally managed configurations which should not be modified by the local system. Additionally, if you are using a version control system (VCS), this collection is where your VCS should place any relevant resources.
The core collection is the child of the external collection. Unlike the previous two collections, resources within core can be configured through the Gateway Webpage. If you are using either a freshly installed Gateway, or a Gateway without any configured deployment modes, your Gateway will be running in the core collection. Deployment modes and resource definition overrides are typically created from core.
Aside from core, deployment modes also use resources from the local collection. The local collection contains data essential to the local host environment, such as certificate details. Your deployment modes will not inherit anything from the local collection, but will use the data within the local collection to function properly on each respective machine.
The following diagram illustrates how these collections are structured:
Deployment Modes​
Deployment modes are created and edited on the Gateway, but you will need to modify the Gateway Configuration File to change the deployment mode your Gateway is running in.
Creating and Editing Deployment Modes​
To view your deployment modes on the Gateway Webpage go to Platform > System > Modes. The Modes page will display information about your deployment modes, including the name, title, description, and number of resource definitions.
To create a new deployment mode, click on Create Mode on the right side of the page. You will be prompted to provide a name, as well as an optional title and description of the deployment mode. The name and title fields are similar to a project in that it is recommended to change the title of the resource instead of the name, as resource definitions are tied to deployment mode names.
Clicking on the three dots menu to the right of an existing deployment mode will provide options to edit or delete the specified deployment mode.
Changing The Active Deployment Mode​
While you can modify the deployment mode and resources within on the Gateway, you cannot change the active deployment mode your Gateway is currently running in using the Gateway Webpage. Instead, you will need to add the following additional Java parameter to your Gateway Configuration file, located in your Ignition install directory > data > ignition.conf:
wrapper.java.additional.x=-Dignition.config.mode=DEPLOYMENT_MODE_NAME_HERE
Replace the x with the next sequential Java parameter and DEPLOYMENT_MODE_NAME_HERE with the actual name of your deployment mode. For example, if you have three previous additional Java parameters and your deployment mode is named Dev, you would need to add the configuration as follows:
wrapper.java.additional.4=-Dignition.config.mode=Dev
You will need to restart your Gateway service before changes to your Gateway Configuration file will take effect.
Only one deployment mode can be active at any given time.
Resource Definitions​
Resource definitions are any Gateway resources that have been created or configured. Within the context of deployment modes, resource definitions are typically created by overriding or duplicating existing resources. These new resource definitions are then assigned to a deployment mode. The deployment mode will use these new definitions if the Gateway is running in the applicable deployment mode.
Resource definitions allow you to customize each deployment mode according to your needs. For example, suppose you create a database connection called Database A for a development deployment mode. You can override or duplicate Database A so that it creates a new and separate database connection resource, and then assign it to a production deployment mode. After this process, you can modify the new database connection so that it connects to a different database or table while the Gateway is running in your production deployment mode.
You cannot create, override, duplicate, or move a resource definition if the targeted deployment mode already has a definition with the same name (such as Database A), as the targeted deployment mode will be unselectable.
If a deployment mode is deleted, any associated resource definitions will also be deleted.
You may notice that some resource definitions will not show up if they are not assigned to the current deployment mode. This can occur in two ways:
- Duplicating a named resource definition to a different deployment mode but providing a different value for the name than the original. See the Duplicating Resources section for more information.
- Creating a named resource definition, and assigning it to a different deployment mode using a name that no other resource definition in your current deployment mode is using. See the Manually Creating Gateway Resources section for more information.
Resource Types​
Deployment modes mainly use named resources and singleton resources. However, deployment modes can also take advantage of system resources.
These resource types are not exclusive to deployment modes, as they are all used throughout the Gateway.
Additionally, just about every Gateway resource can be overridden. The following is a list of Ignition subsystems that cannot have resource overrides.
- Deployment Modes
- Modules
- Projects
- Licenses
Named Resources​
Named resources are individual Gateway resources that are displayed in a list, such as a device connection. In this case, each device connection is counted as a separate named resource and is given a unique name to differentiate them from each other.
Singleton Resources​
Singleton resources are also Gateway resources, but unlike named resources, singleton resources are not created by the user. Singleton resources instead consist of several properties grouped together to form a singular resource definition. An example of this is the Gateway Network Settings page. You can configure multiple properties on this page, however, the entire page will be saved and recognized as a single resource definition.
System Resources​
Since system resources exist within the system collection, these resources are immutable. Clicking on the Edit option within a system resource's three dots menu will open a non-configurable settings window.
If you need to configure different settings for a system resource, you can still create a resource override from that system resource to use as a mutable resource within your targeted deployment mode. If you do not have a user-created deployment mode configured, any system resource overrides in this case will be configured as a resource definition for the core collection, since that is a Gateway's default deployment mode.
Creating Named and Singleton Resources​
There are three ways to create a Gateway resource, though some of these options will not be available depending on the resource type.
- Manually create a Gateway resource
- Overriding Gateway resources
- Duplicating Gateway resources
New named resources can be created either manually, by overriding, or by duplicating. Overriding and duplicating resources seem similar at first glance, but allow you to customize your deployment modes in different ways. New singleton resources can only be created by overriding.
Manually Creating Gateway Resources​
To create a named resource definition and assign it to a deployment mode, follow the steps you normally would when creating a Gateway resource. Once you finish configuring your resource, there will be a dropdown arrow next to the final button to create your resource. From this dropdown, you can select which deployment mode to create and assign the resource to.
Keep in mind that you will only be able to create a resource and assign it to a deployment mode if a separate deployment mode exists and the deployment mode doesn't already have a resource with the same name.
Overriding Gateway Resources​
Overriding Gateway resources consists of taking existing resources and creating an override that the assigned deployment mode will use. Both named and singleton resources can have overrides.
Overriding Named Resources​
When overriding a named resource, the new resource definition will automatically use the same name as the original resource. You will be able to select a deployment mode to assign the override to using the Create Resource Override popup window.
A new banner will also appear at the top of the list. Clicking on Show All will add an additional column to the list that displays which deployment mode the named resource definition is a part of.
In the image below, there is an Allen-Bradley Logix resource defined on the Dev and Prod deployment modes, in addition to core.
After clicking Show All, each override will have submenus which you can access by clicking on the three dots menu on the right. Within the submenu, you can edit or duplicate the override, move the overridden resource definition to a different deployment mode, or remove the override completely.
Editing the override will open a window with the same properties as editing the original resource. You will be able to configure that resource as if it were separate from the original resource since your changes will only affect the associated deployment mode. When editing an override, there will be a banner at the top of the new window indicating which deployment mode your override is a part of.
Duplicating the resource override will let you select which deployment mode to assign the duplicate to, and provide an option to change the name from the original resource. Keep in mind that the duplicated named resource will not appear unless you are in the assigned deployment mode. See the Duplicating Gateway Resources section for more information.
Moving a resource definition allows you to take an existing resource override and place it in a different deployment mode than the currently assigned one.
Once overrides are assigned to their deployment modes, they are not dependent on each other. Deleting one will not impact the other.
Overriding Singleton Resources​
To override a singleton resource, first make sure you have a separate deployment mode available, then navigate to the singleton resource you want to override. Using the Gateway Network Settings page as an example, clicking on the three dots menu on the top right of the page will provide an option to create an override.
When creating a new override, you will be prompted to choose a deployment mode to assign the override to.
The Create Override option will be available as long as a separate deployment mode exists. However, if each deployment mode already has the same overridden singleton resource, you will not be able to select a deployment mode in the Create Override window.
After creating a resource override, a new banner will appear at the top of the form. From this banner, you will be able to select which deployment mode to configure resources for using the dropdown menu on the top right. Toggling between each deployment mode will allow you to configure different settings for separate deployment modes.
After configuring the singleton resource changes for your desired deployment mode, click on Save Changes on the top right.
Toggling between deployment modes using this banner is not the same as changing your Gateway's active deployment mode. Switching between deployment modes here simply allows you to configure different settings for each mode.
Duplicating Gateway Resources​
Duplicating a resource allows you to copy the configuration settings of a named resource and create a separate resource. Singleton resources are unable to be duplicated since they cannot be renamed and have multiple properties that are bundled together as a single resource.
To duplicate a named resource, click on the three dots menu of the named resource you want to duplicate, then click Duplicate.
When duplicating resources, you can both change the name of the new resource and assign it to a deployment mode. This creates three duplication possibilities:
- Provide a new value for the name of the duplicate resource, and assign the resource to a different deployment mode
- Provide a new value for the name of the duplicate resource, and assign the resource to the same deployment mode
- Keep the same resource name, and assign the resource to a different deployment mode
Duplicating resources is not confined to deployment modes only. You can still use the duplicate feature outside of a deployment mode context if you want to create a named resource with a similar configuration.
Duplication Possibility #1 - New Name, Different Deployment Mode​
Providing a new value for the name of the duplicate resource while assigning the duplicate resource to a different deployment mode will create a new and separate resource from the original. Unlike overridden resources, these newly duplicated resources will not appear beneath the original resource as a resource definition. Additionally, you will not be able to see the new resources unless your Gateway is running in the same deployment mode these resources are assigned to.
Alternatively, you can create a resource definition with the same name as the duplicated resource within your current deployment mode. The duplicated resource will appear under the new resource definition, similar to creating a named resource override. You will be able to see this duplicated resource by clicking Show All.
Having the same name is the only criteria for a duplicated resource in a different deployment mode to appear. Using device connections as an example, suppose you are currently in the core deployment mode. On this Gateway, you have an Allen-Bradley Logix driver named Resource A within your core deployment mode and an Allen-Bradley Micro800 driver named Resource B within your dev deployment mode. In this instance, since each resource has a different name and are in different deployment modes, only Resource A will appear in your list.
However, if you duplicate Resource A by naming the new resource Resource B and assigning it to your core deployment mode, both Resource A and Resource B will be visible in your list, even though the driver types are different.
You cannot keep the same resource name and assign the resource to the same deployment mode. Attempting to do so will cause the Gateway to display an error message.
Duplication Possibility #2 - New Name, Same Deployment Mode​
If you duplicate a resource by giving it a different name within the same deployment mode, a new and separate named resource will appear with the new name. This named resource will have the same three dots menu options as the active deployment mode's base resource definition.
Duplication Possibility #3 - Same Name, Different Deployment Mode​
Keeping the same name while assigning the duplicate resource to a different deployment mode will create a new resource under the original resource. This will have the same effect as overriding a resource definition. You can view the new resource by clicking on Show All on the top right, which will display all overridden resource definitions in the list for each deployment mode.
Scanning the File System for Deployment Mode Changes​
Your Gateway will automatically recognize any resource overrides you create within the Gateway Webpage. However, any changes to your Gateway deployment modes through the Ignition file structure outside of the Gateway Webpage, such as through file manipulation or VCS, will not be automatically recognized. To bring in these changes, you can click on Scan File System on the top right of the Modes page to force your Gateway to check for any file changes. This will open a prompt allowing the Gateway to perform a scan of its file structure to apply any missing changes.
The Scan File System button for Gateway deployment mode differs slightly compared to other buttons of the same name, such as for projects on the Gateway's Projects page. While the Project's Scan File System button only scans the projects section of the file system, the Scan File System button for deployment modes will scan the entire Ignition file system.
You can also use a POST request to scan for any file system changes using the syntax below:
{{gateway_address}}/data/api/v1/scan/config
For more information about available HTTP requests for deployment modes, see the OpenAPI documentation at the following location:
{{gateway_address}}/openapi#tag/config-management
While going through the Gateway file structure to add, copy, or move resource configurations, resource overrides, and deployment modes is possible, this is not recommended and should only be used as a last resort.
Deployment Mode Examples​
Click here for examples on creating deployment modes and overriding and duplicating resource definitions.