update kubernetes readmes (#2781)

.github/styles/vocab.txt

@@ -32,6 +32,7 @@ Codehilite
 codeowners
 config
 Config
+configmaps
 configs
 const
 cookiecutter
@@ -67,6 +68,7 @@ graphviz
 Hackathons
 haproxy
 heroku
+horizontalpodautoscalers
 Hostname
 http
 https
@@ -140,6 +142,7 @@ rankdir
 readme
 Readme
 Redash
+replicasets
 repo
 Repo
 repos

plugins/kubernetes-backend/README.md

@@ -6,6 +6,66 @@ This is the backend part of the Kubernetes plugin.
 
 It responds to Kubernetes requests from the frontend.
 
-## Links
+## Configuration
 
-- [The Backstage homepage](https://backstage.io)
+### clusterLocatorMethod
+
+This configures how to determine which clusters a component is running in.
+
+Currently, the only valid locator method is:
+
+#### configMultiTenant
+
+This configuration assumes that all components run on all the provided clusters.
+
+Example:
+
+```yaml
+kubernetes:
+  clusterLocatorMethod: 'configMultiTenant'
+  clusters:
+    - url: http://127.0.0.1:9999
+      name: minikube
+      serviceAccountToken: <TOKEN FROM STEP 4>
+      authProvider: 'serviceAccount'
+    - url: http://127.0.0.2:9999
+      name: gke-cluster-1
+      authProvider: 'google'
+```
+
+##### clusters
+
+Used by the `configMultiTenant` `clusterLocatorMethod` to construct Kubernetes clients.
+
+###### url
+
+The base url to the Kubernetes control plane. Can be found by using the `Kubernetes master` result from running the `kubectl cluster-info` command.
+
+###### name
+
+A name to represent this cluster, this must be unique within the `clusters` array. Users will see this value in the Service Catalog Kubernetes plugin.
+
+###### authProvider
+
+This determines how the Kubernetes client authenticate with the Kubernetes cluster. Valid values are:
+
+| Value            | Description                                                                                                                                                                                                                       |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `serviceAccount` | This will use a Kubernetes [service account](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set. |
+| `google`         | This will use a user's google auth token from the [google auth plugin](https://backstage.io/docs/auth/) to access the Kubernetes API.                                                                                             |
+
+###### serviceAccount (optional)
+
+The service account token to be used when using the `authProvider`, `serviceAccount`.
+
+## RBAC
+
+The current RBAC permissions required are read-only cluster wide, for the following objects:
+
+- pods
+- services
+- configmaps
+- deployments
+- replicasets
+- horizontalpodautoscalers
+- ingresses

plugins/kubernetes-backend/examples/dice-roller/README.md

@@ -1,6 +1,6 @@
 # Dice roller
 
-An app to roll dice (it doesn't actually do that).
+This can be used to run the kubernetes plugin locally against a mock service.
 
 # Viewing in local Minikube running Backstage locally
 
@@ -23,22 +23,24 @@ An app to roll dice (it doesn't actually do that).
 6. Register existing component in Backstage
    - https://github.com/mclarke47/dice-roller/blob/master/catalog-info.yaml
 
-Update `app-config.yaml` as follows.
+Update `app-config.development.yaml` as follows.
 
 ```yaml
----
 kubernetes:
   clusterLocatorMethod: 'configMultiTenant'
   clusters:
     - url: <KUBERNETES MASTER BASE URL FROM STEP 2>
       name: minikube
       serviceAccountToken: <TOKEN FROM STEP 4>
+      authProvider: 'serviceAccount'
 ```
 
 ### Getting the service account token
 
+Mac copy to clipboard:
+
 ```
-kubectl get secret DICE_ROLLER_TOKEN_NAME -o=json | jq -r '.data["token"]' | base64 --decode | pbcopy
+kubectl get secret $(kubectl get sa dice-roller -o=json | jq -r .secrets[0].name) -o=json | jq -r '.data["token"]' | base64 --decode | pbcopy
 ```
 
-Paste into `app-config.yaml` `kubernetes.clusters[].serviceAccountToken`
+Paste into `app-config.development.yaml` `kubernetes.clusters[0].serviceAccountToken`

plugins/kubernetes/README.md

@@ -11,3 +11,24 @@ Your plugin has been added to the example app in this repository, meaning you'll
 You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
 This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
 It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.
+
+## Surfacing your Kubernetes components as part of an entity
+
+### Adding the entity annotation
+
+In order for Backstage to detect that an entity has Kubernetes components,
+the following annotation should be added to the entity.
+
+```yaml
+annotations:
+  'backstage.io/kubernetes-id': dice-roller
+```
+
+### Labeling Kubernetes components
+
+In order for Kubernetes components to show up in the service catalog
+as a part of an entity, Kubernetes components must be labeled with the following label:
+
+```yaml
+'backstage.io/kubernetes-id': <ENTITY_NAME>
+```