Re-organize docs in the repo directories.

README.md

@@ -9,6 +9,10 @@ Varnish. For more information, see:
 * Kubernetes: https://kubernetes.io/
 * Varnish: http://www.varnish-cache.org
 
+The Ingress controller currently supports Kubernetes version 1.9, and
+has also been tested succesfully with 1.10. The Varnish container runs
+version 6.1.1.
+
 ## WORK IN PROGRESS
 
 The Ingress controller implementation is presently under development
@@ -27,9 +31,6 @@ time, including:
 
 # Installation
 
-The Ingress controller currently supports Kubernetes version 1.9, and
-has also been tested succesfully with 1.10.
-
 Varnish for the purposes of Ingress and the controller that manages it
 are implemented in separate containers -- one controller can be used
 to manage a group of Varnish instances. The Dockerfiles and other
@@ -71,49 +72,13 @@ definitions, is in the [``cmd/``](/cmd) folder. The folder also
 containes a Makefile defining targets that encapsulate the build
 process for the controller executable.
 
-# Varnish as a Kubernetes Ingress
-
-Since this project is currently in its early stages, the implementation of
-Ingress definitions for a Varnish instance is subject to change as development
-continues. Presently, an Ingress is realized by loading a
-[VCL](https://varnish-cache.org/docs/trunk/reference/vcl.html) configuration
-that:
-
-* defines
-  [directors](https://varnish-cache.org/docs/trunk/users-guide/vcl-backends.html#directors)
-  that correspond to Services mentioned in the Ingress definition
-  * This is currently hard-wired as the round-robin director.
-* defines
-  [backends](https://varnish-cache.org/docs/trunk/users-guide/vcl-backends.html)
-  corresponding to the Endpoints of the Services. These are assigned to the
-  director defined for the Service.
-  * Endpoint definitions for a Service are obtained from an API query
-    when the VCL configuration is generated, so that the assignments
-    of Endpoints is current at VCL generation time.
-  * The Varnish backend definitions currently only include the Endpoints'
-    IP addresses and ports. There is presently no means to define other
-    features of a backend, such as health checks and timeouts.
-* generates VCL code to implement the routing of requests to backends
-  based on the Host header and/or URL path according to the IngressRules
-  given in the Ingress definition.
-  * Varnish may cache responses according to its default rules for
-    caching, and of course cache hits are delivered without routing the
-    requests further.
-  * In case of a non-cache-hit (miss or pass), the Host header and/or
-    URL path is evaluated according to the IngressRules, and matching
-    requests are assigned to the director corresponding to the matched
-    Service.
-      * An IngressSpec is rejected if it does not specify any Host header.
-      * TLS configuration in the IngressSpec is currently ignored.
-  * The director in turn chooses a backend corresponding to an Endpoint
-    according to its load balancing algorithm (currently only round-robin).
-  * If the request does not match any Service according to the
-    IngressRules, then:
-      * If a default Backend (a Service) was defined in the IngressSpec,
-        then the request is assigned to the corresponding director.
-      * Otherwise, a synthetic 404 Not Found response is generated by
-        Varnish.
-  * If there is no valid Ingress definition (none has been defined
-    since the Varnish instance started, or the only valid definition
-    was deleted), then Varnish generates a synthetic 503 Service Not
-    Available response for every request.
+# Documentation
+
+See the [``docs/``](/docs) folder for technical references and more
+detailed discussions of various topics.
+
+# Repositories
+
+* Primary repo: https://code.uplex.de/uplex-varnish/k8s-ingress
+
+* Mirror: https://gitlab.com/uplex/varnish/k8s-ingress

docs/README.md

+# Documentation
+
+The docs in this folder cover these topics:
+
+* [Varnish as a Kubernetes Ingress](varnish-as-ingress.md)
+
+* [Self-sharding Varnish cluster](self-sharding.md): Discussion of the
+  design, and reference for the configuration

docs/varnish-as-ingress.md

+# Varnish as a Kubernetes Ingress
+
+Varnish as an Ingress is realized by loading a
+[VCL](https://varnish-cache.org/docs/trunk/reference/vcl.html) configuration
+that:
+
+* defines
+  [directors](https://varnish-cache.org/docs/trunk/users-guide/vcl-backends.html#directors)
+  that correspond to Services mentioned in the Ingress definition
+
+  * This is currently hard-wired as the round-robin director.
+
+* defines
+  [backends](https://varnish-cache.org/docs/trunk/users-guide/vcl-backends.html)
+  corresponding to the Endpoints of the Services. These are assigned to the
+  director defined for the Service.
+
+  * Endpoint definitions for a Service are obtained from an API query
+    when the VCL configuration is generated, so that the assignments
+    of Endpoints is current at VCL generation time.
+
+  * The Varnish backend definitions currently only include the Endpoints'
+    IP addresses and ports. There is presently no means to define other
+    features of a backend, such as health checks and timeouts.
+
+* generates VCL code to implement the routing of requests to backends
+  based on the Host header and/or URL path according to the IngressRules
+  given in the Ingress definition.
+
+  * Varnish may cache responses according to its default rules for
+    caching, and of course cache hits are delivered without routing the
+    requests further.
+
+  * In case of a non-cache-hit (miss or pass), the Host header and/or
+    URL path is evaluated according to the IngressRules, and matching
+    requests are assigned to the director corresponding to the matched
+    Service.
+
+      * An IngressSpec is rejected if it does not specify any Host header.
+
+      * TLS configuration in the IngressSpec is currently ignored.
+
+  * The director in turn chooses a backend corresponding to an Endpoint
+    according to its load balancing algorithm (currently only round-robin).
+
+  * If the request does not match any Service according to the
+    IngressRules, then:
+
+      * If a default Backend (a Service) was defined in the IngressSpec,
+        then the request is assigned to the corresponding director.
+
+      * Otherwise, a synthetic 404 Not Found response is generated by
+        Varnish.
+
+  * If there is no valid Ingress definition (none has been defined
+    since the Varnish instance started, or the only valid definition
+    was deleted), then Varnish generates a synthetic 503 Service Not
+    Available response for every request.