API reference¶

This page lists every Shadewright custom resource and the types they use, generated from the Go types in api/. Field descriptions come from the doc comments; validation comes from the kubebuilder markers and CEL rules that the API server enforces.

API group and version: remediation.shadewright.io/v1alpha1

Resource types¶

Kind	Scope	Short names	Summary
Incident	Namespaced		Incident groups repeated symptoms of one problem on one workload.
RemediationPolicy	Cluster		RemediationPolicy says which actions are allowed, on which targets, within which bounds, and whether a human must approve.
RemediationRequest	Namespaced	`rr`	RemediationRequest is one proposed fix: a typed action on one object, carried out as a GitOps pull request after deterministic policy allows it.
RemediationSettings	Cluster		RemediationSettings is the single cluster-wide configuration object, named default.

Incident¶

Incident groups repeated symptoms of one problem on one workload.

API version: remediation.shadewright.io/v1alpha1
Kind: Incident
Scope: Namespaced

Field	Type	Required	Description
`metadata`	ObjectMeta	No	Standard object metadata.
`spec`	IncidentSpec	Yes	spec identifies the incident. Rule: spec is immutable; a different symptom is a new Incident
`status`	IncidentStatus	No	status is the deduplication state.

RemediationPolicy¶

RemediationPolicy says which actions are allowed, on which targets, within which bounds, and whether a human must approve. Its generation is part of every plan digest, so changing it invalidates pending approvals. The name must be a DNS label (at most 63 characters), since requests reference it.

API version: remediation.shadewright.io/v1alpha1
Kind: RemediationPolicy
Scope: Cluster

Validation rules:

name must be at most 63 characters: size(self.metadata.name) <= 63

Field	Type	Required	Description
`metadata`	ObjectMeta	No	Standard object metadata.
`spec`	RemediationPolicySpec	Yes	spec is the policy.
`status`	RemediationPolicyStatus	No	status reports whether the policy is usable.

RemediationRequest¶

RemediationRequest is one proposed fix: a typed action on one object, carried out as a GitOps pull request after deterministic policy allows it.

API version: remediation.shadewright.io/v1alpha1
Kind: RemediationRequest
Scope: Namespaced

Field	Type	Required	Description
`metadata`	ObjectMeta	No	Standard object metadata.
`spec`	RemediationRequestSpec	Yes	spec is the plan. Rule: spec is immutable; a changed plan is a new RemediationRequest Rule: AdjustKedaMaxReplicas can only target a keda.sh ScaledObject Rule: SetContainerMemoryLimit can only target an apps/v1 Deployment or StatefulSet
`status`	RemediationRequestStatus	No	status is the progress, written by the controller.

RemediationSettings¶

RemediationSettings is the single cluster-wide configuration object, named default.

API version: remediation.shadewright.io/v1alpha1
Kind: RemediationSettings
Scope: Cluster

Validation rules:

there is one RemediationSettings and it is named default: self.metadata.name == 'default'

Field	Type	Required	Description
`metadata`	ObjectMeta	No	Standard object metadata.
`spec`	RemediationSettingsSpec	Yes	spec holds the settings.
`status`	RemediationSettingsStatus	No	status reports whether the settings are usable.

Types¶

Types used by the resources above, in alphabetical order.

Action¶

Action is one entry from the action catalog. Exactly the member named by type is set.

Validation rules:

adjustKedaMaxReplicas must be set if and only if type is AdjustKedaMaxReplicas: self.type == 'AdjustKedaMaxReplicas' ? has(self.adjustKedaMaxReplicas) : !has(self.adjustKedaMaxReplicas)
setContainerMemoryLimit must be set if and only if type is SetContainerMemoryLimit: self.type == 'SetContainerMemoryLimit' ? has(self.setContainerMemoryLimit) : !has(self.setContainerMemoryLimit)

Used by: RemediationRequestSpec.

Field	Type	Required	Description
`type`	ActionType	Yes	type selects the action. One of `AdjustKedaMaxReplicas`, `SetContainerMemoryLimit`
`adjustKedaMaxReplicas`	AdjustKedaMaxReplicas	No	adjustKedaMaxReplicas holds the parameters for AdjustKedaMaxReplicas. Rule: desiredValue must differ from previousValue
`setContainerMemoryLimit`	SetContainerMemoryLimit	No	setContainerMemoryLimit holds the parameters for SetContainerMemoryLimit. Rule: desired must differ from previous Rule: previous and desired must be whole bytes Rule: previous must be between 1Mi and 1Ti Rule: desired must be between 1Mi and 1Ti

