The use cases below illustrate the tasks that declarative configuration supports. Many operators and developers will have different approaches to these tasks. Use of declarative configuration simplifies management of variants and migration between versions of the system configuration.
Deploying a new application
A system integrator (SI) creates an application on Rhino to deploy to multiple sites in a customer’s network.
The SI creates a single VM image with the components needed for the application deployed into Rhino and a configuration fragment describing the configuration common to all sites. For each site, the SI creates a configuration fragment describing the configuration of the components specific to that site. They combine this configuration fragment with the common fragment to create a site-specific configuration bundle.
Using the VM image, the SI starts a fleet of virtual machines on each site.
They import the site-specific configuration bundle using the rhino-console command importdeclarativeconfig <config-bundle.zip> -o output.json and save the resulting output file.
Rhino applies the configuration and converges the actual state of the updated components to match the newly imported desired state.
Upgrade
A developer creates a new version of the application on Rhino to deploy in a customer’s network. The developer has created a VM image with the components needed for the application deployed into Rhino.
The developer uses the rhino-console command exportdeclarativeconfig <old-config-bundle.zip> to write the state of the operational cluster to a file.
The developer unzips this configuration bundle and saves it in a version control repository for the customer.
The developer uses a transformation script to update component versions and configuration properties from the pre-upgrade values to the post-upgrade ones.
Using the VM image, the developer starts an initial subset of the new cluster.
They import the post-upgrade configuration bundle using the rhino-console command importdeclarativeconfig <config-bundle.zip> -o output.json and save the resulting output file.
Rhino applies the configuration and converges the actual state of the updated components to match the newly imported desired state.
The developer runs the rhino-console command waittilconverged and watches for alarms.
Once the actual state has converged, the system administrator redirects traffic to the new cluster and shuts down VMs hosting the old cluster one by one while booting VMs for the new cluster to replace them.
Maintenance
Unlike versions of Rhino prior to 3.0.0, the declarative state management commands do not require disabling and re-enabling symmetric activation state mode when performing operations on a single Rhino node. The default behavior is to have a default desired state for the cluster and use temporary per-node state configuration to override this as needed.
Temporary stop
A system administrator using rhino-console can use the desired state management commands to temporarily deactivate nodes for maintenance.
For example, to deactivate a node while running diagnostics that have the potential to interrupt call flow, the administrator runs the console command setsleedesiredstate <node-ID> stopped.
After the task is complete, they then run removepernodesiredstate <node-ID> to return the node to the same state as the rest of the cluster.
Reboot
A system administrator needs to reboot the host VM for OS updates.
They run the OS reboot command.
The init script for the Rhino service runs the console command shutdown -nodes <node-IDs> -timeout <drain timeout> to shut down the Rhino nodes running on the host.
No change is made to the desired state, so when the host restarts, the nodes return to the same state as before the reboot.
Backup
A system administrator makes configuration backups before performing configuration changes. Backups are made before and after importing a partial configuration or after running a series of console commands that change the configuration of components.
The administrator uses the rhino-console command exportdeclarativeconfig <pre-change-bundle.zip> to write the state of the operational cluster to a file.
The administrator unzips this configuration bundle and compares it with the latest version in the version control repository.
If it is different, the administrator adds it to the repository with a commit message describing the difference.
The administrator makes the planned configuration changes to the system using a management interface.
They use the rhino-console command exportdeclarativeconfig <post-change-bundle.zip> to write the state of the operational cluster to a file.
They unzip this configuration bundle and save it in the version control repository with a commit message describing the purpose of the change.
