challenges

Documentation

Index

• Variables
• type Challenge
  • func LoadDir(dir string) ([]*Challenge, []error)
  • func ParseBytes(data []byte, slug string) (*Challenge, error)
  • func ParseFile(path, slug string) (*Challenge, error)
• type ChallengeTypeInfo
• type ConditionCheck
• type ConditionSpec
• type ConnectivityCheck
• type ConnectivitySpec
• type EventSpec
• type LogSpec
• type MatchMode
• type Objective
• type ObjectiveType
• type RbacCheck
• type RbacSpec
• type SourcePod
• type SpecCheck
• type SpecSpec
• type StatusCheck
• type StatusSpec
• type TLSConfig
• type Target
• type Theme
• type TriggerConfig
• type TriggerType
• type TriggeredSpec
• type TypeRegistration
• type ValidationError
  • func Validate(c *Challenge) []ValidationError
  • func ValidateImageReferences(challengeDir, slug string) []ValidationError
  • func ValidateKyvernoImagePolicy(challengeDir, slug string) []ValidationError
  • func ValidateManifests(challengeDir string) []ValidationError
  • func (e ValidationError) Error() string

Variables

var ChallengeTypeValues = func() []string {
	slugs := make([]string, len(ChallengeTypes))
	for i, t := range ChallengeTypes {
		slugs[i] = t.Slug
	}
	return slugs
}()

ChallengeTypeValues derives the slug list from ChallengeTypes for enum validation.

var ChallengeTypes = []ChallengeTypeInfo{
	{"fix", "Fix", "Something is broken in production. Diagnose the root cause and repair it.", "wrench"},
	{"operate", "Operate", "The infrastructure is running. Execute a specific operational task to move forward.", "terminal"},
	{"improve", "Improve", "The application works but isn't production-ready. Strengthen its reliability, security, or observability.", "shield-check"},
	{"migrate", "Migrate", "Transition a workload to a new configuration, resource type, or cluster setup.", "arrow-right-left"},
}

ChallengeTypes is the exhaustive list of challenge types.

var DifficultyValues = []string{"easy", "medium", "hard"}

DifficultyValues is the exhaustive list of valid difficulty levels.

var RegisteredTypes = []TypeRegistration{
	{TypeStatus, StatusSpec{}, "StatusSpec"},
	{TypeCondition, ConditionSpec{}, "ConditionSpec"},
	{TypeLog, LogSpec{}, "LogSpec"},
	{TypeEvent, EventSpec{}, "EventSpec"},
	{TypeConnectivity, ConnectivitySpec{}, "ConnectivitySpec"},
	{TypeRbac, RbacSpec{}, "RbacSpec"},
	{TypeSpec, SpecSpec{}, "SpecSpec"},
	{TypeTriggered, TriggeredSpec{}, "TriggeredSpec"},
}

RegisteredTypes lists all objective types in display order. This is the single source for schema generation — add new types here only.

var ThemeValues = func() []string {
	slugs := make([]string, len(Themes))
	for i, t := range Themes {
		slugs[i] = t.Slug
	}
	return slugs
}()

ThemeValues derives the slug list from Themes for enum validation.

var Themes = []Theme{
	{"pods-containers", "Pods & Containers", "Challenges dealing with pod configuration, multi-container setups, and lifecycle.", "box"},
	{"resources-scaling", "Resources & Scaling", "Managing resource limits, requests, and autoscaling workloads.", "chart-line"},
	{"networking", "Networking", "Challenges involving connectivity, network policies, and communication between components.", "globe"},
	{"volumes-secrets", "Volumes & Secrets", "Managing sensitive data and persistent storage in Kubernetes.", "key"},
	{"rbac-security", "RBAC & Security", "Challenges related to access control, user permissions, and security policies.", "lock"},
	{"scheduling-affinity", "Scheduling & Affinity", "Tasks focusing on how and where pods are scheduled based on rules or constraints.", "compass"},
	{"jobs-cronjobs", "Jobs & CronJobs", "Working with one-time or scheduled tasks in Kubernetes.", "timer"},
	{"ingress-tls", "Ingress & TLS", "Setting up and securing external access to services using Ingress and TLS.", "shield"},
	{"monitoring-debugging", "Monitoring & Debugging", "Troubleshooting issues using logs, probes, and diagnostic tools.", "search"},
}

