Documentation

Index

Constants

This section is empty.

Variables

View Source
var File_go_chromium_org_luci_led_job_job_proto protoreflect.FileDescriptor
View Source
var RdbChoices = flagenum.Enum{
	"on":  RDBOn,
	"off": RDBOff,
}

Functions

func ToCasInstance

func ToCasInstance(swarmingHost string) (string, error)

    Convert a swarming host name to cas instance name.

    Types

    type Buildbucket

    type Buildbucket struct {
    	BbagentArgs      *proto.BBAgentArgs    `protobuf:"bytes,1,opt,name=bbagent_args,json=bbagentArgs,proto3" json:"bbagent_args,omitempty"`
    	CipdPackages     []*api.CIPDPackage    `protobuf:"bytes,2,rep,name=cipd_packages,json=cipdPackages,proto3" json:"cipd_packages,omitempty"`
    	EnvVars          []*api.StringPair     `protobuf:"bytes,3,rep,name=env_vars,json=envVars,proto3" json:"env_vars,omitempty"`
    	EnvPrefixes      []*api.StringListPair `protobuf:"bytes,4,rep,name=env_prefixes,json=envPrefixes,proto3" json:"env_prefixes,omitempty"`
    	ExtraTags        []string              `protobuf:"bytes,5,rep,name=extra_tags,json=extraTags,proto3" json:"extra_tags,omitempty"`
    	BotPingTolerance *durationpb.Duration  `protobuf:"bytes,7,opt,name=bot_ping_tolerance,json=botPingTolerance,proto3" json:"bot_ping_tolerance,omitempty"`
    	Containment      *api.Containment      `protobuf:"bytes,8,opt,name=containment,proto3" json:"containment,omitempty"`
    	// Indicates that this build should be generated as a legacy kitchen task when
    	// launched.
    	LegacyKitchen bool `protobuf:"varint,9,opt,name=legacy_kitchen,json=legacyKitchen,proto3" json:"legacy_kitchen,omitempty"`
    	// Eventually becomes the name of the launched swarming task.
    	Name string `protobuf:"bytes,10,opt,name=name,proto3" json:"name,omitempty"`
    	// This field contains the path relative to ${ISOLATED_OUTDIR} for the final
    	// build.proto result. If blank, will cause the job not to emit any build
    	// proto to the output directory.
    	//
    	// For bbagent-based jobs this must have the file extension ".pb", ".textpb"
    	// or ".json", to get the respective encoding.
    	//
    	// For legacy kitchen jobs this must have the file extension ".json".
    	//
    	// By default, led will populate this with "build.proto.json".
    	FinalBuildProtoPath string `protobuf:"bytes,11,opt,name=final_build_proto_path,json=finalBuildProtoPath,proto3" json:"final_build_proto_path,omitempty"`
    	// contains filtered or unexported fields
    }

      Buildbucket is, ideally, just a BBAgentArgs, but there are bits of data that led needs to track which aren't currently contained in BBAgentArgs.

      Where it makes sense, this additional data should be moved from this Buildbucket message into BBAgentArgs, but for now we store it separately to get led v2 up and running.

      func (*Buildbucket) Descriptor

      func (*Buildbucket) Descriptor() ([]byte, []int)

        Deprecated: Use Buildbucket.ProtoReflect.Descriptor instead.

        func (*Buildbucket) EnsureBasics

        func (b *Buildbucket) EnsureBasics()

          EnsureBasics ensures that the following fields are non-nil:

          b.BbagentArgs
          b.BbagentArgs.Build
          b.BbagentArgs.Build.Exe
          b.BbagentArgs.Build.Infra
          b.BbagentArgs.Build.Infra.Logdog
          b.BbagentArgs.Build.Infra.Swarming
          b.BbagentArgs.Build.Input
          b.BbagentArgs.Build.Input.Properties
          

          func (*Buildbucket) GetBbagentArgs

          func (x *Buildbucket) GetBbagentArgs() *proto.BBAgentArgs

          func (*Buildbucket) GetBotPingTolerance

          func (x *Buildbucket) GetBotPingTolerance() *durationpb.Duration

          func (*Buildbucket) GetCipdPackages

          func (x *Buildbucket) GetCipdPackages() []*api.CIPDPackage

          func (*Buildbucket) GetContainment

          func (x *Buildbucket) GetContainment() *api.Containment

          func (*Buildbucket) GetEnvPrefixes

          func (x *Buildbucket) GetEnvPrefixes() []*api.StringListPair

          func (*Buildbucket) GetEnvVars

          func (x *Buildbucket) GetEnvVars() []*api.StringPair

          func (*Buildbucket) GetExtraTags

          func (x *Buildbucket) GetExtraTags() []string

          func (*Buildbucket) GetFinalBuildProtoPath

          func (x *Buildbucket) GetFinalBuildProtoPath() string

          func (*Buildbucket) GetLegacyKitchen

          func (x *Buildbucket) GetLegacyKitchen() bool

          func (*Buildbucket) GetName

          func (x *Buildbucket) GetName() string

          func (*Buildbucket) ProtoMessage

          func (*Buildbucket) ProtoMessage()

          func (*Buildbucket) ProtoReflect

          func (x *Buildbucket) ProtoReflect() protoreflect.Message

          func (*Buildbucket) Reset

          func (x *Buildbucket) Reset()

          func (*Buildbucket) String

          func (x *Buildbucket) String() string

          func (*Buildbucket) WriteProperties

          func (b *Buildbucket) WriteProperties(inputs map[string]interface{})

            WriteProperties writes an input property on this Buildbucket message.

            type CIPDPkgs

            type CIPDPkgs map[string]string

              CIPDPkgs is a mapping of the CIPD packages within a Definition in the form of:

              "subdir:name/of/package" -> "version"
              

              type Definition

              type Definition struct {
              
              	// Types that are assignable to JobType:
              	//	*Definition_Buildbucket
              	//	*Definition_Swarming
              	JobType isDefinition_JobType `protobuf_oneof:"job_type"`
              	// WILL BE DEPRECATED AFTER MIGRATION TO RBE-CAS (crbug.com/1145959).
              	//
              	// If set, this holds the CASTree to use with the build, when launched.
              	//
              	// At the time of launch, this will be merged with
              	// swarming.task_slice[*].properties.inputs_ref, if any.
              	//
              	// The 'server' and 'namespace' fields here are used as the defaults for any
              	// digests specified without server/namespace.
              	UserPayload *api.CASTree `protobuf:"bytes,3,opt,name=user_payload,json=userPayload,proto3" json:"user_payload,omitempty"`
              	// [In Experiment]
              	// If set, this holds the CASReference to use with the job, when launched.
              	//
              	// At the time of launch, this will be merged with
              	// swarming.task_slice[*].properties.cas_input_root, if any.
              	//
              	// can only use either cas_user_payload or user_payload.
              	CasUserPayload *api.CASReference `protobuf:"bytes,4,opt,name=cas_user_payload,json=casUserPayload,proto3" json:"cas_user_payload,omitempty"`
              	// contains filtered or unexported fields
              }

              func (*Definition) CasInstance

              func (jd *Definition) CasInstance() (string, error)

                returns the corresponding cas instance from job's Swarming hostname.

                func (*Definition) Descriptor

                func (*Definition) Descriptor() ([]byte, []int)

                  Deprecated: Use Definition.ProtoReflect.Descriptor instead.

                  func (*Definition) Edit

                  func (jd *Definition) Edit(cb func(m Editor)) error

                    Edit runs a mutator function with an Editor.

                    If one of the edit operations has an error, further method calls on the Editor are ignored and this returns the error.

                    func (*Definition) FlattenToSwarming

                    func (jd *Definition) FlattenToSwarming(ctx context.Context, uid, parentTaskId string, ks KitchenSupport, resultdb RDBEnablement) error

                      FlattenToSwarming modifies this Definition to populate the Swarming field from the Buildbucket field.

                      After flattening, HighLevelEdit functionality will no longer work on this Definition.

                      `uid` and `parentTaskId`, if specified, override the user and parentTaskId fields, respectively.

                      func (*Definition) GetBuildbucket

                      func (x *Definition) GetBuildbucket() *Buildbucket

                      func (*Definition) GetCasUserPayload

                      func (x *Definition) GetCasUserPayload() *api.CASReference

                      func (*Definition) GetJobType

                      func (m *Definition) GetJobType() isDefinition_JobType

                      func (*Definition) GetSwarming

                      func (x *Definition) GetSwarming() *Swarming

                      func (*Definition) GetUserPayload

                      func (x *Definition) GetUserPayload() *api.CASTree

                      func (*Definition) HighLevelEdit

                      func (jd *Definition) HighLevelEdit(cb func(m HighLevelEditor)) error

                        HighLevelEdit runs a mutator function with a HighLevelEditor.

                        If one of the edit operations has an error, further method calls on the HighLevelEditor are ignored and this returns the error.

                        func (*Definition) HighLevelInfo

                        func (jd *Definition) HighLevelInfo() HighLevelInfo

                          HighLevelInfo returns an accessor object which can returns high-level information about the Definition.

                          Only returns a functioning implementation for Buildbucket jobs, otherwise returns nil.

                          func (*Definition) Info

                          func (jd *Definition) Info() Info

                            Info returns a generic accessor object which can return generic information about the Definition.

                            Returns nil if the Definition doesn't support Info().

                            func (*Definition) ProtoMessage

                            func (*Definition) ProtoMessage()

                            func (*Definition) ProtoReflect

                            func (x *Definition) ProtoReflect() protoreflect.Message

                            func (*Definition) Reset

                            func (x *Definition) Reset()

                            func (*Definition) String

                            func (x *Definition) String() string

                            type Definition_Buildbucket

                            type Definition_Buildbucket struct {
                            	// Represents a buildbucket-native task; May be recovered from a swarming
                            	// task, or provided directly via buildbucket.
                            	Buildbucket *Buildbucket `protobuf:"bytes,1,opt,name=buildbucket,proto3,oneof"`
                            }

                            type Definition_Swarming

                            type Definition_Swarming struct {
                            	// Represents a swarming task. This will be filled for jobs sourced directly
                            	// from swarming which weren't recognized as a buildbucket task.
                            	//
                            	// A limited subset of the edit and info functionality is available for
                            	// raw swarming jobs.
                            	Swarming *Swarming `protobuf:"bytes,2,opt,name=swarming,proto3,oneof"`
                            }

                            type DimensionEditCommand

                            type DimensionEditCommand struct {
                            	SetValues    []ExpiringValue
                            	RemoveValues []string
                            	AddValues    []ExpiringValue
                            }

                              DimensionEditCommand is instruction on how to process the values in the task associated with a swarming dimension.

                              The fields are processed in order:

                              * if SetValues is non-nil, the dimension values are set to this set
                                (including empty).
                              * if RemoveValues is non-empty, these values will be removed from the
                                dimension values.
                              * if AddValues is non-empty, these values will ber added to the dimension
                                values.
                              

                              If the set of values at the end of this process is empty, the dimension will be removed from the task. Otherwise the dimension will be set to the sorted remaining values.

                              type DimensionEditCommands

                              type DimensionEditCommands map[string]*DimensionEditCommand

                                DimensionEditCommands is a mapping of dimension name to a set of commands to apply to the values of that dimension.

                                func MakeDimensionEditCommands

                                func MakeDimensionEditCommands(commands []string) (DimensionEditCommands, error)

                                  MakeDimensionEditCommands takes a slice of commands in the form of:

                                  dimension=
                                  dimension=value
                                  dimension=value@1234
                                  
                                  dimension-=value
                                  
                                  dimension+=value
                                  dimension+=value@1234
                                  

                                  Logically:

                                  * dimension_name - The name of the dimension to modify
                                  * operator
                                    * "=" - Add value to SetValues. If empty, ensures that SetValues is
                                      non-nil (i.e. clear all values for this dimension).
                                    * "-=" - Add value to RemoveValues.
                                    * "+=" - Add value to AddValues.
                                  * value - The dimension value for the operand
                                  * expiration seconds - The time at which this value should expire.
                                  

                                  All equivalent operations for the same dimension will be grouped into a single DimensionEditCommand in the order they appear in `commands`.

                                  type Editor

                                  type Editor interface {
                                  	// ClearCurrentIsolated removes all isolateds from this Definition.
                                  	ClearCurrentIsolated()
                                  
                                  	// ClearDimensions removes all dimensions.
                                  	ClearDimensions()
                                  
                                  	// SetDimensions sets the full set of dimensions.
                                  	SetDimensions(dims ExpiringDimensions)
                                  
                                  	// EditDimensions edits the swarming dimensions.
                                  	EditDimensions(dimEdits DimensionEditCommands)
                                  
                                  	// CIPDPkgs allows you to edit the cipd packages. The mapping is in the form
                                  	// of:
                                  	//
                                  	//    "subdir:name/of/package" -> "version"
                                  	//
                                  	// If version is empty, this package will be removed (if it's present).
                                  	CIPDPkgs(cipdPkgs CIPDPkgs)
                                  
                                  	// Env edits the swarming environment variables (i.e. those set before the
                                  	// user payload runs).
                                  	//
                                  	// The map given is a map of environment variable to its value; If the value
                                  	// is "", then the environment variable is removed.
                                  	Env(env map[string]string)
                                  
                                  	// PrefixPathEnv controls swarming's env_prefix mapping for $PATH.
                                  	//
                                  	// Values prepended with '!' will remove them from the existing list of values
                                  	// (if present). Otherwise these values will be appended to the current list
                                  	// of PATH-prefix-envs.
                                  	PrefixPathEnv(values []string)
                                  
                                  	// Priority edits the swarming task priority.
                                  	Priority(priority int32)
                                  
                                  	// SwarmingHostname allows you to modify the current SwarmingHostname used by
                                  	// this led pipeline.
                                  	SwarmingHostname(host string)
                                  
                                  	// TaskName allows you to set the swarming task name of the job.
                                  	TaskName(name string)
                                  
                                  	// Tags appends the given values to the task's tags.
                                  	Tags(values []string)
                                  }

                                    Editor represents low-level mutations you can make on a job.Definition.

                                    You may edit a job.Definition by calling its Edit method.

                                    type ExpiringDimensions

                                    type ExpiringDimensions map[string][]ExpiringValue

                                      ExpiringDimensions is a map from dimension name to a list of values corresponding to that dimension.

                                      When retrieved from a led library, the values will be sorted by expiration time, followed by value. Expirations of 0 (i.e. "infinite") are sorted last.

                                      func (ExpiringDimensions) String

                                      func (e ExpiringDimensions) String() string

                                      type ExpiringValue

                                      type ExpiringValue struct {
                                      	Value      string
                                      	Expiration time.Duration
                                      }

                                        ExpiringValue represents a tuple of dimension value, plus an expiration time.

                                        If Expiration is zero, it counts as "no expiration".

                                        type HighLevelEditor

                                        type HighLevelEditor interface {
                                        	Editor
                                        
                                        	// Experimental sets the task to either be marked 'experimental' or not.
                                        	Experimental(isExperimental bool)
                                        
                                        	// Experiments enables or disables experiments.
                                        	//
                                        	// If `exps[<name>]` is true, the corresponding experiment will be enabled.
                                        	// If it is false, the experiment will be disabled (if it was enabled).
                                        	//
                                        	// Experiments enabled in the build, but not mentioned in `exps` map are left
                                        	// enabled.
                                        	Experiments(exps map[string]bool)
                                        
                                        	// Properties edits the recipe properties.
                                        	//
                                        	// `props` should be a mapping of the top-level property to JSON-encoded data
                                        	// for the value of this property. If the value is "", then the top-level
                                        	// property will be deleted.
                                        	//
                                        	// If `auto` is true, then values which do not decode as JSON will be treated
                                        	// as literal strings. For example, given a value `literal string` with
                                        	// auto=true, this would be equivalent to passing the value `"literal string"`
                                        	// with auto=false.
                                        	Properties(props map[string]string, auto bool)
                                        
                                        	// TaskPayloadSource sets the task payload to either use the provided CIPD
                                        	// package and version, or the UserPayload if they are empty.
                                        	//
                                        	// If cipdPkg is specified without cipdVers, cipdVers will be set to "latest".
                                        	TaskPayloadSource(cipdPkg, cipdVers string)
                                        
                                        	// TaskPayloadPath sets the location of where bbagent should locate the task
                                        	// payload data within the task.
                                        	TaskPayloadPath(path string)
                                        
                                        	// TaskPayloadCmd sets the arguments used to run the task payload.
                                        	//
                                        	// args[0] is the path, relative to the payload path, of the executable to
                                        	// run.
                                        	//
                                        	// NOTE: Kitchen tasks ignore this value.
                                        	TaskPayloadCmd(args []string)
                                        
                                        	// ClearGerritChanges removes all GerritChanges from the job.
                                        	ClearGerritChanges()
                                        
                                        	// AddGerritChange ensures the GerritChange is in the set of input CLs.
                                        	AddGerritChange(cl *bbpb.GerritChange)
                                        
                                        	// RemoveGerritChange ensures the GerritChange is not in the set of input CLs.
                                        	RemoveGerritChange(cl *bbpb.GerritChange)
                                        
                                        	// GitilesCommit sets the GitilesCommit.
                                        	//
                                        	// If `commit` is nil, removes the commit.
                                        	GitilesCommit(commit *bbpb.GitilesCommit)
                                        }

                                          HighLevelEditor represents high-level mutations you can make on a job.Definition.

                                          Currently only Buildbucket job.Definitions support high level edits.

                                          You may edit a job.Definition by calling its HighLevelEdit method.

                                          type HighLevelInfo

                                          type HighLevelInfo interface {
                                          	Info
                                          
                                          	// Returns true iff the job is marked as 'experimental'.
                                          	Experimental() bool
                                          
                                          	// Returns a sorted list of enabled experiments.
                                          	Experiments() []string
                                          
                                          	// Returns the input properties of this build as a map of top-level key to
                                          	// its JSON-encoded value.
                                          	Properties() (map[string]string, error)
                                          
                                          	// TaskPayloadSource returns the CIPD package and version of the user's task
                                          	// payload. If they are empty, then it means the source of the user task
                                          	// payload is within the UserPayload in the job.Definition.
                                          	TaskPayloadSource() (cipdPkg, cipdVers string)
                                          
                                          	// TaskPayloadPath returns the location of where bbagent/kitchen will locate
                                          	// the task payload data within the task.
                                          	TaskPayloadPath() (path string)
                                          
                                          	// TaskPayloadCmd returns the arguments used to run the task payload.
                                          	//
                                          	// args[0] is the path, relative to the payload path, of the executable to
                                          	// run.
                                          	//
                                          	// If this is empty, it defaults to []string{"luciexe"}.
                                          	//
                                          	// NOTE: Kitchen tasks ignore this value.
                                          	TaskPayloadCmd() (args []string)
                                          
                                          	// Returns the gerrit changes associated with this job.
                                          	GerritChanges() []*bbpb.GerritChange
                                          
                                          	// Returns the gitiles commit associated with this job.
                                          	GitilesCommit() *bbpb.GitilesCommit
                                          }

                                            HighLevelInfo represents high-level information for Buildbucket job Definitions.

                                            HighLevelInfo includes all capabilities of `Info` as well.

                                            type Info

                                            type Info interface {
                                            	// SwarmingHostname retrieves the Swarming hostname this Definition will use.
                                            	SwarmingHostname() string
                                            
                                            	// TaskName retrieves the human-readable Swarming task name from the
                                            	// Definition.
                                            	TaskName() string
                                            
                                            	// CurrentIsolated returns the current isolated contents for the
                                            	// Definition. If the CASTree or CASReference has no hash value,
                                            	// this returns an empty isolated obj.
                                            	//
                                            	// Returns error if this is a Swarming job where the slices have differing
                                            	// isolateds.
                                            	CurrentIsolated() (*isolated, error)
                                            
                                            	// Dimensions returns a single map of all dimensions in the job Definition
                                            	// and what their latest expiration is.
                                            	//
                                            	// For dimensions which "don't expire", they will report an expiration time of
                                            	// the total task expiration.
                                            	Dimensions() (ExpiringDimensions, error)
                                            
                                            	// CIPDPkgs returns the mapping of all CIPD packages in the task, in the
                                            	// same format that Editor.CIPDPkgs takes.
                                            	//
                                            	// Returns an error if not all slices in the swarming task have the same set
                                            	// of packages.
                                            	CIPDPkgs() (CIPDPkgs, error)
                                            
                                            	// Env returns any environment variable overrides in the job.
                                            	Env() (map[string]string, error)
                                            
                                            	// PrefixPathEnv returns the list of $PATH prefixes
                                            	PrefixPathEnv() ([]string, error)
                                            
                                            	// Priority returns the job's current swarming priority value.
                                            	Priority() int32
                                            
                                            	// Tags returns the job's current swarming tags.
                                            	Tags() []string
                                            }

                                              Info represents the common low-level information for all job Definitions.

                                              Swarming and Buildbucket implement this interface.

                                              type KitchenSupport

                                              type KitchenSupport interface {
                                              	FromSwarming(ctx context.Context, in *swarming.SwarmingRpcsNewTaskRequest, out *Buildbucket) error
                                              	GenerateCommand(ctx context.Context, bb *Buildbucket) ([]string, error)
                                              }

                                                KitchenSupport is the object for an interface to support 'LegacyKitchen' job definitions.

                                                See 'infra/tools/led2' for the only real implementation of this.

                                                This is abstracted out because 'kitchen' and its libraries live in infra, not in luci-go. Once kitchen is deleted, this will go away as well.

                                                func NoKitchenSupport

                                                func NoKitchenSupport() KitchenSupport

                                                  NoKitchenSupport returns a null implementation of KitchenSupport which always returns errors if it ends up processing a kitchen job.

                                                  type RDBEnablement

                                                  type RDBEnablement string

                                                    For accepting the "-resultdb" flag of "led launch".

                                                    const (
                                                    	// Swarming/ResultDB integration will be forcefully enabled.
                                                    	RDBOn RDBEnablement = "on"
                                                    	// Swarming/ResultDB integration will be forcefully disabled.
                                                    	RDBOff RDBEnablement = "off"
                                                    )

                                                    func (*RDBEnablement) Set

                                                    func (r *RDBEnablement) Set(v string) error

                                                    func (*RDBEnablement) String

                                                    func (r *RDBEnablement) String() string

                                                    type Swarming

                                                    type Swarming struct {
                                                    	Task     *api.TaskRequest `protobuf:"bytes,1,opt,name=task,proto3" json:"task,omitempty"`
                                                    	Hostname string           `protobuf:"bytes,2,opt,name=hostname,proto3" json:"hostname,omitempty"`
                                                    	// contains filtered or unexported fields
                                                    }

                                                      Swarming is the raw TaskRequest. When a Definition is in this form, the user's ability to manipulate it via `led` subcommands is extremely limited.

                                                      func (*Swarming) Descriptor

                                                      func (*Swarming) Descriptor() ([]byte, []int)

                                                        Deprecated: Use Swarming.ProtoReflect.Descriptor instead.

                                                        func (*Swarming) GetHostname

                                                        func (x *Swarming) GetHostname() string

                                                        func (*Swarming) GetTask

                                                        func (x *Swarming) GetTask() *api.TaskRequest

                                                        func (*Swarming) ProtoMessage

                                                        func (*Swarming) ProtoMessage()

                                                        func (*Swarming) ProtoReflect

                                                        func (x *Swarming) ProtoReflect() protoreflect.Message

                                                        func (*Swarming) Reset

                                                        func (x *Swarming) Reset()

                                                        func (*Swarming) String

                                                        func (x *Swarming) String() string

                                                        Directories

                                                        Path Synopsis