ActionType¶

ActionType is the closed catalog of remediation actions (ADR-0003). Adding a value needs typed parameters, policy bounds, a GitOps patcher and a test that it is refused outside its bounds.

Underlying type: string
One of AdjustKedaMaxReplicas, SetContainerMemoryLimit

Used by: Action, PolicyAction.

Value	Description
`AdjustKedaMaxReplicas`	ActionAdjustKedaMaxReplicas changes maxReplicaCount of a KEDA ScaledObject.
`SetContainerMemoryLimit`	ActionSetContainerMemoryLimit changes the memory limit of one container in a workload's pod template.

AdjustKedaMaxReplicas¶

AdjustKedaMaxReplicas changes spec.maxReplicaCount of a ScaledObject. previousValue must match the file in Git when the patch is applied, or the plan is stale.

Validation rules:

desiredValue must differ from previousValue: self.desiredValue != self.previousValue

Used by: Action.

Field	Type	Required	Description
`previousValue`	integer	Yes	previousValue is the value the plan was made against. Maximum: 1000 Minimum: 1
`desiredValue`	integer	Yes	desiredValue is the new maxReplicaCount. Maximum: 1000 Minimum: 1

ApprovalMode¶

ApprovalMode says whether a human must approve.

Underlying type: string
One of Required, Optional

Used by: RemediationPolicySpec.

Value	Description
`Required`	ApprovalRequired always needs human review, whatever the request asks.
`Optional`	ApprovalOptional honours approvalRequired=false; repository rules still apply.

AzureKeyVaultKey¶

AzureKeyVaultKey is a key in Azure Key Vault that may only sign (ADR-0006).

Used by: Signer.

Field	Type	Required	Description
`keyID`	string	Yes	keyID is the key identifier, with or without a version, for example https://<vault>.vault.azure.net/keys/github-app. Maximum length: 2048 Pattern: `^https://[a-z0-9-]+\.vault\.azure\.net/keys/[A-Za-z0-9-]+(/[0-9a-f]{32})?$`

GitBranch¶

GitBranch is a branch name. Names that git or a shell could read as something else (a leading dash, refs/, HEAD, '..', '.lock') are refused, and so is the shadewright/ prefix Shadewright uses for its own branches.

Underlying type: string
Maximum length: 255
Minimum length: 1
Pattern: ^[A-Za-z0-9_][A-Za-z0-9_.-]*(/[A-Za-z0-9_][A-Za-z0-9_.-]*)*$

Validation rules:

must be a plain branch name, not HEAD, refs/..., shadewright/... or one containing '..' or '.lock': !self.contains('..') && !self.endsWith('.lock') && !self.contains('.lock/') && self != 'HEAD' && !self.startsWith('refs/') && !self.startsWith('shadewright/')

Used by: GitRepository, ResolvedSource.

GitFilePath¶

GitFilePath is one YAML file, relative to a repository root. Every segment starts with a letter, digit or underscore, so absolute paths, parent references, hidden directories such as .github, option-like names and wildcards are all refused.

Underlying type: string
Maximum length: 512
Minimum length: 1
Pattern: ^[A-Za-z0-9_][A-Za-z0-9_.-]*(/[A-Za-z0-9_][A-Za-z0-9_.-]*)*\.ya?ml$

Used by: ResolvedSource.

GitHubRepository¶

GitHubRepository holds the GitHub App settings for one repository.

Used by: GitRepository.

Field	Type	Required	Description
`appClientID`	string	Yes	appClientID is the GitHub App's client ID. Maximum length: 64 Minimum length: 1
`installationID`	integer	Yes	installationID is the App's installation that covers this repository. Minimum: 1
`signer`	Signer	Yes	signer says where the App's private key is. Rule: a signer must be configured

GitPathPattern¶

GitPathPattern is a glob, relative to a repository root, for files a policy may patch. * matches within one path segment and ** across segments; neither matches a segment that starts with a dot. The first segment must be literal, so a pattern cannot cover the whole repository, and no segment may start with a dot or a dash.

