github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.17.2/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  ```
    37  
    38  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`.
    39  Implementing similar behavior using an HTTPProxy looks like this:
    40  
    41  ```yaml
    42  # httpproxy.yaml
    43  apiVersion: projectcontour.io/v1
    44  kind: HTTPProxy
    45  metadata:
    46    name: basic
    47  spec:
    48    virtualhost:
    49      fqdn: foo-basic.bar.com
    50    routes:
    51      - conditions:
    52        - prefix: /
    53        services:
    54          - name: s1
    55            port: 80
    56  ```
    57  
    58  **Lines 1-5**: As with all other Kubernetes objects, an HTTPProxy needs apiVersion, kind, and metadata fields.
    59  
    60  **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.
    61  
    62  
    63  ## Interacting with HTTPProxies
    64  
    65  As with all Kubernetes objects, you can use `kubectl` to create, list, describe, edit, and delete HTTPProxy CRDs.
    66  
    67  Creating an HTTPProxy:
    68  
    69  ```bash
    70  $ kubectl create -f basic.httpproxy.yaml
    71  httpproxy "basic" created
    72  ```
    73  
    74  Listing HTTPProxies:
    75  
    76  ```bash
    77  $ kubectl get httpproxy
    78  NAME      AGE
    79  basic     24s
    80  ```
    81  
    82  Describing HTTPProxy:
    83  
    84  ```bash
    85  $ kubectl describe httpproxy basic
    86  Name:         basic
    87  Namespace:    default
    88  Labels:       <none>
    89  API Version:  projectcontour.io/v1
    90  Kind:         HTTPProxy
    91  Metadata:
    92    Cluster Name:
    93    Creation Timestamp:  2019-07-05T19:26:54Z
    94    Resource Version:    19373717
    95    Self Link:           /apis/projectcontour.io/v1/namespaces/default/httpproxy/basic
    96    UID:                 6036a9d7-8089-11e8-ab00-f80f4182762e
    97  Spec:
    98    Routes:
    99      Conditions:
   100        Prefix: /
   101      Services:
   102        Name:  s1
   103        Port:  80
   104    Virtualhost:
   105      Fqdn:  foo-basic.bar.com
   106  Events:    <none>
   107  ```
   108  
   109  Deleting HTTPProxies:
   110  
   111  ```bash
   112  $ kubectl delete httpproxy basic
   113  httpproxy "basic" deleted
   114  ```
   115  
   116  ## Status Reporting
   117  
   118  There are many misconfigurations that could cause an HTTPProxy or delegation to be invalid.
   119  To aid users in resolving these issues, Contour updates a `status` field in all HTTPProxy objects.
   120  In the current specification, invalid HTTPProxy are ignored by Contour and will not be used in the ingress routing configuration.
   121  
   122  If an HTTPProxy object is valid, it will have a status property that looks like this:
   123  
   124  ```yaml
   125  status:
   126    currentStatus: valid
   127    description: valid HTTPProxy
   128  ```
   129  
   130  If the HTTPProxy is invalid, the `currentStatus` field will be `invalid` and the `description` field will provide a description of the issue.
   131  
   132  As an example, if an HTTPProxy object has specified a negative value for weighting, the HTTPProxy status will be:
   133  
   134  ```yaml
   135  status:
   136    currentStatus: invalid
   137    description: "route '/foo': service 'home': weight must be greater than or equal to zero"
   138  ```
   139  
   140  Some examples of invalid configurations that Contour provides statuses for:
   141  
   142  - Negative weight provided in the route definition.
   143  - Invalid port number provided for service.
   144  - Prefix in parent does not match route in delegated route.
   145  - Root HTTPProxy created in a namespace other than the allowed root namespaces.
   146  - A given Route of an HTTPProxy both delegates to another HTTPProxy and has a list of services.
   147  - Orphaned route.
   148  - Delegation chain produces a cycle.
   149  - Root HTTPProxy does not specify fqdn.
   150  - Multiple prefixes cannot be specified on the same set of route conditions.
   151  - Multiple header conditions of type "exact match" with the same header key.
   152  - Contradictory header conditions on a route, e.g. a "contains" and "notcontains" condition for the same header and value.
   153  
   154  ## HTTPProxy API Specification
   155  
   156  The full HTTPProxy specification is described in detail in the [API documentation][4].
   157  There are a number of working examples of HTTPProxy objects in the [`examples/example-workload`][3] directory of the Contour Github repository.
   158  
   159   [1]: https://kubernetes.io/docs/concepts/services-networking/ingress/
   160   [2]: https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/annotations.md
   161   [3]: {{< param github_url>}}/tree/{{< param version >}}/examples/example-workload/httpproxy
   162   [4]: api.md