The Ingress object was added to Kubernetes in version 1.1 to describe properties of a cluster-wide reverse HTTP proxy. Since that time, the Ingress API has remained relatively unchanged, and the need to express implementation-specific capabilities has inspired an explosion of annotations.
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.
A minimal Ingress object might look like:
# ingress.yaml apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: basic spec: rules: - host: foo-basic.bar.com http: paths: - backend: serviceName: s1 servicePort: 80
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
Implementing similar behavior using an HTTPProxy looks like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 # httpproxy.yaml apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: basic spec: virtualhost: fqdn: foo-basic.bar.com routes: - conditions: - prefix: / services: - name: s1 port: 80
Lines 1-5: As with all other Kubernetes objects, an HTTPProxy needs apiVersion, kind, and metadata fields. Note that the HTTPProxy API is currently considered beta.
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.
As with all Kubernetes objects, you can use
kubectl to create, list, describe, edit, and delete HTTPProxy CRDs.
Creating an HTTPProxy:
$ kubectl create -f basic.httpproxy.yaml httpproxy "basic" created
$ kubectl get httpproxy NAME AGE basic 24s
$ kubectl describe httpproxy basic Name: basic Namespace: default Labels: <none> API Version: projectcontour.io/v1 Kind: HTTPProxy Metadata: Cluster Name: Creation Timestamp: 2019-07-05T19:26:54Z Resource Version: 19373717 Self Link: /apis/projectcontour.io/v1/namespaces/default/httpproxy/basic UID: 6036a9d7-8089-11e8-ab00-f80f4182762e Spec: Routes: Conditions: Prefix: / Services: Name: s1 Port: 80 Virtualhost: Fqdn: foo-basic.bar.com Events: <none>
$ kubectl delete httpproxy basic httpproxy "basic" deleted
There are many misconfigurations that could cause an HTTPProxy or delegation to be invalid.
To aid users in resolving these issues, Contour updates a
status field in all HTTPProxy objects.
In the current specification, invalid HTTPProxy are ignored by Contour and will not be used in the ingress routing configuration.
If an HTTPProxy object is valid, it will have a status property that looks like this:
status: currentStatus: valid description: valid HTTPProxy
If the HTTPProxy is invalid, the
currentStatus field will be
invalid and the
description field will provide a description of the issue.
As an example, if an HTTPProxy object has specified a negative value for weighting, the HTTPProxy status will be:
status: currentStatus: invalid description: "route '/foo': service 'home': weight must be greater than or equal to zero"
Some examples of invalid configurations that Contour provides statuses for:
The full HTTPProxy specification is described in detail in the API documentation.
There are a number of working examples of HTTPProxy objects in the
examples/example-workload directory of the Contour Github repository.