Merge branch 'master' into doc-edits-0.2

deployment/README.md

@@ -71,7 +71,7 @@ The Kubernetes Discoverer is responsible for looking at all services and endpoin
 # Kubernetes secret
 $ kubectl -n gimbal-discovery create secret generic remote-discover-kubecfg \
     --from-file=config=./config \
-    --from-literal=cluster-name=node02
+    --from-literal=backend-name=node02
 
 # Deploy Discoverer
 $ kubectl apply -f gimbal-discoverer/02-kubernetes-discoverer.yaml
@@ -89,7 +89,7 @@ The Openstack Discoverer is responsible for looking at all LBaaS and members in
 # Openstack secret
 $ kubectl -n gimbal-discovery create secret generic remote-discover-openstack \
     --from-file=certificate-authority-data=./ca.pem \
-    --from-literal=cluster-name=openstack \
+    --from-literal=backend-name=openstack \
     --from-literal=username=admin \
     --from-literal=password=abc123 \
     --from-literal=auth-url=https://api.openstack:5000/ \

deployment/gimbal-discoverer/02-kubernetes-discoverer.yaml

@@ -26,13 +26,13 @@ spec:
         imagePullPolicy: Always
         name: kubernetes-discoverer
         command: ["/kubernetes-discoverer"]
-        args: ["--discover-kubecfg-file", "/etc/remote-discover-kubecfg/config", "--cluster-name", "$(CLUSTER_NAME)"]
+        args: ["--discover-kubecfg-file", "/etc/remote-discover-kubecfg/config", "--backend-name", "$(CLUSTER_NAME)"]
         env:
         - name: CLUSTER_NAME
           valueFrom:
             secretKeyRef:
               name: remote-discover-kubecfg
-              key: cluster-name
+              key: backend-name
         volumeMounts:
         - name: discover-kubecfg
           readOnly: true

deployment/gimbal-discoverer/02-openstack-discoverer.yaml

@@ -26,13 +26,13 @@ spec:
           imagePullPolicy: Always
           name: openstack-discoverer
           command: ["/openstack-discoverer"]
-          args: ["--cluster-name", "$(CLUSTER_NAME)", "--openstack-certificate-authority","/etc/remote-openstack-config/ca.pem"]
+          args: ["--backend-name", "$(CLUSTER_NAME)", "--openstack-certificate-authority","/etc/remote-openstack-config/ca.pem"]
           env:
             - name: CLUSTER_NAME
               valueFrom:
                 secretKeyRef:
                   name: remote-discover-openstack
-                  key: cluster-name
+                  key: backend-name
             - name: OS_USERNAME
               valueFrom:
                 secretKeyRef:

deployment/grafana/02-grafana-configmap.yaml

@@ -255,21 +255,21 @@ data:
           "steppedLine": false,
           "targets": [
             {
-              "expr": "sum(gimbal_service_error_total{namespace=~\"$Namespace\",clustername=~\"$BackendCluster\"}) by (clustername)",
+              "expr": "sum(gimbal_service_error_total{namespace=~\"$Namespace\",backendname=~\"$BackendCluster\"}) by (backendname)",
               "format": "time_series",
               "hide": false,
               "interval": "",
               "intervalFactor": 1,
-              "legendFormat": "Service errors: {{clustername}}",
+              "legendFormat": "Service errors: {{backendname}}",
               "refId": "A"
             },
             {
-              "expr": "sum(gimbal_endpoints_error_total{namespace=~\"$Namespace\",clustername=~\"$BackendCluster\"}) by (clustername)",
+              "expr": "sum(gimbal_endpoints_error_total{namespace=~\"$Namespace\",backendname=~\"$BackendCluster\"}) by (backendname)",
               "format": "time_series",
               "hide": false,
               "interval": "",
               "intervalFactor": 1,
-              "legendFormat": "Endpoints errors: {{clustername}}",
+              "legendFormat": "Endpoints errors: {{backendname}}",
               "refId": "B"
             }
           ],
