Miscellaneous doc polish.

README.md

@@ -15,10 +15,9 @@ version 6.1.1.
 
 ## WORK IN PROGRESS
 
-The Ingress controller implementation is presently under development
-as a minimum viable product (MVP) and is undergoing initial testing. It is
-currently subject to a number of limitations, expected to be removed over
-time, including:
+The Ingress controller implementation is presently in development and
+is undergoing initial testing. It is currently subject to a number of
+limitations, expected to be removed over time, including:
 
 * No support for TLS connections
 * The controller only attends to definitions (Ingresses, Services and
@@ -26,9 +25,13 @@ time, including:
 * Only one Ingress definition is valid at a time. If more than one definition
   is added to the namespace, then the most recent definition becomes valid.
 * A variety of elements in the implementation are hard-wired, as
-  detailed in the documentation, These are expected to become configurable
+  detailed in the documentation. These are expected to become configurable
   in further development.
 
+Other features are subject to change on short notice. Testing and
+feedback are nevertheless welcome, and very valuable at this early
+stage.
+
 # Installation
 
 Varnish for the purposes of Ingress and the controller that manages it

container/README.md

@@ -22,8 +22,14 @@ If you are testing with ``minikube``, set the environment variable
 ``MINIKUBE=1`` before running ``make container``, so that the
 container will be available to the local k8s cluster:
 ```
-$ MINIKUBE=1 make container
+$ make MINIKUBE=1 container
 ```
+Use ``DOCKER_BUILD_OPTIONS`` to alter the ``docker build`` command:
+```
+# Re-build the controller image without using the cache
+$ make DOCKER_BUILD_OPTIONS=--no-cache controller
+```
+
 Both images must be pushed to a repository available to the k8s
 cluster.
 

deploy/README.md

 # Deploying an Ingress
 
-There is a variety of ways to deploy an Ingress in a Kubernetes
-cluster. The YAML configurations in this folder prepare a simple
-method of deployment, suitable for testing and editing according to
-your needs.
+Deployment of the Varnish Ingress in a Kubernetes cluster must fulfill
+some requirements, while in some respects you can make choices
+suitable to your requirements. The YAML configurations in this folder
+prepare a method of deployment, suitable for testing and editing as
+needed.
 
 ## Namespace and ServiceAccount
 
@@ -47,6 +48,11 @@ $ kubectl apply -f adm-secret.yaml
 # the Secret:
 $ head -c32 /dev/urandom | base64
 ```
+**IMPORTANT**: Please do *not* copy the secret data from the sample
+manifest in your deployment; create a new secret, for example using
+the command shown above. The purpose of authorization is defeated if
+everyone uses the same secret from an example.
+
 **TO DO**: The ``metadata.name`` field of the Secret is currently
 hard-wired to the value ``adm-secret``, and the key for the Secret (in
 the ``data`` field) is hard-wired to ``admin``. The Secret must be
@@ -74,13 +80,16 @@ properly:
 * ``spec.template`` must specify a ``label`` with a value that is
   matched by the Varnish admin Service described below. In this
   example:
+
 ```
   template:
     metadata:
       labels:
         app: varnish-ingress
 ```
+
 * The HTTP, readiness and admin ports must be specified:
+
 ```
         ports:
         - name: http
@@ -90,16 +99,19 @@ properly:
         - name: admport
           containerPort: 6081
 ```
-**TO DO**: The ports are currently hard-wired to these port numbers.
-A port for TLS access is currently not supported.
+
+  **TO DO**: The ports are currently hard-wired to these port numbers.
+  A port for TLS access is currently not supported.
 * ``volumeMounts`` and ``volumes`` must be specified so that the
   Secret defined above is available to Varnish:
+
 ```
         volumeMounts:
         - name: adm-secret
           mountPath: "/var/run/varnish"
           readOnly: true
 ```
+
 ```
       volumes:
       - name: adm-secret
@@ -109,15 +121,17 @@ A port for TLS access is currently not supported.
           - key: admin
             path: _.secret
 ```
-**TO DO**: The ``mountPath`` is currently hard-wired to
-``/var/run/varnish``.  The ``secretName`` is hard-wired to
-``adm-secret``, the ``key`` to ``admin``, and ``path`` to
-``_.secret``.
+  **TO DO**: The ``mountPath`` is currently hard-wired to
+  ``/var/run/varnish``.  The ``secretName`` is hard-wired to
+  ``adm-secret``, the ``key`` to ``admin``, and ``path`` to
+  ``_.secret``.
+
 * The liveness check should determine if the Varnish master process is
   running. Since Varnish is started in the foreground as the entry
   point of the container, the container is live if it is running at
   all. This check verifies that a ``varnishd`` process with parent PID
   0 is found in the process table:
+
 ```
         livenessProbe:
           exec:
@@ -127,14 +141,17 @@ A port for TLS access is currently not supported.
             - "0"
             - varnishd
 ```
+
 * The readiness check is an HTTP probe at the reserved listener (named
   ``k8sport`` above) for the URL path ``/ready``:
+
 ```
         readinessProbe:
           httpGet:
             path: /ready
             port: k8sport
 ```
+
   The port name must match the name given for port 8080 above.
 
 ### varnishd options
@@ -197,7 +214,7 @@ Among these restrictions are:
 With a Deployment, you may choose a resource such as a LoadBalancer or
 Nodeport to create external access to Varnish's HTTP port. The present
 example creates a Nodeport, which is simple for development and
-testing (a LoadBalancer is more likely in production deployments):
+testing:
 ```
 $ kubectl apply -f nodeport.yaml
 ```
@@ -220,22 +237,27 @@ The Service definition must fulfill some requirements:
   Endpoints to be listed when the container is not ready (since
   the Varnish instances are initialized in the not ready state).
   The means for doing so has changed in different versions of
-  Kubernetes. In versions up 1.9, this annotation must be used:
+  Kubernetes. In versions up to 1.9, this annotation must be used:
+
 ```
   annotations:
     service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
 ```
+
   Since 1.9, the annotation is deprecated, and this field in ``spec``
   should be specified instead:
+
 ```
 spec:
   publishNotReadyAddresses: true
 ```
+
   In recent versions, both specifications are permitted in the YAML,
   as in example YAML (the annotation is deprecated, but is not yet an
   error).
 * The ``selector`` must match the ``label`` given for the Varnish
   deployment, as discussed above. In the present example:
+
 ```
   selector:
     app: varnish-ingress
@@ -257,6 +279,7 @@ The requirements are:
 * The ``image`` must be ``varnish-ingress/controller``.
 * ``spec.template.spec`` must specify the ``POD_NAMESPACE``
   environment variable:
+
 ```
         env:
         - name: POD_NAMESPACE

docs/self-sharding.md

@@ -155,6 +155,9 @@ defined for an Ingress, or if it has any other value, then sharding is
 not configured, and all other ``self-sharding-*`` annotations are
 ignored.
 
+The ``self-sharding-*`` parameters are all optional; default values
+hold if they are left out of the configuration.
+
 These parameters configure the corresponding values for the
 [health probes](https://varnish-cache.org/docs/6.1/reference/vcl.html#probes)
 that instances in the cluster use to check one another's health: