Documentation
¶
Overview ¶
Package runner contains the runner, the component responsible for carrying out runs by executing terraform processes, either as part of the server or remotely via agents.
templ: version: v0.3.833
Index ¶
- Constants
- Variables
- func NewAgentsCommand(apiClient *otfapi.Client) *cobra.Command
- type AgentOptions
- type Config
- type CreateAgentPoolOptions
- type CreateAgentTokenOptions
- type Job
- type JobStatus
- type Pool
- type Runner
- type RunnerMeta
- type RunnerMetaAgentPool
- type RunnerStatus
- type ServerRunnerOptions
- type Service
- func (s *Service) AddHandlers(r *mux.Router)
- func (s *Service) CreateAgentPool(ctx context.Context, opts CreateAgentPoolOptions) (*Pool, error)
- func (s *Service) CreateAgentToken(ctx context.Context, poolID resource.ID, opts CreateAgentTokenOptions) (*agentToken, []byte, error)
- func (s *Service) DeleteAgentToken(ctx context.Context, tokenID resource.ID) (*agentToken, error)
- func (s *Service) GetAgentPool(ctx context.Context, poolID resource.ID) (*Pool, error)
- func (s *Service) GetAgentToken(ctx context.Context, tokenID resource.ID) (*agentToken, error)
- func (s *Service) ListAgentTokens(ctx context.Context, poolID resource.ID) ([]*agentToken, error)
- func (f Service) NewAgentToken(poolID resource.ID, opts CreateAgentTokenOptions) (*agentToken, []byte, error)
- func (s *Service) NewAllocator(logger logr.Logger) *allocator
- func (s *Service) NewManager() *manager
- func (s *Service) WatchAgentPools(ctx context.Context) (<-chan pubsub.Event[*Pool], func())
- func (s *Service) WatchJobs(ctx context.Context) (<-chan pubsub.Event[*Job], func())
- func (s *Service) WatchRunners(ctx context.Context) (<-chan pubsub.Event[*RunnerMeta], func())
- type ServiceOptions
Constants ¶
const DefaultMaxJobs = 5
Variables ¶
var ( ErrInvalidJobStateTransition = errors.New("invalid job state transition") ErrMalformedJobSpecString = errors.New("malformed stringified job spec") )
var ( ErrCannotDeletePoolReferencedByWorkspaces = errors.New("agent pool is still being used by workspaces in your organization. You must switch your workspaces to a different agent pool or execution mode before you can delete this agent pool") ErrWorkspaceNotAllowedToUsePool = errors.New("access to this agent pool is not allowed - you must explictly grant access to the workspace first") ErrPoolAssignedWorkspacesNotAllowed = errors.New("workspaces assigned to the pool have not been granted access to the pool") )
var ErrInvalidStateTransition = errors.New("invalid runner state transition")
var PluginCacheDir = filepath.Join(os.TempDir(), "plugin-cache")
Functions ¶
Types ¶
type AgentOptions ¶
func NewAgentOptionsFromFlags ¶
func NewAgentOptionsFromFlags(flags *pflag.FlagSet) *AgentOptions
type Config ¶
type Config struct {
Name string // descriptive name given to runner
MaxJobs int // number of jobs the runner can execute at any one time
Sandbox bool // isolate privileged ops within sandbox
Debug bool // toggle debug mode
PluginCache bool // toggle use of terraform's shared plugin cache
TerraformBinDir string // destination directory for terraform binaries
}
func NewConfigFromFlags ¶
type CreateAgentPoolOptions ¶
type CreateAgentTokenOptions ¶
type CreateAgentTokenOptions struct {
Description string `json:"description" schema:"description,required"`
}
type Job ¶
type Job struct {
ID resource.ID `jsonapi:"primary,jobs"`
// ID of the run that this job is for.
RunID resource.ID `jsonapi:"attribute" json:"run_id"`
// Phase of run that this job is for.
Phase internal.PhaseType `jsonapi:"attribute" json:"phase"`
// Current status of job.
Status JobStatus `jsonapi:"attribute" json:"status"`
// ID of agent pool the job's workspace is assigned to use. If non-nil then
// the job is allocated to an agent runner belonging to the pool. If nil then
// the job is allocated to a server runner.
AgentPoolID *resource.ID `jsonapi:"attribute" json:"agent_pool_id"`
// Name of job's organization
Organization string `jsonapi:"attribute" json:"organization"`
// ID of job's workspace
WorkspaceID resource.ID `jsonapi:"attribute" json:"workspace_id"`
// ID of runner that this job is allocated to. Only set once job enters
// JobAllocated state.
RunnerID *resource.ID `jsonapi:"attribute" json:"runner_id"`
// Signaled is non-nil when a cancelation signal has been sent to the job
// and it is true when it has been forceably canceled.
Signaled *bool `jsonapi:"attribute" json:"signaled"`
}
Job is the unit of work corresponding to a run phase. A job is allocated to a runner, which then executes the work through to completion.
type Pool ¶
type Pool struct {
resource.ID
Name string
CreatedAt time.Time
// Pool belongs to an organization with this name.
Organization string
// Whether pool of agents is accessible to all workspaces in organization
// (true) or only those specified in AllowedWorkspaces (false).
OrganizationScoped bool
// IDs of workspaces allowed to access pool. Ignored if OrganizationScoped
// is true.
AllowedWorkspaces []resource.ID
// IDs of workspaces assigned to the pool. Note: this is a subset of
// AllowedWorkspaces.
AssignedWorkspaces []resource.ID
}
Pool is a group of remote runners sharing one or more tokens, assigned to an organization or particular workspaces within the organization.
type Runner ¶
type Runner struct {
*RunnerMeta
Sandbox bool // isolate privileged ops within sandbox
Debug bool // toggle debug mode
PluginCache bool // toggle use of terraform's shared plugin cache
TerraformBinDir string // destination directory for terraform binaries
// contains filtered or unexported fields
}
func NewServerRunner ¶
func NewServerRunner(opts ServerRunnerOptions) (*Runner, error)
NewServerRunner constructs a server runner.
func (*Runner) Registered ¶
func (r *Runner) Registered() <-chan *RunnerMeta
Registered returns the daemon's corresponding runner on a channel once it has successfully registered.
type RunnerMeta ¶
type RunnerMeta struct {
ID resource.ID `jsonapi:"primary,runners"`
// Optional name
Name string `jsonapi:"attribute" json:"name"`
// Version of runner
Version string `jsonapi:"attribute" json:"version"`
// Current status of runner
Status RunnerStatus `jsonapi:"attribute" json:"status"`
// Max number of jobs runner can execute
MaxJobs int `jsonapi:"attribute" json:"max_jobs"`
// Current number of jobs allocated to runner.
CurrentJobs int `jsonapi:"attribute" json:"current_jobs"`
// Last time a ping was received from the runner.
LastPingAt time.Time `jsonapi:"attribute" json:"last-ping-at"`
// Last time the status was updated
LastStatusAt time.Time `jsonapi:"attribute" json:"last-status-at"`
// IP address of runner.
IPAddress netip.Addr `jsonapi:"attribute" json:"ip-address"`
// Info about the runner's agent pool. Non-nil if agent runner; nil if server
// runner.
AgentPool *RunnerMetaAgentPool `jsonapi:"attribute" json:"agent-pool"`
}
RunnerMeta is information about a runner.
func (*RunnerMeta) CanAccess ¶
func (m *RunnerMeta) CanAccess(action authz.Action, req *authz.AccessRequest) bool
func (*RunnerMeta) IsAgent ¶
func (m *RunnerMeta) IsAgent() bool
func (*RunnerMeta) LogValue ¶
func (m *RunnerMeta) LogValue() slog.Value
func (*RunnerMeta) String ¶
func (m *RunnerMeta) String() string
type RunnerMetaAgentPool ¶
type RunnerMetaAgentPool struct {
// ID of agent's pool.
ID resource.ID `json:"id"`
// Name of agent's pool
Name string `json:"name"`
// Agent pool's organization.
OrganizationName string `json:"organization-name"`
// ID of agent token that was used to authenticate runner.
TokenID resource.ID `json:"token-id"`
}
func (*RunnerMetaAgentPool) LogValue ¶
func (m *RunnerMetaAgentPool) LogValue() slog.Value
type RunnerStatus ¶
type RunnerStatus string
const ( RunnerIdle RunnerStatus = "idle" RunnerBusy RunnerStatus = "busy" RunnerExited RunnerStatus = "exited" RunnerErrored RunnerStatus = "errored" RunnerUnknown RunnerStatus = "unknown" )
type ServerRunnerOptions ¶
type ServerRunnerOptions struct {
*Config
Logger logr.Logger
Runners *Service
Runs runClient
Workspaces workspaceClient
Variables variablesClient
State stateClient
Configs configClient
Logs logsClient
Server hostnameClient
Jobs operationJobsClient
}
ServerRunnerOptions are options for constructing a server runner.
type Service ¶
type Service struct {
logr.Logger
*authz.Authorizer
// contains filtered or unexported fields
}
func NewService ¶
func NewService(opts ServiceOptions) *Service
func (*Service) AddHandlers ¶
func (*Service) CreateAgentPool ¶
func (*Service) CreateAgentToken ¶
func (*Service) DeleteAgentToken ¶
func (*Service) GetAgentPool ¶
func (*Service) GetAgentToken ¶
func (*Service) ListAgentTokens ¶
func (Service) NewAgentToken ¶
func (f Service) NewAgentToken(poolID resource.ID, opts CreateAgentTokenOptions) (*agentToken, []byte, error)
NewAgentToken constructs a token for an agent, returning both the representation of the token, and the cryptographic token itself.
func (*Service) NewAllocator ¶
func (*Service) NewManager ¶
func (s *Service) NewManager() *manager