@@ -348,7 +348,7 @@ data:
           "steppedLine": false,
           "targets": [
             {
-              "expr": "sum(gimbal_service_error_total{namespace=~\"$Namespace\",clustername=~\"$BackendCluster\"}) by (namespace)",
+              "expr": "sum(gimbal_service_error_total{namespace=~\"$Namespace\",backendname=~\"$BackendCluster\"}) by (namespace)",
               "format": "time_series",
               "hide": false,
               "interval": "",
@@ -357,7 +357,7 @@ data:
               "refId": "A"
             },
             {
-              "expr": "sum(gimbal_endpoints_error_total{namespace=~\"$Namespace\",clustername=~\"$BackendCluster\"}) by (namespace)",
+              "expr": "sum(gimbal_endpoints_error_total{namespace=~\"$Namespace\",backendname=~\"$BackendCluster\"}) by (namespace)",
               "format": "time_series",
               "hide": false,
               "interval": "",
@@ -446,11 +446,11 @@ data:
           "steppedLine": false,
           "targets": [
             {
-              "expr": "gimbal_queuesize{clustername=~\"$BackendCluster\"} ",
+              "expr": "gimbal_queuesize{backendname=~\"$BackendCluster\"} ",
               "format": "time_series",
               "hide": false,
               "intervalFactor": 1,
-              "legendFormat": "{{clustername}}",
+              "legendFormat": "{{backendname}}",
               "refId": "A"
             }
           ],
@@ -529,12 +529,12 @@ data:
           "steppedLine": false,
           "targets": [
             {
-              "expr": "gimbal_discoverer_cycle_duration_ms{clustername=~\"$BackendCluster\"} ",
+              "expr": "gimbal_discoverer_cycle_duration_ms{backendname=~\"$BackendCluster\"} ",
               "format": "time_series",
               "hide": false,
               "interval": "",
               "intervalFactor": 1,
-              "legendFormat": "{{clustername}}",
+              "legendFormat": "{{backendname}}",
               "refId": "A"
             }
           ],
@@ -613,11 +613,11 @@ data:
           "steppedLine": false,
           "targets": [
             {
-              "expr": "avg(gimbal_discoverer_api_latency_ms{clustername=~\"$BackendCluster\"}) by (clustername)",
+              "expr": "avg(gimbal_discoverer_api_latency_ms{backendname=~\"$BackendCluster\"}) by (backendname)",
               "format": "time_series",
               "hide": false,
               "intervalFactor": 1,
-              "legendFormat": "{{clustername}}",
+              "legendFormat": "{{backendname}}",
               "refId": "A"
             }
           ],
@@ -694,7 +694,7 @@ data:
             "multi": true,
             "name": "BackendCluster",
             "options": [],
-            "query": "label_values(clustername)",
+            "query": "label_values(backendname)",
             "refresh": 2,
             "regex": "",
             "sort": 0,

discovery/README.md

@@ -27,7 +27,7 @@ The following arguments are available to customize the Discoverer:
 | --num-threads  | 2  |  Specify number of threads to use when processing queue items. | ALL
 | --gimbal-kubecfg-file  | ""  | Location of kubecfg file for access to kubernetes cluster hosting Gimbal | ALL
 | --discover-kubecfg-file | ""  | Location of kubecfg file for access to remote kubernetes cluster to watch for services / endpoints | Kubernetes
-| --cluster-name  | ""  |   Name of cluster scraping for services & endpoints | ALL
+| --backend-name  | ""  |   Name of cluster scraping for services & endpoints | ALL
 | --debug | false | Enable debug logging | ALL
 | --reconciliation-period | 30s | The interval of time between reconciliation loop runs | Openstack
 | --http-client-timeout | 5s | The HTTP client request timeout | Openstack
@@ -65,15 +65,15 @@ $ kubectl create secret generic remote-discover-openstack --from-literal=keyston
 The Kubernetes discoverer requires two configs, first is the Gimbal system which will run Contour and store services & endpoints, the other is the remote cluster to scrape for services & endpoints. The config file is standard kubeconfig file, just make sure it's named `config`. Please include any certs required to access to the remote cluster api:
 
 ```
-$ go run cmd/kubernetes-discoverer/main.go --gimbal-kubecfg-file=./config --discover-kubecfg-file=./config --cluster-name=clustername
+$ go run cmd/kubernetes-discoverer/main.go --gimbal-kubecfg-file=./config --discover-kubecfg-file=./config --backend-name=backendname
 ```
 
 ### Openstack
 
 The Openstack discoverer requires the config for the Gimbal Kubernetes cluster which will run Contour and store services & endpoints, the other is the remote cluster to scrape for load balancers and members. The config file is standard kubeconfig file, just make sure it's named `config`. Please include any certs required to access to the remote cluster api:
 
 ```
-$ OS_USERNAME=user OS_PASSWORD=password OS_AUTH_URL=https://url OS_TENANT_NAME=tenant go run cmd/openstack-discoverer/main.go --gimbal-kubecfg-file=./config --cluster-name=clustername
+$ OS_USERNAME=user OS_PASSWORD=password OS_AUTH_URL=https://url OS_TENANT_NAME=tenant go run cmd/openstack-discoverer/main.go --gimbal-kubecfg-file=./config --backend-name=backendname
 ```
 
 ## Build / Test

discovery/cmd/kubernetes-discoverer/main.go

@@ -37,7 +37,7 @@ var (
 	gimbalKubeCfgFile     string
 	discovererKubeCfgFile string
 	numProcessThreads     int
-	clusterName           string
+	backendName           string
 	resyncInterval        time.Duration
 	debug                 bool
 	prometheusListenPort  int
@@ -49,7 +49,7 @@ func init() {
 	flag.IntVar(&numProcessThreads, "num-threads", 2, "Specify number of threads to use when processing queue items.")
 	flag.StringVar(&gimbalKubeCfgFile, "gimbal-kubecfg-file", "", "Location of kubecfg file for access to gimbal system kubernetes api, defaults to service account tokens")
 	flag.StringVar(&discovererKubeCfgFile, "discover-kubecfg-file", "", "Location of kubecfg file for access to remote discover system kubernetes api")
-	flag.StringVar(&clusterName, "cluster-name", "", "Name of cluster")
+	flag.StringVar(&backendName, "backend-name", "", "Name of backend (must be unique)")
 	flag.DurationVar(&resyncInterval, "resync-interval", time.Minute*30, "Default resync period for watcher to refresh")
 	flag.BoolVar(&debug, "debug", false, "Enable debug logging.")
 	flag.IntVar(&prometheusListenPort, "prometheus-listen-address", 8080, "The address to listen on for Prometheus HTTP requests")
@@ -79,10 +79,10 @@ func main() {
 	}
 
 	// Verify cluster name is passed
-	if util.IsInvalidClusterName(clusterName) {
-		log.Fatalf("The Kubernetes cluster name must be provided using the `--cluster-name` flag or the one passed is invalid")
+	if util.IsInvalidBackendName(backendName) {
+		log.Fatalf("The Kubernetes cluster name must be provided using the `--backend-name` flag or the one passed is invalid")
 	}
-	log.Infof("ClusterName is: %s", clusterName)
+	log.Infof("BackendName is: %s", backendName)
 
 	// Discovered cluster is passed
 	if discovererKubeCfgFile == "" {
@@ -104,7 +104,7 @@ func main() {
 
 	kubeInformerFactory := kubeinformers.NewSharedInformerFactory(k8sDiscovererClient, resyncInterval)
 
-	c := k8s.NewController(log, gimbalKubeClient, kubeInformerFactory, clusterName, numProcessThreads, discovererMetrics)
+	c := k8s.NewController(log, gimbalKubeClient, kubeInformerFactory, backendName, numProcessThreads, discovererMetrics)
 	if err != nil {
 		log.Fatal("Could not init Controller! ", err)
 	}

discovery/cmd/openstack-discoverer/main.go

@@ -41,7 +41,7 @@ var (
 	printVersion                      bool
 	gimbalKubeCfgFile                 string
 	discoverStackCfgFile              string
-	clusterName                       string
+	backendName                       string
 	numProcessThreads                 int
 	debug                             bool
 	reconciliationPeriod              time.Duration
@@ -60,7 +60,7 @@ const (
 func init() {
 	flag.BoolVar(&printVersion, "version", false, "Show version and quit")
 	flag.StringVar(&gimbalKubeCfgFile, "gimbal-kubecfg-file", "", "Location of kubecfg file for access to gimbal system kubernetes api, defaults to service account tokens")
-	flag.StringVar(&clusterName, "cluster-name", "", "Name of cluster")
+	flag.StringVar(&backendName, "backend-name", "", "Name of cluster (must be unique)")
 	flag.IntVar(&numProcessThreads, "num-threads", 2, "Specify number of threads to use when processing queue items.")
 	flag.BoolVar(&debug, "debug", false, "Enable debug logging.")
 	flag.DurationVar(&reconciliationPeriod, "reconciliation-period", 30*time.Second, "The interval of time between reconciliation loop runs.")
@@ -92,10 +92,10 @@ func main() {
 	discovererMetrics.RegisterPrometheus()
 
 	// Validate cluster name
-	if util.IsInvalidClusterName(clusterName) {
-		log.Fatalf("The Kubernetes cluster name must be provided using the `--cluster-name` flag or the one passed is invalid")
+	if util.IsInvalidBackendName(backendName) {
+		log.Fatalf("The Kubernetes cluster name must be provided using the `--backend-name` flag or the one passed is invalid")
 	}
-	log.Infof("ClusterName is: %s", clusterName)
+	log.Infof("BackendName is: %s", backendName)
 
 	gimbalKubeClient, err := k8s.NewClient(gimbalKubeCfgFile, log)
 	if err != nil {
@@ -133,7 +133,7 @@ func main() {
 	transport := &openstack.LogRoundTripper{
 		RoundTripper: http.DefaultTransport,
 		Log:          log,
-		ClusterName:  clusterName,
+		BackendName:  backendName,
 		ClusterType:  clusterType,
 		Metrics:      &discovererMetrics,
 	}
@@ -170,7 +170,7 @@ func main() {
 	}
 
 	reconciler := openstack.NewReconciler(
-		clusterName,
+		backendName,
 		clusterType,
 		gimbalKubeClient,
 		reconciliationPeriod,

discovery/design/kubernetes.md

@@ -66,33 +66,33 @@ Based on the Service and Pod definitions, Endpoints’ "Target Port" may be diff
 
 The Kubernetes Discoverer will write the available Services and Endpoint information to the corresponding Team namespace as standard Kubernetes services & endpoints.
 
-The discoverer will only be responsible for monitoring a single cluster at a time. If multiple clusters are required to be watched, then multiple discoverer components will need to be deployed. Initially, discoverer's will be deployed manually via Deployments, but further iterations will introduce a Disovery Operator which will take over this repsonsibility. 
+The discoverer will only be responsible for monitoring a single cluster at a time. If multiple clusters are required to be watched, then multiple discoverer components will need to be deployed. Initially, discoverer's will be deployed manually via Deployments, but further iterations will introduce a Discovery Operator which will take over this responsibility. 
 
 ## Detailed Design
 
 Watches are setup to monitor for changes to Services or Endpoints in a Kubernetes cluster. These updates (e.g. ADD, MODIFY, DELETE) are places onto a queue. Items are processed off of that rate-limited queue so that we can maintain sane performance. The queue is an in-memory queue with no durability aimed at reducing the load on the Gimbal Kubernetes API. 
 
-If additional processing is required, then an argument can be changed to increase the number of threads available to consume items from the queue. All objects syncronized to the coresponding Team namespace. When an object is added or updated, the entire object is copied with all labels, anotations, etc. Additional labels are added so that Izzy can have more detailed information about the object. 
+If additional processing is required, then an argument can be changed to increase the number of threads available to consume items from the queue. All objects synchronized to the corresponding Team namespace. When an object is added or updated, the entire object is copied with all labels, annotations, etc. Additional labels are added so that Izzy can have more detailed information about the object. 
 
 Those labels are defined as:
 
-- gimbal.heptio.com/backend: ClusterName (Defined via argument)
+- gimbal.heptio.com/backend: BackendName (Defined via argument)
 - gimbal.heptio.com/service: [ServiceName]
 
-The name of the syncronized object will be a hash of the `ClusterName-ServiceName`. The name is hashed because of length restrictions when creating a service object.
+The name of the synchronized object will be a hash of the `BackendName-ServiceName`. The name is hashed because of length restrictions when creating a service object.
 
 In the event that the total length of the hash is larger than 63 characters (maximum allowed length), then the components are hashed to keep within the limits. All attempts are made to keep the name as descriptive to the source as possible. 
 
-The discoverer should syncronize the cluster on first startup so that any changes missed while being offline are properly updated. This is handled automatically since a new watch on a resource sends the current list of items upon initialization. The add logic then checks to see if the object is already existing and in that case passes it off to the update method. 
+The discoverer should synchronize the cluster on first startup so that any changes missed while being offline are properly updated. This is handled automatically since a new watch on a resource sends the current list of items upon initialization. The add logic then checks to see if the object is already existing and in that case passes it off to the update method. 
 
 The discoverer component will have arguments which will allow users to customize or override default values:
 
 - *num-threads*: Specify number of threads to use when processing queue items.
 - *gimbal-kubecfg-file*: Location of kubecfg file for access to kubernetes cluster hosting Izzy
 - *discover-kubecfg-file*: Location of kubecfg file for access to remote kubernetes cluster to watch for services / endpoints
-- *cluster-name*: Name of cluster scraping for services & endpoints
+- *backend-name*: Name of cluster scraping for services & endpoints
 
-By default, the `kube-system` namespace is isgnored when looking for services / endpoints. Future iterations of discoverer should allow for namespace whilelisting and blacklisting to allow for further customization. 
+By default, the `kube-system` namespace is ignored when looking for services / endpoints. Future iterations of discoverer should allow for namespace whitelisting and blacklisting to allow for further customization. 
 
 ## Security/Performance Concerns
 

discovery/design/openstack.md

@@ -32,9 +32,9 @@ cluster.
 Given that Izzy will support multiple OpenStack clusters, all the resources synced by the OpenStack discoverer must be
 scoped to a specific cluster to avoid collisions.
 
-Thus, the `name` of synced Services and Endpoints will be `ClusterName-Name`:
+Thus, the `name` of synced Services and Endpoints will be `BackendName-Name`:
 
-- `ClusterName`: The name of the OpenStack cluster. This is configurable through a command-line flag.
+- `BackendName`: The name of the OpenStack cluster. This is configurable through a command-line flag.
 - `Name`: The OpenStack Load Balancer's name concatenated (using hyphen as a separator) with the Load Balancer's ID. If
   the load balancer does not have a name, the ID is used. (Names are optional in OpenStack).
 
@@ -99,7 +99,7 @@ the OpenStack Load Balancer:
 | Service             | Load Balancer                                  |
 |---------------------|------------------------------------------------|
 | `Namespace`         | `ProjectId -> Project Name`                    |
-| `Name`              | `ClusterName-Name`                             |
+| `Name`              | `BackendName-Name`                             |
 | `Ports[i].Name`     | `Listeners[i].Name-Listeners[i].Protocol_Port` |
 | `Ports[i].Protocol` | `Listeners[i].Protocol`                        |
 | `Ports[i].Port`     | `Listeners[i].Protocol_Port`                   |
@@ -114,7 +114,7 @@ the Load Balancer's Listeners, Pools and Pool Members.
 
 The Kubernetes Endpoint will be derived as follows:
 
-- Set the `name` to `ClusterName-Name`
+- Set the `name` to `BackendName-Name`
 - For each Listener, group all members that are listening on the same port into an `EndpointSubset`.
 - Set the `name` of the `EndpointPort` to `port-${Listeners[i].Protocol_Port}`.
 - Set the `addresses` list of the `EndpointSubset` to the list of IP addresses of each member in the group.