diff --git a/apis/projectcontour/v1/detailedconditions.go b/apis/projectcontour/v1/detailedconditions.go new file mode 100644 index 00000000000..f075cd45855 --- /dev/null +++ b/apis/projectcontour/v1/detailedconditions.go @@ -0,0 +1,104 @@ +// Copyright Project Contour Authors +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// +k8s:deepcopy-gen=package + +// Package v1 is the v1 version of the API. +// +groupName=projectcontour.io +package v1 + +// SubCondition is a Condition-like type intended for use as a subcondition inside a DetailedCondition. +// +// It contains a subset of the Condition fields. +// +// It is intended for warnings and errors, so `type` names should use abnormal-true polarity, +// that is, they should be of the form "ErrorPresent: true". +// +// The expected lifecycle for these errors is that they should only be present when the error or warning is, +// and should be removed when they are not relevant. +type SubCondition struct { + // Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + // + // This must be in abnormal-true polarity, that is, `ErrorFound` or `controller.io/ErrorFound`. + // + // The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt) + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:Pattern=`^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$` + // +kubebuilder:validation:MaxLength=316 + Type string `json:"type" protobuf:"bytes,1,opt,name=type"` + // Status of the condition, one of True, False, Unknown. + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:Enum=True;False;Unknown + Status ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status"` + // Reason contains a programmatic identifier indicating the reason for the condition's last transition. + // Producers of specific condition types may define expected values and meanings for this field, + // and whether the values are considered a guaranteed API. + // + // The value should be a CamelCase string. + // + // This field may not be empty. + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:MaxLength=1024 + // +kubebuilder:validation:MinLength=1 + // +kubebuilder:validation:Pattern=`^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$` + Reason string `json:"reason" protobuf:"bytes,3,opt,name=reason"` + // Message is a human readable message indicating details about the transition. + // + // This may be an empty string. + // + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:MaxLength=32768 + Message string `json:"message" protobuf:"bytes,4,opt,name=message"` +} + +// TODO(youngnick): Replace the inlined Condition with metav1.Condition once we have moved to a client-go +// version that includes it. Also includes deleting kubeconditions.go. + +// DetailedCondition is an extension of the normal Kubernetes conditions, with two extra +// fields to hold sub-conditions, which provide more detailed reasons for the state (True or False) +// of the condition. +// +// `errors` holds information about sub-conditions which are fatal to that condition and render its state False. +// +// `warnings` holds information about sub-conditions which are not fatal to that condition and do not force the state to be False. +// +// Remember that Conditions have a type, a status, and a reason. +// +// The type is the type of the condition, the most important one in this CRD set is `Valid`. +// +// In the case of `Valid`, `status: true` means that the object is has been ingested into Contour with no errors. +// `warnings` may still be present, and will be indicated in the Reason field. +// +// `Valid`, `status: false` means that the object has had one or more fatal errors during processing into Contour. +// The details of the errors will be present under the `errors` field. +// +// There should never be subconditions under `errors` when `status` is `true`. +type DetailedCondition struct { + Condition `json:",inline"` + // Errors contains a slice of relevant error subconditions for this object. + // + // Subconditions are expected to appear when relevant (when there is a error), and disappear when not relevant. + // An empty slice here indicates no errors. + // +optional + Errors []SubCondition `json:"errors,omitempty"` + // Warnings contains a slice of relevant warning subconditions for this object. + // + // Subconditions are expected to appear when relevant (when there is a warning), and disappear when not relevant. + // An empty slice here indicates no warnings. + // +optional + Warnings []SubCondition `json:"warnings,omitempty"` +} diff --git a/apis/projectcontour/v1/doc.go b/apis/projectcontour/v1/doc.go index 217d098d312..4c5b5f1f891 100644 --- a/apis/projectcontour/v1/doc.go +++ b/apis/projectcontour/v1/doc.go @@ -13,6 +13,18 @@ // +k8s:deepcopy-gen=package -// Package v1 is the v1 version of the API. +// This package holds the specification for the projectcontour.io Custom Resource Definitions (CRDs). +// +// In building this CRD, we've inadvertently overloaded the word "Condition", so we've tried to make +// this spec clear as to which types of condition are which. +// +// `MatchConditions` are used by `Routes` and `Includes` to specify rules to match requests against for either +// routing or inclusion. +// +// `DetailedConditions` are used in the `Status` of these objects to hold information about the relevant +// state of the object and the world around it. +// +// `SubConditions` are used underneath `DetailedConditions` to give more detail to errors or warnings. +// // +groupName=projectcontour.io package v1 diff --git a/apis/projectcontour/v1/httpproxy.go b/apis/projectcontour/v1/httpproxy.go index 95da9e35460..ad303dfe5d1 100644 --- a/apis/projectcontour/v1/httpproxy.go +++ b/apis/projectcontour/v1/httpproxy.go @@ -21,7 +21,7 @@ import ( // HTTPProxySpec defines the spec of the CRD. type HTTPProxySpec struct { // Virtualhost appears at most once. If it is present, the object is considered - // to be a "root". + // to be a "root" HTTPProxy. // +optional VirtualHost *VirtualHost `json:"virtualhost,omitempty"` // Routes are the ingress routes. If TCPProxy is present, Routes is ignored. @@ -30,7 +30,8 @@ type HTTPProxySpec struct { // TCPProxy holds TCP proxy information. // +optional TCPProxy *TCPProxy `json:"tcpproxy,omitempty"` - // Includes allow for specific routing configuration to be appended to another HTTPProxy in another namespace. + // Includes allow for specific routing configuration to be included from another HTTPProxy, + // possibly in another namespace. // +optional Includes []Include `json:"includes,omitempty"` } @@ -104,11 +105,11 @@ type HeaderMatchCondition struct { // to be a "root". type VirtualHost struct { // The fully qualified domain name of the root of the ingress tree - // all leaves of the DAG rooted at this object relate to the fqdn + // all leaves of the DAG rooted at this object relate to the fqdn. Fqdn string `json:"fqdn"` // If present describes tls properties. The SNI names that will be matched on // are described in fqdn, the tls.secretName secret must contain a - // matching certificate + // certificate that itself contains a name that matches the FQDN. // +optional TLS *TLS `json:"tls,omitempty"` } @@ -467,12 +468,30 @@ type HTTPProxyStatus struct { // +optional // LoadBalancer contains the current status of the load balancer. LoadBalancer corev1.LoadBalancerStatus `json:"loadBalancer,omitempty"` + // +optional + // Conditions contains information about the current status of the HTTPProxy, + // in an upstream-friendly container. + // + // Contour will update a single condition, `Valid`, that is in normal-true polarity. + // That is, when `currentStatus` is `valid`, the `Valid` condition will be `status: true`, + // and vice versa. + // + // Contour will leave untouched any other Conditions set in this block, + // in case some other controller wants to add a Condition. + // + // If you are another controller owner and wish to add a condition, you *should* + // namespace your condition with a label, like `controller.domain.com/ConditionName`. + // +patchMergeKey=type + // +patchStrategy=merge + // +listType=map + // +listMapKey=type + Conditions []DetailedCondition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` } // +genclient // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object -// HTTPProxy is an Ingress CRD specification +// HTTPProxy is an Ingress CRD specification. // +k8s:openapi-gen=true // +kubebuilder:printcolumn:name="FQDN",type="string",JSONPath=".spec.virtualhost.fqdn",description="Fully qualified domain name" // +kubebuilder:printcolumn:name="TLS Secret",type="string",JSONPath=".spec.virtualhost.tls.secretName",description="Secret with TLS credentials" @@ -485,6 +504,7 @@ type HTTPProxy struct { metav1.ObjectMeta `json:"metadata"` Spec HTTPProxySpec `json:"spec"` + // Status is a container for computed information about the HTTPProxy. // +optional Status HTTPProxyStatus `json:"status,omitempty"` } diff --git a/apis/projectcontour/v1/kubeconditions.go b/apis/projectcontour/v1/kubeconditions.go new file mode 100644 index 00000000000..4a73f12eef0 --- /dev/null +++ b/apis/projectcontour/v1/kubeconditions.go @@ -0,0 +1,109 @@ +/* +Copyright 2015 The Kubernetes Authors. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// +k8s:deepcopy-gen=package + +// Package v1 is the v1 version of the API. +// +groupName=projectcontour.io +package v1 + +// TODO(youngnick): This whole file is a copy-and-paste from +// the current upstream master of "k8s.io/apimachinery/pkg/apis/meta/v1". +// This should be removed once we update to a version of client-go +// that includes a metav1.Condition type. +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" +) + +type ConditionStatus string + +// These are valid condition statuses. "ConditionTrue" means a resource is in the condition. +// "ConditionFalse" means a resource is not in the condition. "ConditionUnknown" means kubernetes +// can't decide if a resource is in the condition or not. In the future, we could add other +// intermediate conditions, e.g. ConditionDegraded. +const ( + ConditionTrue ConditionStatus = "True" + ConditionFalse ConditionStatus = "False" + ConditionUnknown ConditionStatus = "Unknown" +) + +// Condition contains details for one aspect of the current state of this API Resource. +// +// This struct is intended for direct use as an array at the field path .status.conditions. For example, +// ```go +// type FooStatus struct{ +// // Represents the observations of a foo's current state. +// // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" +// // +patchMergeKey=type +// // +patchStrategy=merge +// // +listType=map +// // +listMapKey=type +// Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` +// +// // other fields +// } +// ``` +type Condition struct { + // Type of condition in CamelCase or in foo.example.com/CamelCase. + // + // Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be + // useful (see .node.status.conditions), the ability to deconflict is important. + // + // The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt) + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:Pattern=`^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$` + // +kubebuilder:validation:MaxLength=316 + Type string `json:"type" protobuf:"bytes,1,opt,name=type"` + // status of the condition, one of True, False, Unknown. + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:Enum=True;False;Unknown + Status ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status"` + // observedGeneration represents the .metadata.generation that the condition was set based upon. + // + // For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date + // with respect to the current state of the instance. + // +optional + // +kubebuilder:validation:Minimum=0 + ObservedGeneration int64 `json:"observedGeneration,omitempty" protobuf:"varint,3,opt,name=observedGeneration"` + // lastTransitionTime is the last time the condition transitioned from one status to another. + // + // This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:Type=string + // +kubebuilder:validation:Format=date-time + LastTransitionTime metav1.Time `json:"lastTransitionTime" protobuf:"bytes,4,opt,name=lastTransitionTime"` + // Reason contains a programmatic identifier indicating the reason for the condition's last transition. + // + // Producers of specific condition types may define expected values and meanings for this field, + // and whether the values are considered a guaranteed API. + // + // The value should be a CamelCase string. + // + // This field may not be empty. + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:MaxLength=1024 + // +kubebuilder:validation:MinLength=1 + // +kubebuilder:validation:Pattern=`^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$` + Reason string `json:"reason" protobuf:"bytes,5,opt,name=reason"` + // message is a human readable message indicating details about the transition. + // + // This may be an empty string. + // +required + // +kubebuilder:validation:Required + // +kubebuilder:validation:MaxLength=32768 + Message string `json:"message" protobuf:"bytes,6,opt,name=message"` +} diff --git a/apis/projectcontour/v1/tlscertificatedelegation.go b/apis/projectcontour/v1/tlscertificatedelegation.go index f8765317005..b5b68ffa38f 100644 --- a/apis/projectcontour/v1/tlscertificatedelegation.go +++ b/apis/projectcontour/v1/tlscertificatedelegation.go @@ -37,6 +37,29 @@ type CertificateDelegation struct { TargetNamespaces []string `json:"targetNamespaces"` } +// TLSCertificateDelegationStatus allows for the status of the delegation +// to be presented to the user. +type TLSCertificateDelegationStatus struct { + // +optional + // Conditions contains information about the current status of the HTTPProxy, + // in an upstream-friendly container. + // + // Contour will update a single condition, `Valid`, that is in normal-true polarity. + // That is, when `currentStatus` is `valid`, the `Valid` condition will be `status: true`, + // and vice versa. + // + // Contour will leave untouched any other Conditions set in this block, + // in case some other controller wants to add a Condition. + // + // If you are another controller owner and wish to add a condition, you *should* + // namespace your condition with a label, like `controller.domain.com\ConditionName`. + // +patchMergeKey=type + // +patchStrategy=merge + // +listType=map + // +listMapKey=type + Conditions []DetailedCondition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` +} + // +genclient // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object @@ -44,11 +67,14 @@ type CertificateDelegation struct { // See design/tls-certificate-delegation.md for details. // +k8s:openapi-gen=true // +kubebuilder:resource:scope=Namespaced,path=tlscertificatedelegations,shortName=tlscerts,singular=tlscertificatedelegation +// +kubebuilder:subresource:status type TLSCertificateDelegation struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata"` Spec TLSCertificateDelegationSpec `json:"spec"` + // +optional + Status TLSCertificateDelegationStatus `json:"status,omitempty"` } // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object diff --git a/apis/projectcontour/v1/zz_generated.deepcopy.go b/apis/projectcontour/v1/zz_generated.deepcopy.go index 2aed1332607..35907bed1b6 100644 --- a/apis/projectcontour/v1/zz_generated.deepcopy.go +++ b/apis/projectcontour/v1/zz_generated.deepcopy.go @@ -44,6 +44,48 @@ func (in *CertificateDelegation) DeepCopy() *CertificateDelegation { return out } +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *Condition) DeepCopyInto(out *Condition) { + *out = *in + in.LastTransitionTime.DeepCopyInto(&out.LastTransitionTime) +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Condition. +func (in *Condition) DeepCopy() *Condition { + if in == nil { + return nil + } + out := new(Condition) + in.DeepCopyInto(out) + return out +} + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *DetailedCondition) DeepCopyInto(out *DetailedCondition) { + *out = *in + in.Condition.DeepCopyInto(&out.Condition) + if in.Errors != nil { + in, out := &in.Errors, &out.Errors + *out = make([]SubCondition, len(*in)) + copy(*out, *in) + } + if in.Warnings != nil { + in, out := &in.Warnings, &out.Warnings + *out = make([]SubCondition, len(*in)) + copy(*out, *in) + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DetailedCondition. +func (in *DetailedCondition) DeepCopy() *DetailedCondition { + if in == nil { + return nil + } + out := new(DetailedCondition) + in.DeepCopyInto(out) + return out +} + // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *DownstreamValidation) DeepCopyInto(out *DownstreamValidation) { *out = *in @@ -176,6 +218,13 @@ func (in *HTTPProxySpec) DeepCopy() *HTTPProxySpec { func (in *HTTPProxyStatus) DeepCopyInto(out *HTTPProxyStatus) { *out = *in in.LoadBalancer.DeepCopyInto(&out.LoadBalancer) + if in.Conditions != nil { + in, out := &in.Conditions, &out.Conditions + *out = make([]DetailedCondition, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HTTPProxyStatus. @@ -459,6 +508,21 @@ func (in *Service) DeepCopy() *Service { return out } +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *SubCondition) DeepCopyInto(out *SubCondition) { + *out = *in +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SubCondition. +func (in *SubCondition) DeepCopy() *SubCondition { + if in == nil { + return nil + } + out := new(SubCondition) + in.DeepCopyInto(out) + return out +} + // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *TCPHealthCheckPolicy) DeepCopyInto(out *TCPHealthCheckPolicy) { *out = *in @@ -557,6 +621,7 @@ func (in *TLSCertificateDelegation) DeepCopyInto(out *TLSCertificateDelegation) out.TypeMeta = in.TypeMeta in.ObjectMeta.DeepCopyInto(&out.ObjectMeta) in.Spec.DeepCopyInto(&out.Spec) + in.Status.DeepCopyInto(&out.Status) } // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TLSCertificateDelegation. @@ -631,6 +696,28 @@ func (in *TLSCertificateDelegationSpec) DeepCopy() *TLSCertificateDelegationSpec return out } +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *TLSCertificateDelegationStatus) DeepCopyInto(out *TLSCertificateDelegationStatus) { + *out = *in + if in.Conditions != nil { + in, out := &in.Conditions, &out.Conditions + *out = make([]DetailedCondition, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TLSCertificateDelegationStatus. +func (in *TLSCertificateDelegationStatus) DeepCopy() *TLSCertificateDelegationStatus { + if in == nil { + return nil + } + out := new(TLSCertificateDelegationStatus) + in.DeepCopyInto(out) + return out +} + // DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. func (in *TimeoutPolicy) DeepCopyInto(out *TimeoutPolicy) { *out = *in diff --git a/examples/contour/01-crds.yaml b/examples/contour/01-crds.yaml index 84a02f7117d..f3e539d138d 100644 --- a/examples/contour/01-crds.yaml +++ b/examples/contour/01-crds.yaml @@ -38,7 +38,7 @@ spec: status: {} validation: openAPIV3Schema: - description: HTTPProxy is an Ingress CRD specification + description: HTTPProxy is an Ingress CRD specification. properties: apiVersion: description: 'APIVersion defines the versioned schema of this representation @@ -57,7 +57,7 @@ spec: properties: includes: description: Includes allow for specific routing configuration to be - appended to another HTTPProxy in another namespace. + included from another HTTPProxy, possibly in another namespace. items: description: Include describes a set of policies that can be applied to an HTTPProxy in a namespace. @@ -726,17 +726,18 @@ spec: type: object virtualhost: description: Virtualhost appears at most once. If it is present, the - object is considered to be a "root". + object is considered to be a "root" HTTPProxy. properties: fqdn: description: The fully qualified domain name of the root of the ingress tree all leaves of the DAG rooted at this object relate - to the fqdn + to the fqdn. type: string tls: description: If present describes tls properties. The SNI names that will be matched on are described in fqdn, the tls.secretName - secret must contain a matching certificate + secret must contain a certificate that itself contains a name + that matches the FQDN. properties: clientValidation: description: "ClientValidation defines how to verify the client @@ -777,8 +778,205 @@ spec: type: object type: object status: - description: HTTPProxyStatus reports the current state of the HTTPProxy. + description: Status is a container for computed information about the HTTPProxy. properties: + conditions: + description: "Conditions contains information about the current status + of the HTTPProxy, in an upstream-friendly container. \n Contour will + update a single condition, `Valid`, that is in normal-true polarity. + That is, when `currentStatus` is `valid`, the `Valid` condition will + be `status: true`, and vice versa. \n Contour will leave untouched + any other Conditions set in this block, in case some other controller + wants to add a Condition. \n If you are another controller owner and + wish to add a condition, you *should* namespace your condition with + a label, like `controller.domain.com/ConditionName`." + items: + description: "DetailedCondition is an extension of the normal Kubernetes + conditions, with two extra fields to hold sub-conditions, which + provide more detailed reasons for the state (True or False) of the + condition. \n `errors` holds information about sub-conditions which + are fatal to that condition and render its state False. \n `warnings` + holds information about sub-conditions which are not fatal to that + condition and do not force the state to be False. \n Remember that + Conditions have a type, a status, and a reason. \n The type is the + type of the condition, the most important one in this CRD set is + `Valid`. \n In the case of `Valid`, `status: true` means that the + object is has been ingested into Contour with no errors. `warnings` + may still be present, and will be indicated in the Reason field. + \n `Valid`, `status: false` means that the object has had one or + more fatal errors during processing into Contour. The details of + the errors will be present under the `errors` field. \n There should + never be subconditions under `errors` when `status` is `true`." + properties: + errors: + description: "Errors contains a slice of relevant error subconditions + for this object. \n Subconditions are expected to appear when + relevant (when there is a error), and disappear when not relevant. + An empty slice here indicates no errors." + items: + description: "SubCondition is a Condition-like type intended + for use as a subcondition inside a DetailedCondition. \n It + contains a subset of the Condition fields. \n It is intended + for warnings and errors, so `type` names should use abnormal-true + polarity, that is, they should be of the form \"ErrorPresent: + true\". \n The expected lifecycle for these errors is that + they should only be present when the error or warning is, + and should be removed when they are not relevant." + properties: + message: + description: "Message is a human readable message indicating + details about the transition. \n This may be an empty + string." + maxLength: 32768 + type: string + reason: + description: "Reason contains a programmatic identifier + indicating the reason for the condition's last transition. + Producers of specific condition types may define expected + values and meanings for this field, and whether the values + are considered a guaranteed API. \n The value should be + a CamelCase string. \n This field may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + \n This must be in abnormal-true polarity, that is, `ErrorFound` + or `controller.io/ErrorFound`. \n The regex it matches + is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - message + - reason + - status + - type + type: object + type: array + lastTransitionTime: + description: "lastTransitionTime is the last time the condition + transitioned from one status to another. \n This should be when + the underlying condition changed. If that is not known, then + using the time when the API field changed is acceptable." + format: date-time + type: string + message: + description: "message is a human readable message indicating details + about the transition. \n This may be an empty string." + maxLength: 32768 + type: string + observedGeneration: + description: "observedGeneration represents the .metadata.generation + that the condition was set based upon. \n For instance, if .metadata.generation + is currently 12, but the .status.conditions[x].observedGeneration + is 9, the condition is out of date with respect to the current + state of the instance." + format: int64 + minimum: 0 + type: integer + reason: + description: "Reason contains a programmatic identifier indicating + the reason for the condition's last transition. \n Producers + of specific condition types may define expected values and meanings + for this field, and whether the values are considered a guaranteed + API. \n The value should be a CamelCase string. \n This field + may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in CamelCase or in foo.example.com/CamelCase. + \n Many .condition.type values are consistent across resources + like Available, but because arbitrary conditions can be useful + (see .node.status.conditions), the ability to deconflict is + important. \n The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + warnings: + description: "Warnings contains a slice of relevant warning subconditions + for this object. \n Subconditions are expected to appear when + relevant (when there is a warning), and disappear when not relevant. + An empty slice here indicates no warnings." + items: + description: "SubCondition is a Condition-like type intended + for use as a subcondition inside a DetailedCondition. \n It + contains a subset of the Condition fields. \n It is intended + for warnings and errors, so `type` names should use abnormal-true + polarity, that is, they should be of the form \"ErrorPresent: + true\". \n The expected lifecycle for these errors is that + they should only be present when the error or warning is, + and should be removed when they are not relevant." + properties: + message: + description: "Message is a human readable message indicating + details about the transition. \n This may be an empty + string." + maxLength: 32768 + type: string + reason: + description: "Reason contains a programmatic identifier + indicating the reason for the condition's last transition. + Producers of specific condition types may define expected + values and meanings for this field, and whether the values + are considered a guaranteed API. \n The value should be + a CamelCase string. \n This field may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + \n This must be in abnormal-true polarity, that is, `ErrorFound` + or `controller.io/ErrorFound`. \n The regex it matches + is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - message + - reason + - status + - type + type: object + type: array + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + x-kubernetes-list-map-keys: + - type + x-kubernetes-list-type: map currentStatus: type: string description: @@ -840,6 +1038,8 @@ spec: - tlscerts singular: tlscertificatedelegation scope: Namespaced + subresources: + status: {} validation: openAPIV3Schema: description: TLSCertificateDelegation is an TLS Certificate Delegation CRD specificiation. @@ -885,6 +1085,208 @@ spec: required: - delegations type: object + status: + description: TLSCertificateDelegationStatus allows for the status of the + delegation to be presented to the user. + properties: + conditions: + description: "Conditions contains information about the current status + of the HTTPProxy, in an upstream-friendly container. \n Contour will + update a single condition, `Valid`, that is in normal-true polarity. + That is, when `currentStatus` is `valid`, the `Valid` condition will + be `status: true`, and vice versa. \n Contour will leave untouched + any other Conditions set in this block, in case some other controller + wants to add a Condition. \n If you are another controller owner and + wish to add a condition, you *should* namespace your condition with + a label, like `controller.domain.com\\ConditionName`." + items: + description: "DetailedCondition is an extension of the normal Kubernetes + conditions, with two extra fields to hold sub-conditions, which + provide more detailed reasons for the state (True or False) of the + condition. \n `errors` holds information about sub-conditions which + are fatal to that condition and render its state False. \n `warnings` + holds information about sub-conditions which are not fatal to that + condition and do not force the state to be False. \n Remember that + Conditions have a type, a status, and a reason. \n The type is the + type of the condition, the most important one in this CRD set is + `Valid`. \n In the case of `Valid`, `status: true` means that the + object is has been ingested into Contour with no errors. `warnings` + may still be present, and will be indicated in the Reason field. + \n `Valid`, `status: false` means that the object has had one or + more fatal errors during processing into Contour. The details of + the errors will be present under the `errors` field. \n There should + never be subconditions under `errors` when `status` is `true`." + properties: + errors: + description: "Errors contains a slice of relevant error subconditions + for this object. \n Subconditions are expected to appear when + relevant (when there is a error), and disappear when not relevant. + An empty slice here indicates no errors." + items: + description: "SubCondition is a Condition-like type intended + for use as a subcondition inside a DetailedCondition. \n It + contains a subset of the Condition fields. \n It is intended + for warnings and errors, so `type` names should use abnormal-true + polarity, that is, they should be of the form \"ErrorPresent: + true\". \n The expected lifecycle for these errors is that + they should only be present when the error or warning is, + and should be removed when they are not relevant." + properties: + message: + description: "Message is a human readable message indicating + details about the transition. \n This may be an empty + string." + maxLength: 32768 + type: string + reason: + description: "Reason contains a programmatic identifier + indicating the reason for the condition's last transition. + Producers of specific condition types may define expected + values and meanings for this field, and whether the values + are considered a guaranteed API. \n The value should be + a CamelCase string. \n This field may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + \n This must be in abnormal-true polarity, that is, `ErrorFound` + or `controller.io/ErrorFound`. \n The regex it matches + is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - message + - reason + - status + - type + type: object + type: array + lastTransitionTime: + description: "lastTransitionTime is the last time the condition + transitioned from one status to another. \n This should be when + the underlying condition changed. If that is not known, then + using the time when the API field changed is acceptable." + format: date-time + type: string + message: + description: "message is a human readable message indicating details + about the transition. \n This may be an empty string." + maxLength: 32768 + type: string + observedGeneration: + description: "observedGeneration represents the .metadata.generation + that the condition was set based upon. \n For instance, if .metadata.generation + is currently 12, but the .status.conditions[x].observedGeneration + is 9, the condition is out of date with respect to the current + state of the instance." + format: int64 + minimum: 0 + type: integer + reason: + description: "Reason contains a programmatic identifier indicating + the reason for the condition's last transition. \n Producers + of specific condition types may define expected values and meanings + for this field, and whether the values are considered a guaranteed + API. \n The value should be a CamelCase string. \n This field + may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in CamelCase or in foo.example.com/CamelCase. + \n Many .condition.type values are consistent across resources + like Available, but because arbitrary conditions can be useful + (see .node.status.conditions), the ability to deconflict is + important. \n The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + warnings: + description: "Warnings contains a slice of relevant warning subconditions + for this object. \n Subconditions are expected to appear when + relevant (when there is a warning), and disappear when not relevant. + An empty slice here indicates no warnings." + items: + description: "SubCondition is a Condition-like type intended + for use as a subcondition inside a DetailedCondition. \n It + contains a subset of the Condition fields. \n It is intended + for warnings and errors, so `type` names should use abnormal-true + polarity, that is, they should be of the form \"ErrorPresent: + true\". \n The expected lifecycle for these errors is that + they should only be present when the error or warning is, + and should be removed when they are not relevant." + properties: + message: + description: "Message is a human readable message indicating + details about the transition. \n This may be an empty + string." + maxLength: 32768 + type: string + reason: + description: "Reason contains a programmatic identifier + indicating the reason for the condition's last transition. + Producers of specific condition types may define expected + values and meanings for this field, and whether the values + are considered a guaranteed API. \n The value should be + a CamelCase string. \n This field may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + \n This must be in abnormal-true polarity, that is, `ErrorFound` + or `controller.io/ErrorFound`. \n The regex it matches + is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - message + - reason + - status + - type + type: object + type: array + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + x-kubernetes-list-map-keys: + - type + x-kubernetes-list-type: map + type: object required: - metadata - spec diff --git a/examples/render/contour.yaml b/examples/render/contour.yaml index 0c08354cf23..76e615840b2 100644 --- a/examples/render/contour.yaml +++ b/examples/render/contour.yaml @@ -150,7 +150,7 @@ spec: status: {} validation: openAPIV3Schema: - description: HTTPProxy is an Ingress CRD specification + description: HTTPProxy is an Ingress CRD specification. properties: apiVersion: description: 'APIVersion defines the versioned schema of this representation @@ -169,7 +169,7 @@ spec: properties: includes: description: Includes allow for specific routing configuration to be - appended to another HTTPProxy in another namespace. + included from another HTTPProxy, possibly in another namespace. items: description: Include describes a set of policies that can be applied to an HTTPProxy in a namespace. @@ -838,17 +838,18 @@ spec: type: object virtualhost: description: Virtualhost appears at most once. If it is present, the - object is considered to be a "root". + object is considered to be a "root" HTTPProxy. properties: fqdn: description: The fully qualified domain name of the root of the ingress tree all leaves of the DAG rooted at this object relate - to the fqdn + to the fqdn. type: string tls: description: If present describes tls properties. The SNI names that will be matched on are described in fqdn, the tls.secretName - secret must contain a matching certificate + secret must contain a certificate that itself contains a name + that matches the FQDN. properties: clientValidation: description: "ClientValidation defines how to verify the client @@ -889,8 +890,205 @@ spec: type: object type: object status: - description: HTTPProxyStatus reports the current state of the HTTPProxy. + description: Status is a container for computed information about the HTTPProxy. properties: + conditions: + description: "Conditions contains information about the current status + of the HTTPProxy, in an upstream-friendly container. \n Contour will + update a single condition, `Valid`, that is in normal-true polarity. + That is, when `currentStatus` is `valid`, the `Valid` condition will + be `status: true`, and vice versa. \n Contour will leave untouched + any other Conditions set in this block, in case some other controller + wants to add a Condition. \n If you are another controller owner and + wish to add a condition, you *should* namespace your condition with + a label, like `controller.domain.com/ConditionName`." + items: + description: "DetailedCondition is an extension of the normal Kubernetes + conditions, with two extra fields to hold sub-conditions, which + provide more detailed reasons for the state (True or False) of the + condition. \n `errors` holds information about sub-conditions which + are fatal to that condition and render its state False. \n `warnings` + holds information about sub-conditions which are not fatal to that + condition and do not force the state to be False. \n Remember that + Conditions have a type, a status, and a reason. \n The type is the + type of the condition, the most important one in this CRD set is + `Valid`. \n In the case of `Valid`, `status: true` means that the + object is has been ingested into Contour with no errors. `warnings` + may still be present, and will be indicated in the Reason field. + \n `Valid`, `status: false` means that the object has had one or + more fatal errors during processing into Contour. The details of + the errors will be present under the `errors` field. \n There should + never be subconditions under `errors` when `status` is `true`." + properties: + errors: + description: "Errors contains a slice of relevant error subconditions + for this object. \n Subconditions are expected to appear when + relevant (when there is a error), and disappear when not relevant. + An empty slice here indicates no errors." + items: + description: "SubCondition is a Condition-like type intended + for use as a subcondition inside a DetailedCondition. \n It + contains a subset of the Condition fields. \n It is intended + for warnings and errors, so `type` names should use abnormal-true + polarity, that is, they should be of the form \"ErrorPresent: + true\". \n The expected lifecycle for these errors is that + they should only be present when the error or warning is, + and should be removed when they are not relevant." + properties: + message: + description: "Message is a human readable message indicating + details about the transition. \n This may be an empty + string." + maxLength: 32768 + type: string + reason: + description: "Reason contains a programmatic identifier + indicating the reason for the condition's last transition. + Producers of specific condition types may define expected + values and meanings for this field, and whether the values + are considered a guaranteed API. \n The value should be + a CamelCase string. \n This field may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + \n This must be in abnormal-true polarity, that is, `ErrorFound` + or `controller.io/ErrorFound`. \n The regex it matches + is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - message + - reason + - status + - type + type: object + type: array + lastTransitionTime: + description: "lastTransitionTime is the last time the condition + transitioned from one status to another. \n This should be when + the underlying condition changed. If that is not known, then + using the time when the API field changed is acceptable." + format: date-time + type: string + message: + description: "message is a human readable message indicating details + about the transition. \n This may be an empty string." + maxLength: 32768 + type: string + observedGeneration: + description: "observedGeneration represents the .metadata.generation + that the condition was set based upon. \n For instance, if .metadata.generation + is currently 12, but the .status.conditions[x].observedGeneration + is 9, the condition is out of date with respect to the current + state of the instance." + format: int64 + minimum: 0 + type: integer + reason: + description: "Reason contains a programmatic identifier indicating + the reason for the condition's last transition. \n Producers + of specific condition types may define expected values and meanings + for this field, and whether the values are considered a guaranteed + API. \n The value should be a CamelCase string. \n This field + may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in CamelCase or in foo.example.com/CamelCase. + \n Many .condition.type values are consistent across resources + like Available, but because arbitrary conditions can be useful + (see .node.status.conditions), the ability to deconflict is + important. \n The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + warnings: + description: "Warnings contains a slice of relevant warning subconditions + for this object. \n Subconditions are expected to appear when + relevant (when there is a warning), and disappear when not relevant. + An empty slice here indicates no warnings." + items: + description: "SubCondition is a Condition-like type intended + for use as a subcondition inside a DetailedCondition. \n It + contains a subset of the Condition fields. \n It is intended + for warnings and errors, so `type` names should use abnormal-true + polarity, that is, they should be of the form \"ErrorPresent: + true\". \n The expected lifecycle for these errors is that + they should only be present when the error or warning is, + and should be removed when they are not relevant." + properties: + message: + description: "Message is a human readable message indicating + details about the transition. \n This may be an empty + string." + maxLength: 32768 + type: string + reason: + description: "Reason contains a programmatic identifier + indicating the reason for the condition's last transition. + Producers of specific condition types may define expected + values and meanings for this field, and whether the values + are considered a guaranteed API. \n The value should be + a CamelCase string. \n This field may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + \n This must be in abnormal-true polarity, that is, `ErrorFound` + or `controller.io/ErrorFound`. \n The regex it matches + is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - message + - reason + - status + - type + type: object + type: array + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + x-kubernetes-list-map-keys: + - type + x-kubernetes-list-type: map currentStatus: type: string description: @@ -952,6 +1150,8 @@ spec: - tlscerts singular: tlscertificatedelegation scope: Namespaced + subresources: + status: {} validation: openAPIV3Schema: description: TLSCertificateDelegation is an TLS Certificate Delegation CRD specificiation. @@ -997,6 +1197,208 @@ spec: required: - delegations type: object + status: + description: TLSCertificateDelegationStatus allows for the status of the + delegation to be presented to the user. + properties: + conditions: + description: "Conditions contains information about the current status + of the HTTPProxy, in an upstream-friendly container. \n Contour will + update a single condition, `Valid`, that is in normal-true polarity. + That is, when `currentStatus` is `valid`, the `Valid` condition will + be `status: true`, and vice versa. \n Contour will leave untouched + any other Conditions set in this block, in case some other controller + wants to add a Condition. \n If you are another controller owner and + wish to add a condition, you *should* namespace your condition with + a label, like `controller.domain.com\\ConditionName`." + items: + description: "DetailedCondition is an extension of the normal Kubernetes + conditions, with two extra fields to hold sub-conditions, which + provide more detailed reasons for the state (True or False) of the + condition. \n `errors` holds information about sub-conditions which + are fatal to that condition and render its state False. \n `warnings` + holds information about sub-conditions which are not fatal to that + condition and do not force the state to be False. \n Remember that + Conditions have a type, a status, and a reason. \n The type is the + type of the condition, the most important one in this CRD set is + `Valid`. \n In the case of `Valid`, `status: true` means that the + object is has been ingested into Contour with no errors. `warnings` + may still be present, and will be indicated in the Reason field. + \n `Valid`, `status: false` means that the object has had one or + more fatal errors during processing into Contour. The details of + the errors will be present under the `errors` field. \n There should + never be subconditions under `errors` when `status` is `true`." + properties: + errors: + description: "Errors contains a slice of relevant error subconditions + for this object. \n Subconditions are expected to appear when + relevant (when there is a error), and disappear when not relevant. + An empty slice here indicates no errors." + items: + description: "SubCondition is a Condition-like type intended + for use as a subcondition inside a DetailedCondition. \n It + contains a subset of the Condition fields. \n It is intended + for warnings and errors, so `type` names should use abnormal-true + polarity, that is, they should be of the form \"ErrorPresent: + true\". \n The expected lifecycle for these errors is that + they should only be present when the error or warning is, + and should be removed when they are not relevant." + properties: + message: + description: "Message is a human readable message indicating + details about the transition. \n This may be an empty + string." + maxLength: 32768 + type: string + reason: + description: "Reason contains a programmatic identifier + indicating the reason for the condition's last transition. + Producers of specific condition types may define expected + values and meanings for this field, and whether the values + are considered a guaranteed API. \n The value should be + a CamelCase string. \n This field may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + \n This must be in abnormal-true polarity, that is, `ErrorFound` + or `controller.io/ErrorFound`. \n The regex it matches + is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - message + - reason + - status + - type + type: object + type: array + lastTransitionTime: + description: "lastTransitionTime is the last time the condition + transitioned from one status to another. \n This should be when + the underlying condition changed. If that is not known, then + using the time when the API field changed is acceptable." + format: date-time + type: string + message: + description: "message is a human readable message indicating details + about the transition. \n This may be an empty string." + maxLength: 32768 + type: string + observedGeneration: + description: "observedGeneration represents the .metadata.generation + that the condition was set based upon. \n For instance, if .metadata.generation + is currently 12, but the .status.conditions[x].observedGeneration + is 9, the condition is out of date with respect to the current + state of the instance." + format: int64 + minimum: 0 + type: integer + reason: + description: "Reason contains a programmatic identifier indicating + the reason for the condition's last transition. \n Producers + of specific condition types may define expected values and meanings + for this field, and whether the values are considered a guaranteed + API. \n The value should be a CamelCase string. \n This field + may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in CamelCase or in foo.example.com/CamelCase. + \n Many .condition.type values are consistent across resources + like Available, but because arbitrary conditions can be useful + (see .node.status.conditions), the ability to deconflict is + important. \n The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + warnings: + description: "Warnings contains a slice of relevant warning subconditions + for this object. \n Subconditions are expected to appear when + relevant (when there is a warning), and disappear when not relevant. + An empty slice here indicates no warnings." + items: + description: "SubCondition is a Condition-like type intended + for use as a subcondition inside a DetailedCondition. \n It + contains a subset of the Condition fields. \n It is intended + for warnings and errors, so `type` names should use abnormal-true + polarity, that is, they should be of the form \"ErrorPresent: + true\". \n The expected lifecycle for these errors is that + they should only be present when the error or warning is, + and should be removed when they are not relevant." + properties: + message: + description: "Message is a human readable message indicating + details about the transition. \n This may be an empty + string." + maxLength: 32768 + type: string + reason: + description: "Reason contains a programmatic identifier + indicating the reason for the condition's last transition. + Producers of specific condition types may define expected + values and meanings for this field, and whether the values + are considered a guaranteed API. \n The value should be + a CamelCase string. \n This field may not be empty." + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: "Type of condition in `CamelCase` or in `foo.example.com/CamelCase`. + \n This must be in abnormal-true polarity, that is, `ErrorFound` + or `controller.io/ErrorFound`. \n The regex it matches + is (dns1123SubdomainFmt/)?(qualifiedNameFmt)" + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - message + - reason + - status + - type + type: object + type: array + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + x-kubernetes-list-map-keys: + - type + x-kubernetes-list-type: map + type: object required: - metadata - spec diff --git a/site/docs/master/api-reference.html b/site/docs/master/api-reference.html index a8899c6f011..b768c2672d1 100644 --- a/site/docs/master/api-reference.html +++ b/site/docs/master/api-reference.html @@ -6,7 +6,14 @@
-
Package v1 is the v1 version of the API.
+This package holds the specification for the projectcontour.io Custom Resource Definitions (CRDs).
+In building this CRD, we’ve inadvertently overloaded the word “Condition”, so we’ve tried to make +this spec clear as to which types of condition are which.
+MatchConditions
are used by Routes
and Includes
to specify rules to match requests against for either
+routing or inclusion.
DetailedConditions
are used in the Status
of these objects to hold information about the relevant
+state of the object and the world around it.
SubConditions
are used underneath DetailedConditions
to give more detail to errors or warnings.
-
HTTPProxy is an Ingress CRD specification
+HTTPProxy is an Ingress CRD specification.
(Optional)
Virtualhost appears at most once. If it is present, the object is considered -to be a “root”. +to be a “root” HTTPProxy. |
(Optional)
- Includes allow for specific routing configuration to be appended to another HTTPProxy in another namespace. +Includes allow for specific routing configuration to be included from another HTTPProxy, +possibly in another namespace. |
Status is a container for computed information about the HTTPProxy.
status
++(Appears on: +DetailedCondition) +
++
Condition contains details for one aspect of the current state of this API Resource.
+This struct is intended for direct use as an array at the field path .status.conditions. For example,
+type FooStatus struct{
+// Represents the observations of a foo's current state.
+// Known .status.conditions.type are: "Available", "Progressing", and "Degraded"
+// +patchMergeKey=type
+// +patchStrategy=merge
+// +listType=map
+// +listMapKey=type
+Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
+// other fields
+}
+
+
+Field | +Description | +
---|---|
+type
++ +string + + |
+
+ Type of condition in CamelCase or in foo.example.com/CamelCase. +Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be +useful (see .node.status.conditions), the ability to deconflict is important. +The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt) + |
+
+status
++ + +ConditionStatus + + + |
+
+ status of the condition, one of True, False, Unknown. + |
+
+observedGeneration
++ +int64 + + |
+
+(Optional)
+ observedGeneration represents the .metadata.generation that the condition was set based upon. +For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the instance. + |
+
+lastTransitionTime
++ + +Kubernetes meta/v1.Time + + + |
+
+ lastTransitionTime is the last time the condition transitioned from one status to another. +This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + |
+
+reason
++ +string + + |
+
+ Reason contains a programmatic identifier indicating the reason for the condition’s last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + |
+
+message
++ +string + + |
+
+ message is a human readable message indicating details about the transition. +This may be an empty string. + |
+
string
alias)+(Appears on: +Condition, +SubCondition) +
++
++(Appears on: +HTTPProxyStatus, +TLSCertificateDelegationStatus) +
++
DetailedCondition is an extension of the normal Kubernetes conditions, with two extra +fields to hold sub-conditions, which provide more detailed reasons for the state (True or False) +of the condition.
+errors
holds information about sub-conditions which are fatal to that condition and render its state False.
warnings
holds information about sub-conditions which are not fatal to that condition and do not force the state to be False.
Remember that Conditions have a type, a status, and a reason.
+The type is the type of the condition, the most important one in this CRD set is Valid
.
In the case of Valid
, status: true
means that the object is has been ingested into Contour with no errors.
+warnings
may still be present, and will be indicated in the Reason field.
Valid
, status: false
means that the object has had one or more fatal errors during processing into Contour.
+The details of the errors will be present under the errors
field.
There should never be subconditions under errors
when status
is true
.
Field | +Description | +
---|---|
+Condition
++ + +Condition + + + |
+
+
+(Members of |
+
+errors
++ + +[]SubCondition + + + |
+
+(Optional)
+ Errors contains a slice of relevant error subconditions for this object. +Subconditions are expected to appear when relevant (when there is a error), and disappear when not relevant. +An empty slice here indicates no errors. + |
+
+warnings
++ + +[]SubCondition + + + |
+
+(Optional)
+ Warnings contains a slice of relevant warning subconditions for this object. +Subconditions are expected to appear when relevant (when there is a warning), and disappear when not relevant. +An empty slice here indicates no warnings. + |
+
@@ -442,7 +674,7 @@
Virtualhost appears at most once. If it is present, the object is considered -to be a “root”.
+to be a “root” HTTPProxy.Includes allow for specific routing configuration to be appended to another HTTPProxy in another namespace.
+Includes allow for specific routing configuration to be included from another HTTPProxy, +possibly in another namespace.
LoadBalancer contains the current status of the load balancer.
+conditions
+Conditions contains information about the current status of the HTTPProxy, +in an upstream-friendly container.
+Contour will update a single condition, Valid
, that is in normal-true polarity.
+That is, when currentStatus
is valid
, the Valid
condition will be status: true
,
+and vice versa.
Contour will leave untouched any other Conditions set in this block, +in case some other controller wants to add a Condition.
+If you are another controller owner and wish to add a condition, you should
+namespace your condition with a label, like controller.domain.com/ConditionName
.
+(Appears on: +DetailedCondition) +
++
SubCondition is a Condition-like type intended for use as a subcondition inside a DetailedCondition.
+It contains a subset of the Condition fields.
+It is intended for warnings and errors, so type
names should use abnormal-true polarity,
+that is, they should be of the form “ErrorPresent: true”.
The expected lifecycle for these errors is that they should only be present when the error or warning is, +and should be removed when they are not relevant.
+ +Field | +Description | +
---|---|
+type
++ +string + + |
+
+ Type of condition in This must be in abnormal-true polarity, that is, The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt) + |
+
+status
++ + +ConditionStatus + + + |
+
+ Status of the condition, one of True, False, Unknown. + |
+
+reason
++ +string + + |
+
+ Reason contains a programmatic identifier indicating the reason for the condition’s last transition. +Producers of specific condition types may define expected values and meanings for this field, +and whether the values are considered a guaranteed API. +The value should be a CamelCase string. +This field may not be empty. + |
+
+message
++ +string + + |
+
+ Message is a human readable message indicating details about the transition. +This may be an empty string. + |
+
@@ -1748,6 +2085,49 @@
+(Appears on: +TLSCertificateDelegation) +
++
TLSCertificateDelegationStatus allows for the status of the delegation +to be presented to the user.
+ +Field | +Description | +
---|---|
+conditions
++ + +[]DetailedCondition + + + |
+
+(Optional)
+ Conditions contains information about the current status of the HTTPProxy, +in an upstream-friendly container. +Contour will update a single condition, Contour will leave untouched any other Conditions set in this block, +in case some other controller wants to add a Condition. +If you are another controller owner and wish to add a condition, you should
+namespace your condition with a label, like |
+
@@ -1873,7 +2253,7 @@
The fully qualified domain name of the root of the ingress tree -all leaves of the DAG rooted at this object relate to the fqdn
+all leaves of the DAG rooted at this object relate to the fqdn.If present describes tls properties. The SNI names that will be matched on are described in fqdn, the tls.secretName secret must contain a -matching certificate
+certificate that itself contains a name that matches the FQDN.