Job.Plan endpoint

api/jobs.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"fmt"
 	"sort"
 	"time"
 )
@@ -116,6 +117,24 @@ func (j *Jobs) PeriodicForce(jobID string, q *WriteOptions) (string, *WriteMeta,
 	return resp.EvalID, wm, nil
 }
 
+func (j *Jobs) Plan(job *Job, diff bool, q *WriteOptions) (*JobPlanResponse, *WriteMeta, error) {
+	if job == nil {
+		return nil, nil, fmt.Errorf("must pass non-nil job")
+	}
+
+	var resp JobPlanResponse
+	req := &JobPlanRequest{
+		Job:  job,
+		Diff: diff,
+	}
+	wm, err := j.client.write("/v1/job/"+job.ID+"/plan", req, &resp, q)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return &resp, wm, nil
+}
+
 // periodicForceResponse is used to deserialize a force response
 type periodicForceResponse struct {
 	EvalID string
@@ -256,3 +275,67 @@ type registerJobResponse struct {
 type deregisterJobResponse struct {
 	EvalID string
 }
+
+type JobPlanRequest struct {
+	Job  *Job
+	Diff bool
+}
+
+type JobPlanResponse struct {
+	JobModifyIndex uint64
+	CreatedEvals   []*Evaluation
+	Diff           *JobDiff
+	Annotations    *PlanAnnotations
+}
+
+type JobDiff struct {
+	Type       string
+	ID         string
+	Fields     []*FieldDiff
+	Objects    []*ObjectDiff
+	TaskGroups []*TaskGroupDiff
+}
+
+type TaskGroupDiff struct {
+	Type    string
+	Name    string
+	Fields  []*FieldDiff
+	Objects []*ObjectDiff
+	Tasks   []*TaskDiff
+	Updates map[string]uint64
+}
+
+type TaskDiff struct {
+	Type        string
+	Name        string
+	Fields      []*FieldDiff
+	Objects     []*ObjectDiff
+	Annotations []string
+}
+
+type FieldDiff struct {
+	Type        string
+	Name        string
+	Old, New    string
+	Annotations []string
+}
+
+type ObjectDiff struct {
+	Type    string
+	Name    string
+	Fields  []*FieldDiff
+	Objects []*ObjectDiff
+}
+
+type PlanAnnotations struct {
+	DesiredTGUpdates map[string]*DesiredUpdates
+}
+
+type DesiredUpdates struct {
+	Ignore            uint64
+	Place             uint64
+	Migrate           uint64
+	Stop              uint64
+	InPlaceUpdate     uint64
+	DestructiveUpdate uint64
+}

api/jobs_test.go

@@ -350,6 +350,76 @@ func TestJobs_PeriodicForce(t *testing.T) {
 	t.Fatalf("evaluation %q missing", evalID)
 }
 
+func TestJobs_Plan(t *testing.T) {
+	c, s := makeClient(t, nil, nil)
+	defer s.Stop()
+	jobs := c.Jobs()
+
+	// Create a job and attempt to register it
+	job := testJob()
+	eval, wm, err := jobs.Register(job, nil)
+	if err != nil {
+		t.Fatalf("err: %s", err)
+	}
+	if eval == "" {
+		t.Fatalf("missing eval id")
+	}
+	assertWriteMeta(t, wm)
+
+	// Check that passing a nil job fails
+	if _, _, err := jobs.Plan(nil, true, nil); err == nil {
+		t.Fatalf("expect an error when job isn't provided")
+	}
+
+	// Make a plan request
+	planResp, wm, err := jobs.Plan(job, true, nil)
+	if err != nil {
+		t.Fatalf("err: %s", err)
+	}
+	if planResp == nil {
+		t.Fatalf("nil response")
+	}
+
+	if planResp.JobModifyIndex == 0 {
+		t.Fatalf("bad JobModifyIndex value: %#v", planResp)
+	}
+	if planResp.Diff == nil {
+		t.Fatalf("got nil diff: %#v", planResp)
+	}
+	if planResp.Annotations == nil {
+		t.Fatalf("got nil annotations: %#v", planResp)
+	}
+	// Can make this assertion because there are no clients.
+	if len(planResp.CreatedEvals) == 0 {
+		t.Fatalf("got no CreatedEvals: %#v", planResp)
+	}
+
+	// Make a plan request w/o the diff
+	planResp, wm, err = jobs.Plan(job, false, nil)
+	if err != nil {
+		t.Fatalf("err: %s", err)
+	}
+	assertWriteMeta(t, wm)
+
+	if planResp == nil {
+		t.Fatalf("nil response")
+	}
+
+	if planResp.JobModifyIndex == 0 {
+		t.Fatalf("bad JobModifyIndex value: %d", planResp.JobModifyIndex)
+	}
+	if planResp.Diff != nil {
+		t.Fatalf("got non-nil diff: %#v", planResp)
+	}
+	if planResp.Annotations == nil {
+		t.Fatalf("got nil annotations: %#v", planResp)
+	}
+	// Can make this assertion because there are no clients.
+	if len(planResp.CreatedEvals) == 0 {
+		t.Fatalf("got no CreatedEvals: %#v", planResp)
+	}
+}
+
 func TestJobs_NewBatchJob(t *testing.T) {
 	job := NewBatchJob("job1", "myjob", "region1", 5)
 	expect := &Job{

command/agent/job_endpoint.go

@@ -51,6 +51,9 @@ func (s *HTTPServer) JobSpecificRequest(resp http.ResponseWriter, req *http.Requ
 	case strings.HasSuffix(path, "/periodic/force"):
 		jobName := strings.TrimSuffix(path, "/periodic/force")
 		return s.periodicForceRequest(resp, req, jobName)
+	case strings.HasSuffix(path, "/plan"):
+		jobName := strings.TrimSuffix(path, "/plan")
+		return s.jobPlan(resp, req, jobName)
 	default:
 		return s.jobCRUD(resp, req, path)
 	}
@@ -74,6 +77,32 @@ func (s *HTTPServer) jobForceEvaluate(resp http.ResponseWriter, req *http.Reques
 	return out, nil
 }
 
+func (s *HTTPServer) jobPlan(resp http.ResponseWriter, req *http.Request,
+	jobName string) (interface{}, error) {
+	if req.Method != "PUT" && req.Method != "POST" {
+		return nil, CodedError(405, ErrInvalidMethod)
+	}
+
+	var args structs.JobPlanRequest
+	if err := decodeBody(req, &args); err != nil {
+		return nil, CodedError(400, err.Error())
+	}
+	if args.Job == nil {
+		return nil, CodedError(400, "Job must be specified")
+	}
+	if jobName != "" && args.Job.ID != jobName {
+		return nil, CodedError(400, "Job ID does not match")
+	}
+	s.parseRegion(req, &args.Region)
+
+	var out structs.JobPlanResponse
+	if err := s.agent.RPC("Job.Plan", &args, &out); err != nil {
+		return nil, err
+	}
+	setIndex(resp, out.Index)
+	return out, nil
+}
+
 func (s *HTTPServer) periodicForceRequest(resp http.ResponseWriter, req *http.Request,
 	jobName string) (interface{}, error) {
 	if req.Method != "PUT" && req.Method != "POST" {

command/agent/job_endpoint_test.go

@@ -483,3 +483,39 @@ func TestHTTP_PeriodicForce(t *testing.T) {
 		}
 	})
 }
+
+func TestHTTP_JobPlan(t *testing.T) {
+	httpTest(t, nil, func(s *TestServer) {
+		// Create the job
+		job := mock.Job()
+		args := structs.JobPlanRequest{
+			Job:          job,
+			Diff:         true,
+			WriteRequest: structs.WriteRequest{Region: "global"},
+		}
+		buf := encodeReq(args)
+
+		// Make the HTTP request
+		req, err := http.NewRequest("PUT", "/v1/job/"+job.ID+"/plan", buf)
+		if err != nil {
+			t.Fatalf("err: %v", err)
+		}
+		respW := httptest.NewRecorder()
+
+		// Make the request
+		obj, err := s.Server.JobSpecificRequest(respW, req)
+		if err != nil {
+			t.Fatalf("err: %v", err)
+		}
+
+		// Check the response
+		plan := obj.(structs.JobPlanResponse)
+		if plan.Annotations == nil {
+			t.Fatalf("bad: %v", plan)
+		}
+
+		if plan.Diff == nil {
+			t.Fatalf("bad: %v", plan)
+		}
+	})
+}