Underlying type: string
Maximum length: 512
Minimum length: 1
Pattern: ^[A-Za-z0-9_][A-Za-z0-9_.-]*(/[A-Za-z0-9_*][A-Za-z0-9_.*-]*)*$

Validation rules:

must not contain '..': !self.contains('..')

Used by: PolicyGitOps.

GitProviderType¶

GitProviderType names a Git hosting adapter (ADR-0004, ADR-0013).

Underlying type: string
One of GitHub

Used by: GitRepository.

Value	Description
`GitHub`	GitProviderGitHub uses a GitHub App.

GitRepository¶

GitRepository is a repository Shadewright may open pull requests in. Requests and policies refer to it by name, so the model never chooses a URL or credentials.

Validation rules:

github must be set if and only if provider is GitHub: self.provider == 'GitHub' ? has(self.github) : !has(self.github)
a GitHub repository URL must be https://github.com/<owner>/<repo> in lower case, without .git: self.provider != 'GitHub' || (self.url.matches('^https://github[.]com/[a-z0-9-]+/[a-z0-9_.-]+$') && !self.url.endsWith('.git') && !self.url.endsWith('/.') && !self.url.endsWith('/..'))

Used by: RemediationSettingsSpec.

Field	Type	Required	Description
`name`	Name	Yes	name is how policies and requests refer to the repository. Maximum length: 63 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
`url`	string	Yes	url is the HTTPS clone URL, without credentials, query or fragment. It must match the URL of the Flux source that delivers a target, or no change is made. Maximum length: 512 Pattern: `^https://[a-z0-9.-]+(:[0-9]+)?(/[A-Za-z0-9_~-][A-Za-z0-9_.~-]*)+$`
`targetBranch`	GitBranch	No	targetBranch is the only branch pull requests may target. The branch Flux tracks must equal it. Default: `main` Maximum length: 255 Minimum length: 1 Pattern: `^[A-Za-z0-9_][A-Za-z0-9_.-](/[A-Za-z0-9_][A-Za-z0-9_.-])*$` Rule: must be a plain branch name, not HEAD, refs/..., shadewright/... or one containing '..' or '.lock'
`provider`	GitProviderType	Yes	provider selects the Git hosting adapter. One of `GitHub`
`github`	GitHubRepository	No	github holds GitHub App settings.

IncidentPhase¶

IncidentPhase summarizes an incident.

Underlying type: string
One of Open, Analyzing, Proposed, Escalated, Resolved

Used by: IncidentStatus.

Value	Description
`Open`	IncidentOpen means symptoms are being collected and no analysis is running.
`Analyzing`	IncidentAnalyzing means the analyzer is working on the incident.
`Proposed`	IncidentProposed means the analysis produced a RemediationRequest.
`Escalated`	IncidentEscalated means the analysis made no proposal and handed the incident to a human.
`Resolved`	IncidentResolved means the symptoms stopped or a remediation succeeded.

IncidentRef¶

IncidentRef points to the Incident a request answers, in the same namespace.

Used by: RemediationRequestSpec.

Field	Type	Required	Description
`name`	string	Yes	name of the Incident. Maximum length: 253 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`
`uid`	UID	Yes	uid of the Incident. Pattern: `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`

IncidentSpec¶

IncidentSpec identifies a group of similar symptoms (design section 3.2). It is immutable: a different fingerprint is a different incident.

Validation rules:

spec is immutable; a different symptom is a new Incident: self == oldSelf

Used by: Incident.

Field	Type	Required	Description
`fingerprint`	string	Yes	fingerprint is the hash of cluster, namespace, owner, reason, action, type, reporting controller and normalized symptom. Pattern: `^sha256:[0-9a-f]{64}$`
`subject`	ObjectRef	Yes	subject is the object the symptoms are correlated to: the owning workload when there is one.
`reason`	string	Yes	reason is the event reason or status reason, for example FailedScheduling or OOMKilled. Maximum length: 128 Minimum length: 1
`type`	string	No	type is the event type. Default: `Warning` One of `Normal`, `Warning`
`reportingController`	string	No	reportingController is the component that reported the symptom. Maximum length: 253
`symptom`	string	No	symptom is the normalized, redacted description: variable parts removed, secrets never included. Maximum length: 1024

IncidentStatus¶

IncidentStatus holds the deduplication state that must survive restarts (ADR-0007). No logs or transcripts.

Used by: Incident.

Field	Type	Required	Description
`phase`	IncidentPhase	No	phase summarizes the incident. One of `Open`, `Analyzing`, `Proposed`, `Escalated`, `Resolved`
`firstSeen`	Time	No	firstSeen is when the first observation arrived.
`lastSeen`	Time	No	lastSeen is when the latest observation arrived.
`count`	integer	No	count is the number of observations, counting event series increments, not totals. Minimum: 0
`lastAnalysisTime`	Time	No	lastAnalysisTime is when the analyzer last ran; it drives the cooldown.
`analysisRecords`	RecordID array	No	analysisRecords are the newest analysis record IDs, oldest first. Maximum items: 20 Maximum length: 256 Minimum length: 1 List type: atomic
`remediationRequests`	Name array	No	remediationRequests are the names of requests made for this incident, oldest first. Maximum items: 20 Maximum length: 63 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` List type: atomic
`conditions`	Condition array	No	conditions explain the phase. List type: map List key: `type`

