Kubernetes API

API Docs

Table of Contents

Constraint

Constraint represents a constraint to the domain of the parameters

Field Description Scheme Required
name The optional name of the constraint string false
order The ordering constraint to impose *OrderConstraint false
sum The sum constraint to impose *SumConstraint false

Back to TOC

Experiment

Experiment is the Schema for the experiments API

Field Description Scheme Required
metadata Standard object metadata ObjectMeta false
spec Specification of the desired behavior for an experiment ExperimentSpec false
status Current status of an experiment ExperimentStatus false

Back to TOC

ExperimentList

ExperimentList contains a list of Experiment

Field Description Scheme Required
metadata Standard list metadata ListMeta false
items The list of experiments []Experiment true

Back to TOC

ExperimentSpec

ExperimentSpec defines the desired state of Experiment

Field Description Scheme Required
replicas Replicas is the number of trials to execute concurrently, defaults to 1 *int32 false
optimization Optimization defines additional configuration for the optimization []Optimization false
parameters Parameters defines the search space for the experiment []Parameter true
constraints Constraints defines restrictions on the parameter domain for the experiment []Constraint false
metrics Metrics defines the outcomes for the experiment []Metric true
patches Patches is a sequence of templates written against the experiment parameters that will be used to put the cluster into the desired state []PatchTemplate false
namespaceSelector NamespaceSelector is used to locate existing namespaces for trials *LabelSelector false
namespaceTemplate NamespaceTemplate can be specified to create new namespaces for trials; if specified created namespaces must be matched by the namespace selector *NamespaceTemplateSpec false
selector Selector locates trial resources that are part of this experiment *LabelSelector false
template Template for creating a new trial. The resulting trial must be matched by Selector. The template can provide an initial namespace, however other namespaces (matched by NamespaceSelector) will be used if the effective replica count is more then one TrialTemplateSpec false

Back to TOC

ExperimentStatus

ExperimentStatus defines the observed state of Experiment

Field Description Scheme Required
phase Phase is a brief human readable description of the experiment status string true
activeTrials ActiveTrials is the observed number of running trials int32 true

Back to TOC

Metric

Metric represents an observable outcome from a trial run

Field Description Scheme Required
name The name of the metric string true
minimize Indicator that the goal of the experiment is to minimize the value of this metric bool false
type The metric collection type, one of: local|pods|prometheus|datadog|jsonpath, default: local MetricType false
query Collection type specific query, e.g. Go template for “local”, PromQL for “prometheus” or a JSON pointer expression (with curly braces) for “jsonpath” string true
errorQuery Collection type specific query for the error associated with collected metric value string false
scheme The scheme to use when collecting metrics string false
selector Selector matching services to collect this metric from, only the first matched service to provide a value is used *LabelSelector false
port The port number or name on the matched service to collect the metric value from intstr.IntOrString false
path URL path component used to collect the metric value from an endpoint (used as a prefix for the Prometheus API) string false

Back to TOC

NamespaceTemplateSpec

NamespaceTemplateSpec is used as a template for creating new namespaces

Field Description Scheme Required
metadata Standard object metadata ObjectMeta false
spec Specification of the namespace corev1.NamespaceSpec false

Back to TOC

Optimization

Optimization is a configuration setting for the optimizer

Field Description Scheme Required
name Name is the name of the optimization configuration to set string true
value Value is string representation of the optimization configuration string true

Back to TOC

OrderConstraint

OrderConstraint defines a constraint between the ordering of two parameters in the experiment

Field Description Scheme Required
lowerParameter LowerParameter is the name of the parameter that must be the smaller of two parameters string true
upperParameter UpperParameter is the name of the parameter that must be the larger of two parameters string true

Back to TOC

Parameter

Parameter represents the domain of a single component of the experiment search space

Field Description Scheme Required
name The name of the parameter string true
min The inclusive minimum value of the parameter int64 false
max The inclusive maximum value of the parameter int64 false

Back to TOC

PatchReadinessGate

PatchReadinessGate contains a reference to a condition

Field Description Scheme Required
conditionType ConditionType refers to a condition in the patched target’s condition list string true

Back to TOC

PatchTemplate

PatchTemplate defines a target resource and a patch template to apply

Field Description Scheme Required
type The patch type, one of: strategic|merge|json, default: strategic PatchType false
patch A Go Template that evaluates to valid patch string true
targetRef Direct reference to the object the patch should be applied to *ObjectReference false
readinessGates ReadinessGates will be evaluated for patch target readiness. A patch target is ready if all conditions specified in the readiness gates have a status equal to “True”. If no readiness gates are specified, some target types may have default gates assigned to them. Some condition checks may result in errors, e.g. a condition type of “Ready” is not allowed for a ConfigMap. Condition types starting with “redskyops.dev/” may not appear in the patched target’s condition list, but are still evaluated against the resource’s state. []PatchReadinessGate false

