runner

package
v0.3.15 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 13, 2025 License: MPL-2.0 Imports: 56 Imported by: 0

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

View Source 
const DefaultMaxJobs = 5

Variables

View Source 
var (
	ErrInvalidJobStateTransition = errors.New("invalid job state transition")
	ErrMalformedJobSpecString    = errors.New("malformed stringified job spec")
)
View Source 
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")
)
View Source 
var ErrInvalidStateTransition = errors.New("invalid runner state transition")
View Source 
var PluginCacheDir = filepath.Join(os.TempDir(), "plugin-cache")

Functions

func NewAgentsCommand 

func NewAgentsCommand(apiClient *otfapi.Client) *cobra.Command

Types

type AgentOptions 

type AgentOptions struct {
	*Config

	URL   string
	Token string
}

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 

func NewConfigFromFlags(flags *pflag.FlagSet) *Config

type CreateAgentPoolOptions 

type CreateAgentPoolOptions struct {
	Name string `schema:"name,required"`
	// name of org
	Organization string `schema:"organization_name,required"`
	// defaults to true
	OrganizationScoped *bool
	// IDs of workspaces allowed to access the pool.
	AllowedWorkspaces []resource.ID
}

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.

func (*Job) CanAccess 

func (j *Job) CanAccess(action authz.Action, req *authz.AccessRequest) bool

func (*Job) LogValue 

func (j *Job) LogValue() slog.Value

func (*Job) String 

func (j *Job) String() string

type JobStatus 

type JobStatus string
const (
	JobUnallocated JobStatus = "unallocated"
	JobAllocated   JobStatus = "allocated"
	JobRunning     JobStatus = "running"
	JobFinished    JobStatus = "finished"
	JobErrored     JobStatus = "errored"
	JobCanceled    JobStatus = "canceled"
)

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.

func (*Pool) LogValue 

func (p *Pool) LogValue() slog.Value

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 NewAgent 

func NewAgent(logger logr.Logger, opts AgentOptions) (*Runner, error)

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.

func (*Runner) Start 

func (r *Runner) Start(ctx context.Context) error

Start the runner daemon.

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 (s *Service) AddHandlers(r *mux.Router)

func (*Service) CreateAgentPool 

func (s *Service) CreateAgentPool(ctx context.Context, opts CreateAgentPoolOptions) (*Pool, error)

func (*Service) CreateAgentToken 

func (s *Service) CreateAgentToken(ctx context.Context, poolID resource.ID, opts CreateAgentTokenOptions) (*agentToken, []byte, error)

func (*Service) DeleteAgentToken 

func (s *Service) DeleteAgentToken(ctx context.Context, tokenID resource.ID) (*agentToken, error)

func (*Service) GetAgentPool 

func (s *Service) GetAgentPool(ctx context.Context, poolID resource.ID) (*Pool, error)

func (*Service) GetAgentToken 

func (s *Service) GetAgentToken(ctx context.Context, tokenID resource.ID) (*agentToken, error)

func (*Service) ListAgentTokens 

func (s *Service) ListAgentTokens(ctx context.Context, poolID resource.ID) ([]*agentToken, error)

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 (s *Service) NewAllocator(logger logr.Logger) *allocator

func (*Service) NewManager 

func (s *Service) NewManager() *manager

func (*Service) WatchAgentPools 

func (s *Service) WatchAgentPools(ctx context.Context) (<-chan pubsub.Event[*Pool], func())

func (*Service) WatchJobs 

func (s *Service) WatchJobs(ctx context.Context) (<-chan pubsub.Event[*Job], func())

func (*Service) WatchRunners 

func (s *Service) WatchRunners(ctx context.Context) (<-chan pubsub.Event[*RunnerMeta], func())

type ServiceOptions 

type ServiceOptions struct {
	logr.Logger
	*sql.DB
	*sql.Listener
	*tfeapi.Responder

	RunService       *otfrun.Service
	WorkspaceService *workspace.Service
	TokensService    *tokens.Service
	Authorizer       *authz.Authorizer
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.