Add chaincode job concept to doc

Also documents removing vm.endpoint from core.yaml and other minor
updates

See #229 and #223

Signed-off-by: James Taylor <[email protected]>

Author: jt-nti

docs/concepts/chaincode-job.md

@@ -0,0 +1,63 @@
+# Chaincode job
+
+The k8s builder runs chaincode images using a long running [Kubernetes job](https://kubernetes.io/docs/concepts/workloads/controllers/job/). Using jobs instead of bare pods [enables Kubernetes to clean up chaincode pods automatically](https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/).
+
+The k8s builder uses labels and annotations to help identify the Kubernetes objects it creates.
+
+## Labels
+
+Kubernetes objects created by the k8s builder have the following labels.
+
+app.kubernetes.io/name[^1]
+
+: The name of the application, `hyperledger-fabric`
+
+app.kubernetes.io/component[^1]
+
+: The application component, `chaincode`
+
+app.kubernetes.io/created-by[^1]
+
+: The tool that created the object, `fabric-builder-k8s`
+
+app.kubernetes.io/managed-by[^1]
+
+: The tool used to manage the application, `fabric-builder-k8s`
+
+fabric-builder-k8s-cclabel
+
+: The chaincode label, e.g. `mycc`
+
+fabric-builder-k8s-cchash
+
+: Base32 encoded chaincode hash, e.g. `U7FELJ6MQXY5RHEQLN3VSIBWD3IITI3E4EVJW3KVXJ24SZO522UQ`
+
+    The chaincode hash is base32 encoded so that it fits in the maximum number of characters allowed for a Kubernetes label value. For example, if you have the chaincode package ID, use the following commands to base32 encode the chaincode hash.
+
+    ```shell
+    echo $PACKAGE_ID | cut -d':' -f2 | xxd -r -p | base32 | tr -d '='
+    ```
+
+[^1]:
+    Kubernetes defines [recommended labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/) to describe applications and instances of applications.
+
+## Annotations
+
+Kubernetes objects created by the k8s builder have the following annotations.
+
+fabric-builder-k8s-ccid
+
+: The full chaincode package ID, e.g. `mycc:a7ca45a7cc85f1d89c905b775920361ed089a364e12a9b6d55ba75c965ddd6a9`
+
+fabric-builder-k8s-mspid
+
+: The membership service provider ID, e.g. `DigiBank`
+
+fabric-builder-k8s-peeraddress
+
+: The peer address, e.g. `peer0.digibank.example.com`
+
+fabric-builder-k8s-peerid
+
+: The peer ID, e.g. `peer0`
+

docs/configuring/overview.md

@@ -6,20 +6,33 @@ Fabric peers must be configured to use the k8s external builder, and to propagat
 
 External builders are configured in the `core.yaml` file, for example:
 
+```yaml
+externalBuilders:
+  - name: k8s_builder
+    path: /opt/hyperledger/k8s_builder
+    propagateEnvironment:
+      - CORE_PEER_ID
+      - FABRIC_K8S_BUILDER_DEBUG
+      - FABRIC_K8S_BUILDER_NAMESPACE
+      - FABRIC_K8S_BUILDER_NODE_ROLE
+      - FABRIC_K8S_BUILDER_OBJECT_NAME_PREFIX
+      - FABRIC_K8S_BUILDER_SERVICE_ACCOUNT
+      - FABRIC_K8S_BUILDER_START_TIMEOUT
+      - KUBERNETES_SERVICE_HOST
+      - KUBERNETES_SERVICE_PORT
 ```
-  externalBuilders:
-    - name: k8s_builder
-      path: /opt/hyperledger/k8s_builder
-      propagateEnvironment:
-        - CORE_PEER_ID
-        - FABRIC_K8S_BUILDER_DEBUG
-        - FABRIC_K8S_BUILDER_NAMESPACE
-        - FABRIC_K8S_BUILDER_NODE_ROLE
-        - FABRIC_K8S_BUILDER_OBJECT_NAME_PREFIX
-        - FABRIC_K8S_BUILDER_SERVICE_ACCOUNT
-        - FABRIC_K8S_BUILDER_START_TIMEOUT
-        - KUBERNETES_SERVICE_HOST
-        - KUBERNETES_SERVICE_PORT
+
+If you are only planning to use the k8s builder and do not need to fallback to the legacy Docker build process for any chaincode, check your `core.yaml` file for the `vm.endpoint` Docker endpoint configuration shown below and remove it if necessary.
+
+```yaml
+vm:
+  # Endpoint of the vm management system.  For docker can be one of the following in general
+  # unix:///var/run/docker.sock
+  # http://localhost:2375
+  # https://localhost:2376
+  # If you utilize external chaincode builders and don't need the default Docker chaincode builder,
+  # the endpoint should be unconfigured so that the peer's Docker health checker doesn't get registered.
+  endpoint: unix:///var/run/docker.sock
 ```
 
 For more information, see [Configuring external builders and launchers](https://hyperledger-fabric.readthedocs.io/en/latest/cc_launcher.html#configuring-external-builders-and-launchers) in the Fabric documentation.

docs/getting-started/demo.md

@@ -19,8 +19,7 @@ Download the sample Kubernetes test network (fabric-samples isn't tagged so we'l
 export FABRIC_SAMPLES_COMMIT=1058f9ffe16add583d1a11342deb5a9df3e5b72c
 curl -sSL "https://github.com/hyperledger/fabric-samples/archive/${FABRIC_SAMPLES_COMMIT}.tar.gz" | \
   tar -xzf - --strip-components=1 \
-    fabric-samples-${FABRIC_SAMPLES_COMMIT}/test-network-k8s \
-    fabric-samples-${FABRIC_SAMPLES_COMMIT}/asset-transfer-basic/chaincode-java
+    fabric-samples-${FABRIC_SAMPLES_COMMIT}/test-network-k8s
 ```
 
 ## Configure the Kubernetes test network
@@ -59,10 +58,10 @@ You can query the chaincode metadata to confirm that the sample was deployed suc
 ./network chaincode query sample-contract '{"Args":["org.hyperledger.fabric:GetMetadata"]}'
 ```
 
-Use the `kubectl` command to inspect chaincode pods.
+Use the `kubectl` command to inspect chaincode jobs.
 
 ```shell
-kubectl -n test-network describe pods -l app.kubernetes.io/created-by=fabric-builder-k8s
+kubectl -n test-network describe jobs -l app.kubernetes.io/created-by=fabric-builder-k8s
 ```
 
 ## Running transactions

docs/getting-started/install.md

@@ -16,7 +16,7 @@ Prebuilt binaries are available to download from the [releases page](https://git
 
 To install from source in `/opt/hyperledger/k8s_builder`, use the `go install` command.
 
-```
+```shell
 mkdir -p /opt/hyperledger/k8s_builder/bin
 cd /opt/hyperledger/k8s_builder/bin
 GOBIN="${PWD}" go install github.com/hyperledger-labs/fabric-builder-k8s/cmd/[email protected]

docs/tutorials/bevel-operator.md

@@ -126,7 +126,7 @@ kubectl hlf chaincode install --path=./go-contract-v0.7.2.tgz \
 
 Get the chaincode's PACKAGE_ID
 
-```
+```shell
 export PACKAGE_ID=$(kubectl hlf chaincode calculatepackageid --path=./go-contract-v0.7.2.tgz --language=golang --label=$CHAINCODE_LABEL) && echo $PACKAGE_ID
 ```
 

docs/tutorials/package-chaincode.md

@@ -15,7 +15,7 @@ IMAGEJSON-EOF
 The k8s builder uses digests because these are immutable, unlike tags.
 The docker inspect command can be used to find the digest if required.
 
-```
+```shell
 docker pull ghcr.io/hyperledger-labs/go-contract:v0.7.2
 docker inspect --format='{{index .RepoDigests 0}}' ghcr.io/hyperledger-labs/go-contract:v0.7.2 | cut -d'@' -f2
 ```

mkdocs.yml

@@ -101,6 +101,7 @@ nav:
     - Chaincode builder: concepts/chaincode-builder.md
     - Chaincode image: concepts/chaincode-image.md
     - Chaincode package: concepts/chaincode-package.md
+    - Chaincode job: concepts/chaincode-job.md
   - Configuring:
     - Configuration overview: configuring/overview.md
     - Kubernetes permissions: configuring/kubernetes-permissions.md