Merge pull request #1099 from caseydavenport/policy-controller-go

Golang policy controller docs

Author: caseydavenport

master/getting-started/kubernetes/installation/hosted/calico.yaml

@@ -295,15 +295,6 @@ spec:
                 configMapKeyRef:
                   name: calico-config
                   key: etcd_cert
-            # The location of the Kubernetes API.  Use the default Kubernetes
-            # service for API access.
-            - name: K8S_API
-              value: "https://kubernetes.default:443"
-            # Since we're running in the host namespace and might not have KubeDNS
-            # access, configure the container's /etc/hosts to resolve
-            # kubernetes.default to the correct service clusterIP.
-            - name: CONFIGURE_ETC_HOSTS
-              value: "true"
           volumeMounts:
             # Mount in the etcd TLS secrets.
             - mountPath: /calico-secrets

master/getting-started/kubernetes/installation/hosted/kubeadm/1.5/calico.yaml

@@ -288,12 +288,3 @@ spec:
                 configMapKeyRef:
                   name: calico-config
                   key: etcd_endpoints
-            # The location of the Kubernetes API.  Use the default Kubernetes
-            # service for API access.
-            - name: K8S_API
-              value: "https://kubernetes.default:443"
-            # Since we're running in the host namespace and might not have KubeDNS
-            # access, configure the container's /etc/hosts to resolve
-            # kubernetes.default to the correct service clusterIP.
-            - name: CONFIGURE_ETC_HOSTS
-              value: "true"

master/getting-started/kubernetes/installation/policy-controller.yaml

@@ -41,14 +41,3 @@ spec:
             # your etcd cluster.
             - name: ETCD_ENDPOINTS
               value: "<ETCD_ENDPOINTS>"
-            # Location of the Kubernetes API - this shouldn't need to be
-            # changed so long as it is used in conjunction with
-            # CONFIGURE_ETC_HOSTS="true".
-            - name: K8S_API
-              value: "https://kubernetes.default:443"
-            # Configure /etc/hosts within the container to resolve
-            # the kubernetes.default Service to the correct clusterIP
-            # using the environment provided by the kubelet.
-            # This removes the need for KubeDNS to resolve the Service.
-            - name: CONFIGURE_ETC_HOSTS
-              value: "true"

master/reference/policy-controller/configuration.md

@@ -2,7 +2,7 @@
 title: Configuring the Calico policy controller
 ---
 
-The policy controller is primarily configured through environment variables.  When running
+The policy controller is primarily configured through environment variables. When running
 the policy controller as a Kubernetes pod, this is accomplished through the pod manifest `env`
 section.
 
@@ -13,57 +13,35 @@ section.
 The policy controller supports the following environment variables to configure
 etcd access:
 
-* `ETCD_ENDPOINTS`: The list of etcd nodes in your cluster. e.g `http://10.0.0.1:2379,http://10.0.0.2:2379`
-* `ETCD_CA_CERT_FILE`: The full path to the CA certificate file for the Certificate Authority that signed the etcd server key/certificate pair.
-* `ETCD_CERT_FILE`: The full path to the client certificate file for accessing the etcd cluster.
-* `ETCD_KEY_FILE`: The full path to the client key file for accessing the etcd cluster.
+| Environment   | Description | Schema |
+| ------------- | ----------- | ------ |
+| `ETCD_ENDPOINTS`    | The list of etcd nodes in your cluster. e.g `http://10.0.0.1:2379,http://10.0.0.2:2379`
+| `ETCD_CA_CERT_FILE` | The full path to the CA certificate file for the Certificate Authority that signed the etcd server key/certificate pair. | path
+| `ETCD_CERT_FILE`    | The full path to the client certificate file for accessing the etcd cluster. | path
+| `ETCD_KEY_FILE`     | The full path to the client key file for accessing the etcd cluster. | path
 
-> **Note**: When running etcd with TLS enabled, the addresses in 
-> `ETCD_ENDPOINTS` must be hostname values such as `etcd-host:2379`, 
-> NOT IP addresses.
-{: .alert .alert-info}
+The `*_FILE` variables are _paths_ to the corresponding certificates/keys. As such, when the policy controller is running as a Kubernetes pod, you
+must ensure that the files exist within the pod. This is usually done in one of two ways:
 
-The `*_FILE` variables are _paths_ to the corresponding certificates / keys.  As such, when the policy controller is running as a Kubernetes pod, you
-must ensure that the files exist within the pod.  This is usually done in one of two ways:
-
-* Mount the certificates from the host.  This requires that the certs be present on the host that the policy controller is scheduled to / running on.
+* Mount the certificates from the host. This requires that the certs be present on the host running the policy controller.
 * Use Kubernetes [Secrets](http://kubernetes.io/docs/user-guide/secrets/) to mount the certificates into the Pod as files.
 
 ### Configuring Kubernetes API access
 
-The policy controller must access the Kubernetes API in order to learn about NetworkPolicy, Pod, and Namespace events.
-
-The following environment variables are useful for configuring API access:
-
-* `K8S_API`: The location of the Kubernetes API, including transport and port. e.g `https://kubernetes.default:443`
-* `CONFIGURE_ETC_HOSTS`: Whether or not the policy controller should configure its /etc/hosts file to resolve the Kubernetes Service clusterIP.  When "true", the policy controller will resolve `kubernetes.default` to the configured clusterIP of the Kubernetes API.
-
-It is recommended to use the following configuration for API access:
-
-```
-- name: K8S_API
-  value: "https://kubernetes.default:443"
-- name: CONFIGURE_ETC_HOSTS
-  value: "true"
-```
-
-## The leader election container
+The policy controller must have read access to the Kubernetes API in order to monitor NetworkPolicy, Pod, and Namespace events.
 
-The leader election container is an optional sidecar container which performs leader election using the Kubernetes API.
-This ensures that only a single instance of the policy controller is ever active.
-
-The leader election container is only recommended when running the policy controller as a static pod in a multi-master deployment.
-
-However, it is instead recommended to use a `ReplicaSet` with a single replica to ensure that one instance
-will always be running without need for leader election.
-
-### Kubernetes API access
-
-The leader election container also needs Kubernetes API access, which can be configured through a `kubeconfig` file placed in
-the root directory of the container. This can be done by mounting a file from the host, or using Kubernetes [ConfigMap resources](http://kubernetes.io/docs/user-guide/configmap/).
+When running the policy controller as a self-hosted Kubernetes Pod, Kubernetes API access is [configured automatically][in-cluster-config] and
+no additional configuration is required. However, the controller also supports an explicit [kubeconfig][kubeconfig] file override to
+configure API access if needed.
 
 ### Other configuration
 
-* `LOG_LEVEL`: Supports the standard Python log levels. e.g. `LOG_LEVEL=debug`, defaults to `info`
+The following environment variables can be used to configure the policy controller.
+
+| Environment   | Description | Schema |
+| ------------- | ----------- | ------ |
+| `LOG_LEVEL`     | Minimum log level to be displayed. | debug, info, warning, error |
+| `KUBECONFIG`    | Path to a kubeconfig file for kubernetes API access | path |
 
-More information on leader election can be found in the [kubernetes/contrib](https://github.com/kubernetes/contrib/tree/master/election#simple-leader-election-with-kubernetes-and-docker) repository.
+[in-cluster-config]: https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/#accessing-the-api-from-a-pod
+[kubeconfig]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/