Getting Started with Spread

Introduction

Spread is an open source command line tool that makes it easy to version Kubernetes objects, set up a local Kubernetes cluster (see: localkube), and deploy to Kubernetes clusters in one command.

In this guide, you'll learn how to install Spread, set up your project directory, and deploy an example application.

You'll also find detailed documentation on Spread commands.

Let's get started! This guide assumes you've installed the following:

• Git
• Go (v 1.6)

Install Spread

Install with go get (-d is for download only):

$ go get -d rsprd.com/spread/cmd/spread

Go into the correct directory:

cd $GOPATH/src/rsprd.com/spread

If libgit2 is not installed:

make install-libgit2

Then:

make build/spread

If an error about libraries missing comes up, set up your library path like:

export LD_LIBRARY_PATH=/usr/local/lib:$ LD_LIBRARY_PATH

Or, if you prefer using Homebrew (OS X only):

$ brew tap redspread/spread
$ brew install spread-versioning

Set Up Your Directory

Note: If you'd like to use our example repo, skip this step! If you'd like to set up your own repo, carry on.

In order to take advantage of Spread's one-command deploy feature, spread deploy, you'll need to set up your directory with a few specific naming conventions:

• All ReplicationController and Pod files should go in the root directory
• Any ReplicationController files should end in .rc.yaml or .rc.json, depending on the respective file extension
• Any Pod files should end in .pod.yaml or .pod.json, depending on the respective file extension
• All other Kubernetes object files should go in a directory named rs

There is no limit to the number of ReplicationControllers or Pods in the root directory.

Here is an example directory with Spread's naming conventions:

Dockerfile
app.rc.yaml
database.rc.yaml
rs
 |_
 	  service.yaml
    secret.yaml

Spin Up a Kubernetes Cluster

In order to deploy your application, you'll need to have a running Kubernetes cluster (local or remote).

To spin up a local cluster:

This assumes you have the following installed:

• Docker
• docker-machine
• VirtualBox
• kubectl*

(Note: For Mac and Windows users, the fastest way to install everything is Docker Toolbox.)

Get started:

1. Create a machine called dev: docker-machine create --driver virtualbox dev
2. Start your docker-machine: docker-machine start dev
3. Connect to the docker daemon: eval "$(docker-machine env dev)"
4. Spin up a local cluster using localkube: spread cluster start
5. To stop the cluster: spread cluster stop

To spin up a remote cluster:

• Follow all the steps in this quickstart guide for spinning up a cluster on Google Cloud Platform.

*For local development, it's useful to also install kubectl, the command line tool for interacting with the Kubernetes API. You can download kubectl from the Kubernetes release artifact site with the curl tool.

Linux:

$ curl -O https://storage.googleapis.com/kubernetes-release/release/v1.2.3/bin/linux/amd64/kubectl

Darwin:

$ curl -O https://storage.googleapis.com/kubernetes-release/release/v1.2.3/bin/darwin/amd64/kubectl

After downloading the binary, ensure it is executable and move it into your PATH:

$ chmod +x kubectl  
$ mv kubectl /usr/local/bin/kubectl

Deploy Example Application

You're ready to deploy your first application! We've got one set up for you already to deploy:

1. Clone Mattermost, the open source Slack: $ git clone http://github.com/redspread/kube-mattermost
2. Deploy Mattermost to your cluster: $ spread deploy .
3. For remote clusters, the IP address is returned to you to put into your browser. For local clusters, the NodePort is returned to you, and you can find the IP address with docker-machine env <MACHINE_NAME>, then put the IP:NodePort into your browser to see your self-hosted app!

For a more detailed walkthrough of setting up this Mattermost application, see the full guide.

Next Steps

Explore Spread's commands in more detail.