The node-parameters.yaml file describes a wide range of properties of the VM to be built. You can find an example file at the bottom of this page.

Important Be careful when editing the yaml file - the yaml file format is very flexible, but spaces and other small easily overlooked characters can be significant. You are unlikely to have any problems if you only change the values inside the quotes.

The example file includes a description of each value in the file. When the vmbc tool runs, it will validate the values, and provide guidance if any values are not acceptable.

The node-parameters.yaml file consists of three distinct sections:

node-metadata

In the first part of the file, you specify high-level properties of your product.

Naming

Specify the name of the product and a version number. The version number is used in filenames, and should not include spaces, but beyond that no conventions are assumed. It is likely that you change the version, but not the product name, each time you release a new VM.

You need to specify the product name in three forms:

Field Description Format

product-name

The "official" full name of your product. It appears in the OVF (for VMware builds) and as the Rhino SNMP agent description.

Any string of up to 100 characters

display-name

The "friendly" name of the product, used for display purposes. This is often the same as, or a shortened form of, the product-name. It appears on the console when you boot the VM.

Any string of up to 32 characters

image-name

An identifier to represent this product amongst others your end users may be deploying. This identifier is used in a number of places, notably the filename of the image, the VNFC type field in the SDF, and the CDS group ID.

A string of up to 32 characters, consisting only of letters a-z and A-Z, numbers 0-9, and hyphens (-)

OS user

Set the username of the default Linux user, and a password for that user. The password must be at least 8 characters long, but has no other restrictions.

Tip The password is only used for build and initial deployment of the custom VM. For example, if the VM fails to bootstrap successfully, the VM user will use the username and password you specify here to log in through the console in their VM host’s GUI to diagnose the problem. Once the VM is up and running, the user of the VM will specify a new password in the SDF as part of runtime configuration.

Signaling traffic types

You can specify the signaling traffic types used by the VM. Any signaling traffic type that you wish to use with the VM needs to be defined here. This allows for use of more than two signaling interfaces, since each interface requires at least one traffic type. For valid signaling traffic types see the YANG schema.

Tip

VMs built by VMBC always use the management traffic type. If you configure Rhino to run in clustered mode, the VMs will use the cluster traffic type as well. These are independent of any signaling traffic types.

If you configure Rhino to run in pooled mode, or if replication is enabled, the internal signaling traffic type is mandatory, as it is used by Rhino for pool and replication traffic.

If you don’t specify any signaling traffic types, the VM will default to having a mandatory custom-signaling traffic type and an optional custom-signaling2 traffic type.

Refer to the Custom VM Install Guide for more information about traffic types and their relationship to the VM’s network interfaces.

Parallel upgrade support

You can specify settings for parallel upgrade.

flavors

The second part of the file is concerned with specifying the virtual hardware specifications of the VM that is produced, in particular the allocated resources for CPU, memory, and disk sizes. These specifications apply only to VMs produced to run on VMware’s vSphere or vCloud platforms, or the Microsoft Azure cloud platform (in which case you specify an Azure SKU and disk type). For OpenStack deployments, the user configures the flavor on the host before deploying the VM.

Although these parameters apply only to VMware platforms, this file has appropriated the name flavor (as used by OpenStack) to describe a configuration of CPU, memory and disk size. You can specify multiple flavors. For example, you might create a small configuration for lab deployments, and a larger configuration expected to be used in production. Whilst there is no fixed limit to the number of flavors you can have, each flavor ends up being built separately into the VM image file, so the size of the VM images is affected by the number of flavors that you specify.

It is likely that you may want to experiment to come up with appropriate values for these parameters. You can find some guidelines on how to size your VM in the Sizing your VM section.

rhino-parameters

The third part of the file specifies parameters that will affect the installed Rhino:

  • whether the installed Rhino should run in cluster mode or pool mode

  • whether the installed Rhino should have replication enabled

  • whether to build images with a Rhino license pre-installed

  • a set of JVM tuning parameters that will affect Rhino’s performance

Note

Running Rhino in unclustered mode is no longer supported; only pooled or clustered modes are supported. Pooled mode is similar to unclustered mode in that each Rhino instance needs configuring separately, but also allows certain "clustered-style" operations such as statistics gathering, viewing the status of all Rhino nodes with a single management command, and session replication.

The preinstall-license option

If you choose to build images with a license installed (preinstall-license is set to true), VMBC installs onto the VM the same license that you provide in the build. This way, the end user does not have to provide a license of their own when configuring the VM (though can still replace the license if they wish). Check with your Metaswitch Customer Care Representative as to whether the license you are using to build the VMs is suitable for your end users.

Specifying JVM tuning and garbage collection options

Specify the heap size, new size, and maximum new size options as numbers without any suffix. Values are in megabytes.

You can also specify garbage collection options. These should be in the form of JVM command-line arguments including the "-XX" or similar prefix, one option per line. For example, to enable G1GC (the Garbage First garbage collector) with a 150 ms maximum pause time, specify

gc-options:
  - "-XX:+UseG1GC"
  - "-XX:MaxGCPauseMillis=150"