KedaMaxReplicasBounds¶

KedaMaxReplicasBounds bounds AdjustKedaMaxReplicas. Decreases are refused unless maxDecreasePercent is set.

Validation rules:

min must not be greater than max: self.min <= self.max

Used by: PolicyAction.

Field	Type	Required	Description
`min`	integer	No	min is the lowest maxReplicaCount the policy allows. Default: `1` Maximum: 1000 Minimum: 1
`max`	integer	Yes	max is the highest maxReplicaCount the policy allows. Maximum: 1000 Minimum: 1
`maxIncreasePercent`	integer	No	maxIncreasePercent limits one increase relative to the previous value. Default: `50` Maximum: 1000 Minimum: 1
`maxDecreasePercent`	integer	No	maxDecreasePercent limits one decrease relative to the previous value; 0 refuses every decrease. Default: `0` Maximum: 90 Minimum: 0

MemoryLimitBounds¶

MemoryLimitBounds bounds SetContainerMemoryLimit. Decreases are refused unless maxDecreasePercent is set.

Validation rules:

min and max must be whole bytes: quantity(string(self.min)).isInteger() && quantity(string(self.max)).isInteger()
min must be at least 1Mi: quantity(string(self.min)).compareTo(quantity('1Mi')) >= 0
max must be at most 1Ti: quantity(string(self.max)).compareTo(quantity('1Ti')) <= 0
min must not be greater than max: quantity(string(self.min)).compareTo(quantity(string(self.max))) <= 0

Used by: PolicyAction.

Field	Type	Required	Description
`min`	Quantity	Yes	min is the lowest memory limit the policy allows.
`max`	Quantity	Yes	max is the highest memory limit the policy allows.
`maxIncreasePercent`	integer	No	maxIncreasePercent limits one increase relative to the previous value. Default: `50` Maximum: 1000 Minimum: 1
`maxDecreasePercent`	integer	No	maxDecreasePercent limits one decrease relative to the previous value; 0 refuses every decrease. Default: `0` Maximum: 90 Minimum: 0

Name¶

Name is a DNS label used to reference other Shadewright objects or entries.

Underlying type: string
Maximum length: 63
Minimum length: 1
Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

Used by: GitRepository, IncidentStatus, PolicyGitOps, PolicyTargets, RemediationPolicySpec, RemediationRequestSpec, ResolvedSource.

ObjectRef¶

ObjectRef identifies one Kubernetes object. The UID pins it, so an object recreated under the same name is never mistaken for the one an incident or a plan was about.

Used by: IncidentSpec, RemediationRequestSpec.

