Update docs with general Kubernetes config info

Includes details of how to provide image pull secrets when chaincode
images are in registries which require credentials

Closes hyperledger-labs#65

Signed-off-by: James Taylor <jamest@uk.ibm.com>

README.md

@@ -3,7 +3,7 @@
 Kubernetes [external chaincode builder](https://hyperledger-fabric.readthedocs.io/en/latest/cc_launcher.html)
 for Hyperledger Fabric.
 
-With the k8s-builder, the Fabric administrator is responsible for preparing a chaincode image, publishing to a
+With the k8s builder, the Fabric administrator is responsible for preparing a chaincode image, publishing to a
 container registry, and preparing a [chaincode package](https://hyperledger-fabric.readthedocs.io/en/latest/cc_launcher.html#chaincode-packages)
 with coordinates of the contract's immutable image digest.  When Fabric detects the installation of a `type=k8s`
 contract, the builder assumes full ownership of the lifecycle of pods, containers, and network linkages necessary 
@@ -12,12 +12,12 @@ to communicate securely with the peer.
 
 Advantages:
 
-- [X] Chaincode runs _immediately_ on channel commit.
-- [X] k8s-builder avoids the complexity and administrative burdens associated with Chaincode-as-a-Service. 
-- [X] Pre-published chaincode images avoid code-compilation errors at deployment time.
-- [X] Pre-published chaincode images encourage modern, industry accepted CI/CD best practices.
-- [X] Pre-published chaincode images remove any and all dependencies on a root-level _docker daemon_.
-- [X] Pre-published chaincode images provide traceability and change management features (e.g. Git commit hash as image tag)
+- 🚀 Chaincode runs _immediately_ on channel commit.
+- ✨ Avoids the complexity and administrative burdens associated with Chaincode-as-a-Service. 
+- 🔥 Pre-published chaincode images avoid code-compilation errors at deployment time.
+- 🏗️ Pre-published chaincode images encourage modern, industry accepted CI/CD best practices.
+- 🛡️ Pre-published chaincode images remove any and all dependencies on a root-level _docker daemon_.
+- 🕵️ Pre-published chaincode images provide traceability and change management features (e.g. Git commit hash as image tag)
 
 The aim is for the builder to work as closely as possible with the existing [Fabric chaincode lifecycle](https://hyperledger-fabric.readthedocs.io/en/latest/chaincode_lifecycle.html), making sensible compromises for deploying chaincode on Kubernetes within those constraints.
 (The assumption being that there are more people with Kubernetes skills than are familiar with the inner workings of Fabric!)
@@ -38,13 +38,8 @@ For example:
   Unfortunately due to limitations in Fabric's builder and launcher implementation, that is not possible and the peer expects to control the chaincode process.
 
 
-**Status:** the k8s builder has been tested in a number of Kubernetes environments, deployment platforms, and
-provides semantic-revision aware [release tags](https://github.com/hyperledger-labs/fabric-builder-k8s/tags) for the
-external builder binaries.  The current status should be considered as STABLE and any bugs or enhancements delivered as
-GitHub Issues in conjunction with community PRs.
-
-With the k8s-builder, _chaincode just works!_
-
+**Status:** the k8s builder is [close to a version 1 release](https://github.com/hyperledger-labs/fabric-builder-k8s/milestone/1) and has been tested in a number of Kubernetes environments, deployment platforms, and provides semantic-revision aware [release tags](https://github.com/hyperledger-labs/fabric-builder-k8s/tags) for the external builder binaries.
+The current status should be considered as STABLE and any bugs or enhancements delivered as GitHub Issues in conjunction with community PRs.
 
 ## Usage
 
@@ -75,6 +70,8 @@ External builders are configured in the `core.yaml` file, for example:
 
 See [External Builders and Launchers](https://hyperledger-fabric.readthedocs.io/en/latest/cc_launcher.html) for details of Hyperledger Fabric builders.
 
+As well as configuring Fabric to use the k8s builder, you will need to [configure Kubernetes](docs/KUBERNETES_CONFIG.md) to allow the builder to start chaincode pods successfully.
+
 There are addition docs with more detailed usage instructions for specific Fabric network deployments:
 
 - [Kubernetes Test Network](docs/TEST_NETWORK_K8S.md)

docs/KUBERNETES_CONFIG.md

@@ -0,0 +1,106 @@
+# Kubernetes Configuration
+
+## Builder requirements
+
+The k8s builder needs sufficient permissions to manage chaincode pods on behalf of the Fabric `peer`.
+
+| Resource | Permissions                      |
+| -------- | -------------------------------- |
+| pods     | get, list, watch, create, delete |
+| secrets  | create, patch                    |
+
+For example, follow these steps if the builder will be running in the `default` namespace using the `default` service account.
+
+1. Create a `fabric-builder-role` role.
+
+```shell
+cat <<EOF | kubectl apply -f -
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: fabric-builder-role
+  namespace: default
+rules:
+  - apiGroups:
+      - ""
+      - apps
+    resources:
+      - pods
+      - configmaps
+      - secrets
+    verbs:
+      - get
+      - list
+      - watch
+      - create
+      - delete
+      - patch
+EOF
+```
+
+2. Create a `fabric-builder-rolebinding` role binding.
+
+```shell
+cat <<EOF | kubectl apply -f -
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: fabric-builder-rolebinding
+  namespace: default
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: fabric-builder-role 
+subjects:
+- namespace: default 
+  kind: ServiceAccount
+  name: default 
+EOF
+```
+
+3. Check the permissions, e.g.
+
+```shell
+kubectl auth can-i patch secrets --namespace test-network --as system:serviceaccount:default:default
+```
+
+## Chaincode requirements
+
+By default, the k8s builder starts chaincode pods in the same namespace, however the `FABRIC_K8S_BUILDER_NAMESPACE` environment variable can be used to start chaincode pods in a different namespace.
+
+Chaincode pods are created with a service account defined by the `FABRIC_K8S_BUILDER_SERVICE_ACCOUNT` environment variable, or the `default` service account if the variable is not set.
+If your chaincode images are published to registries which require credentials, you will need to add image pull secrets to the service account.
+
+For example, follow these steps if `FABRIC_K8S_BUILDER_NAMESPACE` and `FABRIC_K8S_BUILDER_SERVICE_ACCOUNT` are both set to `fabric-chaincode`.
+
+1. Create the `fabric-chaincode` namespace.
+
+```shell
+kubectl create namespace chaincode
+```
+
+2. Create the `fabric-chaincode` service account.
+
+```shell
+kubectl create serviceaccount fabric-chaincode --namespace=fabric-chaincode
+```
+
+3. Create an imagePullSecret.
+
+```shell
+kubectl create secret docker-registry fabregistrykey --namespace=fabric-chaincode \
+    --docker-server=DOCKER_SERVER \
+    --docker-username=DOCKER_USERNAME \
+    --docker-password=DOCKER_PASSWORD \
+    --docker-email=DOCKER_EMAIL
+```
+
+4. Add the image pull secret to the service account.
+
+```shell
+kubectl patch serviceaccount fabric-chaincode --namespace=fabric-chaincode -p '{"imagePullSecrets": [{"name": "fabregistrykey"}]}'
+```
+
+See the Kubernetes [Configure Service Accounts for Pods](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account) documentation for details.