github.com/projectcontour/contour@v1.28.2/site/content/docs/1.27/config/inclusion-delegation.md (about)

     1  # HTTPProxy Inclusion
     2  
     3  HTTPProxy permits the splitting of a system's configuration into separate HTTPProxy instances using **inclusion**.
     4  
     5  Inclusion, as the name implies, allows for one HTTPProxy object to be included in another, optionally with some conditions inherited from the parent.
     6  Contour reads the inclusion tree and merges the included routes into one big object internally before rendering Envoy config.
     7  Importantly, the included HTTPProxy objects do not have to be in the same namespace.
     8  
     9  Each tree of HTTPProxy starts with a root, the top level object of the configuration for a particular virtual host.
    10  Each root HTTPProxy defines a `virtualhost` key, which describes properties such as the fully qualified name of the virtual host, TLS configuration, etc.
    11  
    12  HTTPProxies included from the root must not contain a virtualhost key.
    13  Root objects cannot include other roots either transitively or directly.
    14  This permits the owner of an HTTPProxy root to allow the inclusion of a portion of the route space inside a virtual host, and to allow that route space to be further subdivided with inclusions.
    15  Because the path is not necessarily used as the only key, the route space can be multi-dimensional.
    16  
    17  ## Conditions and Inclusion
    18  
    19  Like Routes, Inclusion may specify a set of [conditions][1].
    20  These conditions are added to any conditions on the routes included.
    21  This process is recursive.
    22  
    23  Conditions are sets of individual condition statements, for example `prefix: /blog` is the condition that the matching request's path must start with `/blog`.
    24  When conditions are combined through inclusion Contour merges the conditions inherited via inclusion with any conditions specified on the route.
    25  This may result in duplicates, for example two `prefix:` conditions, mix of both `prefix:` and `exact` or `prefix` and `regex` conditions, or two header match conditions with the same name and value.
    26  To resolve this Contour applies the following logic.
    27  
    28  - `prefix:` conditions are concatenated together in the order they were applied from the root object. For example the conditions, `prefix: /api`, `prefix: /v1` becomes a single `prefix: /api/v1` conditions. Note: Multiple prefixes cannot be supplied on a single set of Route conditions.
    29  - `exact:` conditions are also concatenated just like `prefix:` conditions, but `exact:` conditions are not allowed in include match conditions. If the child httpproxy has `exact:` condition then after concatenation, it becomes a single `exact:` condition. For example, `prefix: /static` and `exact: /main.js` become a single `exact: /static/main.js` condition.
    30  - `regex:` conditions are also concatenated just like `prefix:` conditions, but `regex:` conditions are not allowed in include match conditions. If the child httpproxy has `regex:` condition then after concatenation, it becomes a single `regex:` condition. For example, `prefix: /static` and `regex: /.*/main.js` become a single `regex: /static/.*/main.js` condition.
    31  - Proxies with repeated identical `header:` conditions of type "exact match" (the same header keys exactly) are marked as "Invalid" since they create an un-routable configuration.
    32  
    33  ## Configuring Inclusion
    34  
    35  Inclusion is a top-level field in the HTTPProxy [spec][2] element.
    36  It requires one field, `name`, and has two optional fields:
    37  
    38  - `namespace`. This will assume the included HTTPProxy is in the same namespace if it's not specified.
    39  - a `conditions` block.
    40  
    41  ## Inclusion Within the Same Namespace
    42  
    43  HTTPProxies can include other HTTPProxy objects in the namespace by specifying the name of the object and its namespace in the top-level `includes` block.
    44  Note that `includes` is a list, and so it must use the YAML list construct.
    45  
    46  In this example, the HTTPProxy `include-root` has included the configuration for paths matching `/service2` from the HTTPProxy named `service2` in the same namespace as `include-root` (the `default` namespace).
    47  It's important to note that `service2` HTTPProxy has not defined a `virtualhost` property as it is NOT a root HTTPProxy.
    48  
    49  ```yaml
    50  # httpproxy-inclusion-samenamespace.yaml
    51  apiVersion: projectcontour.io/v1
    52  kind: HTTPProxy
    53  metadata:
    54    name: include-root
    55    namespace: default
    56  spec:
    57    virtualhost:
    58      fqdn: root.bar.com
    59    includes:
    60    # Includes the /service2 path from service2 in the same namespace
    61    - name: service2
    62      namespace: default
    63      conditions:
    64      - prefix: /service2
    65    routes:
    66      - conditions:
    67        - prefix: /
    68        services:
    69          - name: s1
    70            port: 80
    71  ---
    72  apiVersion: projectcontour.io/v1
    73  kind: HTTPProxy
    74  metadata:
    75    name: service2
    76    namespace: default
    77  spec:
    78    routes:
    79      - services: # matches /service2
    80          - name: s2
    81            port: 80
    82      - conditions:
    83        - prefix: /blog # matches /service2/blog
    84        services:
    85          - name: blog
    86            port: 80
    87  ```
    88  
    89  ## Inclusion Across Namespaces
    90  
    91  Inclusion can also happen across Namespaces by specifying a `namespace` in the `inclusion`.
    92  This is a particularly powerful paradigm for enabling multi-team Ingress management.
    93  
    94  If the `--watch-namespaces` configuration flag is used, it must define all namespaces that will be referenced by the inclusion.
    95  
    96  In this example, the root HTTPProxy has included configuration for paths matching `/blog` to the `blog` HTTPProxy object in the `marketing` namespace.
    97  
    98  ```yaml
    99  # httpproxy-inclusion-across-namespaces.yaml
   100  ---
   101  apiVersion: projectcontour.io/v1
   102  kind: HTTPProxy
   103  metadata:
   104    name: namespace-include-root
   105    namespace: default
   106  spec:
   107    virtualhost:
   108      fqdn: ns-root.bar.com
   109    includes:
   110    # delegate the subpath, `/blog` to the HTTPProxy object in the marketing namespace with the name `blog`
   111    - name: blog
   112      namespace: marketing
   113      conditions:
   114      - prefix: /blog
   115    routes:
   116      - services:
   117          - name: s1
   118            port: 80
   119  
   120  ---
   121  apiVersion: projectcontour.io/v1
   122  kind: HTTPProxy
   123  metadata:
   124    name: blog
   125    namespace: marketing
   126  spec:
   127    routes:
   128      - services:
   129          - name: s2
   130            port: 80
   131  ```
   132  
   133  ## Orphaned HTTPProxy children
   134  
   135  It is possible for HTTPProxy objects to exist that have not been delegated to by another HTTPProxy.
   136  These objects are considered "orphaned" and will be ignored by Contour in determining ingress configuration.
   137  
   138  [1]: request-routing#conditions
   139  [2]: api/#projectcontour.io/v1.HTTPProxySpec