Back to TOC

SumConstraint

SumConstraint defines a constraint between the sum of a collection of parameters

Field Description Scheme Required
bound Bound for the sum of the listed parameters resource.Quantity true
isUpperBound IsUpperBound determines if the bound values is an upper or lower bound on the sum bool false
parameters Parameters that should be summed []SumConstraintParameter true

Back to TOC

SumConstraintParameter

SumConstraintParameter is a weighted parameter specification in a sum constraint

Field Description Scheme Required
name Name of the parameter string true
weight Weight of the parameter resource.Quantity true

Back to TOC

TrialTemplateSpec

TrialTemplateSpec is used as a template for creating new trials

Field Description Scheme Required
metadata Standard object metadata ObjectMeta false
spec Specification of the desired behavior for the trial TrialSpec false

Back to TOC

API Docs

Table of Contents

Assignment

Assignment represents an individual name/value pair. Assignment names must correspond to parameter names on the associated experiment.

Field Description Scheme Required
name Name of the parameter being assigned string true
value Value of the assignment int64 true

Back to TOC

ConfigMapHelmValuesFromSource

ConfigMapHelmValuesFromSource is a reference to a ConfigMap that contains “*values.yaml” keys

Field Description Scheme Required
N/A

Back to TOC

HelmValue

HelmValue represents a value in a Helm template

Field Description Scheme Required
name The name of Helm value as passed to one of the set options string true
forceString Force the value to be treated as a string bool false
value Set a Helm value using the evaluated template. Templates are evaluated using the same rules as patches intstr.IntOrString false
valueFrom Source for a Helm value *HelmValueSource false

Back to TOC

HelmValueSource

HelmValueSource represents a source for a Helm value

Field Description Scheme Required
parameterRef Selects a trial parameter assignment as a Helm value *ParameterSelector false

Back to TOC

HelmValuesFromSource

HelmValuesFromSource represents a source of a values mapping

Field Description Scheme Required
configMap The ConfigMap to select from *ConfigMapHelmValuesFromSource false

Back to TOC

ParameterSelector

ParameterSelector selects a trial parameter assignment. Note that parameters values are used as is (i.e. in numeric form), for more control over the formatting of a parameter assignment use the template option on HelmValue.

Field Description Scheme Required
name The name of the trial parameter to use string true

Back to TOC

PatchOperation

PatchOperation represents a patch used to prepare the cluster for a trial run, includes the evaluated parameter assignments as necessary

Field Description Scheme Required
targetRef The reference to the object that the patched should be applied to ObjectReference true
patchType The patch content type, must be a type supported by the Kubernetes API server types.PatchType true
data The raw data representing the patch to be applied []byte true
attemptsRemaining The number of remaining attempts to apply the patch, will be automatically set to zero if the patch is successfully applied int false

Back to TOC

ReadinessCheck

ReadinessCheck represents a check to determine when the patched application is “ready” and it is safe to start the trial run job

Field Description Scheme Required
targetRef TargetRef is the reference to the object to test the readiness of ObjectReference true
selector Selector may be used to trigger a search for multiple related objects to search; this may have RBAC implications, in particular “list” permissions are required *LabelSelector false
conditionTypes ConditionTypes are the status conditions that must be “True”; in addition to conditions that appear in the status of the target object, additional special conditions starting with “redskyops.dev/” can be tested []string false
initialDelaySeconds InitialDelaySeconds is the approximate number of seconds after all of the patches have been applied to start evaluating this check int32 false
periodSeconds PeriodSeconds is the approximate amount of time in between evaluation attempts of this check int32 false
attemptsRemaining AttemptsRemaining is the number of failed attempts to allow before marking the entire trial as failed, will be automatically set to zero if the check has been successfully evaluated int32 false
lastCheckTime LastCheckTime is the timestamp of the last evaluation attempt *Time false

Back to TOC

SetupTask

SetupTask represents the configuration necessary to apply application state to the cluster prior to each trial run and remove that state after the run concludes

Field Description Scheme Required
name The name that uniquely identifies the setup task string true
image Override the default image used for performing setup tasks string false
skipCreate Flag to indicate the creation part of the task can be skipped bool false
skipDelete Flag to indicate the deletion part of the task can be skipped bool false
volumeMounts Volume mounts for the setup task []VolumeMount false
helmChart The Helm chart reference to release as part of this task string false
helmChartVersion The Helm chart version, empty means use the latest string false
helmValues The Helm values to set, ignored unless helmChart is also set []HelmValue false
helmValuesFrom The Helm values, ignored unless helmChart is also set []HelmValuesFromSource false

