Overview
This section describes how to configure the custom Rhino application VMs - that is, the processes of making and applying configuration changes.
It is not intended as a full checklist of the steps to take during an upgrade or full installation - for example, business level change-control processes are not discussed.
The configuration process is based on modifying configuration files, which are validated and sent to a central configuration data
store (CDS) using the rvtconfig tool.
The custom Rhino application VMs will poll the CDS, and will pull down and apply any changes.
Initial setup
The initial configuration process starts with the example YAML files distributed alongside the custom Rhino application VMs, as described in Example configuration YAML files.
|
Metaswitch strongly recommends that the configuration files are stored in a version control system (VCS). A VCS allows version control, rollback, traceability, and reliable storage of the system’s configuration. |
If a VCS is not a viable option for you, you must take backups of the configuration before making any changes. The configuration backups are your responsibility and must be made every time a change is required. In this case, we recommend that you store the full set of configuration files in a reliable cloud storage system (for example, OneDrive) and keep the backups in different folders named with a progressive number and a timestamp of the backup date (for example, v1-20210310T1301).
The rest of the guide is written assuming the use of a VCS to manage the configuration files.
Initially, add the full set of example YAMLs into your VCS as a baseline, alongside the solution definition files
(SDFs) described in the custom Rhino application VM install guides.
You should store all files (including the SDFs for all nodes) in a single directory yamls with no subdirectories.
Making changes
To change the system configuration, the first step is to edit the configuration files, making the desired changes (as described in this guide). You can do this on any machine using a text editor (one with YAML support is recommended). After you have made the changes, record them in the VCS.
Validating the changes
On the SIMPL VM, as the admin user, change to the directory /home/admin/.
Check out (or copy) your yamls directory to this location, as /home/admin/yamls/.
|
|
If network access allows, we recommend that you retrieve the files directly from the VCS into this directory, rather than copying them. Having a direct VCS connection means that changes made at this point in the process are more likely to be committed back into the VCS, a critical part of maintaining the match between live and stored configuration. |
At this point, use the rvtconfig tool to validate the configuration used for all relevant nodes.
|
|
For more information on the rvtconfig tool, see rvtconfig.
|
The relevant nodes depend on which configuration files have been changed. To determine the mapping between configuration files and nodes, consult Example configuration YAML files.
The rvtconfig tool is delivered as part of the VM image CSAR file, and unpacked into
/home/admin/.local/share/csar/<csar name>/<version>/resources/rvtconfig.
|
It is important that the rvtconfig binary used to validate a node’s configuration is from a matching release.
That is, if the change is being made to a node that is at version x.y.z-p1, the rvtconfig binary must
be from a version x.y.z CSAR.
|
For example, assume a change has been made to the custom-vmpool-config.yaml file in the custom Rhino application network.
This would require reconfiguration of the custom node at version 4.0.0.
To validate this change, use the following command from the /home/admin/ directory.
./.local/share/csar/custom/4.0.0/resources/rvtconfig validate -t custom -i ./yamls
If the node fails validation, update the files to fix the errors as reported, and record the changes in your VCS.
|
|
If the VM image does not have a pre-installed license, then a Rhino license must be included in the ./yamls directory.
|
Uploading the changes
Once the file is validated, record the local changes in your VCS.
Next, use the rvtconfig upload-config command to upload the changes to the CDS.
As described in
Uploading configuration to CDS with upload-config,
the upload-config command requires a number of command line arguments.
The full syntax to use for this use case is:
rvtconfig upload-config -c <cds-ip-addresses> -t <node type> -i <config-path> --vm-version <vm_version>
where:
-
<cds-ip-addresses>is the signaling IP address of a CDS node. -
<deployment-id>can be found in the relevant SDF. -
<node type>is the node being configured, as described above. -
<config-path>is the path of the directory containing the YAML and SDFs. -
<vm_version>is the version string of the node being configured.
As with validation, the rvtconfig executable must match the version of software being configured.
Take the example of a change to the custom-vmpool-config.yaml as above, on a custom Rhino application network with nodes at version
4.0.0, a deployment ID of prod, and a CDS at IP 192.0.0.1.
In this environment the configuration could be uploaded with the following commands (from /home/admin/):
./.local/share/csar/custom/4.0.0/resources/rvtconfig upload-config -c 192.0.0.1 -t custom -i ./yamls --vm-version 4.0.0
Verifying the changes
Once the upload is completed, the software on the VMs will apply the configuration from the CDS. You can verify this by monitoring the system logs on the relevant nodes.