Themes is the exhaustive list of challenge themes.

Types

type Challenge

type Challenge struct {
	Slug               string      `json:"slug"`
	Title              string      `json:"title"`
	Description        string      `json:"description"`
	Theme              string      `json:"theme"`
	Difficulty         string      `json:"difficulty"`
	Type               string      `json:"type"`
	EstimatedTime      int         `json:"estimatedTime"`
	InitialSituation   string      `json:"initialSituation"`
	MinRequiredVersion string      `json:"minRequiredVersion,omitempty"`
	Objectives         []Objective `json:"objectives"`
}

Challenge is the fully parsed and validated challenge, including its slug derived from the folder name.

func LoadDir

func LoadDir(dir string) ([]*Challenge, []error)

LoadDir scans dir for challenge subdirectories and parses each challenge.yaml found. Returns all valid challenges and a list of per-challenge errors (non-fatal).

func ParseBytes

func ParseBytes(data []byte, slug string) (*Challenge, error)

ParseBytes parses a challenge from raw YAML bytes.

func ParseFile

func ParseFile(path, slug string) (*Challenge, error)

ParseFile reads and parses a challenge.yaml. The slug must be passed explicitly (derived from the folder name by the caller).

type ChallengeTypeInfo

type ChallengeTypeInfo struct {
	Slug        string `json:"slug"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Logo        string `json:"logo"`
}

ChallengeTypeInfo holds display metadata for a challenge type.

type ConditionCheck

type ConditionCheck struct {
	Type   string `yaml:"type" json:"type"`
	Status string `yaml:"status" json:"status"`
}

type ConditionSpec

type ConditionSpec struct {
	Target Target           `yaml:"target" json:"target"`
	Checks []ConditionCheck `yaml:"checks" json:"checks"`
}

ConditionSpec validates Kubernetes resource conditions (Ready, Available, etc.).

type ConnectivityCheck

type ConnectivityCheck struct {
	URL                string     `yaml:"url" json:"url"`
	ExpectedStatusCode int        `yaml:"expectedStatusCode" json:"expectedStatusCode"`
	TimeoutSeconds     int        `yaml:"timeoutSeconds,omitempty" json:"timeoutSeconds,omitempty"`
	HostHeader         string     `yaml:"hostHeader,omitempty" json:"hostHeader,omitempty"`
	TLS                *TLSConfig `yaml:"tls,omitempty" json:"tls,omitempty"`
}

type ConnectivitySpec

type ConnectivitySpec struct {
	Mode      string              `yaml:"mode,omitempty" json:"mode,omitempty"`
	SourcePod SourcePod           `yaml:"sourcePod" json:"sourcePod"`
	Targets   []ConnectivityCheck `yaml:"targets" json:"targets"`
}

ConnectivitySpec tests HTTP connectivity between pods or from the CLI host.

type EventSpec

type EventSpec struct {
	Target           Target   `yaml:"target" json:"target"`
	ForbiddenReasons []string `yaml:"forbiddenReasons" json:"forbiddenReasons"`
	RequiredReasons  []string `yaml:"requiredReasons,omitempty" json:"requiredReasons,omitempty"`
	SinceSeconds     int      `yaml:"sinceSeconds,omitempty" json:"sinceSeconds,omitempty"`
}

EventSpec checks Kubernetes events for a target resource.

type LogSpec

type LogSpec struct {
	Target          Target    `yaml:"target" json:"target"`
	Container       string    `yaml:"container,omitempty" json:"container,omitempty"`
	ExpectedStrings []string  `yaml:"expectedStrings" json:"expectedStrings"`
	SinceSeconds    int       `yaml:"sinceSeconds,omitempty" json:"sinceSeconds,omitempty"`
	Previous        bool      `yaml:"previous,omitempty" json:"previous,omitempty"`
	MatchMode       MatchMode `yaml:"matchMode,omitempty" json:"matchMode,omitempty"`
}

LogSpec searches container logs for expected strings.

type MatchMode

type MatchMode string

const (
	MatchModeAllOf MatchMode = "allOf"
	MatchModeAnyOf MatchMode = "anyOf"
)

type Objective

type Objective struct {
	Key         string        `json:"key"`
	Title       string        `json:"title"`
	Description string        `json:"description"`
	Order       int           `json:"order"`
	Type        ObjectiveType `json:"type"`
	Spec        interface{}   `json:"spec"`
}

Objective is a single validation check within a challenge.

type ObjectiveType

type ObjectiveType string

ObjectiveType identifies the executor to use for an objective.

const (
	TypeStatus       ObjectiveType = "status"
	TypeCondition    ObjectiveType = "condition"
	TypeLog          ObjectiveType = "log"
	TypeEvent        ObjectiveType = "event"
	TypeConnectivity ObjectiveType = "connectivity"
	TypeRbac         ObjectiveType = "rbac"
	TypeSpec         ObjectiveType = "spec"
	TypeTriggered    ObjectiveType = "triggered"
)

type RbacCheck

type RbacCheck struct {
	Verb        string `yaml:"verb" json:"verb"`
	Resource    string `yaml:"resource" json:"resource"`
	Subresource string `yaml:"subresource,omitempty" json:"subresource,omitempty"`
	Namespace   string `yaml:"namespace,omitempty" json:"namespace,omitempty"`
	Allowed     bool   `yaml:"allowed" json:"allowed"`
}

type RbacSpec

type RbacSpec struct {
	ServiceAccount string      `yaml:"serviceAccount" json:"serviceAccount"`
	Namespace      string      `yaml:"namespace" json:"namespace"`
	Checks         []RbacCheck `yaml:"checks" json:"checks"`
}

RbacSpec validates ServiceAccount permissions via SubjectAccessReview.

type SourcePod

type SourcePod struct {
	Name          string            `yaml:"name,omitempty" json:"name,omitempty"`
	LabelSelector map[string]string `yaml:"labelSelector,omitempty" json:"labelSelector,omitempty"`
	Namespace     string            `yaml:"namespace,omitempty" json:"namespace,omitempty"`
}

type SpecCheck

type SpecCheck struct {
	Path     string      `yaml:"path" json:"path"`
	Exists   *bool       `yaml:"exists,omitempty" json:"exists,omitempty"`
	Value    interface{} `yaml:"value,omitempty" json:"value,omitempty"`
	Contains interface{} `yaml:"contains,omitempty" json:"contains,omitempty"`
}

type SpecSpec

type SpecSpec struct {
	Target Target      `yaml:"target" json:"target"`
	Checks []SpecCheck `yaml:"checks" json:"checks"`
}

SpecSpec validates resource manifest fields (spec, metadata, etc.).

type StatusCheck

type StatusCheck struct {
	Field    string      `yaml:"field" json:"field"`
	Operator string      `yaml:"operator" json:"operator"`
	Value    interface{} `yaml:"value" json:"value"`
}

type StatusSpec

type StatusSpec struct {
	Target Target        `yaml:"target" json:"target"`
	Checks []StatusCheck `yaml:"checks" json:"checks"`
}

StatusSpec validates arbitrary status fields using comparison operators.

type TLSConfig

type TLSConfig struct {
	InsecureSkipVerify bool `yaml:"insecureSkipVerify,omitempty" json:"insecureSkipVerify,omitempty"`
	ValidateExpiry     bool `yaml:"validateExpiry,omitempty" json:"validateExpiry,omitempty"`
	ValidateSANs       bool `yaml:"validateSANs,omitempty" json:"validateSANs,omitempty"`
}

type Target

type Target struct {
	Kind          string            `yaml:"kind" json:"kind"`
	Name          string            `yaml:"name,omitempty" json:"name,omitempty"`
	LabelSelector map[string]string `yaml:"labelSelector,omitempty" json:"labelSelector,omitempty"`
}

Target identifies a Kubernetes resource to validate.

type Theme

type Theme struct {
	Slug        string `json:"slug"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Logo        string `json:"logo"`
}

