Initializing a Machine Image using cloud-init

You can initialize a software event broker cloud or machine image with the cloud-init utility. At start-up, cloud-init iterates through a list of provisioned datasources looking for valid meta-data and user-data.

  • meta-data is supplied as key value pairs, and can be used to configure instance specific parameters such as instance-id, hostname, and local IP addresses.
  • user-data can be provided in many forms including files, scripts, and #cloud-config, which provides YAML-formatted cloud-init specific instructions. It can be used to update instance software packages, execute first-boot scripts, install certificates and configure users, groups, and authentication keys.

The software event broker doesn't prevent the processing of any user-data (including #cloud-config commands) that are not applicable, or possibly harmful to system stability. Also, the software event broker neither prevents user-data from including scripts, nor does it selectively execute script content.

The following table lists the valid datasources for the various software event brokers.

Solace PubSub+ software event broker Datasources
Standard, all VM Images NoCloud
Standard, AMI for Amazon Web Services EC2
Standard, OpenStack OpenStack
Enterprise Evaluation Edition, all VM Images NoCloud
Enterprise Evaluation Edition, AMI for Amazon Web Services EC2
Enterprise Evaluation Edition, OpenStack OpenStack
Enterprise, all VM Images NoCloud
Enterprise, AMI for Amazon Web Services EC2
Enterprise, Open Stack OpenStack

The NoCloud datasource can load user provided initial configuration in user-data and meta-data from an ISO loaded in the Virtual Machine Guest CDROM drive. For instructions on how to create the ISO, see Creating NoCloud Datasources.

Setting Configuration Keys

You can use a cloud-init module called solace to define configuration keys as environment variables for the software event broker's container. Configuration via environment variables is supported where the variable name consists of the configuration key hierarchy concatenated with the underscore character. Environment variables are specified in /etc/solace/solace-container.env.conf, and configuration keys set by the solace moduleʼs configuration_keys directive are written to /etc/solace/solace-container.env.conf.

The solace module, shown with its associated configuration_keys directive, has the following syntax within #cloud-config.

#cloud-config
solace:
configuration_keys:
<CONFIGURATION_KEY>: <VALUE>
<CONFIGURATION_KEY>: <VALUE>

Configuration Keys for the Software Event Broker

To learn more about the configuration keys that you can use with the software event broker, see Configuration Keys.

Assigning Volumes to External Storage Devices

You can assign persistent storage volumes to external storage devices with cloud-init using the solace moduleʼs storage directive. The solace module, shown with its associated configuration_keys and storage directives, has the following syntax within #cloud-config.

#cloud-config
solace:
  configuration_keys:
    <CONFIGURATION_KEY>: <VALUE>
    <CONFIGURATION_KEY>: <VALUE>
  storage:
    <VOLUME>:
      device: <DEVICE>

An example of the use of the storage directive is shown in Initializing the Configuration for AWS.

Initializing User Authentication

By default, the sysadmin user account is unlocked with an undefined password. Remote login is explicitly blocked until the sysadmin user password has been defined.

In cloud environments, the provider typically configures sysadmin users with a qualified cloud-init datasource, and usually sysadmin users are also assigned public/private SSH keys from cloud-init user-data. However, it is also possible for you to define the sysadmin password with cloud-init user-data, and you may also define additional host user accounts using cloud-init user-data.

In enterprise environments, the system administrator is responsible for creating and configuring software event broker instances. Typically, the sysadmin user is assigned a password on first login attempt at the Virtual Machine console. It is also possible to assign the password, or supply a public/private SSH key with cloud-init user-data, provided by an ISO image installed in the virtual machine CD-ROM drive. For example, text similar to the following #cloud-config snippet can be used to set the sysadmin password.

#cloud-config

password: sysadmin chpasswd: {expire: False}

Initializing the Timezone

For software event broker 9.4.0 release onwards, you can set the timezone by adding the timezone: <timezone> in the #cloud-config. As shown in the example below, the following #cloud-config snippet sets the timezone to Canada/Eastern.

#cloud-config

password: sysadmin chpasswd: {expire: False} timezone: Canada/Eastern

Configuring the Maximum Number of Connections

You can configure the maximum number of client connections with the system/scaling/maxconnectioncount configuration key. For more information, see Modifying System Limits Using System Scaling Parameters.

The following shows an example of a user-data text snippet that sets the maximum client connection value to 10,000.

#cloud-config
solace:
configuration_keys:
system_scaling_maxconnectioncount: 10000

Creating NoCloud Datasources