Back to TOC

Trial

Trial is the Schema for the trials API

Field Description Scheme Required
metadata Standard object metadata ObjectMeta false
spec Specification of the desired behavior for a trial TrialSpec false
status Current status of a trial TrialStatus false

Back to TOC

TrialCondition

TrialCondition represents an observed condition of a trial

Field Description Scheme Required
type The condition type, e.g. “redskyops.dev/trial-complete” TrialConditionType true
status The status of the condition, one of “True”, “False”, or “Unknown corev1.ConditionStatus true
lastProbeTime The last known time the condition was checked Time true
lastTransitionTime The time at which the condition last changed status Time true
reason A reason code describing the why the condition occurred string false
message A human readable message describing the transition string false

Back to TOC

TrialList

TrialList contains a list of Trial

Field Description Scheme Required
metadata Standard list metadata ListMeta false
items The list of trials []Trial true

Back to TOC

TrialReadinessGate

TrialReadinessGate represents a readiness check on one or more objects that must pass after patches have been applied, but before the trial run job can start

Field Description Scheme Required
kind Kind of the readiness target string false
name Name of the readiness target, mutually exclusive with “Selector” string false
apiVersion APIVersion of the readiness target string false
selector Selector matches the resources whose condition must be checked, mutually exclusive with “Name” *LabelSelector false
conditionTypes ConditionTypes are the status conditions that must be “True” []string false
initialDelaySeconds InitialDelaySeconds is the approximate number of seconds after all of the patches have been applied to start evaluating this check int32 false
periodSeconds PeriodSeconds is the approximate amount of time in between evaluation attempts of this check; defaults to 10 seconds, minimum value is 1 second int32 false
failureThreshold FailureThreshold is number of times that any of the specified ready conditions may be “False”; defaults to 3, minimum value is 1 int32 false

Back to TOC

TrialSpec

TrialSpec defines the desired state of Trial

Field Description Scheme Required
experimentRef ExperimentRef is the reference to the experiment that contains the definitions to use for this trial, defaults to an experiment in the same namespace with the same name *ObjectReference false
assignments Assignments are used to patch the cluster state prior to the trial run []Assignment false
selector Selector matches the job representing the trial run *LabelSelector false
template Template is the job template used to create trial run jobs *JobTemplateSpec false
initialDelaySeconds InitialDelaySeconds is number of seconds to wait after a trial becomes ready before starting the trial run job int32 false
startTimeOffset The offset used to adjust the start time to account for spin up of the trial run *metav1.Duration false
approximateRuntime The approximate amount of time the trial run should execute (not inclusive of the start time offset) *metav1.Duration false
ttlSecondsAfterFinished The minimum number of seconds before an attempt should be made to clean up the trial, if unset or negative no attempt is made to clean up the trial *int32 false
ttlSecondsAfterFailure The minimum number of seconds before an attempt should be made to clean up a failed trial, defaults to TTLSecondsAfterFinished *int32 false
readinessGates The readiness gates to check before running the trial job []TrialReadinessGate false
patchOperations PatchOperations are the patches from the experiment evaluated in the context of this trial []PatchOperation false
readinessChecks ReadinessChecks are the all of the objects whose conditions need to be inspected for this trial []ReadinessCheck false
values Values are the collected metrics at the end of the trial run []Value false
setupTasks Setup tasks that must run before the trial starts (and possibly after it ends) []SetupTask false
setupVolumes Volumes to make available to setup tasks, typically ConfigMap backed volumes []Volume false
setupServiceAccountName Service account name for running setup tasks, needs enough permissions to add and remove software string false
setupDefaultClusterRole Cluster role name to be assigned to the setup service account when creating namespaces string false
setupDefaultRules Policy rules to be assigned to the setup service account when creating namespaces []rbacv1.PolicyRule false

Back to TOC

TrialStatus

TrialStatus defines the observed state of Trial

Field Description Scheme Required
phase Phase is a brief human readable description of the trial status string true
assignments Assignments is a string representation of the trial assignments for reporting purposes string true
values Values is a string representation of the trial values for reporting purposes string true
startTime StartTime is the effective (possibly adjusted) time the trial run job started *Time false
completionTime CompletionTime is the effective (possibly adjusted) time the trial run job completed *Time false
conditions Condition is the current state of the trial []TrialCondition false

Back to TOC

Value

Value represents an observed metric value after a trial run has completed successfully. Value names must correspond to metric names on the associated experiment.

Field Description Scheme Required
name The metric name the value corresponds to string true
value The observed float64 value, formatted as a string string true
error The observed float64 error (standard deviation), formatted as a string string false
attemptsRemaining The number of remaining attempts to observer the value, will be automatically set to zero if the metric is successfully collected int false

Back to TOC