github.com/projectcontour/contour@v1.28.2/site/content/docs/1.24/config/fundamentals.md (about)

     1  # HTTPProxy Fundamentals
     2  
     3  The [Ingress][1] object was added to Kubernetes in version 1.1 to describe properties of a cluster-wide reverse HTTP proxy.
     4  Since that time, the Ingress API has remained relatively unchanged, and the need to express implementation-specific capabilities has inspired an [explosion of annotations][2].
     5  
     6  The goal of the HTTPProxy Custom Resource Definition (CRD) is to expand upon the functionality of the Ingress API to allow for a richer user experience as well addressing the limitations of the latter's use in multi tenant environments.
     7  
     8  ## Key HTTPProxy Benefits
     9  
    10  - Safely supports multi-team Kubernetes clusters, with the ability to limit which Namespaces may configure virtual hosts and TLS credentials.
    11  - Enables including of routing configuration for a path or domain from another HTTPProxy, possibly in another Namespace.
    12  - Accepts multiple services within a single route and load balances traffic across them.
    13  - Natively allows defining service weighting and load balancing strategy without annotations.
    14  - Validation of HTTPProxy objects at creation time and status reporting for post-creation validity.
    15  
    16  ## Ingress to HTTPProxy
    17  
    18  A minimal Ingress object might look like:
    19  
    20  ```yaml
    21  # ingress.yaml
    22  apiVersion: networking.k8s.io/v1
    23  kind: Ingress
    24  metadata:
    25    name: basic
    26  spec:
    27    rules:
    28    - host: foo-basic.bar.com
    29      http:
    30        paths:
    31        - backend:
    32            service:
    33              name: s1
    34              port:
    35                number: 80
    36          pathType: Prefix
    37  ```
    38  
    39  This Ingress object, named `basic`, will route incoming HTTP traffic with a `Host:` header for `foo-basic.bar.com` to a Service named `s1` on port `80`.
    40  Implementing similar behavior using an HTTPProxy looks like this:
    41  
    42  ```yaml
    43  # httpproxy.yaml
    44  apiVersion: projectcontour.io/v1
    45  kind: HTTPProxy
    46  metadata:
    47    name: basic
    48  spec:
    49    virtualhost:
    50      fqdn: foo-basic.bar.com
    51    routes:
    52      - conditions:
    53        - prefix: /
    54        services:
    55          - name: s1
    56            port: 80
    57  ```
    58  
    59  **Lines 1-5**: As with all other Kubernetes objects, an HTTPProxy needs apiVersion, kind, and metadata fields.
    60  
    61  **Lines 7-8**: The presence of the `virtualhost` field indicates that this is a root HTTPProxy that is the top level entry point for this domain.
    62  
    63  
    64  ## Interacting with HTTPProxies
    65  
    66  As with all Kubernetes objects, you can use `kubectl` to create, list, describe, edit, and delete HTTPProxy CRDs.
    67  
    68  Creating an HTTPProxy:
    69  
    70  ```bash
    71  $ kubectl create -f basic.httpproxy.yaml
    72  httpproxy "basic" created
    73  ```
    74  
    75  Listing HTTPProxies:
    76  
    77  ```bash
    78  $ kubectl get httpproxy
    79  NAME      AGE
    80  basic     24s
    81  ```
    82  
    83  Describing HTTPProxy:
    84  
    85  ```bash
    86  $ kubectl describe httpproxy basic
    87  Name:         basic
    88  Namespace:    default
    89  Labels:       <none>
    90  API Version:  projectcontour.io/v1
    91  Kind:         HTTPProxy
    92  Metadata:
    93    Cluster Name:
    94    Creation Timestamp:  2019-07-05T19:26:54Z
    95    Resource Version:    19373717
    96    Self Link:           /apis/projectcontour.io/v1/namespaces/default/httpproxy/basic
    97    UID:                 6036a9d7-8089-11e8-ab00-f80f4182762e
    98  Spec:
    99    Routes:
   100      Conditions:
   101        Prefix: /
   102      Services:
   103        Name:  s1
   104        Port:  80
   105    Virtualhost:
   106      Fqdn:  foo-basic.bar.com
   107  Events:    <none>
   108  ```
   109  
   110  Deleting HTTPProxies:
   111  
   112  ```bash
   113  $ kubectl delete httpproxy basic
   114  httpproxy "basic" deleted
   115  ```
   116  
   117  ## Status Reporting
   118  
   119  There are many misconfigurations that could cause an HTTPProxy or delegation to be invalid.
   120  Contour will make its best effort to process even partially valid configuration and allow traffic to be served for the valid parts.
   121  To aid users in resolving any issues, Contour updates a `status` field in all HTTPProxy objects.
   122  
   123  If an HTTPProxy object is valid, it will have a status property that looks like this:
   124  
   125  ```yaml
   126  status:
   127    currentStatus: valid
   128    description: valid HTTPProxy
   129  ```
   130  
   131  If the HTTPProxy is invalid, the `currentStatus` field will be `invalid` and the `description` field will provide a description of the issue.
   132  
   133  As an example, if an HTTPProxy object has specified a negative value for weighting, the HTTPProxy status will be:
   134  
   135  ```yaml
   136  status:
   137    currentStatus: invalid
   138    description: "route '/foo': service 'home': weight must be greater than or equal to zero"
   139  ```
   140  
   141  Some examples of invalid configurations that Contour provides statuses for:
   142  
   143  - Negative weight provided in the route definition.
   144  - Invalid port number provided for service.
   145  - Prefix in parent does not match route in delegated route.
   146  - Root HTTPProxy created in a namespace other than the allowed root namespaces.
   147  - A given Route of an HTTPProxy both delegates to another HTTPProxy and has a list of services.
   148  - Orphaned route.
   149  - Delegation chain produces a cycle.
   150  - Root HTTPProxy does not specify fqdn.
   151  - Multiple prefixes cannot be specified on the same set of route conditions.
   152  - Multiple header conditions of type "exact match" with the same header key.
   153  - Contradictory header conditions on a route, e.g. a "contains" and "notcontains" condition for the same header and value.
   154  
   155  Invalid configuration is ignored and will be not used in the ingress routing configuration.
   156  Envoy will respond with an error when HTTP request is received on route with invalid configuration on following cases:
   157  
   158  * `502 Bad Gateway` response is sent when HTTPProxy has an include that refers to an HTTPProxy that does not exist.
   159  * `503 Service Unavailable` response is sent when HTTPProxy refers to a service that does not exist.
   160  
   161  ### Example
   162  
   163  Following example has two routes: the first one is valid, the second one refers to a service that does not exist.
   164  
   165  ```yaml
   166  apiVersion: projectcontour.io/v1
   167  kind: HTTPProxy
   168  metadata:
   169    name: multiple-routes-with-a-missing-service
   170  spec:
   171    virtualhost:
   172      fqdn: www.example.com
   173    routes:
   174      - conditions:
   175        - prefix: /
   176        services:
   177          - name: valid-service
   178            port: 80
   179      - conditions:
   180        - prefix: /subpage
   181        services:
   182          - name: service-that-does-not-exist
   183            port: 80
   184  ```
   185  
   186  The `HTTPProxy` will have condition `Valid=false` with detailed error message: `Spec.Routes unresolved service reference: service "default/service-that-does-not-exist" not found`.
   187  Requests received for `http://www.example.com/` will be forwarded to `valid-service` but requests received for `http://www.example.com/subpage` will result in error `503 Service Unavailable` response from Envoy.
   188  
   189  ## HTTPProxy API Specification
   190  
   191  The full HTTPProxy specification is described in detail in the [API documentation][4].
   192  There are a number of working examples of HTTPProxy objects in the [`examples/example-workload`][3] directory of the Contour Github repository.
   193  
   194   [1]: https://kubernetes.io/docs/concepts/services-networking/ingress/
   195   [2]: https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/annotations.md
   196   [3]: {{< param github_url>}}/tree/{{< param branch >}}/examples/example-workload/httpproxy
   197   [4]: api.md