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

Typically only the rs_agent:type and rs_agent:mime_include_url tags are used in order to bootstrap RightLink. To do this, the image must contain a suitable cloud-init that supports user-data retrieval from the cloud. The MultiCloudImage (MCI) must be tagged with rs_agent:type=right_link_lite. The MCI should be tagged with a suitable rightlink.boot.sh script, such as rs_agent:mime_include_url=https://rightlink.rightscale.com/rll/10.5.2/rightlink.boot.sh. As a convenience, more generic versions such as 10 or 10.5 may be specified as a way to install the latest GA version for a lineage. To use, add tag rs_agent:mime_include_url=https://rightlink.rightscale.com/rll/10/rightlink.boot.sh. See the releases page for full list of supported versions to install and release notes.

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.

Tag Purpose
rs_agent:type=right_link_lite Required: tells the platform the type of agent for the purpose of inferring its capabilities. This tag causes the values emitted in the user-data to be tailored to the agent type
rs_agent:mime_include_url=<url> Optional: downloads and execute the contents of the URL using x-include-url. This is the mechanism used to accomplish (2) above and install RightLink at boot time. This tag is NOT compatible with the rs_agent:http_proxy tag.
default: none
rs_agent:mime_shellscript=<url>
rs_agent:hashbang_shellscript=<url>		 Optional: simulates x-include-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:userdata=(query|mime|liquid) Optional: determines the format of the user-data being produced by the platform
  • query: URL-encoded querystring of key/value pairs
  • mime: multipart MIME document
  • liquid: arbitrary; user_data field of MCI/server is rendered as a Liquid template
default: mime if agent type is right_link_lite, query otherwise
rs_agent:mime_identity=(shellscript|write_file) Optional: 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
rs_agent:mime_identity_path=<filepath>
rs_agent:hashbang_identity_path=<filepath>		 Optional: determines where the agent identity parameters are placed
default: /var/lib/rightscale-identity

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=query

  • an ampersand ('&') is appended to the RightScale produced user-data and the user-provided string is appended to that

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

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.

The properties available on the rs_agent object depend on whether the MCI is marked as RightLink or RightLink 10; the properties are named consistently with the key names that would normally be injected as query-string or MIME user-data (e.g. RS_rn_id is one property name if rs_agent:type=right_link and client_id is one property if rs_agent:type=right_link_lite). It is assumed that Liquid rendering will only be used for RightLink 10 agents and only those values are documented here.

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.5.2/rightlink.boot.sh | /usr/bin/bash"