Field	Type	Required	Description
`apiVersion`	string	Yes	apiVersion of the object, for example apps/v1 or keda.sh/v1alpha1. Maximum length: 253 Minimum length: 1 Pattern: `^([a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*/)?v[0-9]+((alpha\|beta)[0-9]+)?$`
`kind`	string	Yes	kind of the object. Maximum length: 63 Minimum length: 1 Pattern: `^[A-Z][A-Za-z0-9]*$`
`namespace`	string	No	namespace of the object; empty for cluster-scoped objects. Maximum length: 63 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
`name`	string	Yes	name of the object. Maximum length: 253 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*$`
`uid`	UID	No	uid of the object. Pattern: `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`

PlanRepository¶

PlanRepository identifies the repository a plan was made for: the URL and provider installation taken from RemediationSettings when planDigest was fixed. Cleanup of a superseded plan touches only this repository, so a settings entry that now points elsewhere can never get an unrelated pull request closed.

Used by: RemediationRequestStatus.

Field	Type	Required	Description
`url`	string	Yes	url is the repository URL from RemediationSettings. Maximum length: 512
`installationID`	integer	No	installationID is the provider installation that covers the repository; 0 when the provider has none. Minimum: 0

PolicyAction¶

PolicyAction allows one action type within bounds. Exactly the bounds member named by type is set.

Validation rules:

adjustKedaMaxReplicas must be set if and only if type is AdjustKedaMaxReplicas: self.type == 'AdjustKedaMaxReplicas' ? has(self.adjustKedaMaxReplicas) : !has(self.adjustKedaMaxReplicas)
setContainerMemoryLimit must be set if and only if type is SetContainerMemoryLimit: self.type == 'SetContainerMemoryLimit' ? has(self.setContainerMemoryLimit) : !has(self.setContainerMemoryLimit)

Used by: RemediationPolicySpec.

Field	Type	Required	Description
`type`	ActionType	Yes	type is the allowed action. One of `AdjustKedaMaxReplicas`, `SetContainerMemoryLimit`
`adjustKedaMaxReplicas`	KedaMaxReplicasBounds	No	adjustKedaMaxReplicas bounds AdjustKedaMaxReplicas. Rule: min must not be greater than max
`setContainerMemoryLimit`	MemoryLimitBounds	No	setContainerMemoryLimit bounds SetContainerMemoryLimit. Rule: min and max must be whole bytes Rule: min must be at least 1Mi Rule: max must be at most 1Ti Rule: min must not be greater than max

PolicyGitOps¶

PolicyGitOps says which repository and files a policy may change.

Used by: RemediationPolicySpec.

Field	Type	Required	Description
`repositoryRef`	Name	Yes	repositoryRef names an entry in RemediationSettings spec.repositories. Maximum length: 63 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
`allowedPaths`	GitPathPattern array	Yes	allowedPaths are glob patterns of files the policy may patch. The resolved file must match one. Maximum items: 32 Maximum length: 512 Minimum items: 1 Minimum length: 1 Pattern: `^[A-Za-z0-9_][A-Za-z0-9_.-](/[A-Za-z0-9_][A-Za-z0-9_.-])*$` List type: set Rule: must not contain '..'

PolicyTargets¶

PolicyTargets says which objects a policy covers.

Used by: RemediationPolicySpec.

Field	Type	Required	Description
`namespaces`	Name array	Yes	namespaces the policy covers. Required: there is no "all namespaces". Maximum items: 64 Maximum length: 63 Minimum items: 1 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` List type: set
`objectSelector`	LabelSelector	No	objectSelector further limits targets by label.

PullRequestStatus¶

PullRequestStatus records the pull request that carries the plan.

Used by: RemediationRequestStatus.

Field	Type	Required	Description
`number`	integer	Yes	number of the pull request. Minimum: 1
`url`	string	Yes	url of the pull request. Maximum length: 2048 Pattern: `^https://`
`headSHA`	string	Yes	headSHA is the commit Shadewright pushed. Any other head stops automation. Pattern: `^[0-9a-f]{40}$`

RecordID¶

RecordID identifies an analysis record in the analysis store.

Underlying type: string
Maximum length: 256
Minimum length: 1

Used by: IncidentStatus.

RemediationMode¶

RemediationMode says how a plan is carried out. GitOps is the only mode (ADR-0003).

Underlying type: string
One of GitOps

Used by: RemediationRequestSpec.

Value	Description
`GitOps`	RemediationModeGitOps changes the cluster only through a pull request to the GitOps repository.

RemediationPhase¶

RemediationPhase summarizes where a request is. Conditions carry the reasons.

Underlying type: string
One of Pending, PolicyChecked, PRCreated, AwaitingApproval, AutoMergeQueued, Merged, WaitingForDelivery, Verifying, Succeeded, Denied, Failed, Expired, Cancelled, Superseded, NeedsIntervention

Used by: RemediationRequestStatus.

