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, 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 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

The AWS setup guide provides the steps required to get a software event broker cloud image running and ready for messaging in Amazon Web Services (AWS). Step 3: 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 PubSub+ software event broker image in AWS, 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

You can also provision the software event broker storage-group at initial setup. You can perform the initialization with a two-step process. In this example the volume storage-group is assigned to a block device, and the admin user is configured and assigned a password.

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

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

   The storage device appears in the software event broker host as xvdb.

2. On AWS's Add Storage screen in the configuration process for the software event broker Cloud Image, add a new volume on which the storage-group will reside. In this example, a 30 GB device called /dev/sdb has been added.

   

3. After you log into the software event broker's host, you can run the solacectl storage command to view 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
   
   /dev/xvdb1                                        30G       1.3G      29G       /mnt/vmr
   ├─storage-group                                   30G       1.0G      29G       /mnt/vmr/storage-group/_data
   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.