PubSub+ software event brokers that are configured to accept the NoCloud cloud-init datasource can load an initial configuration from an ISO loaded in the Virtual Machine Guest CDROM drive.

To create an ISO, perform the following steps:

  1. Create a text file named meta-data. This file may be empty with a length of 0 bytes, or may contain any valid YAML for cloud-init meta-data.
  2. Create a text file named user-data. This file may be empty with a length 0 bytes, or may contain any valid YAML for cloud-init user-data.
  3. Generate the ISO using genisoimage or mkisofs on the Linux host.
    genisoimage -output docker_subnet.iso -volid cidata -joliet -rock user-data meta-data

    or

    mkisofs -output docker_subnet.iso -volid cidata -joliet -rock user-data meta-data

Initializing the Configuration for AWS

AWS Manual Set Up provides the steps required to get a software event broker cloud image running and ready for messaging in Amazon Web Services (AWS). Step 2: Access the Solace CLI , used for setting the admin userʼs password, can be simplified through the use of the configuration keys username/<name>/globalaccesslevel and username/<name>/password. Setting up the admin user using configuration keys allows you to go directly to SolAdmin to manage the Solace PubSub+ software event broker, skipping additional configuration steps in Solace CLI.

Configuring the Admin User

To configure the admin user and assign a password during the initial setup of an AWS Solace PubSub+ software event broker Image, you can enter configuration keys as user-data text, where the user-data consists of the configuration key hierarchy concatenated with the underscore character. Configuration keys as user-data text can be entered into the User data block in the Advanced Details section of the Configure Instance Details screen. In the example below, the password is adminpwd.

#cloud-config

solace:
  configuration_keys:
     username_admin_globalaccesslevel: admin
     username_admin_password: adminpwd

Provisioning Storage for the Software Event Broker

Storage of software event broker storage-elements can also be provisioned at initial setup. You can perform the initialization with a two-step process. In this example the volumes adb and internalSpool will be assigned to a block device, and the admin user will be configured and assigned a password.

  1. You can enter the following user-data text into the User data block in the Advanced Details section of the Configure Instance Details screen:

    #cloud-config
    solace:
      configuration_keys:
         username_admin_globalaccesslevel: admin
         username_admin_password: adminpwd
         service_ssh_port: 22
         service_semp_port: 8080
      storage:
         adb:
             device: xvdb
         internalSpool:
             device: xvdb

  2. The storage device will appear in the software event broker host as xvdb.

  3. At AWSʼs Add Storage screen in the software event broker Cloud Image configuration process, add a new volume on which adb and internalSpool will reside. In this example, a 30 GB device called /dev/sdb has been added.
  4. After logging into the software event brokerʼs host, the solacectl storage command can be used to show the new storage assignment.
    >sudo solacectl storage ls
    Block Devices:
    Name Size Note
    xvda 30.0G Main device
    └─xvda1 0.2G
    └─xvda2 29.8G
    xvdb 30.0G
    └─xvdb1 30.0G
    Storage Volumes:
    Name Size Used Available Path
    /dev/mapper/vg01-root 9.8G 1.1G 8.8G /
    /dev/mapper/vg01-solace 9.8G 67M 9.7G /var/lib/docker/volumes
    ├─adbBackup 9.8G 0 9.7G /var/lib/docker/volumes/adbBackup/_data
    ├─diagnostics 9.8G 4.0K 9.7G /var/lib/docker/volumes/diagnostics/_data
    ├─etc 9.8G 4.0K 9.7G /etc/solace/solace-container.d
    ├─jail 9.8G 9.8M 9.7G /var/lib/docker/volumes/jail/_data
    └─var 9.8G 25M 9.7G /var/lib/docker/volumes/var/_data
    /dev/xvdb1 30G 1.3G 29G /mnt/vmr
    ├─adb 30G 1.0G 29G /mnt/vmr/adb
    └─internalSpool 30G 274M 29G /mnt/vmr/internalSpool
    Image Pool:
    Name Size Used Available
    Image pool 8.905 GB 1.033 GB 7.872 GB

Enabling CloudWatch

The docker-create-opt directive is used to configure the Amazon CloudWatch Docker logging driver. For more information about that driver, refer to Amazon CloudWatch Logs logging driver on Docker's documentation site.

solace:
  docker-create-opt:
    log-driver: awslogs
    log-opt:
      - awslogs-region=<region>
      - awslogs-group=<LogGroup>
      - awslogs-create-group=true

When configuring the Amazon CloudWatch log driver, you may want to use the logging configuration keys to output additional logs to stdout because anything sent to stdout will be sent to CloudWatch.