sigs.k8s.io/gateway-api@v1.0.0/site-src/api-types/referencegrant.md (about)

     1  # ReferenceGrant
     2  
     3  ??? success "Standard Channel in v0.6.0+"
     4  
     5      The `ReferenceGrant` resource is Beta and part of the Standard Channel in `v0.6.0+`.
     6  
     7  !!! note
     8      This resource was originally named "ReferencePolicy". It was renamed
     9      to "ReferenceGrant" to avoid any confusion with policy attachment.
    10  
    11  A ReferenceGrant can be used to enable cross namespace references within
    12  Gateway API. In particular, Routes may forward traffic to backends in other
    13  namespaces, or Gateways may refer to Secrets in another namespace.
    14  
    15  ![Reference Grant](/images/referencegrant-simple.svg)
    16  <!-- Source: https://docs.google.com/presentation/d/11HEYCgFi-aya7FS91JvAfllHiIlvfgcp7qpi_Azjk4E/edit#slide=id.g13c18e3a7ab_0_171 -->
    17  
    18  In the past, we've seen that forwarding traffic across namespace boundaries is a
    19  desired feature, but without a safeguard like ReferenceGrant,
    20  [vulnerabilities](https://github.com/kubernetes/kubernetes/issues/103675) can
    21  emerge.
    22  
    23  If an object is referred to from outside its namespace, the object's owner must
    24  create a ReferenceGrant resource to explicitly allow that reference. Without a
    25  ReferenceGrant, a cross namespace reference is invalid.
    26  
    27  ## Structure
    28  Fundamentally a ReferenceGrant is made up of two lists, a list of resources
    29  references may come from, and a list of resources that may be referenced.
    30  
    31  The `from` list allows you to specify the group, kind, and namespace of
    32  resources that may reference items described in the `to` list.
    33  
    34  The `to` list allows you to specify the group and kind of resources that may be
    35  referenced by items described in the `from` list. The namespace is not necessary
    36  in the `to` list because a ReferenceGrant can only be used to allow references
    37  to resources in the same namespace as the ReferenceGrant.
    38  
    39  ## Example
    40  The following example shows how a HTTPRoute in namespace `foo` can reference a
    41  Service in namespace `bar`. In this example a ReferenceGrant in the `bar`
    42  namespace explicitly allows references to Services from HTTPRoutes in the `foo`
    43  namespace.
    44  
    45  ```yaml
    46  kind: HTTPRoute
    47  metadata:
    48    name: foo
    49    namespace: foo
    50  spec:
    51    rules:
    52    - matches:
    53      - path: /bar
    54      backendRefs:
    55        - name: bar
    56          namespace: bar
    57  ---
    58  kind: ReferenceGrant
    59  metadata:
    60    name: bar
    61    namespace: bar
    62  spec:
    63    from:
    64    - group: gateway.networking.k8s.io
    65      kind: HTTPRoute
    66      namespace: foo
    67    to:
    68    - group: ""
    69      kind: Service
    70  ```
    71  
    72  ## API design decisions
    73  While the API is simplistic in nature, it comes with a few notable decisions:
    74  
    75  1. Each ReferenceGrant only supports a single From and To section. Additional
    76     trust relationships must be modeled with additional ReferenceGrant
    77     resources.
    78  1. Resource names are intentionally excluded from the "From" section of
    79     ReferenceGrant because they rarely provide any meaningful protection. A user
    80     that is able to write to resources of a certain kind within a namespace can
    81     always rename resources or change the structure of the resources to match a
    82     given grant.
    83  1. A single Namespace is allowed per "From" struct. Although a selector would be
    84     more powerful, it encourages unnecessarily insecure configuration.
    85  1. The effect of these resources is purely additive, they stack on top of each
    86     other. This makes it impossible for them to conflict with each other.
    87  
    88  Please see the [API
    89  Specification](/reference/spec#gateway.networking.k8s.io/v1alpha2.ReferenceGrant)
    90  for more details on how specific ReferenceGrant fields are interpreted.
    91  
    92  ## Implementation Guidelines
    93  This API relies on runtime verification. Implementations MUST watch for changes
    94  to these resources and recalculate the validity of cross-namespace references
    95  after each change or deletion.
    96  
    97  When communicating the status of a cross-namespace reference, implementations
    98  MUST NOT expose information about the existence of a resource in another
    99  namespace unless a ReferenceGrant exists allowing the reference to occur. This
   100  means that if a cross-namespace reference is made without a ReferenceGrant to a
   101  resource that doesn't exist, any status conditions or warning messages need to
   102  focus on the fact that a ReferenceGrant does not exist to allow this reference.
   103  No hints should be provided about whether or not the referenced resource exists.
   104  
   105  ## Exceptions
   106  Cross namespace Route -> Gateway binding follows a slightly different pattern
   107  where the handshake mechanism is built into the Gateway resource. For more
   108  information on that approach, refer to the relevant [Security Model
   109  documentation](/concepts/security-model). Although conceptually similar to
   110  ReferenceGrant, this configuration is built directly into Gateway Listeners,
   111  and allows for fine-grained per Listener configuration that would not be
   112  possible with ReferenceGrant.
   113  
   114  There are some situations where it MAY be acceptable to ignore ReferenceGrant
   115  in favor of some other security mechanism. This MAY only be done if other
   116  mechanisms like NetworkPolicy can effectively limit cross-namespace references
   117  by the implementation.
   118  
   119  An implementation choosing to make this exception MUST clearly document that
   120  ReferenceGrant is not honored by their implementations and detail which
   121  alternative safeguards are available. Note that this is unlikely to apply to
   122  ingress implementations of the API and will not apply to all mesh
   123  implementations.
   124  
   125  For an example of the risks involved in cross-namespace references, refer to
   126  [CVE-2021-25740](https://github.com/kubernetes/kubernetes/issues/103675).
   127  Implementations of this API need to be very careful to avoid confused deputy
   128  attacks. ReferenceGrant provides a safeguard for that. Exceptions MUST only be
   129  made by implementations that are absolutely certain that other equally effective
   130  safeguards are in place.
   131  
   132  ## Conformance Level
   133  ReferenceGrant support is a "CORE" conformance level requirement for
   134  cross-namespace references that originate from the following objects:
   135  
   136  - Gateway
   137  - GRPCRoute
   138  - HTTPRoute
   139  - TLSRoute
   140  - TCPRoute
   141  - UDPRoute
   142  
   143  That is, all implementations MUST use this flow for any cross namespace
   144  references in the Gateway and any of the core xRoute types, except as noted
   145  in the Exceptions section above.
   146  
   147  Other "ImplementationSpecific" objects and references MUST also use this flow
   148  for cross-namespace references, except as noted in the Exceptions section above.
   149  
   150  ## Potential Future API Group Change
   151  
   152  ReferenceGrant is starting to gain interest outside of Gateway API and SIG
   153  Network use cases. It is possible that this resource may move to a more neutral
   154  home. Users of the ReferenceGrant API may be required to transition to a
   155  different API Group (instead of `gateway.networking.k8s.io`) at some point in
   156  the future.