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