From 5cbcdf25cfbbb4774cbd0c23b3a87fb0c227e348 Mon Sep 17 00:00:00 2001 From: James Taylor Date: Fri, 17 May 2024 11:18:32 +0100 Subject: [PATCH] Initial mkdocs content See #66 Signed-off-by: James Taylor --- docs/TEST_NETWORK_NANO.md | 84 ------ docs/about/community.md | 3 + docs/about/intro.md | 21 ++ docs/about/objectives.md | 20 ++ docs/assets/Hyperledger_Fabric.svg | 258 ++++++++++++++++++ docs/assets/Hyperledger_Fabric_Icon.svg | 11 + docs/assets/Hyperledger_Fabric_White.svg | 258 ++++++++++++++++++ docs/{content => }/assets/project-icon.png | Bin docs/{content => }/assets/project-logo.png | Bin docs/concepts/chaincode-builder.md | 28 ++ docs/concepts/chaincode-image.md | 18 ++ docs/concepts/chaincode-package.md | 77 ++++++ docs/content/index.md | 1 - .../config.md} | 70 +---- .../demo.md} | 7 +- docs/getting-started/faqs.md | 11 + docs/getting-started/install.md | 1 + docs/getting-started/requirements.md | 67 +++++ docs/mkdocs.yml => mkdocs.yml | 35 ++- docs/requirements.txt => requirements.txt | 0 20 files changed, 809 insertions(+), 161 deletions(-) delete mode 100644 docs/TEST_NETWORK_NANO.md create mode 100644 docs/about/community.md create mode 100644 docs/about/intro.md create mode 100644 docs/about/objectives.md create mode 100644 docs/assets/Hyperledger_Fabric.svg create mode 100644 docs/assets/Hyperledger_Fabric_Icon.svg create mode 100644 docs/assets/Hyperledger_Fabric_White.svg rename docs/{content => }/assets/project-icon.png (100%) rename docs/{content => }/assets/project-logo.png (100%) create mode 100644 docs/concepts/chaincode-builder.md create mode 100644 docs/concepts/chaincode-image.md create mode 100644 docs/concepts/chaincode-package.md delete mode 100644 docs/content/index.md rename docs/{KUBERNETES_CONFIG.md => getting-started/config.md} (52%) rename docs/{TEST_NETWORK_K8S.md => getting-started/demo.md} (93%) create mode 100644 docs/getting-started/faqs.md create mode 100644 docs/getting-started/install.md create mode 100644 docs/getting-started/requirements.md rename docs/mkdocs.yml => mkdocs.yml (63%) rename docs/requirements.txt => requirements.txt (100%) diff --git a/docs/TEST_NETWORK_NANO.md b/docs/TEST_NETWORK_NANO.md deleted file mode 100644 index 9df4cd8..0000000 --- a/docs/TEST_NETWORK_NANO.md +++ /dev/null @@ -1,84 +0,0 @@ -# Nano Test Network - -The k8s builder can be used with the [nano test network](https://github.com/hyperledger/fabric-samples/tree/main/test-network-nano-bash) by following the instructions below. - -## Download builder binaries - -Download the latest builder binaries from the [releases page](https://github.com/hyperledger-labs/fabric-builder-k8s/releases) and extract them to a `k8s_builder/bin` directory in your home directory. - -## Configure builder - -After installing the nano test network prereqs, the `fabric-samples/config/core.yaml` file needs to be updated with the k8s builder configuration. - -``` - externalBuilders: - - name: k8s_builder - path: /k8s_builder - propagateEnvironment: - - CORE_PEER_ID - - KUBECONFIG_PATH -``` - -You can use [yq](https://mikefarah.gitbook.io/yq/) to update the `fabric-samples/config/core.yaml` files. -Make sure you are in the `fabric-samples` directory before running the following commands. - -```shell -FABRIC_K8S_BUILDER_PATH=${HOME}/k8s_builder yq -i '.chaincode.externalBuilders += { "name": "k8s_builder", "path": "${FABRIC_K8S_BUILDER_PATH}" | envsubst(ne), "propagateEnvironment": [ "CORE_PEER_ID", "KUBECONFIG_PATH" ] }' config/core.yaml -``` - -## Kubernetes configuration - -The k8s builder needs a kubeconfig file to access a Kubernetes cluster to deploy chaincode. Make sure the `KUBECONFIG_PATH` environment variable is available on every peer the builder is configured on. - -```shell -export KUBECONFIG_PATH=$HOME/.kube/config -``` - -## Downloading chaincode package - -The [sample contracts for Go, Java, and Node.js](samples/README.md) publish a Docker image which the k8s builder can use _and_ a chaincode package file which can be used with the `peer lifecycle chaincode install` command. -Use of a pre-generated chaincode package .tgz greatly simplifies the deployment, aligning with standard industry practices for CI/CD and git-ops workflows. - -Download a sample chaincode package, e.g. for the Go contract: - -```shell -curl -fsSL \ - https://github.com/hyperledger-labs/fabric-builder-k8s/releases/download/v0.7.2/go-contract-v0.7.2.tgz \ - -o go-contract-v0.7.2.tgz -``` - -## Deploying chaincode - -Deploy the chaincode package as usual, starting by installing the k8s chaincode package. - -```shell -peer lifecycle chaincode install go-contract-v0.7.2.tgz -``` - -Export a `PACKAGE_ID` environment variable for use in the following commands. - -```shell -export PACKAGE_ID=$(peer lifecycle chaincode calculatepackageid go-contract-v0.7.2.tgz) && echo $PACKAGE_ID -``` - -Note: the `PACKAGE_ID` must match the chaincode code package identifier shown by the `peer lifecycle chaincode install` command. - -Approve the chaincode. - -```shell -peer lifecycle chaincode approveformyorg -o 127.0.0.1:6050 --channelID mychannel --name sample-contract --version 1 --package-id $PACKAGE_ID --sequence 1 --tls --cafile ${PWD}/crypto-config/ordererOrganizations/example.com/orderers/orderer.example.com/tls/ca.crt -``` - -Commit the chaincode. - -```shell -peer lifecycle chaincode commit -o 127.0.0.1:6050 --channelID mychannel --name sample-contract --version 1 --sequence 1 --tls --cafile "${PWD}"/crypto-config/ordererOrganizations/example.com/orderers/orderer.example.com/tls/ca.crt -``` - -## Running transactions - -Query the chaincode metadata! - -```shell -peer chaincode query -C mychannel -n sample-contract -c '{"Args":["org.hyperledger.fabric:GetMetadata"]}' -``` diff --git a/docs/about/community.md b/docs/about/community.md new file mode 100644 index 0000000..50e6c89 --- /dev/null +++ b/docs/about/community.md @@ -0,0 +1,3 @@ +# Community + +You can find community discussion related to the Kubernetes Builder on the [#fabric-kubernetes](https://discord.com/channels/905194001349627914/945796983795384331) channel on Hyperledger Discord ([invite link](https://discord.gg/hyperledger)). diff --git a/docs/about/intro.md b/docs/about/intro.md new file mode 100644 index 0000000..18f7bda --- /dev/null +++ b/docs/about/intro.md @@ -0,0 +1,21 @@ +# Introduction + +The Kubernetes external [chaincode builder](../../concepts/chaincode-builder) for Hyperledger Fabric (k8s builder) is an alternative to Fabric's legacy built in Docker chaincode builder, which does not work in a Kubernetes deployment, and the preconfigured chaincode-as-a-service builder, which is more suited to chaincode development and test. + +With the k8s builder, the Fabric administrator is responsible for [preparing a chaincode image](../../concepts/chaincode-image), publishing to a container registry, and [preparing a chaincode package](../../concepts/chaincode-package) 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 to communicate securely with the peer. + + +Advantages: + +🚀 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) diff --git a/docs/about/objectives.md b/docs/about/objectives.md new file mode 100644 index 0000000..c4eee94 --- /dev/null +++ b/docs/about/objectives.md @@ -0,0 +1,20 @@ +# Objectives + +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 limitations. +(The assumption being that there are more people with Kubernetes skills than are familiar with the inner workings of Fabric!) + +The two key principles are: + +1. **The contents of the chaincode package must uniquely identify the chaincode functions executed on the ledger:** + In the case of the k8s builder the chaincode source code is not actually inside the package. + In order not to break the Fabric chaincode lifecycle, the chaincode image must be specified using an immutable `@digest`, not `:label` which can be altered post commit. + See [Pull an image by digest (immutable identifier)](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier) for more details. +2. **The Fabric peer manages the chaincode process, not Kubernetes:** + Running the chaincode in server mode, i.e. allowing the peer to initiate the gRPC connection, would make it possible to leave Kubernetes to manage the chaincode process by creating a chaincode deployment. + 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 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. diff --git a/docs/assets/Hyperledger_Fabric.svg b/docs/assets/Hyperledger_Fabric.svg new file mode 100644 index 0000000..3c7c3da --- /dev/null +++ b/docs/assets/Hyperledger_Fabric.svg @@ -0,0 +1,258 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/Hyperledger_Fabric_Icon.svg b/docs/assets/Hyperledger_Fabric_Icon.svg new file mode 100644 index 0000000..69d8da5 --- /dev/null +++ b/docs/assets/Hyperledger_Fabric_Icon.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/docs/assets/Hyperledger_Fabric_White.svg b/docs/assets/Hyperledger_Fabric_White.svg new file mode 100644 index 0000000..3b53a16 --- /dev/null +++ b/docs/assets/Hyperledger_Fabric_White.svg @@ -0,0 +1,258 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/content/assets/project-icon.png b/docs/assets/project-icon.png similarity index 100% rename from docs/content/assets/project-icon.png rename to docs/assets/project-icon.png diff --git a/docs/content/assets/project-logo.png b/docs/assets/project-logo.png similarity index 100% rename from docs/content/assets/project-logo.png rename to docs/assets/project-logo.png diff --git a/docs/concepts/chaincode-builder.md b/docs/concepts/chaincode-builder.md new file mode 100644 index 0000000..0cec7c1 --- /dev/null +++ b/docs/concepts/chaincode-builder.md @@ -0,0 +1,28 @@ +# Chaincode builder + +The k8s builder can be run in cluster using the `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT` environment variables, or it can connect using a `KUBECONFIG_PATH` environment variable. + +The following optional environment variables can be used to configure the k8s builder: + +- `FABRIC_K8S_BUILDER_DEBUG` whether to enable additional logging +- `FABRIC_K8S_BUILDER_NAMESPACE` specifies the namespace to deploy chaincode to +- `FABRIC_K8S_BUILDER_SERVICE_ACCOUNT` specifies the service account for the chaincode pod + +A `CORE_PEER_ID` environment variable is also currently required. + +External builders are configured in the `core.yaml` file, for example: + +``` + externalBuilders: + - name: k8s_builder + path: /opt/hyperledger/k8s_builder + propagateEnvironment: + - CORE_PEER_ID + - FABRIC_K8S_BUILDER_DEBUG + - FABRIC_K8S_BUILDER_NAMESPACE + - FABRIC_K8S_BUILDER_SERVICE_ACCOUNT + - KUBERNETES_SERVICE_HOST + - KUBERNETES_SERVICE_PORT +``` + +See [External Builders and Launchers](https://hyperledger-fabric.readthedocs.io/en/latest/cc_launcher.html) for details of Hyperledger Fabric builders. diff --git a/docs/concepts/chaincode-image.md b/docs/concepts/chaincode-image.md new file mode 100644 index 0000000..a09d68a --- /dev/null +++ b/docs/concepts/chaincode-image.md @@ -0,0 +1,18 @@ +# Chaincode image + +Unlike the traditional chaincode language support for Go, Java, and Node.js, the k8s builder *does not* build a chaincode Docker image using Docker-in-Docker. +Instead, a chaincode Docker image must be built and published before it can be used with the k8s builder. + +The chaincode will have access to the following environment variables: + +- CORE_CHAINCODE_ID_NAME +- CORE_PEER_ADDRESS +- CORE_PEER_TLS_ENABLED +- CORE_PEER_TLS_ROOTCERT_FILE +- CORE_TLS_CLIENT_KEY_PATH +- CORE_TLS_CLIENT_CERT_PATH +- CORE_TLS_CLIENT_KEY_FILE +- CORE_TLS_CLIENT_CERT_FILE +- CORE_PEER_LOCALMSPID + +See the [sample contracts for Go, Java, and Node.js](https://github.com/hyperledger-labs/fabric-builder-k8s/tree/main/samples) for basic docker images which will work with the k8s builder. diff --git a/docs/concepts/chaincode-package.md b/docs/concepts/chaincode-package.md new file mode 100644 index 0000000..400c925 --- /dev/null +++ b/docs/concepts/chaincode-package.md @@ -0,0 +1,77 @@ +# Chaincode package + +The k8s chaincode package file, which is installed by the `peer lifecycle chaincode install` command, must contain the Docker image name and digest of the chaincode being deployed. + +[Fabric chaincode packages](https://hyperledger-fabric.readthedocs.io/en/latest/cc_launcher.html#chaincode-packages) are `.tgz` files which contain two files: + +- metadata.json - the chaincode label and type +- code.tar.gz - source artifacts for the chaincode + +To create a k8s chaincode package file, start by creating an `image.json` file. +For example, + +```shell +cat << IMAGEJSON-EOF > image.json +{ + "name": "ghcr.io/hyperledger-labs/go-contract", + "digest": "sha256:802c336235cc1e7347e2da36c73fa2e4b6437cfc6f52872674d1e23f23bba63b" +} +IMAGEJSON-EOF +``` + +Note: the k8s chaincode package file uses digests because these are immutable, unlike tags. +The docker inspect command can be used to find the digest if required. + +``` +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 +``` + +Create a `code.tar.gz` archive containing the `image.json` file. + +```shell +tar -czf code.tar.gz image.json +``` + +Create a `metadata.json` file for the chaincode package. +For example, + +```shell +cat << METADATAJSON-EOF > metadata.json +{ + "type": "k8s", + "label": "go-contract" +} +METADATAJSON-EOF +``` + +Create the final chaincode package archive. + +```shell +tar -czf go-contract.tgz metadata.json code.tar.gz +``` + +Ideally the chaincode package should be created in the same CI/CD pipeline which builds the docker image. +There is an example [package-k8s-chaincode-action](https://github.com/hyperledgendary/package-k8s-chaincode-action) GitHub Action which can create the required k8s chaincode package. + +The GitHub Action repository includes a basic shell script which can also be used for automating the process above outside GitHub workflows. +For example, to create a basic k8s chaincode package using the `pkgk8scc.sh` helper script. + +```shell +curl -fsSL https://raw.githubusercontent.com/hyperledgendary/package-k8s-chaincode-action/main/pkgk8scc.sh -o pkgk8scc.sh && chmod u+x pkgk8scc.sh +./pkgk8scc.sh -l go-contract -n ghcr.io/hyperledger-labs/go-contract -d sha256:802c336235cc1e7347e2da36c73fa2e4b6437cfc6f52872674d1e23f23bba63b +``` + +## Chaincode deploy + +Deploy the chaincode package as usual, starting by installing the k8s chaincode package. + +```shell +peer lifecycle chaincode install go-contract.tgz +``` + +You can also use the `peer` command to get the chaincode package ID. + +```shell +export PACKAGE_ID=$(peer lifecycle chaincode calculatepackageid go-contract.tgz) && echo $PACKAGE_ID +``` diff --git a/docs/content/index.md b/docs/content/index.md deleted file mode 100644 index 124e420..0000000 --- a/docs/content/index.md +++ /dev/null @@ -1 +0,0 @@ -This page is intentionally left blank. diff --git a/docs/KUBERNETES_CONFIG.md b/docs/getting-started/config.md similarity index 52% rename from docs/KUBERNETES_CONFIG.md rename to docs/getting-started/config.md index 745b6dc..d02a35a 100644 --- a/docs/KUBERNETES_CONFIG.md +++ b/docs/getting-started/config.md @@ -1,72 +1,4 @@ -# 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 <