From c3a29f494033ee409580fb6bec3ca0f5c0bd8c08 Mon Sep 17 00:00:00 2001 From: Renan DelValle Date: Thu, 11 Aug 2016 11:39:10 -0700 Subject: [PATCH] Integrated information from using the sample client document and reframed the sample client document. Added a link from the README to the getting-started page. --- README.md | 3 +- ...{Getting_Started.md => getting-started.md} | 75 +++++++++++++++---- docs/using-the-sample-client.md | 57 +++++++------- 3 files changed, 89 insertions(+), 46 deletions(-) rename docs/{Getting_Started.md => getting-started.md} (79%) diff --git a/README.md b/README.md index 21f872b..b780f79 100644 --- a/README.md +++ b/README.md @@ -9,12 +9,13 @@ library has been tested. Vendoring a working version of this library is highly r ## Usage +* [Getting started](docs/getting-started.md) * [Using the sample client](docs/using-the-sample-client.md) * [Leveraging the library](docs/leveraging-the-library.md) ## To Do -* Create or import a custom transport that uses https://github.com/jmcvetta/napping to improve efficiency * Allow library to use ZK to find the master +* Create or import a custom transport that uses https://github.com/jmcvetta/napping to improve efficiency * End to end testing with Vagrant setup ## Contributions diff --git a/docs/Getting_Started.md b/docs/getting-started.md similarity index 79% rename from docs/Getting_Started.md rename to docs/getting-started.md index 39937e8..ff30a02 100644 --- a/docs/Getting_Started.md +++ b/docs/getting-started.md @@ -10,6 +10,28 @@ the cluster between the vagrant image and the package manager will be clarified Follow the **[guide](https://github.com/apache/aurora/blob/master/docs/getting-started/vagrant.md)** at the Aurora repository in order to spin up a local cluster until step 4 (Start the local cluster). +### Pre-configured Vagrant box +Alternatively, if Vagrant and VirtualBox are already configured your machine, +you may use a pre-configured vagrant image and skip to the [Creating Aurora Jobs](#creating-aurora-jobs). + +To take this path, start by cloning the following repository: +``` +$ git clone git@github.com:rdelval/aurora.git +``` + +Checking out the DockerComposeExecutor branch: +``` +$ git checkout DockerComposeExecutor +``` + +And bringing the vagrant box +``` +$ cd aurora +$ vagrant up +``` + +**The pre-configured Vagrant box will most likely run on a stale version of Aurora (compared to the master)** + ## Configuring Scheduler to use Docker-Compose executor In order use the docker compose executor with Aurora, we must first give the scheduler a configuration file that contains information on how to run the executor. @@ -169,7 +191,6 @@ Finally, we must get `gorealis` using the `go get` command: go get github.com/rdelval/gorealis ``` - # Creating Aurora Jobs ### Creating a thermos job @@ -236,38 +257,64 @@ go run $GOPATH/src/github.com/rdelval/gorealis/examples/client.go -executor=comp ``` If everything went according to plan, a new job will be shown in the Aurora UI. - -We can further investigate inside the Mesos task sandbox. - -Inside the sandbox, under the sample-app folder, we can find a docker-compose.yml-generated.yml. - -If we inspect this file, we can find the port at which we can find the web server we launched. +We can further investigate inside the Mesos task sandbox. Inside the sandbox, under +the sample-app folder, we can find a docker-compose.yml-generated.yml. If we inspect this file, +we can find the port at which we can find the web server we launched. Under Web->Ports, we find the port Mesos allocated. We can then navigate to: `:`. (In vagrant's case the agent address is `192.68.33.7`) A message from the executor should greet us. -## Cleaning up +# Creating a Thermos job using gorealis +It is also possible to create a thermos job using gorealis. To do this, however, +a thermos payload is required. A thermos payload consists of a JSON blob that details +the entire task as it exists inside the Aurora Scheduler. *Creating the blob is unfortunately +out of the scope of was gorealis does*, so a thermos payload must be generated beforehand or +retrieved from the structdump of an existing task for testing purposes. + +A sample thermos JSON payload may be found [here](../examples/thermos_payload.json) in the examples folder. + +The job struct configuration for a Thermos job looks something like this: +``` +payload, err := ioutil.ReadFile("examples/thermos_payload.json") + +job = realis.NewJob(). + Environment("prod"). + Role("vagrant"). + Name("hello_world_from_gorealis"). + ExecutorName(aurora.AURORA_EXECUTOR_NAME). + ExecutorData(string(payload)). + CPU(1). + RAM(64). + Disk(100). + IsService(true). + InstanceCount(1). + AddPorts(1) +``` + +Using a vagrant setup as an example, we can run the following command to create a Thermos job: +``` +$ cd $GOPATH/src/github.com/rdelval/gorealis +$ go run examples/client.go -executor=thermos -url=http://192.168.33.7:8081 -cmd=create -executor=thermos +``` + +# Cleaning up To stop the jobs we've launched, we can need to send a job kill request to Aurora. It should be noted that although we can't create jobs using a custom executor using the default Aurora client, we can use the default Aurora client to kill them. In addition, we can use gorealis perform the clean up as well. -### Using the Default Client +## Using the Default Client ``` $ aurora job killall devcluster/www-data/prod/hello $ aurora job killall devcluster/vagrant/prod/docker-compose ``` - -### Using gorealis +## Using gorealis ``` $ go run $GOPATH/src/github.com/rdelval/gorealis/examples/client.go -executor=compose -url=http://192.168.33.7:8081 -cmd=kill $ go run $GOPATH/src/github.com/rdelval/gorealis/examples/client.go -executor=thermos -url=http://192.168.33.7:8081 -cmd=kill ``` - - - diff --git a/docs/using-the-sample-client.md b/docs/using-the-sample-client.md index f00f031..ec08ee6 100644 --- a/docs/using-the-sample-client.md +++ b/docs/using-the-sample-client.md @@ -1,48 +1,43 @@ -### Using the Sample client with Thermos -Clone Aurora: +# Using the Sample client with Thermos + +## Usage: ``` -$ git clone git://git.apache.org/aurora.git +client: + -cmd string + Job request type to send to Aurora Scheduler + -executor string + Executor to use (default "thermos") + -password string + Password to use for authorization (default "secret") + -updateId string + Update ID to operate on + -url string + URL at which the Aurora Scheduler exists as [url]:[port] + -username string + Username to use for authorization (default "aurora") ``` -Bring up the vagrant image: -``` -$ cd aurora -$ vagrant up -``` +## Sample commands: +These commands are set to run on a vagrant box. To be able to runt he docker compose +executor examples, the vagrant box must be configured properly to use the docker compose executor. -Download and run the Client to create a Thermos Job: +### Thermos +#### Creating a Thermos job ``` -$ go get github.com/rdelval/gorealis $ cd $GOPATH/src/github.com/rdelval/gorealis $ go run examples/client.go -executor=thermos -url=http://192.168.33.7:8081 -cmd=create ``` - -### Using the Sample client with Docker Compose executor - -Clone modified version of Aurora repo and checkout the right branch: +#### Kill a Thermos job ``` -$ git clone git@github.com:rdelval/aurora.git -$ git checkout DockerComposeExecutor +$ go run $GOPATH/src/github.com/rdelval/gorealis.git/examples/client.go -executor=thermos -url=http://192.168.33.7:8081 -cmd=kill ``` -Bring up the vagrant image: +### Docker Compose executor (custom executor) +### Creating Docker Compose executor job ``` -$ cd aurora -$ vagrant up -``` - -Download and run the Client to create a Docker-Compose Job: -``` -$ go get github.com/rdelval/gorealis $ go run $GOPATH/src/github.com/rdelval/gorealis/examples/client.go -executor=compose -url=http://192.168.33.7:8081 -cmd=create ``` -From the [Aurora web UI](http://192.168.33.7:8081/scheduler/vagrant/prod/docker-compose/0), create struct dump by clicking on the task ID. -In the struct dump, find the port assigned to the task (named "port0"). - -Navigate to the 192.168.33.7:``. -If the page is not found, wait a few minutes while the docker image is downloaded and the container is deployed. - -Finally, terminate the job: +### Kill a Docker Compose executor job ``` $ go run $GOPATH/src/github.com/rdelval/gorealis.git/examples/client.go -executor=compose -url=http://192.168.33.7:8081 -cmd=kill ```