- SoftLayer Python library and bundled CLI tool
slcli, https://pypi.python.org/pypi/SoftLayer/4.0.2. See also https://softlayer-api-python-client.readthedocs.org/en/latest/cli/ pip, a Python package management tool, https://pip.pypa.io/en/stable/
Among other functions, the slcli command can order, deprovision (or ‘cancel’), list provisioned, and upgrade servers. Most often you’ll work with virtual servers in this class, but SoftLayer can also provision bare metal servers. Bare metal servers take longer to provision (often some 20 minutes per machine vs. 2 or 3 minutes for VS provisioning), but are higher-performing than virtual servers especially for I/O-heavy operations. Hourly-billed bare metal servers are available and you might find one useful for certain kinds of big data work. For more information, see http://www.softlayer.com/bare-metal-servers.
To learn more about using slcli, consult the documentation at https://softlayer-api-python-client.readthedocs.org/en/latest/cli/ or execute slcli --help to access inline help.
Warning: Many of the below commands order cloud resources and some options are expensive. The provided SoftLayer resource credits are limited; resolve early to provision systems lean. Avoid wasting resources by leaving systems idle and prefer to automate provisioning, performing work and swiftly deprovisioning systems.
The slcli tool is a convenient frontend for the SoftLayer API (http://sldn.softlayer.com/reference/services/SoftLayer_Account). The API is accessible programmatically via SOAP and bindings in particular languages as well as through a ReST interface. The tool jq (http://stedolan.github.io/jq/) can be used with curl to make convenient use of the ReST API (if you execute this command, make sure to replace the fields in <>'s with your own values):
curl 'https://<username>:<key>@api.softlayer.com/rest/v3/SoftLayer_Account/VirtualGuests.json?objectMask=id;hostname;fullyQualifiedDomainName;primaryIpAddress;operatingSystem.passwords' | jq -r '.[] | select(.hostname == "<my_vms_hostname>") | {fullyQualifiedDomainName,id, root_password: .operatingSystem.passwords[] | select(.username == "root").password, primaryIpAddress}'
You should see results like these:
{
"fullyQualifiedDomainName": "ms.some.domain.tld",
"id": 156169,
"root_password": "Z90NxAS5v",
"primaryIpAddress": "5.15.12.250"
}
SSH is a standardized secure remote shell access tool and OpenSSH is a popular implementation of it. You will use OpenSSH to administer SoftLayer systems in this class. Authentication with text passwords is possible with SSH but not recommended. Instead, prefer use of SSH keys. (To learn more about SSH, visit https://digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process).
SSH keys can be generated at will, are stored in ASCII text, and come in pairs. An OpenSSH public key has a name like “id_rsa.pub” and content like this:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDKZ/ykXspE4h8rXQircz/S/bE4LpOkhi+0PX4jZ0JKLsPl1A0jhrR7SLtUFcMVI+7m06fL66F78GxTSd0FjuqszAUPM92INKsp2UnUqtROO0eW3tJk5M/8v3NOLInh9MV/ftq9milaX15pXNZwLZ6jzbhU9TTJecAGoaOP5Yvwlva1po+HXe6rAWJGnpEpoOZu1ZMOJrG5i2H5sP0NJXU5552l3cMMbdhVXOuOWEx7Rejy9YqehWsqFlE7VU0OFos33IyZf25DX2sIJhHpcM3hnXFtKeNDM8Ius9uPd5M+Zhr2fGofnhkThEgjeS3wOlIqA9hb1SEdUK+F+RDP9q/5 some-key-comment
A corresponding private OpenSSH key has a name like “id_rsa” and a header line like this:
-----BEGIN RSA PRIVATE KEY-----
An SSH private key is a personal authentication credential and should not be published or shared. On the other hand, the public key in the keypair should be distributed. In fact, it is by distributing the public key among endpoint servers that passwordless authentication with them is made possible.
For more information on public key cryptography and its history, visit http://arstechnica.com/security/2013/02/lock-robster-keeping-the-bad-guys-out-with-asymmetric-encryption/. For more detail on cryptopgraphy consult https://engineering.purdue.edu/kak/compsec/NewLectures/Lecture12.pdf.
An SSH keypair can be generated on your Unix system and the public key in the pair can be stored in SoftLayer for use with its systems.
Generate an SSH keypair and please add a key passphrase:
ssh-keygen -f ~/.ssh/id_rsa -b 2048 -t rsa -C 'meaningful comment'
Note that the file path we’ve chosen is the default for OpenSSH. If you already have SSH keys on your system you can choose another filename. It is wise to back up SSH keypairs, but please do not store them unencrypted in cloud storage accounts.
Associate the public key with your SoftLayer account (you can pick any meaningful string you’d like for the SSH key identifier):
slcli sshkey add -f ~/.ssh/id_rsa.pub --note 'added during HW 2' <identifier>
SSH key added: d9:14:8b:41:2e:77:3c:fc:a6:04:c6:3b:d5:46:f9:87
Don’t forget the identifer you used in the above command, you’ll need it later.
Salt is a remote execution toolkit with cloud provisioning and configuration management features. In this section, you’ll install SaltStack’s Salt Master and Salt Cloud components on a SoftLayer VS and get acquainted with their core features. For more information on SaltStack, consult http://docs.saltstack.com/en/latest/ref/.
Salt Cloud is a cloud provisioning program that we’ll use to automate provisioning new VSes.
Provision a new VS (you can choose your own datacenter and domain name if you wish; we recommend using a hostname with the ‘saltmaster’ prefix for Salt configuration management convenience). Note that you’re making use of the SSH key you generated earlier:
slcli vs create -d hou02 --os UBUNTU_LATEST_64 --cpu 1 --memory 1024 --hostname saltmaster --domain someplace.net --key identifier
Use slcli vs list to check up on the provisioning VS. Provisioning is finished when you the ‘action’ field in the output has the value ‘-’.
Use slcli vs list and slcli vs credentials <id> or the SoftLayer management web UI (https://control.softlayer.com/) to discover both the public IP address and the root password of your VS. Login to the VS using SSH (note that you must replace the IP_ADDRESS with the IP you’ve discovered):
ssh root@IP_ADDRESS
Make the following two changes in /etc/ssh/sshd_config to prevent brute force attacks
PermitRootLogin prohibit-password
PasswordAuthentication no
Restart the ssh daemon (google is your friend here)
NOTE that these steps will disable password-based authentication; you will be locked out of your VS if you secure it without having ssh key access first
Install Docker per the instructions in [lab 2] (https://github.com/MIDS-scaling-up/coursework/tree/master/week2/labs/docker)
Create a file named 'Dockerfile' with the contents from the snippet below (Make sure you replace the SL_API ID & KEY with your own):
FROM ubuntu:16.04
RUN apt-get update
RUN apt-get install -y wget python-setuptools python-dev build-essential
RUN easy_install pip
RUN wget -O - https://repo.saltstack.com/apt/ubuntu/16.04/amd64/latest/SALTSTACK-GPG-KEY.pub | apt-key add -
RUN echo 'deb http://repo.saltstack.com/apt/ubuntu/16.04/amd64/latest xenial main' > /etc/apt/sources.list.d/saltstack.list
RUN apt-get update
RUN apt-get install -y salt-master salt-minion salt-ssh salt-syndic salt-cloud salt-api
RUN mkdir -p /etc/salt/{cloud.providers.d,cloud.profiles.d}
RUN pip install SoftLayer
RUN echo '[softlayer]' > ~/.softlayer
RUN echo 'username = YOUR_SL_API_ID' >> ~/.softlayer
RUN echo 'api_key = YOUR_SL_API_KEY' >> ~/.softlayer
RUN echo 'endpoint_url = https://api.softlayer.com/xmlrpc/v3.1/' >> ~/.softlayer
RUN service salt-master start
RUN service salt-syndic start
RUN service salt-api start
ENTRYPOINT ["/bin/bash"]
Then build the image:
docker build --tag salt --file Dockerfile .
Skip to the Configure Salt Cloud section below to run your container.
While logged into the VS:
$ sudo apt-get update && sudo apt-get -y upgrade
$ sudo apt-get install python-pip
You may need to upgrade pip:
$ pip install --upgrade pip
Install SoftLayer:
$ pip install softlayer
Copy the ~/.softlayer file from your local machine to your ubuntu server (or use slcli config setup as in Week 1 with your own API ID and KEY):
$ cat > ~/.softlayer
[softlayer]
username = YOUR_SL_API_ID
api_key = YOUR_SL_API_KEY
endpoint_url = https://api.softlayer.com/xmlrpc/v3.1/
timeout = 0
If copying the file (as above using cat), use CTRL-D to complete changes to the file and return to the $ prompt.
Check that slcli works before you proceed to install salt. Try getting a list of your servers:
$ slcli virtual list
Install Salt Stack
Follow these instructions to install Salt Stack: https://repo.saltstack.com/#ubuntu. Don’t bother with the post-install config because the defaults are fine.
- Run the following command to import the SaltStack repository key:
wget -O - https://repo.saltstack.com/apt/ubuntu/16.04/amd64/latest/SALTSTACK-GPG-KEY.pub | sudo apt-key add -
- Save the following file to /etc/apt/sources.list.d/saltstack.list:
cat > /etc/apt/sources.list.d/saltstack.list
deb http://repo.saltstack.com/apt/ubuntu/16.04/amd64/latest xenial main
Use CTRL-D to complete changes to the file and return to the $ prompt.
-
Run
sudo apt-get update -
Install the salt-minion, salt-master, or other Salt components:
sudo apt-get install -y salt-master salt-minion salt-ssh salt-syndic salt-cloud salt-api
- Start all services:
service salt-master start
service salt-syndic start
service salt-api start
mkdir -p /etc/salt/{cloud.providers.d,cloud.profiles.d}
You next must populate some configuration files on the server. For each command below of the form cat > /path, you type the line provided and the shell will put the cursor at the beginning of a new line. Paste into the window the desired content of the configuration file, hit the ENTER key, and then type the sequence CTRL-d and the shell will give you a new prompt (this is easier than it sounds, I promise). Make sure you use space characters instead of tabs for these files as the YAML format requires it.
Alternately you can use an editor of your choice (vim, emacs, nano).
Write a cloud provider configuration file. Note that you must use your own SL_API ID and KEY as well as your own VM PUBLIC ID.
cat > /etc/salt/cloud.providers.d/softlayer.conf
sl:
minion:
master: YOUR_VM_PUBLIC_IP
user: YOUR_SL_API_ID
apikey: YOUR_SL_API_KEY
driver: softlayer
Verify that you’ve properly written the file to disk:
cat /etc/salt/cloud.providers.d/softlayer.conf
sl:
minion:
master: ...
Write a cloud profiles configuration file:
$ cat > /etc/salt/cloud.profiles.d/softlayer.conf
sl_ubuntu_small:
provider: sl
image: UBUNTU_LATEST_64
cpu_number: 1
ram: 1024
disk_size: 25
local_disk: True
hourly_billing: True
domain: somewhere.net
location: dal06
IF you are using Option 1 (Docker), then run this command to start the container:
docker run -it -v /etc/salt/cloud.providers.d:/etc/salt/cloud.providers.d -v /etc/salt/cloud.profiles.d:/etc/salt/cloud.profiles.d salt
Execute:
salt-cloud -p sl_ubuntu_small mytestvs
You should observe output like this:
mytestvs:
----------
accountId:
278184
createDate:
2015-05-11T20:31:00-07:00
domain:
somewhere.net
fullyQualifiedDomainName:
mytestvs.somewhere.net, sc
globalIdentifier:
9daf76df-b468-4a7b-a1c2-0ab9d60a216a
hostname:
mytestvs
...
(Note that this command does a complete provisioning process and may take a few minutes to complete).
When it provisions a new VS, Salt Cloud can enlist the new VS in its management system. The VS under management is called a Salt “Minion”.
Execute:
salt-key -L
Observe output like the following:
Accepted Keys:
mytestvs
...
Retrieve a system’s configured public IP address:
Execute:
salt 'mytestvs' network.interface_ip eth1
mytestvs:
158.85.137.185
Retrieve network statistics for all systems under management:
salt '*' status.netstats
mytestvs:
----------
IpExt:
----------
InBcastOctets:
3628
InBcastPkts:
...
Before canceling the two VSes you’ve been manipulating, try some more Salt remote execution commands. You can find a list of modules at http://docs.saltstack.com/en/latest/ref/modules/all/. Try to find the applicable execution modules and perform these tasks:
- Resolve a DNS name from the minion (hint: the output will be an IP address)
- Transmit a file from the master to the minion using salt commands
- Use salt to increase the minion OS’s maximum file descriptors limit, apply the changes, and confirm that the increased limit has been set by the OS (hint: the ulimit command is used to check this value)
Salt Cloud can deprovision VSes. This can sometimes be a valuable alternative to the slcli command because Salt’s pattern-matching can be used to delete groups of VMs by name. For now, simply delete the VS we’ve been manipulating:
salt-cloud -dy mytestvs
softlayer:
----------
mytestvs:
True
SoftLayer Object Storage is a reliable key-value storage system. You can interact with either programmatically using a library or through the REST API using an HTTP client like a web browser or the command line tool cURL.
To use Object Storage, you must first order the service and create a container. Multiple containers can be associated with a given account and are a mechanism to separate data. Not unlike a storage device in a personal computing system, a container can store objects and (optionally) folders.
First, create a pay-as-you-go Object Storage account. Issue the command using the special pasting method described earlier for input beginning {"parameters" : … . The jq call will extract the necessary id of of the ordered item for use in following steps. (Note that the command may take a moment to complete execution).
curl 'https://<username>:<api_key>@api.softlayer.com/rest/v3.1/SoftLayer_Product_Order/placeOrder' --data @- | jq -r '.placedOrder.items[] | select(.itemId == 4069) | {id}'
{"parameters" : [
{
"complexType": "SoftLayer_Container_Product_Order_Network_Storage_Hub",
"quantity": 1,
"packageId": 0,
"prices": [{ "id": 16984}]
}
]}
Observe output like:
{
"id": 66901067
}
Each Object Storage account has a storage username you’ll need to use to interact with the storage system. To retrieve yours, execute:
curl 'https://<username>:<api_key>@api.softlayer.com/rest/v3.1/SoftLayer_Account/getHubNetworkStorage.json?objectMask=id;username;billingItem.id;billingItem.orderItemId' | jq -r '.[] | select(.billingItem.orderItemId == <66901067>) | {username}'
Retain the output value:
{ "username": "GGAF-23584-48" }
To manipulate objects in Object Storage you’ll need an authentication token. This is a credential that is valid for approximately 1 day and is required in all HTTP calls to the API. Obtain this information with a call like the one below. Note that a specific datacenter is picked out: Object Store data is specific to a data center and not automatically replicated between them. Also note use of the -i option to curl, this will print HTTP response headers before the payload of the response.
curl -i -H "X-Auth-User:<GGAF-23584-48>:<username>" -H "X-Auth-Key:<api_key>" https://<dal05>.objectstorage.softlayer.net/auth/v1.0
HTTP/1.1 200 OK
...
X-Auth-Token: AUTH_tk1152128357891357189351477
X-Storage-Url: https://dal05.objectstorage.softlayer.net/v1/AUTH_71923841-27f2-4bfa-917d-0cb237987972
...
Retain the values of these two HTTP response headers for subsequent HTTP calls.
Now that you have authentication information and a storage URL you can create a container (note the use of values from previous command's output):
curl -i -X PUT -H "X-Auth-Token: AUTH_tk1152128357891357189351477" https://dal05.objectstorage.softlayer.net/v1/AUTH_71923841-27f2-4bfa-917d-0cb237987972/<myfiles>
curl -i -H "X-Auth-Token: AUTH_tk1152128357891357189351477" https://dal05.objectstorage.softlayer.net/v1/AUTH_71923841-27f2-4bfa-917d-0cb237987972
Note that the primary difference between this command and the creation command is the HTTP method: an HTTP PUT request was used to add a container, the HTTP GET method is assumed if not provided to curl and for this method the SoftLayer API returns a list of containers (below the header output).
Curl can send binary data in an HTTP request and the Object Storage API will store that data in a container. To try it, execute a command like the following. Note the specification of the container and destination file name in the URL path:
curl -i -X PUT -H "X-Auth-Token: AUTH_tk1152128357891357189351477" https://dal05.objectstorage.softlayer.net/v1/AUTH_71923841-27f2-4bfa-917d-0cb237987972/<myfiles/test_file.txt> --data-binary "<some test text>"
You can retrieve this file with another HTTP request:
curl -H "X-Auth-Token: AUTH_tk1152128357891357189351477" https://dal05.objectstorage.softlayer.net/v1/AUTH_71923841-27f2-4bfa-917d-0cb237987972/myfiles/test_file.txt
Output:
some test text
The method we used to test the Object Store are not very convenient. There is a Python library named swift you can use to mitigate the tedium. Install the swift client with the command:
sudo pip install python-swiftclient
Configure the client by setting environment like this:
export ST_AUTH=https://<dal05>.objectstorage.softlayer.net/auth/v1.0
export ST_USER=GGAF-23584-48:<username>
export ST_KEY=<api_key>
You can list containers with swift:
swift list
List files in a container:
swift list myfiles
Download a file from a container:
swift download myfiles test_file.txt
Upload a file from disk (named “another_test_file.txt”) to a new container named “more_files”:
echo "more test content" > /tmp/another_test_file.txt
swift upload more_files /tmp/another_test_file.txt
Provide output of ordering a Virtual Server with the SL CLI and Provision a new VS with Salt Cloud.