From bf890bf9b0f3663267f25694601441652d8c24f2 Mon Sep 17 00:00:00 2001 From: Renan DelValle Date: Tue, 9 Aug 2016 16:18:30 -0700 Subject: [PATCH] Updating documentation for release Moving godoc reference button changing casing of top title --- README.md | 13 +------------ examples/client.go | 1 + job.go | 37 ++++++++++++++++++++++++------------- realis.go | 25 ++++++++++++++----------- updatejob.go | 12 ++++++++---- 5 files changed, 48 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 2c2bc4a..2b4e0a4 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/examples/client.go b/examples/client.go index a8db962..6c6db68 100644 --- a/examples/client.go +++ b/examples/client.go @@ -11,6 +11,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + package main import ( diff --git a/job.go b/job.go index 8e17021..86f7796 100644 --- a/job.go +++ b/job.go @@ -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 { diff --git a/realis.go b/realis.go index 1de17b4..8159bd9 100644 --- a/realis.go +++ b/realis.go @@ -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) diff --git a/updatejob.go b/updatejob.go index 620242d..05b7db1 100644 --- a/updatejob.go +++ b/updatejob.go @@ -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