1 /* 2 Copyright 2021 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 package v1alpha2 18 19 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 20 21 const ( 22 // PolicyLabelKey is the label whose presence identifies a CRD that the 23 // Gateway API Policy attachment model. The value of the label SHOULD be one 24 // of the following: 25 // - A label value of "Inherited" indicates that this Policy is inheritable. 26 // An example of inheritable policy is one which if applied at the Gateway 27 // level would affect all attached HTTPRoutes and their respective 28 // Backends. 29 // - A label value of "Direct" indicates that the policy only affects the 30 // resource to which it is attached and does not affect it's sub resources. 31 PolicyLabelKey = "gateway.networking.k8s.io/policy" 32 ) 33 34 // PolicyTargetReference identifies an API object to apply a direct or 35 // inherited policy to. This should be used as part of Policy resources 36 // that can target Gateway API resources. For more information on how this 37 // policy attachment model works, and a sample Policy resource, refer to 38 // the policy attachment documentation for Gateway API. 39 type PolicyTargetReference struct { 40 // Group is the group of the target resource. 41 Group Group `json:"group"` 42 43 // Kind is kind of the target resource. 44 Kind Kind `json:"kind"` 45 46 // Name is the name of the target resource. 47 Name ObjectName `json:"name"` 48 49 // Namespace is the namespace of the referent. When unspecified, the local 50 // namespace is inferred. Even when policy targets a resource in a different 51 // namespace, it MUST only apply to traffic originating from the same 52 // namespace as the policy. 53 // 54 // +optional 55 Namespace *Namespace `json:"namespace,omitempty"` 56 } 57 58 // PolicyTargetReferenceWithSectionName identifies an API object to apply a direct 59 // policy to. This should be used as part of Policy resources that can target 60 // single resources. For more information on how this policy attachment mode 61 // works, and a sample Policy resource, refer to the policy attachment documentation 62 // for Gateway API. 63 // 64 // Note: This should only be used for direct policy attachment when references 65 // to SectionName are actually needed. In all other cases, PolicyTargetReference 66 // should be used. 67 type PolicyTargetReferenceWithSectionName struct { 68 PolicyTargetReference `json:",inline"` 69 70 // SectionName is the name of a section within the target resource. When 71 // unspecified, this targetRef targets the entire resource. In the following 72 // resources, SectionName is interpreted as the following: 73 // 74 // * Gateway: Listener Name 75 // * Service: Port Name 76 // 77 // If a SectionName is specified, but does not exist on the targeted object, 78 // the Policy must fail to attach, and the policy implementation should record 79 // a `ResolvedRefs` or similar Condition in the Policy's status. 80 // 81 // +optional 82 SectionName *SectionName `json:"sectionName,omitempty"` 83 } 84 85 // PolicyConditionType is a type of condition for a policy. This type should be 86 // used with a Policy resource Status.Conditions field. 87 type PolicyConditionType string 88 89 // PolicyConditionReason is a reason for a policy condition. 90 type PolicyConditionReason string 91 92 const ( 93 // PolicyConditionAccepted indicates whether the policy has been accepted or 94 // rejected by a targeted resource, and why. 95 // 96 // Possible reasons for this condition to be True are: 97 // 98 // * "Accepted" 99 // 100 // Possible reasons for this condition to be False are: 101 // 102 // * "Conflicted" 103 // * "Invalid" 104 // * "TargetNotFound" 105 // 106 PolicyConditionAccepted PolicyConditionType = "Accepted" 107 108 // PolicyReasonAccepted is used with the "Accepted" condition when the policy 109 // has been accepted by the targeted resource. 110 PolicyReasonAccepted PolicyConditionReason = "Accepted" 111 112 // PolicyReasonConflicted is used with the "Accepted" condition when the 113 // policy has not been accepted by a targeted resource because there is 114 // another policy that targets the same resource and a merge is not possible. 115 PolicyReasonConflicted PolicyConditionReason = "Conflicted" 116 117 // PolicyReasonInvalid is used with the "Accepted" condition when the policy 118 // is syntactically or semantically invalid. 119 PolicyReasonInvalid PolicyConditionReason = "Invalid" 120 121 // PolicyReasonTargetNotFound is used with the "Accepted" condition when the 122 // policy is attached to an invalid target resource. 123 PolicyReasonTargetNotFound PolicyConditionReason = "TargetNotFound" 124 ) 125 126 // PolicyAncestorStatus describes the status of a route with respect to an 127 // associated Ancestor. 128 // 129 // Ancestors refer to objects that are either the Target of a policy or above it 130 // in terms of object hierarchy. For example, if a policy targets a Service, the 131 // Policy's Ancestors are, in order, the Service, the HTTPRoute, the Gateway, and 132 // the GatewayClass. Almost always, in this hierarchy, the Gateway will be the most 133 // useful object to place Policy status on, so we recommend that implementations 134 // SHOULD use Gateway as the PolicyAncestorStatus object unless the designers 135 // have a _very_ good reason otherwise. 136 // 137 // In the context of policy attachment, the Ancestor is used to distinguish which 138 // resource results in a distinct application of this policy. For example, if a policy 139 // targets a Service, it may have a distinct result per attached Gateway. 140 // 141 // Policies targeting the same resource may have different effects depending on the 142 // ancestors of those resources. For example, different Gateways targeting the same 143 // Service may have different capabilities, especially if they have different underlying 144 // implementations. 145 // 146 // For example, in BackendTLSPolicy, the Policy attaches to a Service that is 147 // used as a backend in a HTTPRoute that is itself attached to a Gateway. 148 // In this case, the relevant object for status is the Gateway, and that is the 149 // ancestor object referred to in this status. 150 // 151 // Note that a parent is also an ancestor, so for objects where the parent is the 152 // relevant object for status, this struct SHOULD still be used. 153 // 154 // This struct is intended to be used in a slice that's effectively a map, 155 // with a composite key made up of the AncestorRef and the ControllerName. 156 type PolicyAncestorStatus struct { 157 // AncestorRef corresponds with a ParentRef in the spec that this 158 // PolicyAncestorStatus struct describes the status of. 159 AncestorRef ParentReference `json:"ancestorRef"` 160 161 // ControllerName is a domain/path string that indicates the name of the 162 // controller that wrote this status. This corresponds with the 163 // controllerName field on GatewayClass. 164 // 165 // Example: "example.net/gateway-controller". 166 // 167 // The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are 168 // valid Kubernetes names 169 // (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). 170 // 171 // Controllers MUST populate this field when writing status. Controllers should ensure that 172 // entries to status populated with their ControllerName are cleaned up when they are no 173 // longer necessary. 174 ControllerName GatewayController `json:"controllerName"` 175 176 // Conditions describes the status of the Policy with respect to the given Ancestor. 177 // 178 // +listType=map 179 // +listMapKey=type 180 // +kubebuilder:validation:MinItems=1 181 // +kubebuilder:validation:MaxItems=8 182 Conditions []metav1.Condition `json:"conditions,omitempty"` 183 } 184 185 // PolicyStatus defines the common attributes that all Policies should include within 186 // their status. 187 type PolicyStatus struct { 188 // Ancestors is a list of ancestor resources (usually Gateways) that are 189 // associated with the policy, and the status of the policy with respect to 190 // each ancestor. When this policy attaches to a parent, the controller that 191 // manages the parent and the ancestors MUST add an entry to this list when 192 // the controller first sees the policy and SHOULD update the entry as 193 // appropriate when the relevant ancestor is modified. 194 // 195 // Note that choosing the relevant ancestor is left to the Policy designers; 196 // an important part of Policy design is designing the right object level at 197 // which to namespace this status. 198 // 199 // Note also that implementations MUST ONLY populate ancestor status for 200 // the Ancestor resources they are responsible for. Implementations MUST 201 // use the ControllerName field to uniquely identify the entries in this list 202 // that they are responsible for. 203 // 204 // Note that to achieve this, the list of PolicyAncestorStatus structs 205 // MUST be treated as a map with a composite key, made up of the AncestorRef 206 // and ControllerName fields combined. 207 // 208 // A maximum of 16 ancestors will be represented in this list. An empty list 209 // means the Policy is not relevant for any ancestors. 210 // 211 // If this slice is full, implementations MUST NOT add further entries. 212 // Instead they MUST consider the policy unimplementable and signal that 213 // on any related resources such as the ancestor that would be referenced 214 // here. For example, if this list was full on BackendTLSPolicy, no 215 // additional Gateways would be able to reference the Service targeted by 216 // the BackendTLSPolicy. 217 // 218 // +kubebuilder:validation:MaxItems=16 219 Ancestors []PolicyAncestorStatus `json:"ancestors"` 220 } 221