Value	Description
`Pending`	PhasePending means the request was accepted and is waiting for the policy check.
`PolicyChecked`	PhasePolicyChecked means the policy allows the plan and the source in Git is resolved.
`PRCreated`	PhasePRCreated means the branch and pull request exist.
`AwaitingApproval`	PhaseAwaitingApproval means the pull request waits for human review.
`AutoMergeQueued`	PhaseAutoMergeQueued means policy allowed automation and auto-merge is enabled on the pull request.
`Merged`	PhaseMerged means the pull request is merged.
`WaitingForDelivery`	PhaseWaitingForDelivery means the change is merged and the GitOps controller has not applied it yet.
`Verifying`	PhaseVerifying means the change is delivered and the verification checks are running.
`Succeeded`	PhaseSucceeded means every verification check held for stableFor. Terminal.
`Denied`	PhaseDenied means policy refused the plan; no pull request is opened. Terminal.
`Failed`	PhaseFailed means a step failed, for example verification did not pass before the timeout. Terminal.
`Expired`	PhaseExpired means a step reached its deadline. Terminal.
`Cancelled`	PhaseCancelled means the request was cancelled before the change was merged. Terminal.
`Superseded`	PhaseSuperseded means an input of the plan digest changed, so the pull request is closed and a new request is needed. Terminal.
`NeedsIntervention`	PhaseNeedsIntervention means the controller cannot continue on its own, for example because the target is not declared in a plain manifest; a human must act.

RemediationPolicySpec¶

RemediationPolicySpec is what a policy allows: which namespaces may use it, which targets it covers, which actions within which bounds, where in Git changes may go, and whether a human must approve. It is owned by the cluster admin (ADR-0011).

Used by: RemediationPolicy.

