ridv/gorealis-v2
1
0
Fork 0
Code Issues Pull requests Projects Releases 13 Packages Wiki Activity Actions

Updating documentation for release

Browse source 
Moving godoc reference button

changing casing of top title
This commit is contained in:
Renan DelValle 2016-08-09 16:18:30 -07:00
parent 8e7d7b72d4
commit bf890bf9b0
5 changed files with 48 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

13
README.md
View file

@ -1,4 +1,4 @@
# GoRealis
# gorealis [![GoDoc](https://godoc.org/github.com/rdelval/gorealis?status.svg)](https://godoc.org/github.com/rdelval/gorealis)
Go library for communicating with Apache Aurora.
Named after the northern lights (Aurora Borealis).
@ -118,17 +118,6 @@ updateJob.Ram(128)
msg, err := r.UpdateJob(updateJob, "")
```
### Methods:
|Method | Arguments | Description|
|----------|------------|------------|
|CreateJob | `*Job` | Sends a job create request to Apache Aurora |
|KillJob | `*aurora.JobKey` | Attempts to kill all active instances running in Aurora. Only needs environment, role, name |
|RestartJob| `*aurora.JobKey` | Attempts to restart all active instances running in Aurora |
|AddInstances|`*aurora.InstanceKey`, `int32`| Launches the specified number of new instances based on existing job config |
|StartUpdateJob|`*UpdateJob`, `string`| Updates a service job with a new configuration |
|AbortUpdateJob|`*aurora.Jobkey`, `string`, `string`| Abort the job update that matches the ID |
## 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

1
examples/client.go
View file

@ -11,6 +11,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package main
import (

37
job.go
View file

@ -11,6 +11,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package realis
import (
@ -18,6 +19,7 @@ import (
"strconv"
)
// Structure to collect all information pertaining to an Aurora job.
type Job struct {
jobConfig *aurora.JobConfiguration
numCpus *aurora.Resource
@ -26,15 +28,7 @@ type Job struct {
portCount int
}
type CreateJobBuilder struct {
jobConfig *aurora.JobConfiguration
jobKey *aurora.JobKey
taskConfig *aurora.TaskConfig
numCpus *aurora.Resource
ramMb *aurora.Resource
diskMb *aurora.Resource
}
// Create a Job object with everything initialized.
func NewJob() *Job {
jobConfig := aurora.NewJobConfiguration()
taskConfig := aurora.NewTaskConfig()
@ -66,11 +60,13 @@ func NewJob() *Job {
return &Job{jobConfig, numCpus, ramMb, diskMb, 0}
}
// Set Job Key environment.
func (a *Job) Environment(env string) *Job {
a.jobConfig.Key.Environment = env
return a
}
// Set Job Key Role.
func (a *Job) Role(role string) *Job {
a.jobConfig.Key.Role = role
@ -81,16 +77,19 @@ func (a *Job) Role(role string) *Job {
return a
}
// Set Job Key Name.
func (a *Job) Name(name string) *Job {
a.jobConfig.Key.Name = name
return a
}
// Set name of the executor that will the task will be configured to.
func (a *Job) ExecutorName(name string) *Job {
a.jobConfig.TaskConfig.ExecutorConfig.Name = name
return a
}
// Will be included as part of entire task inside the scheduler that will be serialized.
func (a *Job) ExecutorData(data string) *Job {
a.jobConfig.TaskConfig.ExecutorConfig.Data = data
return a
@ -117,30 +116,37 @@ func (a *Job) Disk(disk int64) *Job {
return a
}
// How many failures to tolerate before giving up.
func (a *Job) MaxFailure(maxFail int32) *Job {
a.jobConfig.TaskConfig.MaxTaskFailures = maxFail
return a
}
// How many instances of the job to run
func (a *Job) InstanceCount(instCount int32) *Job {
a.jobConfig.InstanceCount = instCount
return a
}
// Restart the job's tasks if they fail
func (a *Job) IsService(isService bool) *Job {
a.jobConfig.TaskConfig.IsService = isService
return a
}
// Get the current job configurations key to use for some realis calls.
func (a *Job) JobKey() *aurora.JobKey {
return a.jobConfig.Key
}
// Add URI to fetch using the mesos fetcher. Scheduler must have --enable_mesos_fetcher flag
// enabled.
func (a *Job) AddURI(value string, extract bool, cache bool) *Job {
a.jobConfig.TaskConfig.MesosFetcherUris[&aurora.MesosFetcherURI{value, &extract, &cache}] = true
return a
}
// Add a list of URIs with the same extract and cache configuration.
func (a *Job) AddURIs(extract bool, cache bool, values ...string) *Job {
for _, value := range values {
a.jobConfig.TaskConfig.MesosFetcherUris[&aurora.MesosFetcherURI{value, &extract, &cache}] = true
@ -148,13 +154,15 @@ func (a *Job) AddURIs(extract bool, cache bool, values ...string) *Job {
return a
}
// Note: By default Aurora will add the prefix "org.apache.aurora.metadata." to the beginning of each key
// Adds a Mesos label to the job. Note that as of Aurora 0.15.0, Aurora will add the
// prefix "org.apache.aurora.metadata." to the beginning of each key.
func (a *Job) AddLabel(key string, value string) *Job {
a.jobConfig.TaskConfig.Metadata[&aurora.Metadata{key, value}] = true
return a
}
//Each port is equivalent to Marathon's 0 port
// Adds a request for a number of ports to the job configuration. These are random ports as it's
// not currently possible to request specific ports using Aurora.
func (a *Job) AddPorts(num int) *Job {
start := a.portCount
a.portCount += num
@ -166,9 +174,11 @@ func (a *Job) AddPorts(num int) *Job {
return a
}
// Add a Value constraint,
// From Aurora Docs:
// Add a Value constraint
// name - Mesos slave attribute that the constraint is matched against.
// If negated = true , treat this as a 'not' - to avoid specific values.
// Values - list of values we look for in attribute name
func (a *Job) AddValueConstraint(name string,
negated bool,
values ...string) *Job {
@ -183,7 +193,8 @@ func (a *Job) AddValueConstraint(name string,
return a
}
// From Aurora Docs: A constraint the specifies the maximum number of active tasks on a host with
// From Aurora Docs:
// A constraint the specifies the maximum number of active tasks on a host with
// a matching attribute that may be scheduled simultaneously.
func (a *Job) AddLimitConstraint(name string, limit int32) *Job {

25
realis.go
View file

@ -11,6 +11,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
// Package realis provides the ability to use Thrift API to communicate with Apache Aurora.
package realis
@ -35,19 +36,18 @@ type RealisConfig struct {
transport thrift.TTransport
}
// Create a new Client
// Create a new Client with a default transport layer
func NewClient(config RealisConfig) *Realis {
httpTrans := (config.transport).(*thrift.THttpClient)
httpTrans.SetHeader("User-Agent", "GoRealis v0.1")
// Aurora can only communicate in JSON, leave it here as default
protocolFactory := thrift.NewTJSONProtocolFactory()
return &Realis{client: aurora.NewAuroraSchedulerManagerClientFactory(config.transport, protocolFactory)}
}
// Create a default configuration of the transport layer, requires a URL
// Create a default configuration of the transport layer, requires a URL to test connection with.
func NewDefaultConfig(url string) (RealisConfig, error) {
jar, err := cookiejar.New(nil)
@ -72,7 +72,7 @@ func NewDefaultConfig(url string) (RealisConfig, error) {
}
// Helper function to add basic authorization needed to communicate with Apache Aurora
// Helper function to add basic authorization needed to communicate with Apache Aurora.
func AddBasicAuth(config *RealisConfig, username string, password string) {
httpTrans := (config.transport).(*thrift.THttpClient)
httpTrans.SetHeader("Authorization", "Basic "+basicAuth(username, password))
@ -83,12 +83,12 @@ func basicAuth(username, password string) string {
return base64.StdEncoding.EncodeToString([]byte(auth))
}
// Releases resources associated with the realis client
// Releases resources associated with the realis client.
func (r *Realis) Close() {
r.client.Transport.Close()
}
// Uses predefined set of states to retrieve a set of active jobs in Apache Aurora
// Uses predefined set of states to retrieve a set of active jobs in Apache Aurora.
func (r *Realis) getActiveInstanceIds(key *aurora.JobKey) (map[int32]bool, error) {
taskQ := &aurora.TaskQuery{Role: key.Role,
Environment: key.Environment,
@ -110,6 +110,7 @@ func (r *Realis) getActiveInstanceIds(key *aurora.JobKey) (map[int32]bool, error
return jobInstanceIds, nil
}
// Kill a specific instance of a job.
func (r *Realis) KillInstance(key *aurora.JobKey, instanceId int32) (*aurora.Response, error) {
instanceIds := make(map[int32]bool)
@ -124,7 +125,7 @@ func (r *Realis) KillInstance(key *aurora.JobKey, instanceId int32) (*aurora.Res
return response, nil
}
// Sends a kill message to the scheduler for all active tasks under a job
// Sends a kill message to the scheduler for all active tasks under a job.
func (r *Realis) KillJob(key *aurora.JobKey) (*aurora.Response, error) {
instanceIds, err := r.getActiveInstanceIds(key)
@ -145,7 +146,7 @@ func (r *Realis) KillJob(key *aurora.JobKey) (*aurora.Response, error) {
}
}
// Sends a create job message to the scheduler with a specific job configuration
// Sends a create job message to the scheduler with a specific job configuration.
func (r *Realis) CreateJob(auroraJob *Job) (*aurora.Response, error) {
response, err := r.client.CreateJob(auroraJob.jobConfig)
@ -156,7 +157,7 @@ func (r *Realis) CreateJob(auroraJob *Job) (*aurora.Response, error) {
return response, nil
}
// Restarts all active tasks under a job configuration
// Restarts all active tasks under a job configuration.
func (r *Realis) RestartJob(key *aurora.JobKey) (*aurora.Response, error) {
instanceIds, err := r.getActiveInstanceIds(key)
@ -177,7 +178,7 @@ func (r *Realis) RestartJob(key *aurora.JobKey) (*aurora.Response, error) {
}
}
// Update all tasks under a job configuration
// Update all tasks under a job configuration. Currently there's no support for canary deployments.
func (r *Realis) StartJobUpdate(updateJob *UpdateJob, message string) (*aurora.Response, error) {
response, err := r.client.StartJobUpdate(updateJob.req, message)
@ -189,6 +190,7 @@ func (r *Realis) StartJobUpdate(updateJob *UpdateJob, message string) (*aurora.R
return response, nil
}
// Abort Job Update on Aurora. Requires the updateId which can be obtained on the Aurora web UI.
func (r *Realis) AbortJobUpdate(
key *aurora.JobKey,
updateId string,
@ -203,7 +205,8 @@ func (r *Realis) AbortJobUpdate(
return response, nil
}
// Scale up the number of instances under a job configuration
// Scale up the number of instances under a job configuration using the configuration for specific
// instance to scale up.
func (r *Realis) AddInstances(instKey *aurora.InstanceKey, count int32) (*aurora.Response, error) {
response, err := r.client.AddInstances(instKey, count)

12
updatejob.go
View file

@ -11,15 +11,18 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package realis
import "gen-go/apache/aurora"
// Structure to collect all information requrired to create job update
type UpdateJob struct {
*Job //Go Embedding, SetInstanceCount for job is hidden
*Job // SetInstanceCount for job is hidden, access via full qualifier
req *aurora.JobUpdateRequest
}
// Create a default UpdateJob object.
func NewUpdateJob(job *Job) *UpdateJob {
req := aurora.NewJobUpdateRequest()
@ -40,6 +43,7 @@ func NewUpdateJob(job *Job) *UpdateJob {
return &UpdateJob{job, req}
}
// Set instance count the job will have after the update.
func (u *UpdateJob) InstanceCount(inst int32) *UpdateJob {
u.req.InstanceCount = inst
return u
@ -51,13 +55,13 @@ func (u *UpdateJob) BatchSize(size int32) *UpdateJob {
return u
}
// Minimum number of seconds a shard must remain in RUNNING state before considered a success
// Minimum number of seconds a shard must remain in RUNNING state before considered a success.
func (u *UpdateJob) WatchTime(milliseconds int32) *UpdateJob {
u.req.Settings.MaxPerInstanceFailures = milliseconds
return u
}
// Wait for all instances in a group to be done before moving on
// Wait for all instances in a group to be done before moving on.
func (u *UpdateJob) WaitForBatchCompletion(batchWait bool) *UpdateJob {
u.req.Settings.WaitForBatchCompletion = batchWait
return u
@ -76,7 +80,7 @@ func (u *UpdateJob) MaxFailedInstances(inst int32) *UpdateJob {
return u
}
// When False, prevents auto rollback of a failed update
// When False, prevents auto rollback of a failed update.
func (u *UpdateJob) RollbackOnFail(rollback bool) *UpdateJob {
u.req.Settings.RollbackOnFailure = rollback