Introduction

To install at boot, an agent to interpret userdata or metadata and act on it is needed. For Linux, RightLink uses cloud-init for this purpose. Cloud-init accomplishes two things:

  1. Getting the credentials (identity parameters) needed to initialize a RightScale Server via user-data.
  2. Optionally installing and running RightLink at boot time if its not already installed.

The user-data that drives cloud-init is generated by the RightScale platform based on tags on the MultiCloudImage (MCI) and/or the Server/ServerArray. This generated user-data works for most flavors of Linux.

Launching a Server with a Stock Image

To install RightLink at boot, an image must contain a suitable cloud-init that supports user-data retrieval from the cloud. Two tags are needed to install RightLink 10 at boot. The first identifies the instance as RightLink10 based to the RightScale platform. The second causes cloud-init to run a shell script to download and install RightLink. The MultiCloudImage (MCI) or Server must be tagged with:

  1. rs_agent:type=right_link_lite
  2. rs_agent:mime_shellscript=https://rightlink.rightscale.com/rll/10.6.1/rightlink.boot.sh

The second tag above will install version 10.6.1 of RightLink. As a convenience, more generic versions such as 10 or 10.6 may be specified as a way to install the latest GA version for a lineage. For example, add tag rs_agent:mime_shellscript=https://rightlink.rightscale.com/rll/10/rightlink.boot.sh to install the latest 10.x.x agent. See the releases page for full list of supported versions to install and release notes.

Since the script/agent are being downloaded and installed at boot time, there must be outbound connectivity to the rightlink.rightscale.com IP addresses. If there is no outbound connectivity for the instance a proxy should be specified using the rs_agent:http_proxy tag.

It it recommended to use the RightLink 10.x.x Linux Base ServerTemplate available from the Marketplace as a starting point. See the releases page for links.

The simplest way to use your own images is to install cloud-init on them.

Advanced Usage

Supported tags

The RightScale platform supports the following tags for RightLink 10 based instances. There are an additional number of non RightLink 10 specific tags which you can also set. Many of the tags listed on that page are RightLink 6 specific, however all the rs_agent:http_proxy tags apply.

Tag Purpose
rs_agent:type=right_link_lite Required: tells the platform this is a RightLink 10 based instanced.
rs_agent:mime_shellscript=<url> Optional: for mime userdata, downloads and execute the contents of the URL with a simple canned shell script. This better supports older/alternate versions of cloud-init and is also compatible with the rs_agent:http_proxy tag.
default: none
rs_agent:mime_include_url=<url> Optional: downloads and execute the contents of the URL using x-include-url. Deprecated: This tag is NOT compatible with the rs_agent:http_proxy tag.
default: none
rs_agent:powershell_url=<url> Optional: for powershell userdata, downloads and execute the contents of the URL using a canned Powershell script. Compatable with rs_agent:http_proxy tag.
default: none
rs_agent:userdata=(mime|liquid|powershell) Optional: determines the format of the user-data being produced by the platform
  • mime: default for Linux - multipart MIME document
  • powershell: default for Windows - powershell script block
  • liquid: arbitrary; user_data field of MCI/server is rendered as a Liquid template
rs_agent:mime_identity=(shellscript|write_file) Optional: for mime userdata, determines how RightLink agent identity parameters are placed on the instance
  • shellscript: x-shellscript MIME part (default)
  • write_file: cloud-config MIME part containing write_files action

User-Provided User-data

In addition to the generated user-data, The MCI or Server can have user-data and it will be added to the user-data for the instance as follows:

if rs_agent:userdata=mime

  • if the value starts with #! then a text/x-shellscript part is produced
  • if the value starts with http then a text/x-include-url part is produced
  • else the value is placed as-is in a text/plain mime part and should start with a # directive for cloud-init to process it properly

if rs_agent:userdata=liquid

  • the user-data is processed as a liquid template

if rs_agent:userdata=powershell

  • the user-data will be treated as a powershell code block and appended to the rest of the RightScale-generated powershell code.

Liquid User-data

When rs_agent:userdata=liquid is specified on the MCI or server, the platform makes no attempt to format the user-data; instead, it treats the MCI's or incarnator's user data as a Liquid template. The core renders this template, providing an rs_agent object with RightLink / RightLink 10 parameters as its properties.

To use a liquid template with a Server, edit the Server and paste the liquid template into the User Data field in Server Details -> Advanced Options. To use a liquid template with an MCI, paste the liquid template into the User Data field for the image in the Clouds tab for the MCI. Note each cloud/image will have to be edited individually.

Sample Template

The following example generates a cloud-config document for a CoreOS system. It contains a write_files section that writes the instance tokens to the identity file. It uses a for-loop to iterate blindly over the rs_agent variables, making it future-proof if new agent parameters are added. It also has the nice property that conditionally-present variables such as auto_launch and http_proxy do not require a Liquid conditional. If an http_proxy is set via the tag rs_agent:http_proxy it will use it, otherwise the environment variable will be empty and ignored.

#cloud-config

write_files:
  - path: /var/lib/rightscale-identity
    permissions: '0600'
    content: |
      {% for pair in rs_agent %}{{pair[0]}}={{pair[1]}}
      {% endfor %}
coreos:
  units:
    - name: rightlink-install.service
      command: start
      content: |
        [Unit]
        Description=Installs RightLink 10 at boot

        [Service]
        Type=oneshot
        RemainAfterExit=yes
        Environment="https_proxy={{ rs_agent.http_proxy }}"
        ExecStart=/usr/bin/bash -c "/usr/bin/curl -s https://rightlink.rightscale.com/rll/10.6.1/rightlink.boot.sh | /usr/bin/bash"