Theme holds display metadata for a challenge theme.

type TriggerConfig

type TriggerConfig struct {
	Type              TriggerType `yaml:"type" json:"type"`
	URL               string      `yaml:"url,omitempty" json:"url,omitempty"`
	RequestsPerSecond int         `yaml:"requestsPerSecond,omitempty" json:"requestsPerSecond,omitempty"`
	DurationSeconds   int         `yaml:"durationSeconds,omitempty" json:"durationSeconds,omitempty"`
	SourcePod         *SourcePod  `yaml:"sourcePod,omitempty" json:"sourcePod,omitempty"`
	Target            *Target     `yaml:"target,omitempty" json:"target,omitempty"`
	Image             string      `yaml:"image,omitempty" json:"image,omitempty"`
	Container         string      `yaml:"container,omitempty" json:"container,omitempty"`
	Replicas          *int32      `yaml:"replicas,omitempty" json:"replicas,omitempty"`
	WaitSeconds       int         `yaml:"waitSeconds,omitempty" json:"waitSeconds,omitempty"`
}

type TriggerType

type TriggerType string

const (
	TriggerTypeLoad    TriggerType = "load"
	TriggerTypeWait    TriggerType = "wait"
	TriggerTypeDelete  TriggerType = "delete"
	TriggerTypeRollout TriggerType = "rollout"
	TriggerTypeScale   TriggerType = "scale"
)