All JVM tuning parameters are optional. The default heap size is 3072 MB (3 GB), and the default new size and maximum new size is 256 MB.

The default GC options are the same as the Rhino production defaults, which are a suitable starting point for most Rhino applications:

-XX:+UseConcMarkSweepGC
-XX:CMSInitiatingOccupancyFraction=60
-XX:+UseCMSInitiatingOccupancyOnly
-XX:+CMSClassUnloadingEnabled
-XX:+ParallelRefProcEnabled

If you specify anything in the gc-options field, all of these default options no longer apply. Hence, to use CMS but change the initiating occupancy fraction to 70%, you must specify -XX:+UseConcMarkSweepGC and -XX:CMSInitiatingOccupancyFraction=70.

Important We strongly recommend that you experiment to come up with appropriate JVM tuning parameters that match the performance requirements for your application.

Sample node-parameters.yaml file

# The node metadata provides the name and version information for the VM that is being produced
node-metadata:
  # The Linux username that the product code is installed for.
  username: "rhino"

  # The default password for the above user. This can be changed at runtime via configuration.
  default-password: "specify-a-password-here"

  # The name of the product.
  product-name: "Custom VM Rhino Product"

  # A short form of the product name used in naming the output VM. Use hyphens instead of spaces,
  # and prefer lowercase.
  # Also used to derive the CSAR VNF type and the CDS group ID.
  image-name: "custom-vm"

  # A short form of the product name for display purposes, where spaces are acceptable.
  display-name: "Custom VM"

  # The product version number.  No particular format is assumed, but it is used in filenames,
  # and should not contain spaces.
  version: "0.1.0rc2"

  # How many seconds SIMPL should wait for the node to commission.
  # Defaults to 1200, allowed range is 120..3600.
  healthcheck-timeout: 1200

  # How many seconds SIMPL should wait for the node to decommission.
  # Defaults to 900, allowed range is 120..3600.
  decommission-timeout: 900

  # The signaling traffic types used by the VM.
  # Format:
  # - name: <traffic_type_name> (this must be a valid signaling traffic type)
  #   optional: <boolean> (defaults to false if not specified)
  # This field is optional. If not specified, the default traffic types are configured:
  # signaling-traffic-types:
  #     - name: custom-signaling
  #     - name: custom-signaling2
  #       optional: true
  signaling-traffic-types:
      - name: internal
      - name: sip
      - name: diameter
        optional: true

  # Parallel upgrade options.
  # To disable parallel upgrade, remove this section.
  parallel-upgrade:
    # The proportion of the entire deployment that can be upgraded in parallel.
    # The number of VMs upgraded at once is calculated as this factor
    # multiplied by the total number of VMs, and discarding any fractional remainder.
    # For example, if factor is 0.25 and the deployment has 18 VMs,
    # the VMs will be upgraded in groups of 4.
    # This value must be expressed as a number between 0 and 1 (exclusive)
    # and must be formatted as a string.
    # It defaults to 0.25.
    factor: "0.25"

    # The maximum number of VMs to upgrade at once.
    # For example, if factor is 0.25 and we have 16 VMs as above,
    # but max is 3, then the VMs will be upgraded in groups of only 3.
    # This value must be at least 2, and defaults to 10.
    max: 10

# Flavors describe the virtual hardware configuration options for deploying the VM on VMware.
flavors:
  # Name for this configuration
  - name: "small"
    # Optional human-readable description for this configuration
    description: "For small-sized deployments"
    # How much RAM to use for this configuration
    ram-mb: 16384
    # How much disk space to use for this configuration
    disk-gb: 30
    # How many CPUs to allocate to this configuration (v stands for "virtual")
    vcpus: 4

  # A second named configuration - if you only want one configuration then remove this section.
  - name: "medium"
    description: "For medium-sized deployments"
    ram-mb: 16384
    disk-gb: 30
    vcpus: 8

# Rhino parameters affect the behaviour and performance of the installed Rhino instances.
rhino-parameters:
  # Whether the Rhinos on these VM instances will be clustered (true) or pooled (false).
  clustered: false

  # Whether the Rhinos on these VM instances should have replication enabled (true) or not (false).
  # This may only be specified if 'clustered' is true. If 'clustered' is false delete this line.
  # If not specified this defaults to false.
  replication-enabled: false

  # JVM tuning parameters. These parameters affect Rhino performance.
  # The provided values are just examples. They MUST be changed to match the demands of your application.
  tuning-parameters:
    heap-size-mb: 3072
    new-size-mb: 256
    max-new-size-mb: 256

  # Garbage collection (GC) options.
  # If you want to specify custom GC options, uncomment these lines
  # and specify options in full, such as "-XX:+UseConcMarkSweepGC",
  # with each option as a separate list item.
  # gc-options:
  #   - "-XX:+UseConcMarkSweepGC"

  # Whether to build (true) images with a Rhino license pre-installed or not (false).
  # If false, a Rhino license must be provided when configuring the VM(s).
  # If not specified this defaults to true.
  preinstall-license: true
Previous page Next page