Instance Definitions Technical Design
Last updated on Sep 16, 2021.
Last Reviewed and Approved on PENDING REVIEW
Table of Contents
Introduction
This document describes REACTR's instance definitions feature and its technical design.
The technical design was established based on the need for ways to simplify and improve the provisioning process.
Definition of Instance Definitions
Instance definitions are an abstraction layer on top of existing RPS types.
Types currently allow developers define a specific type of resource or target item, its expected or possible Properties and their associated value types (string/int/etc.).
Instance definitions will allow developers to take these generic types and combine them together to create complex,
nested entities composed of many different types through parent/child and assignment relationships, and the known default values for each individual Types' properties.
Examples: SNEs, TCNs, TSI-Large, laptop, could be a VM (because it could be a collection of components).
There are many existing types such as; Vehicle, Computer, VirtualMachine, NetworkConfiguration, etc.
The entities soldiers and developers are now interacting with are complex and composed of many of these types in parent/child hierarchies.
Instance definitions are collections of type definitions that have the ability to create an object.
Type definitions are parts with detailed properties.
The type definitions do not create objects, but they are able to define something you can create which is what an object will consist of.
Example: Virtual Machine, NIC, drive, etc.
Purpose of Generating Instance Definitions
The provisioning process for a Soldier or develoer should be limited to selection of a template (instance definition)
to use for provisioning and providing unit specific data files and RPS should be able to successfully provision with just this information supplied.
The goal is to limit the number of choices and decisions that a soldier, or LSI, would need to make during provisioning.
By simplifying the provisioning process and removing the number of choices a soldier, or LSI,
needs to make in the field, RPS will reduce the likelihood of human error and increase likelihood of adoption due to the improved ease of use.
Solution for Generating Instance Definitions
Overview
To simplify the provisioning process instance definitions can be used as templates to reduce the amount of data the user would need to input and reduce the potential for errors.
The solution for creating instance definitions is a new feature as a part of REACTR that enables developers to create instance definitions,
create instance definition items and export instance definitions.
This new feature is implemented as a web application with a back end that uses Microsoft Azure.
System Workflow
Technologies
| Technology Name |
Description |
Purpose |
| .NET Core |
Open source multi-platform software framework. |
Used as the primary base software framework REACTR and its features. |
| ASP.NET Core |
Open source modular web framework. |
Used as the web stack for the REACTR web application. |
| Azure Database for PostgreSQL |
IaaS PostgreSQL database service in Azure. |
Used as the primary data persistence service for REACTR. |
| JSON |
JavaScript Object Notation file format. |
Used as the data format for instance definition export files. |
| ASP.NET Core MVC |
Web app framework that implements the model view controller pattern. |
Used as the web application stack for the instance definition Items feature in REACTR. |
| Blazor WebAssembly |
Web app framework that enables creation of web apps using C#. |
Used as the web application stack for the instance definitions feature in REACTR. |
| Entity Framework Core |
Object relational mapping framework that supports the development of data-oriented applications. |
Used as the data layer framework for the instance definitions feature in REACTR. |
Architecture
The architecture for the instance definitions feature will consist of adding a new area to the REACTR application that will house all the views,
controllers, business logic, and data access logic.
Modified Software
- Area in REACTR to house the instance definitions feature which consists of the controllers, views, business layer, and data access layer.
New Infrastructure
- Azure Database for PostgreSQL to store instance definition Items and instance definitions.
Security
Overview
| Group Name |
Purpose |
| DEV Instance Definition Admin |
Administrator group for instance definition feature in REACTR development site. |
| PROD Instance Definition Admin |
Administrator group for instance definition feature in REACTR UAT and production sites. |
| DEV Instance Definition Creator |
Creator group for instance definition feature in REACTR development site. |
| PROD Instance Definition Creator |
Creator group for instance definition feature in REACTR UAT and production sites. |
| DEV Instance Definition Viewer |
Viewer group for instance definition feature in REACTR development site. |
| PROD Instance Definition Viewer |
Viewer group for instance definition feature in REACTR UAT and production sites. |
More detailed information on what permissions are available for viewing specific data or performing specific actions is listed in the feature-specific sections
further down in this document.
Persistent Data Design
Data Technical Solution
Instance definition items and instance definitions will be persisted in PostgreSQL.
Separate PostgreSQL tables will exist to house the instance definition items instance definitions, and other supporting data.
Data Dictionary
Associations_ResourceResourceGroup
| Field Name |
C# Data Type |
Description |
| ResourceGroupReferencesId |
UUID |
Foreign key to ResourceGroupReferences |
| ResourceReferencesId |
UUID |
Foreign Key to ResourceReferences |
Associations_ResourceTargetGroup
| Field Name |
C# Data Type |
Description |
| ResourceReferencesId |
UUID |
Foreign Key to ResourceReferences |
| TargetGroupReferencesId |
UUID |
Foreign Key to TargetGroupReferences |
Associations_TargetGroupResourceGroup
| Field Name |
C# Data Type |
Description |
| TargetGroupReferencesId |
UUID |
Foreign Key to TargetGroupReferences |
| ResourceGroupReferencesId |
UUID |
Foreign key to ResourceGroupReferences |
Associations_TargetResource
| Field Name |
C# Data Type |
Description |
| TargetReferencesId |
UUID |
Foreign Key to TargetReferences |
| ResourceReferencesId |
UUID |
Foreign Key to ResourceReferences |
Associations_TargetResourceGroup
| Field Name |
C# Data Type |
Description |
| TargetReferencesId |
UUID |
Foreign Key to TargetReferences |
| ResourceGroupReferencesId |
UUID |
Foreign key to ResourceGroupReferences |
Associations_TargetTargetGroup
| Field Name |
C# Data Type |
Description |
| TargetReferencesId |
UUID |
Foreign Key to TargetReferences |
| TargetGroupReferencesId |
UUID |
Foreign Key to TargetGroupReferences |
CachedDataItems
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| Name |
CITEXT |
Name (or Value depending on how it's used by the application) of the cached data item. |
| Type |
CITEXT |
Type of the cached data item. |
InstanceDefinitionGrouping
| Field Name |
C# Data Type |
Description |
| InstanceDefinitionId |
UUID |
Foreign Key to InstanceDefinitions. |
| InstanceDefinitionGroupId |
UUID |
Foreign Key to InstanceDefinitionGroups. |
InstanceDefinitionGroups
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| Name |
CITEXT |
Name of the Instance Definition Group. |
InstanceDefinitionItemProperty
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| Name |
CITEXT |
Name of the Instance Definition Item Property. |
| Value |
CITEXT |
Value of the Instance Definition Item Property. |
| InstanceDefinitionItemId |
UUID |
Foreign Key to InstanceDefinitionItems. |
InstanceDefinitionItemRoles
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| RoleName |
CITEXT |
Name of the Instance Definition Item Role. |
| InstanceDefinitionItemId |
UUID |
Foreign Key to InstanceDefinitionItems. |
InstanceDefinitionItems
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| Name |
CITEXT |
The name of the item from the original item. |
| EntityName |
CITEXT |
The value that will become the entity name for the item when the Instance Definition is invoked. |
| TypeDefinition |
CITEXT |
The RPS type definition for the item that identifies what the item is and what structure it should have. |
| IsApproved |
BOOLEAN |
Boolean that indicates whether the item is approved for use in Instance Definitions. When something IsApproved=$True, it gets locked and can't be edited unless an administrator unlocks it by setting IsApproved=$False |
| IsActive |
BOOLEAN |
Boolean that indicates whether the item should be active in RPS. IsActive is built into RPS, where ISActive=$True shows that item as active in RPS. Typically in RPS, when IsActive=$False, items are ignored - for example if a maintenance window is not active then it will not be used |
| LastUpdatedBy |
CITEXT |
The name of the user who updated the item. |
| LastUpdatedOn |
TIMESTAMP |
The date/time when the item was updated. |
| CMDBIDs |
TEXT |
List of strings that provides a list of RPS CMDB IDs that the item is associated with. |
| Discriminator |
CITEXT |
The type name of the item (Resource, Target, ResourceGroup, TargetGroup) that is used as a discriminator value by Entity Framework. |
| InstanceDefinitionResourceGroup_IsGlobal |
BOOLEAN |
Boolean that indicates whether the item resource group is to be global in RPS. |
InstanceDefinitionNodeProperty
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| Name |
CITEXT |
Name of the Instance Definition Node Property. |
| Value |
CITEXT |
Value of the Instance Definition Node Property. |
| InstanceDefinitionId |
UUID |
Foreign Key to InstanceDefinitions. |
InstanceDefinitionResourceGroupReference
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| InstanceDefinitionItemId |
UUID |
Foreign Key to InstanceDefinitionItems. |
| InstanceDefinitionId |
UUID |
Foreign Key to InstanceDefinitions. |
| ParentReferenceId |
UUID |
Foreign Key that references another record in this table. |
InstanceDefinitionResourceReference
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| InstanceDefinitionItemId |
UUID |
Foreign Key to InstanceDefinitionItems. |
| InstanceDefinitionId |
UUID |
Foreign Key to InstanceDefinitions. |
| ParentReferenceId |
UUID |
Foreign Key that references another record in this table. |
InstanceDefinitionTargetGroupReference
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| InstanceDefinitionItemId |
UUID |
Foreign Key to InstanceDefinitionItems. |
| InstanceDefinitionId |
UUID |
Foreign Key to InstanceDefinitions. |
| ParentReferenceId |
UUID |
Foreign Key that references another record in this table. |
InstanceDefinitionTargetReference
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| InstanceDefinitionItemId |
UUID |
Foreign Key to InstanceDefinitionItems. |
| InstanceDefinitionId |
UUID |
Foreign Key to InstanceDefinitions. |
| ParentReferenceId |
UUID |
Foreign Key that references another record in this table. |
InstanceDefinitions
| Field Name |
C# Data Type |
Description |
| Id |
UUID |
Primary Key and unique identifier of each record in the table. |
| Name |
CITEXT |
Name of the Instance Definition. |
| IsApproved |
BOOLEAN |
Boolean that indicates whether the item is approved for use. |
| Description |
CITEXT |
Description of the Instance Definition. |
| RequiredProperties |
TEXT |
List of required properties for the Instance Definition. |
| NodeIpAddress |
CITEXT |
IP Address of the Node. |
| NodeSyncEndpointUrl |
CITEXT |
Sync Endpoint URL for the Node. |
| NodeHostName |
CITEXT |
Hostname of the Node. |
| NodeDescription |
CITEXT |
Description of the Node. |
| Name |
CITEXT |
The name of the node from the original node. |
| EntityName |
CITEXT |
The value that will become the entity name for the node when the Instance Definition is invoked. |
| LastUpdatedBy |
CITEXT |
The name of the user who updated the Instance Definition. |
| LastUpdatedOn |
TIMESTAMP |
The date/time when the Instance Definition was updated. |
Glossary
| Term |
Definition |
| RPS |
Rapid Provisioning System |
| REACTR |
RPS Enterprise Automation, Configuration and Testing Routines |
| Instance Definition |
The abstraction layer on top of existing RPS Types. |
| Instance Definition Reference |
The assignment of the instance definition to a root Resource Item, which results in a set of one or more Resource Items to be run. |
| Instance Definition Association |
The association between referenced items, which results in an assignment between any combination of Resource Items, Target Items, Resource Groups, or Target Groups. |
| Instance Definition Item |
An item on the abstraction layer on top of existing RPS Types. |
| Instance Definition Node |
A node item that will result in association of a node with target items that are created when an instance definition is invoked. |
| Instance Definition Group |
A collection of two or more instance definitions. Groups provide the ability to export multiple instance definitions to a single JSON file. |
External Assets