type TriggeredSpec

type TriggeredSpec struct {
	Trigger          TriggerConfig `yaml:"trigger" json:"trigger"`
	WaitAfterSeconds int           `yaml:"waitAfterSeconds" json:"waitAfterSeconds"`
	Then             []Objective   `yaml:"then" json:"then"`
}

TriggeredSpec orchestrates a trigger action followed by a set of validators.

type TypeRegistration

type TypeRegistration struct {
	Type     ObjectiveType
	Spec     interface{}
	SpecName string
}

TypeRegistration associates an ObjectiveType with its empty spec struct for schema generation.

type ValidationError

type ValidationError struct {
	Field   string
	Message string
}

ValidationError describes a single validation failure.

func Validate

func Validate(c *Challenge) []ValidationError

Validate checks that c is well-formed. Returns all errors found, not just the first.

func ValidateImageReferences

func ValidateImageReferences(challengeDir, slug string) []ValidationError

ValidateImageReferences checks that if a challenge has an image/ folder, at least one manifest references the image from the canonical ghcr.io registry path.

func ValidateKyvernoImagePolicy

func ValidateKyvernoImagePolicy(challengeDir, slug string) []ValidationError

ValidateKyvernoImagePolicy checks that if a challenge has an image/Dockerfile, at least one Kyverno policy in policies/ restricts containers to the canonical ghcr.io image.

func ValidateManifests

func ValidateManifests(challengeDir string) []ValidationError

ValidateManifests checks the manifests/ directory of a challenge:

• directory exists and contains at least one YAML file
• each file parses as valid Kubernetes resource(s)
• each resource has apiVersion, kind, and a name (or generateName)
• if the argocd sync-wave annotation is present, its value is a valid integer

func (ValidationError) Error

func (e ValidationError) Error() string