sigs.k8s.io/gateway-api@v1.0.0/site-src/guides/multiple-ns.md (about)

     1  # Cross-Namespace routing
     2  
     3  The Gateway API has core support for cross Namespace routing. This is useful
     4  when more than one user or team is sharing the underlying networking
     5  infrastructure, yet control and configuration must be segmented to minimize
     6  access and fault domains.
     7  
     8  Gateways and Routes can be deployed into different Namespaces and Routes  can
     9  attach to Gateways across Namespace boundaries. This allows user access 
    10  control to be applied differently across Namespaces for Routes and Gateways, 
    11  effectively segmenting access and control to different parts of the
    12  cluster-wide  routing configuration. The ability for Routes to attach to
    13  Gateways across Namespace boundaries are governed by [_Route Attachment_](#cross-namespace-route-attachment). Route attachment is explored
    14  in this guide and demonstrates how independent teams can safely share the same
    15  Gateway.
    16  
    17  In this guide there are two independent teams, _store_ and _site_, operating
    18  in the same Kubernetes cluster in the `store-ns` and `site-ns` Namespaces. These
    19  are their goals and how they use Gateway API resources to accomplish them:
    20  
    21  - The site team has two applications, _home_ and _login_. The team wants to to
    22  isolate access and  configuration across their apps as much as possible to
    23  minimize access and failure domains. They use separate HTTPRoutes attached to
    24  the same Gateway to isolate routing configurations, such as canary rollouts,
    25  but still share the same IP address, port, DNS domain, and TLS certificate.
    26  - The store team has a single Service called _store_ that they have deployed
    27  in the `store-ns` Namespace which also needs to be exposed behind the same IP
    28  address and domain.
    29  - The Foobar Corporation operates behind the `foo.example.com` domain for all
    30  apps. This is controlled by a central infrastructure team, operating in the
    31  `infra-ns` Namespace.
    32  - Lastly, the security team controls the certificate for `foo.example.com`.
    33  By managing this certificate through the single shared Gateway they are able
    34  to centrally control security without directly involving application teams.
    35  
    36  The logical relationship between the Gateway API resources looks like this:
    37  
    38  ![Cross-Namespace routing](/images/cross-namespace-routing.svg)
    39  
    40  ## Cross-namespace Route Attachment
    41  
    42  [Route attachment][attachment] is an important concept that dictates how Routes
    43  attach to Gateways and program their routing rules. It is especially relevant
    44  when there are Routes across Namespaces that share one or more Gateways.
    45  Gateway and Route attachment is bidirectional - attachment can only succeed if
    46  the Gateway owner and Route owner both agree to the relationship. This
    47  bi-directional relationship exists for two reasons:
    48  
    49  - Route owners don't want to overexpose their applications through paths they 
    50  are not aware of.
    51  - Gateway owners don't want certain apps or teams using Gateways without 
    52  permission. For example, an internal service shouldn't be accessible 
    53  through an internet Gateway.
    54  
    55  Gateways support _attachment constraints_ which are fields on Gateway
    56  listeners that restrict which Routes can be attached. Gateways support
    57  Namespaces and Route types as attachment constraints. Any Routes that do not
    58  meet the attachment constraints are not able to attach to that Gateway. 
    59  Similarly, Routes explicitly reference Gateways that they want to attach to
    60  through the Route's `parentRef` field. Together these create a handshake
    61  between the infra owners and application owners that enables them to
    62  independently define how applications are exposed through Gateways. This is
    63  effectively a policy that reduces administrative overhead. App owners can
    64  specify which Gateways their apps should use and infra owners can constrain
    65  the Namespaces and types of Routes that a Gateway accepts.
    66  
    67  
    68  ## Shared Gateway
    69  
    70  The infrastructure team deploys the `shared-gateway` Gateway into the `infra-ns`
    71  Namespace:
    72  
    73  ```yaml
    74  {% include 'standard/cross-namespace-routing/gateway.yaml' %}
    75  ```
    76  
    77  The `https` listener in the above Gateway matches traffic for the
    78  `foo.example.com` domain. This allows the infrastructure team to manage all 
    79  aspects of the domain. The HTTPRoutes below do not need to specify domains
    80  and will match all traffic by default if `hostname` is not set. This makes
    81  it easier to manage HTTPRoutes because they can be domain agnostic, which is
    82  helpful when application domains are not static.
    83  
    84  This Gateway also configures HTTPS using the `foo-example-com` Secret
    85  in the `infra-ns` Namespace. This allows the infrastructure team to centrally
    86  manage TLS on behalf of app owners. The `foo-example-com` certificate will
    87  terminate all traffic going to its attached Routes, without any TLS 
    88  configuration on the HTTPRoutes themselves.
    89  
    90  This Gateway uses a Namespace selector to define which HTTPRoutes are allowed 
    91  to attach. This allows the infrastructure team to constrain who
    92  or which apps can use this Gateway by allowlisting a set of Namespaces.
    93  
    94  
    95  ```yaml
    96  apiVersion: gateway.networking.k8s.io/v1beta1
    97  kind: Gateway
    98  spec:
    99    listeners:
   100    - allowedRoutes:
   101        namespaces:
   102          from: Selector
   103          selector:
   104            matchLabels:
   105              shared-gateway-access: "true"
   106  ...
   107  ```
   108  
   109  _Only_ Namespaces which are labelled `shared-gateway-access: "true"` will be
   110  able to attach their Routes to `shared-gateway`. In the following set of
   111  Namespaces, if an HTTPRoute existed in the `no-external-access` Namespace with
   112  a `parentRef`  for `infra-ns/shared-gateway`, it would be ignored by the
   113  Gateway because the  attachment constraint (Namespace label) was not met.
   114  
   115  ```yaml
   116  {% include 'standard/cross-namespace-routing/0-namespaces.yaml' %}
   117  ```
   118  
   119  Note that attachment constraints on the Gateway are not required, but they are
   120  a best-practice if operating a cluster with many different teams and
   121  Namespaces. In environments where all apps in a cluster have permission to
   122  attach to a Gateway then the `listeners[].routes` field does not have to be
   123  configured and all Routes can freely use the Gateway.
   124  
   125  
   126  ## Route Attachment 
   127  
   128  The store team deploys their route for the `store` Service in the `store-ns`
   129  Namespace:
   130  
   131  ```yaml
   132  {% include 'standard/cross-namespace-routing/store-route.yaml' %}
   133  ```
   134  
   135  This Route has straightforward routing logic as it just matches for
   136  `/store` traffic which it sends to the `store` Service.
   137  
   138  The site team now deploys Routes for their applications. They deploy two
   139  HTTPRoutes into the `site-ns` Namespace:
   140  
   141  - The `home` HTTPRoute acts as a default routing rule, matching for all traffic
   142  to `foo.example.com/*` not matched by an existing routing rule and sending it to
   143  the `home` Service.
   144  - The `login` HTTPRoute  routes traffic for `foo.example.com/login` to
   145  `service/login-v1` and `service/login-v2`. It uses weights to granularly
   146  control traffic distribution between them.
   147  
   148  Both of these Routes use the same Gateway attachment configuration which
   149  specifies `gateway/shared-gateway` in the `infra-ns` Namespace as the only
   150  Gateway that these Routes want to attach to.
   151  
   152  ```yaml
   153  {% include 'standard/cross-namespace-routing/site-route.yaml' %}
   154  ```
   155  
   156  After these three Routes are deployed, they will all be attached to the
   157  `shared-gateway` Gateway. The Gateway merges these Routes into a single flat
   158  list of routing rules. [Routing precedence](/reference/spec/#gateway.networking.k8s.io/v1beta1.HTTPRouteRule)
   159  between these routing rules is determined by most specific match and
   160  conflicts are handled according to [conflict
   161  resolution](/concepts/guidelines#conflicts). This provides predictable and
   162  deterministic merging of routing rules between independent users.
   163  
   164  Thanks to cross-Namespace routing, the Foobar Corporation can distribute
   165  ownership of their infrastructure more evenly, while still retaining centralized
   166  control. This gives them the best of both worlds, all delivered through
   167  declarative and open source APIs.
   168  
   169  [attachment]:/concepts/api-overview/#attaching-routes-to-gateways