diff --git a/DOC.md b/DOC.md new file mode 100644 index 0000000..9d0c7c7 --- /dev/null +++ b/DOC.md @@ -0,0 +1,984 @@ +# API Reference + +Packages: + +- [nodedisruption.criteo.com/v1alpha1](#nodedisruptioncriteocomv1alpha1) + +# nodedisruption.criteo.com/v1alpha1 + +Resource Types: + +- [ApplicationDisruptionBudget](#applicationdisruptionbudget) + +- [NodeDisruptionBudget](#nodedisruptionbudget) + +- [NodeDisruption](#nodedisruption) + + + + +## ApplicationDisruptionBudget +[↩ Parent](#nodedisruptioncriteocomv1alpha1 ) + + + + + + +ApplicationDisruptionBudget is the Schema for the applicationdisruptionbudgets API + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
apiVersionstringnodedisruption.criteo.com/v1alpha1true
kindstringApplicationDisruptionBudgettrue
metadataobjectRefer to the Kubernetes API documentation for the fields of the `metadata` field.true
specobject + ApplicationDisruptionBudgetSpec defines the desired state of ApplicationDisruptionBudget
+ 		false
statusobject + DisruptionBudgetStatus defines the observed state of ApplicationDisruptionBudget
+ 		false
+ + +### ApplicationDisruptionBudget.spec +[↩ Parent](#applicationdisruptionbudget) + + + +ApplicationDisruptionBudgetSpec defines the desired state of ApplicationDisruptionBudget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
maxDisruptionsinteger + A NodeDisruption is allowed if at most "maxDisruptions" nodes selected by selectors are unavailable after the disruption.
+ 		true
healthHookobject + Define a optional hook to call when validating a NodeDisruption. It perform a POST http request containing the NodeDisruption that is being validated. Maintenance will proceed only if the endpoint responds 2XX.
+ 		false
healthURLstring + Health URL is deprecated and will be removed in next version, please use healthHook instead. Health URL is an optional URL to call to validate the state of the application. Maintenance will proceed only if the endpoint responds 2XX.
+ 		false
podSelectorobject + PodSelector query over pods whose nodes are managed by the disruption budget.
+ 		false
pvcSelectorobject + PVCSelector query over PVCs whose nodes are managed by the disruption budget.
+ 		false
+ + +### ApplicationDisruptionBudget.spec.healthHook +[↩ Parent](#applicationdisruptionbudgetspec) + + + +Define a optional hook to call when validating a NodeDisruption. It perform a POST http request containing the NodeDisruption that is being validated. Maintenance will proceed only if the endpoint responds 2XX. + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
caBundlestring + a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used.
+ 		false
urlstring + URL that will be called by the hook, in standard URL form (`scheme://host:port/path`).
+ 		false
+ + +### ApplicationDisruptionBudget.spec.podSelector +[↩ Parent](#applicationdisruptionbudgetspec) + + + +PodSelector query over pods whose nodes are managed by the disruption budget. + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
matchExpressions[]object + matchExpressions is a list of label selector requirements. The requirements are ANDed.
+ 		false
matchLabelsmap[string]string + matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.
+ 		false
+ + +### ApplicationDisruptionBudget.spec.podSelector.matchExpressions[index] +[↩ Parent](#applicationdisruptionbudgetspecpodselector) + + + +A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
keystring + key is the label key that the selector applies to.
+ 		true
operatorstring + operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
+ 		true
values[]string + values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.
+ 		false
+ + +### ApplicationDisruptionBudget.spec.pvcSelector +[↩ Parent](#applicationdisruptionbudgetspec) + + + +PVCSelector query over PVCs whose nodes are managed by the disruption budget. + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
matchExpressions[]object + matchExpressions is a list of label selector requirements. The requirements are ANDed.
+ 		false
matchLabelsmap[string]string + matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.
+ 		false
+ + +### ApplicationDisruptionBudget.spec.pvcSelector.matchExpressions[index] +[↩ Parent](#applicationdisruptionbudgetspecpvcselector) + + + +A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
keystring + key is the label key that the selector applies to.
+ 		true
operatorstring + operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
+ 		true
values[]string + values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.
+ 		false
+ + +### ApplicationDisruptionBudget.status +[↩ Parent](#applicationdisruptionbudget) + + + +DisruptionBudgetStatus defines the observed state of ApplicationDisruptionBudget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
currentDisruptionsinteger + Number of disruption currently seen on the cluster
+
+ Default: 0
+ 		true
disruptions[]object + Disruptions contains a list of disruptions that are related to the budget
+ 		true
disruptionsAllowedinteger + Number of disruption allowed on the nodes of this
+
+ Default: 0
+ 		true
watchedNodes[]string + List of nodes that are being watched by the controller Disruption on this nodes will will be made according to the budget of this cluster.
+ 		false
+ + +### ApplicationDisruptionBudget.status.disruptions[index] +[↩ Parent](#applicationdisruptionbudgetstatus) + + + +Basic information about disruptions + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
namestring + Name of the disruption
+ 		true
statestring + State of the disruption
+ 		true
+ +## NodeDisruptionBudget +[↩ Parent](#nodedisruptioncriteocomv1alpha1 ) + + + + + + +NodeDisruptionBudget is the Schema for the nodedisruptionbudgets API + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
apiVersionstringnodedisruption.criteo.com/v1alpha1true
kindstringNodeDisruptionBudgettrue
metadataobjectRefer to the Kubernetes API documentation for the fields of the `metadata` field.true
specobject + NodeDisruptionBudgetSpec defines the desired state of NodeDisruptionBudget
+ 		false
statusobject + DisruptionBudgetStatus defines the observed state of ApplicationDisruptionBudget
+ 		false
+ + +### NodeDisruptionBudget.spec +[↩ Parent](#nodedisruptionbudget) + + + +NodeDisruptionBudgetSpec defines the desired state of NodeDisruptionBudget + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
maxDisruptedNodesinteger + A NodeDisruption is allowed if at most "maxDisruptedNodes" nodes selected by selectors are unavailable after the disruption.
+ 		true
minUndisruptedNodesinteger + A NodeDisruption is allowed if at most "minUndisruptedNodes" nodes selected by selectors are unavailable after the disruption.
+ 		true
nodeSelectorobject + NodeSelector query over pods whose nodes are managed by the disruption budget.
+ 		false
+ + +### NodeDisruptionBudget.spec.nodeSelector +[↩ Parent](#nodedisruptionbudgetspec) + + + +NodeSelector query over pods whose nodes are managed by the disruption budget. + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
matchExpressions[]object + matchExpressions is a list of label selector requirements. The requirements are ANDed.
+ 		false
matchLabelsmap[string]string + matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.
+ 		false
+ + +### NodeDisruptionBudget.spec.nodeSelector.matchExpressions[index] +[↩ Parent](#nodedisruptionbudgetspecnodeselector) + + + +A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
keystring + key is the label key that the selector applies to.
+ 		true
operatorstring + operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
+ 		true
values[]string + values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.
+ 		false
+ + +### NodeDisruptionBudget.status +[↩ Parent](#nodedisruptionbudget) + + + +DisruptionBudgetStatus defines the observed state of ApplicationDisruptionBudget + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
currentDisruptionsinteger + Number of disruption currently seen on the cluster
+
+ Default: 0
+ 		true
disruptions[]object + Disruptions contains a list of disruptions that are related to the budget
+ 		true
disruptionsAllowedinteger + Number of disruption allowed on the nodes of this
+
+ Default: 0
+ 		true
watchedNodes[]string + List of nodes that are being watched by the controller Disruption on this nodes will will be made according to the budget of this cluster.
+ 		false
+ + +### NodeDisruptionBudget.status.disruptions[index] +[↩ Parent](#nodedisruptionbudgetstatus) + + + +Basic information about disruptions + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
namestring + Name of the disruption
+ 		true
statestring + State of the disruption
+ 		true
+ +## NodeDisruption +[↩ Parent](#nodedisruptioncriteocomv1alpha1 ) + + + + + + +NodeDisruption is the Schema for the nodedisruptions API + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
apiVersionstringnodedisruption.criteo.com/v1alpha1true
kindstringNodeDisruptiontrue
metadataobjectRefer to the Kubernetes API documentation for the fields of the `metadata` field.true
specobject + NodeDisruptionSpec defines the desired state of NodeDisruption
+ 		false
statusobject + NodeDisruptionStatus defines the observed state of NodeDisruption (/!\ it is eventually consistent)
+ 		false
+ + +### NodeDisruption.spec +[↩ Parent](#nodedisruption) + + + +NodeDisruptionSpec defines the desired state of NodeDisruption + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
nodeSelectorobject + Label query over nodes that will be impacted by the disruption
+ 		false
retryobject + Configure the retrying behavior of a NodeDisruption
+ 		false
+ + +### NodeDisruption.spec.nodeSelector +[↩ Parent](#nodedisruptionspec) + + + +Label query over nodes that will be impacted by the disruption + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
matchExpressions[]object + matchExpressions is a list of label selector requirements. The requirements are ANDed.
+ 		false
matchLabelsmap[string]string + matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed.
+ 		false
+ + +### NodeDisruption.spec.nodeSelector.matchExpressions[index] +[↩ Parent](#nodedisruptionspecnodeselector) + + + +A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
keystring + key is the label key that the selector applies to.
+ 		true
operatorstring + operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
+ 		true
values[]string + values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch.
+ 		false
+ + +### NodeDisruption.spec.retry +[↩ Parent](#nodedisruptionspec) + + + +Configure the retrying behavior of a NodeDisruption + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
deadlinestring + Deadline after which the disruption is not retried
+
+ Format: date-time
+ 		false
enabledboolean + Enable retrying
+ 		false
+ + +### NodeDisruption.status +[↩ Parent](#nodedisruption) + + + +NodeDisruptionStatus defines the observed state of NodeDisruption (/!\ it is eventually consistent) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
disruptedDisruptionBudgets[]object + List of all the budgets disrupted by the NodeDisruption
+ 		false
disruptedNodes[]string + List of all the nodes that are disrupted by this NodeDisruption
+ 		false
nextRetryDatestring + Date of the next attempt
+
+ Format: date-time
+ 		false
stateenum + Disruption status
+
+ Enum: pending, granted, rejected
+ Default: pending
+ 		false
+ + +### NodeDisruption.status.disruptedDisruptionBudgets[index] +[↩ Parent](#nodedisruptionstatus) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
okboolean +
+ 		true
reasonstring +
+ 		true
referenceobject + This is the same as types.NamespacedName but serialisable to JSON
+ 		false
+ + +### NodeDisruption.status.disruptedDisruptionBudgets[index].reference +[↩ Parent](#nodedisruptionstatusdisrupteddisruptionbudgetsindex) + + + +This is the same as types.NamespacedName but serialisable to JSON + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionRequired
kindstring +
+ 		true
namestring +
+ 		true
namespacestring +
+ 		true
diff --git a/Makefile b/Makefile index c9f4955..5b6ce47 100644 --- a/Makefile +++ b/Makefile @@ -60,6 +60,10 @@ fmt: ## Run go fmt against code. lint: golangci ## Run golangci $(LOCALBIN)/golangci-lint run +.PHONY: gen-doc +gen-doc: crdoc ## Run golangci + $(LOCALBIN)/crdoc --resources config/crd/bases/ --output DOC.md + .PHONY: vet vet: ## Run go vet against code. go vet ./... @@ -184,6 +188,10 @@ $(ENVTEST): $(LOCALBIN) golangci: ## Run golangci test -s $(LOCALBIN)/golangci-lint || GOBIN=$(LOCALBIN) go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest +.PHONY: crdoc +crdoc: ## Run crdoc + test -s $(LOCALBIN)/crdoc|| GOBIN=$(LOCALBIN) go install fybrik.io/crdoc@v0.6.3 + $(KIND): $(LOCALBIN) test -s $(LOCALBIN)/kind || GOBIN=$(LOCALBIN) GO111MODULE=on go install sigs.k8s.io/kind@$(KIND_VERSION) diff --git a/README.md b/README.md index fab70e5..d4b02af 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,10 @@ Kubernetes primitives and PDB only provide pod-level healthiness protection thro Unfortunately, at the moment Kubernetes doesn't provide such API. Prior to the Node Disruption Controller (NDC), we addressed this need through periodic checks, where we set `maxUnavailable=0` if the service is unhealthy. However, asynchronous health checking is dangerous as it hard to check when the last health check was made (the periodic system could be broken and the state not updated for a long time) or it cannot be fast enough and lead to multiple evictions being granted before reacting. NDC prevents these issues by providing a synchronous health checking API. +## API reference + +[API reference](./DOC.md) + ## Description The primary purpose of the Node Disruption Controller (NDC) is to provide a set of APIs to ensure safety of voluntary node-level disruptions, such as maintenances. Typically, maintenance involves the eviction of pods from a node and potentially rendering the node temporarily or permanently unavailable.