modagent

Documentation

Index

• Constants
• type API
• type Config
• type Factory
• type GitLabRequestConfig
  • func ApplyRequestOptions(opts []GitLabRequestOption) (*GitLabRequestConfig, error)
• type GitLabRequestOption
  • func WithJSONRequestBody(body any) GitLabRequestOption
  • func WithRequestBody(body io.Reader, contentType string) GitLabRequestOption
  • func WithRequestHeader(header string, values ...string) GitLabRequestOption
  • func WithRequestMethod(method string) GitLabRequestOption
  • func WithRequestQueryParam(key string, values ...string) GitLabRequestOption
• type GitLabResponse
• type Module

Constants

const (
	// The field manager name for the ones agentk owns, see
	// https://kubernetes.io/docs/reference/using-api/server-side-apply/#field-management
	FieldManager = "agentk"
)

Types

type API

type API interface {
	modshared.API
	// MakeGitLabRequest allows to make an HTTP call to a module's endpoint in GitLab.
	// The correct usage pattern is below. The calling code MUST close the body to release resources!
	// Draining the body is not necessary.
	//
	// resp, err := r.api.MakeGitLabRequest(ctx, "/<path>", <options>)
	// if err != nil {
	//   // handle error
	// }
	// defer errz.SafeClose(resp.Body, &retError) // make sure to check the returned error. E.g. use this helper.
	//
	// // Use resp - check HTTP response status, header, read body, etc.
	MakeGitLabRequest(ctx context.Context, path string, opts ...GitLabRequestOption) (*GitLabResponse, error)
	GetAgentID(ctx context.Context) (int64, error)
	TryGetAgentID() (int64, bool)
	GetGitLabExternalURL(ctx context.Context) (url.URL, error)
}

API provides the API for the module to use.

type Config

type Config struct {
	// Log can be used for logging from the module.
	// It should not be used for logging from gRPC API methods. Use modshared.RPCAPIFromContext(ctx) instead.
	Log       *slog.Logger
	AgentMeta *entity.AgentMeta
	API       API
	// K8sUtilFactory provides means to interact with the Kubernetes cluster agentk is running in.
	K8sUtilFactory util.Factory
	// KASConn is the gRPC connection to gitlab-kas.
	// Modules that use this field must use modshared.ModuleStartAfterServers start phase.
	KASConn grpc.ClientConnInterface
	// APIServer is a gRPC server that can be used to expose API endpoints to gitlab-kas and/or GitLab.
	// It can be used to add endpoints in Factory.New.
	// Request handlers can obtain the per-request logger using modshared.RPCAPIFromContext(requestContext).
	APIServer grpctool.GRPCServer
	// RegisterKASAPI allows to register a gRPC API endpoint that agentk proxies to kas.
	RegisterKASAPI func(*grpc.ServiceDesc)
	// AgentName is a string "gitlab-agent". Can be used as a user agent, server name, service name, etc.
	AgentName string
	// ServiceAccountName is a string defined by default as "gitlab-agent".
	ServiceAccountName string
	Validator          prototool.Validator
}

Config holds configuration for a Module.

type Factory

type Factory interface {
	modshared.Factory
	// IsProducingLeaderModules returns if the modules that this Factory produces are leader modules or not.
	// A leader module must only be run once across all agent replicas.
	IsProducingLeaderModules() bool
	// New creates a new instance of a Module.
	// Can return nil if no module is necessary.
	New(*Config) (Module, error)
}

type GitLabRequestConfig

type GitLabRequestConfig struct {
	Method string
	Header http.Header
	Query  url.Values
	Body   io.ReadCloser
}

func ApplyRequestOptions

func ApplyRequestOptions(opts []GitLabRequestOption) (*GitLabRequestConfig, error)

type GitLabRequestOption

type GitLabRequestOption func(*GitLabRequestConfig) error

func WithJSONRequestBody

func WithJSONRequestBody(body any) GitLabRequestOption

func WithRequestBody

func WithRequestBody(body io.Reader, contentType string) GitLabRequestOption

WithRequestBody specifies request body to send and HTTP Content-Type header if contentType is not empty. If body implements io.ReadCloser, its Close() method will be called once the data has been sent. If body is nil, no body or Content-Type header is sent.

func WithRequestHeader

func WithRequestHeader(header string, values ...string) GitLabRequestOption

func WithRequestMethod

func WithRequestMethod(method string) GitLabRequestOption

WithRequestMethod specifies request HTTP method.

func WithRequestQueryParam

func WithRequestQueryParam(key string, values ...string) GitLabRequestOption

type GitLabResponse

type GitLabResponse struct {
	Status     string // e.g. "200 OK"
	StatusCode int32  // e.g. 200
	Header     http.Header
	Body       io.ReadCloser
}

type Module

type Module interface {
	// Run runs the module.
	// Run must block until the context signals done or the cfg channel is closed. Run must not return before that.
	// If the Run method returns before any of the stop signals is received the module runner will panic.
	// cfg is a channel that gets configuration updates sent to it. It's closed when the module should shut down.
	// cfg sends configuration objects that are shared and must not be mutated.
	// Module should make a copy if it needs to mutate the object.
	// Applying configuration may take time, the provided context may signal done if module should shut down.
	// cfg only provides the latest available configuration, intermediate configuration states are discarded.
	// Run is responsible that it acts according to the received configuration, even if that is just to wait for
	// a new one.
	Run(ctx context.Context, cfg <-chan *agentcfg.AgentConfiguration) error
	// DefaultAndValidateConfiguration applies defaults and validates the passed configuration.
	// It is called each time on configuration update before sending it via the channel passed to Run().
	// cfg is a shared instance, module can mutate only the part of it that it owns and only inside of this method.
	DefaultAndValidateConfiguration(cfg *agentcfg.AgentConfiguration) error
	// Name returns module's name.
	Name() string
}