Field	Type	Required	Description
`requestNamespaces`	Name array	No	requestNamespaces are the namespaces whose RemediationRequests may use this policy. A request from any other namespace is Denied, so being able to create requests somewhere does not grant this policy. Default: `[shadewright-system]` Maximum items: 16 Maximum length: 63 Minimum items: 1 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` List type: set
`targets`	PolicyTargets	Yes	targets the policy covers.
`actions`	PolicyAction array	Yes	actions the policy allows, at most one entry per type. MaxItems follows the size of the action catalog; keeping it small keeps the CEL cost of the bounds rules within the API server's budget. Maximum items: 4 Minimum items: 1 List type: map List key: `type` Rule: adjustKedaMaxReplicas must be set if and only if type is AdjustKedaMaxReplicas Rule: setContainerMemoryLimit must be set if and only if type is SetContainerMemoryLimit
`gitOps`	PolicyGitOps	Yes	gitOps limits where changes may be made.
`approval`	ApprovalMode	No	approval says whether human review is always required. Default: `Required` One of `Required`, `Optional`

RemediationPolicyStatus¶

RemediationPolicyStatus reports whether the policy is usable.

Used by: RemediationPolicy.

Field	Type	Required	Description
`observedGeneration`	integer	No	observedGeneration is the generation the status describes.
`conditions`	Condition array	No	conditions report problems such as an unknown repositoryRef. List type: map List key: `type`

RemediationRequestSpec¶

RemediationRequestSpec is one concrete plan. It is immutable: a different plan is a new request, so an approval can never carry over to a changed plan. It names what to change, not where: the repository, branch and file are resolved by the controller (ADR-0012), so the author cannot point a change at another file. Each action type fixes the kinds it may target.

Validation rules:

spec is immutable; a changed plan is a new RemediationRequest: self == oldSelf
AdjustKedaMaxReplicas can only target a keda.sh ScaledObject: self.action.type != 'AdjustKedaMaxReplicas' || (self.targetRef.apiVersion.startsWith('keda.sh/') && self.targetRef.kind == 'ScaledObject')
SetContainerMemoryLimit can only target an apps/v1 Deployment or StatefulSet: self.action.type != 'SetContainerMemoryLimit' || (self.targetRef.apiVersion == 'apps/v1' && self.targetRef.kind in ['Deployment', 'StatefulSet'])

Used by: RemediationRequest.

Field	Type	Required	Description
`incidentRef`	IncidentRef	Yes	incidentRef is the incident this plan answers.
`targetRef`	ObjectRef	Yes	targetRef is the live object the change is about. Rule: targetRef.uid is required (`has(self.uid) && size(self.uid) > 0`) Rule: targetRef.namespace is required (`has(self.namespace) && size(self.namespace) > 0`)
`mode`	RemediationMode	No	mode is how the plan is carried out. Default: `GitOps` One of `GitOps`
`approvalRequired`	boolean	No	approvalRequired asks for human review. false is a request for automation that policy may refuse; it never lowers policy or repository rules. Default: `true`
`policyRef`	Name	Yes	policyRef names the RemediationPolicy that must allow this plan. Maximum length: 63 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
`action`	Action	Yes	action is the typed change. Rule: adjustKedaMaxReplicas must be set if and only if type is AdjustKedaMaxReplicas Rule: setContainerMemoryLimit must be set if and only if type is SetContainerMemoryLimit
`verification`	Verification	No	verification says when the change counts as a success. Default: `{}` Rule: stableFor must be at least 1m Rule: timeout must be at most 24h Rule: timeout must be longer than stableFor

RemediationRequestStatus¶

RemediationRequestStatus is written only by the remediation controller.

Used by: RemediationRequest.

Field	Type	Required	Description
`observedGeneration`	integer	No	observedGeneration is the generation the status describes.
`phase`	RemediationPhase	No	phase summarizes progress. One of `Pending`, `PolicyChecked`, `PRCreated`, `AwaitingApproval`, `AutoMergeQueued`, `Merged`, `WaitingForDelivery`, `Verifying`, `Succeeded`, `Denied`, `Failed`, `Expired`, `Cancelled`, `Superseded`, `NeedsIntervention`
`effectiveApprovalRequired`	boolean	No	effectiveApprovalRequired is what policy decided, which may be stricter than spec.approvalRequired.
`source`	ResolvedSource	No	source is where the change is made, resolved by the controller before the policy check.
`planDigest`	string	No	planDigest covers the semantic change, the target UID, the resolved source with the repository URL and provider installation from RemediationSettings, and the policy UID and generation. It is fixed when the branch is created; if any input changes later, the request becomes Superseded and its PR is closed. Pattern: `^sha256:[0-9a-f]{64}$`
`planRepository`	PlanRepository	No	planRepository is the repository and installation the plan digest covers, set together with planDigest.
`policyRevision`	string	No	policyRevision is the policy name and generation the decision used, as name/generation. The policy UID is recorded next to it, because a deleted and recreated policy can reach the same generation again. Maximum length: 128
`policyUID`	UID	No	policyUID is the UID of the policy the decision used. It is part of the plan digest. Pattern: `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`
`pullRequest`	PullRequestStatus	No	pullRequest is set once the pull request exists.
`deadline`	Time	No	deadline is when the current step gives up.
`conditions`	Condition array	No	conditions explain the phase. Types: PolicyAllowed, PullRequestOpened, Approved, Delivered, Verified and PlanFresh. List type: map List key: `type`

RemediationSettingsSpec¶

RemediationSettingsSpec holds cluster-wide settings, including the kill switch.

Used by: RemediationSettings.

Field	Type	Required	Description
`paused`	boolean	No	paused stops every write: pull requests, auto-merge and issues. Analysis continues. Checked right before each write. Default: `false`
`maxConcurrentRemediations`	integer	No	maxConcurrentRemediations limits requests between PolicyChecked and a terminal phase. Default: `1` Maximum: 20 Minimum: 1
`maxAnalysesPerDay`	integer	No	maxAnalysesPerDay limits model-backed analyses per UTC day; 0 disables the model. Default: `100` Maximum: 10000 Minimum: 0
`repositories`	GitRepository array	No	repositories Shadewright may open pull requests in. URLs are unique, so a Flux source matches at most one entry. Maximum items: 16 List type: map List key: `name` Rule: repository URLs must be unique (`self.all(r, self.exists_one(s, s.url == r.url))`)

RemediationSettingsStatus¶

RemediationSettingsStatus reports whether the settings are usable.

Used by: RemediationSettings.

Field	Type	Required	Description
`observedGeneration`	integer	No	observedGeneration is the generation the status describes.
`conditions`	Condition array	No	conditions report problems such as an unreachable signer. List type: map List key: `type`

ResolvedSource¶

ResolvedSource is where the controller found the target's declaration in Git (ADR-0012). It is derived from the Flux objects that deliver the target and from RemediationSettings, never taken from the request.

Used by: RemediationRequestStatus.

Field	Type	Required	Description
`repositoryRef`	Name	Yes	repositoryRef is the RemediationSettings entry whose URL matches the Flux source. Maximum length: 63 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
`targetBranch`	GitBranch	Yes	targetBranch is the branch the pull request targets: the branch Flux tracks, which must equal the repository's targetBranch in RemediationSettings. Maximum length: 255 Minimum length: 1 Pattern: `^[A-Za-z0-9_][A-Za-z0-9_.-](/[A-Za-z0-9_][A-Za-z0-9_.-])*$` Rule: must be a plain branch name, not HEAD, refs/..., shadewright/... or one containing '..' or '.lock'
`path`	GitFilePath	Yes	path is the file that declares the target. Maximum length: 512 Minimum length: 1 Pattern: `^[A-Za-z0-9_][A-Za-z0-9_.-](/[A-Za-z0-9_][A-Za-z0-9_.-])*\.ya?ml$`
`baseCommit`	string	Yes	baseCommit is the full SHA of the target branch the change was made against. It is fixed when the branch is created; later merges to the target branch do not change it. Pattern: `^[0-9a-f]{40}$`

SetContainerMemoryLimit¶

SetContainerMemoryLimit changes resources.limits.memory of one container. previous must match the file in Git when the patch is applied, or the plan is stale. Both values are whole bytes between 1Mi and 1Ti.

Validation rules:

desired must differ from previous: quantity(string(self.desired)).compareTo(quantity(string(self.previous))) != 0
previous and desired must be whole bytes: quantity(string(self.previous)).isInteger() && quantity(string(self.desired)).isInteger()
previous must be between 1Mi and 1Ti: quantity(string(self.previous)).compareTo(quantity('1Mi')) >= 0 && quantity(string(self.previous)).compareTo(quantity('1Ti')) <= 0
desired must be between 1Mi and 1Ti: quantity(string(self.desired)).compareTo(quantity('1Mi')) >= 0 && quantity(string(self.desired)).compareTo(quantity('1Ti')) <= 0

Used by: Action.

Field	Type	Required	Description
`container`	string	Yes	container is the container name in the pod template. Maximum length: 63 Minimum length: 1 Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
`previous`	Quantity	Yes	previous is the limit the plan was made against.
`desired`	Quantity	Yes	desired is the new limit.

Signer¶

Signer says where the GitHub App private key lives. The key never enters the cluster.

Validation rules:

a signer must be configured: has(self.azureKeyVault)

Used by: GitHubRepository.

Field	Type	Required	Description
`azureKeyVault`	AzureKeyVaultKey	No	azureKeyVault signs with a non-exportable Key Vault key through workload identity.

UID¶

UID is a Kubernetes object UID in its canonical lower-case form.

Underlying type: string
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Used by: IncidentRef, ObjectRef, RemediationRequestStatus.

Verification¶

Verification says when a delivered change counts as a success. The controller always adds the checks the action type needs (DeliveryRevisionApplied, plus KedaReady or NoNewOOMKills), so a request can only make verification stricter.

Validation rules:

stableFor must be at least 1m: !has(self.stableFor) || duration(self.stableFor) >= duration('1m')
timeout must be at most 24h: !has(self.timeout) || duration(self.timeout) <= duration('24h')
timeout must be longer than stableFor: !has(self.timeout) || !has(self.stableFor) || duration(self.timeout) > duration(self.stableFor)

Used by: RemediationRequestSpec.

Field	Type	Required	Description
`timeout`	Duration	No	timeout is how long to wait for delivery and stability before giving up. Default: `10m`
`stableFor`	Duration	No	stableFor is how long all checks must hold. Default: `3m`
`checks`	VerificationCheck array	No	checks to run in addition to the ones the action type always needs. One of `DeliveryRevisionApplied`, `WorkloadHealthy`, `KedaReady`, `QueueBacklogDecreasing`, `NoNewOOMKills` Maximum items: 8 List type: set

VerificationCheck¶

VerificationCheck is a named, deterministic check run after delivery. DeliveryRevisionApplied: the GitOps controller has applied the revision that contains the merged change. WorkloadHealthy: the target workload is available and its rollout is complete. KedaReady: the KEDA ScaledObject reports Ready. QueueBacklogDecreasing: the backlog that drives the ScaledObject is going down. NoNewOOMKills: no container of the target is OOMKilled after the change.

Underlying type: string
One of DeliveryRevisionApplied, WorkloadHealthy, KedaReady, QueueBacklogDecreasing, NoNewOOMKills

Used by: Verification.