The goal of this project is to act as an executable specification in the form of a test suite, implementing a standard, actively maintained ingress-controller conformance specification.
The conformance test suite will both ensure consistency across implementations, as well as simplify the work needed for other implementations to conform to the specification. The test suite can also be viewed through human readable descriptions of what it is testing so that implementers can understand the tests without reading source code.
At the moment, ingress-controller-conformance
does not apply modifications to the running resources in the target Kubernetes cluster.
You must manually install and setup you environment targeted by the kubectl config current-context
:
- Apply the backing ingress-controller implementation. Samples are available under
examples/
. - Apply all, or a subset, of the ingress and service resources found under
deployments
. Files under the deployments folder match implemented check names.
$ ./ingress-controller-conformance context
Using active Kubernetes context 'docker-desktop'
The target Kubernetes cluster is running verion v1.14.6
Supports Ingress kind APIVersion: 'extensions/v1beta1'
Supports Ingress kind APIVersion: 'networking.k8s.io/v1beta1'
List, in a human-readable form, all Ingress verifications
$ ./ingress-controller-conformance list
- Ingress with host rule should send traffic to the correct backend service (host-rules)
- [SAMPLE] Ingress with path rule without a trailing slash should send traffic to the correct backend service, and preserve the original request path (path-rules-foo)
- [SAMPLE] Ingress with path rule without a trailing slash should send traffic to the correct backend service, and preserve the original request including sub-paths (path-rules-foo-trailing)
- [SAMPLE] Ingress with path rule with a trailing slash should send traffic to the correct backend service, and preserve the original request path (path-rules-bar)
- [SAMPLE] Ingress with path rule with a trailing slash should send traffic to the correct backend service, and preserve the original request including sub-paths and double '/' (path-rules-bar-subpath)
- Ingress with no rules should send traffic to the correct backend service (single-service)
Execute a series of assertions on the deployed ingress-controller, using your kubectl
current-context.
$ ./ingress-controller-conformance verify
Running 'all' verifications...
Running 'host-rules' verifications...
Running 'path-rules' verifications...
Running 'path-rules-foo' verifications...
1) Assertion failed: Expected the request path would be '/foo' but was '/'
Check failed: path-rules-foo
Running 'path-rules-foo-trailing' verifications...
1) Assertion failed: Expected the request path would be '/foo/' but was '//'
Check failed: path-rules-foo-trailing
Running 'path-rules-bar' verifications...
1) Assertion failed: Expected the request path would be '/bar/' but was '/'
Check failed: path-rules-bar
Running 'path-rules-bar-subpath' verifications...
1) Assertion failed: Expected the request path would be '/bar//bershop' but was '//bershop'
Check failed: path-rules-bar-subpath
Running 'single-service' verifications...
--- Verification completed ---
3 checks passed! 4 failures!
in 1.777148914s
$ ./ingress-controller-conformance help
Kubernetes ingress controller conformance test suite in Go.
Complete documentation is available at https://github.com/kubernetes-sigs/ingress-controller-conformance
Usage:
ingress-controller-conformance [command]
Available Commands:
context Print the current Kubernetes context, server version, and supported Ingress APIVersions
help Help about any command
list List all Ingress verifications
verify Run Ingress verifications for conformance
Flags:
-h, --help help for ingress-controller-conformance
Use "ingress-controller-conformance [command] --help" for more information about a command.
The ingress-conformance-echo
binary is published as docker image of the same name. The purpose of this component is to handle backend-requests made through an Ingress interface and respond using data from the original request. This, in turn, allows to build assertions on the original HTTP request as it is relayed through the ingress-controller.
# You may chose to pass in a TEST_ID environment variable to assert which running process actually handles the downstream request.
$ TEST_ID=sample ./echoserver
Starting server, listening on port 3000
Reporting TestId 'sample'
# You can then send test HTTP requests on localhost:3000
$ curl localhost:3000
{"TestId":"sample","Path":"/","Host":"localhost:3000","Method":"GET","Proto":"HTTP/1.1","Headers":{"Accept":["*/*"],"User-Agent":["curl/7.54.0"]}}
$ docker build -f build/package/Dockerfile . -t agervais/ingress-conformance-echo:latest
$ docker push agervais/ingress-conformance-echo:latest
$ go build
$ go build -o echoserver tools/echoserver.go
$ export VERSION=0.0.1 # Or git tag
$ go build -ldflags "-X github.com/kubernetes-sigs/ingress-controller-conformance/cmd.VERSION=$VERSION"