◷ Reading Time: 17 minutes
FlexRule Server 8.0+ can be run in Azure Container Instances.
Simple Architecture using Azure Container Instances
The simplest architecture using Azure Container Instances is deploying two containers: one master and one agent.
The examples on this page use the architecture above to run FlexRule Server.
- The addresses will use the host machine’s public IP address for routing.
http://[host]:9000goes to the Master API.http://[host]:9010goes to the Workbench.http://[host]:9003goes to the Agent API.
All nodes must have access and connect to the same database.
Before you Start
1. Configure an Azure SQL Database for FlexRule Server.
FlexRule Server will need to connect to a database. To create this database, you can run the FlexRule Server Master Windows Installer. As path of the installation wizard, you will be given the option to connect to SQL Server / Azure SQL Server and create a new database. Once you create this database you can use it with Azure Container Instances.
You must install the On-Premise Windows version of FlexRule Server Master and create the database and configuration file. Then you will be able to use the values from the configuration file for your Azure Container Instance as environment variables.
2. Allow access through any firewalls in your environment.
You’ll need to allow communication on particular ports in your network or environment. In this guide, we’re using TCP ports 9000, 9003, and 9010.
How to Run FlexRule Server
You must install the On-Premise Windows version of FlexRule Server Master and create the database and configuration file before proceeding. The configuration files created will have the values you need for the environment variables in your container instances.
1. Find your Configuration Values
Open the configuration files you created from your FlexRule Server On-Premise Windows installation.
[Server Install Path]\Master\FlexRule.Server.Master.dll.config
[Server Install Path]\ExecAgent\FlexRule.Server.ExecAgent.dll.config
e.g. C:\Program Files (x86)\Pliant Framework\FlexRule Server\8.0.117\Master\FlexRule.Server.Master.dll.config
e.g. C:\Program Files (x86)\Pliant Framework\FlexRule Server\8.0.117\ExecAgent
These two files are in an XML format and contain the keys and values you will need for the docker configuration in the next step.
2. Create a FlexRule Master Instance
In Azure Portal, navigate to the resource group you would like to use or create a new resource group to use for FlexRule Server components.
Click on Add to create a new resource.
Choose Containers > Container Instances.
Complete the details for your container. We recommend you to label this container as a master. You can also give it a number if you plan on adding more master instances in the future.
The container image we are using is from a public repository hosted in docker hub and uses the Linux operating system type.
Click Next to go to the Networking section.
Mark Include public IP address as Yes.
Add the ports we are using for FlexRule Server: 9000, 9003, 9010.
Optionally, you can give your container instance a DNS name label if you prefer to use this instead of an IP address to get to your master instance.
Click Next to go to the Advanced section.
Set a Restart policy. We recommend you initially use Never so you can check for any errors, make changes, and restart the container manually.
Add Environment Variables.
Database details for connecting to the FlexRule Server database.
Master_DB_Server | Server address to your Azure SQL database. |
Master_DB_Name | Name of your database on the server. |
Master_DB_User | Username which has access to the database. |
Master_DB_Password | Password for the username specified. |
URLs for communication between FlexRule Server components.
Master_ApiAddress | Container instance public IP address or DNS name label with port number 9000. |
Master_WorkbenchAuth | Container instance public IP address or DNS name label with port number 9000. |
Master_WorkbenchAddress | Container instance public IP address or DNS name label with port number 9010. |
Keys used for licensing, communication, and encryption.
AuthSigningKey | Get this configuration value from the configuration file created during step 1. |
MasterAgentSharedSecret | Get this configuration value from the configuration file created during step 1. |
MasterEncryptionPassword | Get this configuration value from the configuration file created during step 1. |
License | Obtain a FlexRule Server license key file and copy-paste its value here. |
Static values – copy and paste these in as environment variables.
LogFolder | /frs |
Master_WorkbenchPath | Workbench |
Master_GenericLogger | FlexRule.Server.Logging.LogFileWriter,FlexRule.Server.Library |
Monitoring_Channel | [{type:'ConsoleTraceListener', initialData:'', name:'ConsoleTraceListener'}] |
Monitoring_Event | [{event:'GenericTraceEvent', channel:'ConsoleTraceListener', level:'Verbose', enabled:true},{event:'ExceptionTraceEvent', channel:'ConsoleTraceListener', level:'Error', enabled:true}] |
This is what it looks like once you’ve added all the required environment variables.
Click on Review + Create to review your details.
Click on Create. This will start your deployment for the current container instance.
Once the deployment is complete, click on Go to resource.
In the details for your container instance go to Settings > Containers.
Choose the container that was created. The State for the container will be Running if it started successfully.
In the Logs tab you will be able to see the output from the container. If you can see the following message, FlexRule Server Master has started successfully.
If there were any errors with starting FlexRule Server, the container will have the State Terminated. You can use the logs from the container and the troubleshooting section at the end of this page to resolve some common issues.
Use the Workbench Address to get to the FlexRule Server Master Workbench application to check that it is working. You should be able to see this in the logs, however it’s what we set as an environment variable earlier.
Use the username and password you specified when setting up the Windows installation.
3. Create a FlexRule Server Agent Instance
In Azure Portal, navigate to the resource group you would like to use or create a new resource group to use for FlexRule Server components.
Click on Add to create a new resource.
Choose Containers > Container Instances.
Complete the details for your container. We recommend you to label this container as an agent. You should also give it a number as it’s likely you’ll add more agents in the future.
The container image we are using is from a public repository hosted in docker hub and uses the Linux operating system type. This details are the same as for the master instance as we’re using the same image.
Click Next to go to the Networking section.
Mark Include public IP address as Yes.
Add the ports we are using for FlexRule Server: 9000, 9003, 9010.
Optionally, you can give your container instance a DNS name label if you prefer to use this instead of an IP address to get to your agent instance.
Click Next to go to the Advanced section.
Set a Restart policy. We recommend you initially use Never so you can check for any errors, make changes, and restart the container manually.
Add Environment Variables. These are different for agents and masters.
Database details for connecting to the FlexRule Server database.
Agent_DB_Server | Server address to your Azure SQL database. |
Agent_DB_Name | Name of your database on the server. |
Agent_DB_User | Username which has access to the database. |
Agent_DB_Password | Password for the username specified. |
URLs for communication between FlexRule Server components.
Agent_ApiAddress | http://*:9003 where 9003 is port number for this agent. |
Agent_MasterAddress | Address to the master instance with port number. |
Keys used for licensing, communication, and encryption.
Agent_Runtimes | [{version:'*',license:'Your_Runtime_License_Key'}] |
AuthSigningKey | Get this configuration value from the configuration file created during step 1. |
License | Obtain a FlexRule Server license key file and copy-paste its value here. |
MasterAgentSharedSecret | Get this configuration value from the configuration file created during step 1. |
MasterEncryptionPassword | Get this configuration value from the configuration file created during step 1. |
Please note that the Runtime license and Server license are two different license keys.
Static values – copy and paste these in as environment variables.
Agent_GenericLogger | FlexRule.Server.Logging.LogFileWriter,FlexRule.Server.Library |
LogFolder | /frs |
Monitoring_Channel | [{type:'ConsoleTraceListener', initialData:'', name:'ConsoleTraceListener'}] |
Monitoring_Event | [{event:'GenericTraceEvent', channel:'ConsoleTraceListener', level:'Verbose', enabled:true},{event:'ExceptionTraceEvent', channel:'ConsoleTraceListener', level:'Error', enabled:true}] |
This is what it looks like once you’ve added all the required environment variables.
Add the following command to the command override.
[ "/app/entry.sh", "-runagent -container" ]
This command override tells the container image to start as an agent.
Click on Review + Create to review your details.
Click on Create. This will start your deployment for the current container instance.
Wait for the deployment. This usually takes a few minutes.
Once the deployment is complete, click on Go to resource.
In the details for your container instance go to Settings > Containers.
Choose the container that was created. The State for the container will be Running if it started successfully.
In the Logs tab you will be able to see the output from the container. If you can see the following message, FlexRule Server Agent has started successfully.
If there were any errors with starting FlexRule Server, the container will have the State Terminated. You can use the logs from the container and the troubleshooting section at the end of this page to resolve some common issues.
4. Connect the Agent to the Master
Open the Workbench using the Master_WorkbenchAddress you specified in step 2. and sign in to FlexRule Server using the username and password you specified when setting up the Windows installation.
Navigate to Admin > Agents.
Click on New Agent.
Give your agent a name, and description, and enter the public IP or DNS name label for your agent with its port number at the end in the Host URL field.
Click on Save.
You should now have an agent added to your list of agents.
Toggle the Status to ON to enable your agent.
The agent will be pinged from the master to ensure communication is available. If successful, you’ll see a confirmation that the status has been set.
5. Execute a service to test the deployment
Once you have access to the Workbench, use our Service Execution articles to learn how to test FlexRule Server.
Troubleshooting
Value cannot be null
Unhandled Exception: System.ArgumentNullException: Value cannot be null.
This usually happens when one of the required environment variables is not specified. Ensure you have added all the environment variables for your container instance.
SQL Server Issues
Failed to start FlexRule Master Server: Number: 0
Type: System.Data.SqlClient.SqlException
Message: A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible. Verify that the instance name is correct and that SQL Server is configured to allow remote connections. (provider: SQL Network Interfaces, error: 26 - Error Locating Server/Instance Specified)
There are several common reasons this can happen:
1. The address to the server is incorrect.
2. There is a firewall or rule blocking the connection.
You can check whether the server address is contactable by using SQL Server Management Studio to connect to it. If you can’t use the server address exactly as you entered it as an environment variable, it will not work with FlexRule Server either.
License Initialization
Type: FlexRule.Server.License.LicenseInitializationException
Message: License initialization error: 5
Your license key is invalid or was entered incorrectly.
- Ensure you are entering the FlexRule Server license key and the FlexRule Runtime license key into the correct fields. These are two separate keys used for different products.
- The values entered into the form fields when generating the commands should not include single quotes or double quotes around the key.
If you don’t have a valid license for FlexRule Server or FlexRule Runtime, please contact FlexRule support to obtain a trial license.
Cryptographic Exception
System.Security.Cryptography.CryptographicException : Padding is invalid and cannot be removed.
This exception occurs when one of the keys in the command configuration (most likely MasterEncryptionPassword) does not match the database’s keys. The configuration passed as environment variables must match those when the database was set up.