Merge pull request #2577 from sownak/develop

[fabric] Genesis update and add new channel

docs/source/guides/fabric/add-cli.md

@@ -3,7 +3,7 @@
 [//]: # (SPDX-License-Identifier: Apache-2.0)
 [//]: # (##############################################################################################)
 
-# Add a CLI to Hyperledger Fabric Peer
+# Add CLI to a Peer
 
 This guide explains how to add a CLI to an existing Hyperledger Fabric network using two methods:
 
@@ -57,7 +57,7 @@ This guide explains how to add a CLI to an existing Hyperledger Fabric network u
 
 ## Method 2: Using `helm install`
 
-1. **Update the values.yaml file**
+1. **Update the fabric-cli values.yaml file**
 
 	The `values.yaml` file allows you to configure various aspects of the CLI, including:
 
@@ -74,8 +74,8 @@ This guide explains how to add a CLI to an existing Hyperledger Fabric network u
 
 	Execute the following command to install the CLI chart:
 	```bash
-	helm repo add bevel https://hyperledger.github.io/bevel
-	helm install <release-name> bevel/fabric-cli --namespace <namespace> --values <values-file.yaml>
+	# From platforms/hyperledger-fabric/charts directory
+	helm install <release-name> ./fabric-cli --namespace <namespace> --values <values-file.yaml>
 	```
 	Replace the following placeholders:
 

docs/source/guides/fabric/add-new-channel.md

@@ -3,47 +3,153 @@
 [//]: # (SPDX-License-Identifier: Apache-2.0)
 [//]: # (##############################################################################################)
 
-<a name = "adding-new-channel-to-existing-network-in-fabric"></a>
-# Adding a new channel in Hyperledger Fabric
+# Add a new channel
 
-- [Prerequisites](#prerequisites)
-- [Modifying Configuration File](#modifying-configuration-file)
-- [Run playbook](#run-playbook)
+This guide explains how to add a new channel in a Hyperledger Fabric network using two methods:
 
+1. Using the `add-new-channel.yaml` playbook: This method involves running an Ansible playbook that automates the process of adding a new channel to the network.
+
+1. Using `helm install`: This method involves using the `helm install` commands to directly add a new channel to the network.
 
-<a name = "prerequisites"></a>
 ## Prerequisites
-To add a new channel a fully configured Fabric network must be present already, i.e. a Fabric network which has Orderers, Peers, Channels (with all Peers already in the channels). The corresponding crypto materials should also be present in their respective Hashicorp Vault. 
+- A fully configured Fabric network with Orderers, Peers, Peer Organization.
+- Corresponding crypto materials present in Hashicorp Vault or Kubernetes secrets.
+- Hyperledger Bevel configured.
+
+!!! important
+
+    Do not try to add a new organization as a part of this operation. Use only existing organizations for new channel creation. 
+
+## Method 1: Using the `add-new-channel.yaml` playbook
+
+1. **Update Configuration File**
+
+    - Edit the `network.yaml` file to include a new channel with the following details:
+        - `channel_status: new`
+        - `org_status: existing`
+        - Organization details (name, CA address, MSP ID, etc.)
+		- Orderer information
+    - Remove existing channels or use `channel_status: existing`
+    - Refer to the [networkyaml-fabric.md](../networkyaml-fabric.md) guide for details on editing the configuration file.
+
+    Snippet from `network.channels` section below:
+
+    ```yaml
+    --8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-new-channel.yaml:66:193"
+    ```
+
+    !!! tip
+
+        For reference, see sample [network-fabric-add-channel.yaml](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/configuration/samples/network-fabric-add-new-channel.yaml) file.
+
+1. **Run Playbook**
+
+    Execute the following command to run the `add-new-channel.yaml` playbook:
+
+    ```
+    ansible-playbook platforms/hyperledger-fabric/configuration/add-new-channel.yaml --extra-vars "@path-to-network.yaml"
+    ```
+    Replace `path-to-network.yaml` with the actual path to your updated `network.yaml` file.
+
+	This will add a new channel to the existing Fabric network.
+
+## Method 2: Using `helm install`
+
+1. **Update the fabric-genesis values.yaml file**
+
+    Following changes are must in the `values.yaml` file for a new channel to be added to the network:
 
----
-**NOTE**: Do not try to add a new organization as a part of this operation. Use only existing organization for new channel addition. 
+    - `settings.generateGenesis: false` only needed for Fabric 2.2.x to not generate the syschannel genesis block.
+    - `channels` to include the new channel.
+	- All other fields as required by your new channel.
+    Refer to the [fabric-genesis chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-genesis) for a complete list of available configuration options.
 
----
+1. **Generate the new channel artifacts**
 
-<a name = "create_config_file"></a>
-## Modifying Configuration File
+    First, save the admin MSP and TLS files for the new participants (peers and/or orderers) locally.
+    ```bash
+        # Obtain certificates and the configuration file of each peer organization, place in fabric-genesis/files
+        cd ./platforms/hyperledger-fabric/charts/fabric-genesis/files
+        kubectl --namespace org1-net get secret admin-msp -o json > org2.json
+        kubectl --namespace org1-net get configmap peer0-msp-config -o json > org1-config-file.json
 
-Refer [this guide](../networkyaml-fabric.md) for details on editing the configuration file.
+        #If additional orderer from a different organization is needed in genesis
+        kubectl --namespace orderer-net get secret orderer4-tls -o json > orderer4-orderer-tls.json
+    ```
 
-While modifying the configuration file(`network.yaml`) for adding new channel, all the existing channel should have `channel_status` tag as `existing` and the new channel should have `channel_status` tag as `new` under `network.channels` e.g.
+    Execute the following command to install the Genesis chart to generate the channel artifacts:
+	```bash
+    cd ../..
+	helm dependency update ./fabric-genesis
+	helm install <release-name> ./fabric-genesis --namespace <namespace> --values <values-file.yaml>
+	```
+	Replace the following placeholders:
 
-```yaml
---8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-new-channel.yaml:66:193"
-```
+	- `<release-name>`: The desired name for the channel artifacts release.
+	- `<namespace>`: The Kubernetes namespace where the orderer admins are already present.
+	- `<values-file.yaml>`: The path to a YAML file containing the new channel configuration values from Step 1.
 
-The `network.yaml` file should contain the specific `network.organization` details along with the orderer information.
+1. **Create channel for Hyperledger Fabric 2.5.x**
 
+    Execute the following command to create the channel for Hyperledger Fabric 2.5.x:
+    ```bash
+    # Create channel
+    helm install <new-channel-name> ./fabric-osnadmin-channel-create --namespace <namespace> --values <values-file.yaml>
+    ```
+    Replace the following placeholders:
 
-For reference, see `network-fabric-add-channel.yaml` file [here](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/configuration/samples/network-fabric-add-new-channel.yaml).
+	- `<new-channel-name>`: Release name must be the new channel name.
+	- `<namespace>`: The Kubernetes namespace where `fabric-genesis` was installed.
+	- `<values-file.yaml>`: The path to a YAML file containing the new channel configuration values.
+    Refer to the [fabric-osnadmin-channel-create chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-osnadmin-channel-create) for a complete list of available configuration options.
 
-<a name = "run_network"></a>
-## Run playbook
+    Execute the following command for each Peer which is to join the new Channel:
+    ```bash
+    helm install <release-name> ./fabric-channel-join --namespace <namespace> --values <values-file.yaml>
+    ```
+    Replace the following placeholders:
 
-The [add-new-channel.yaml](https://github.com/hyperledger/bevel/blob/main/platforms/hyperledger-fabric/configuration/add-new-channel.yaml) playbook is used to add a new channel to the existing network. This can be done using the following command
+	- `<release-name>`: The desired name for the join-channel release.
+	- `<namespace>`: The Kubernetes namespace where corresponding peer exists.
+	- `<values-file.yaml>`: The path to a YAML file containing the join-channel configuration values.
+    Refer to the [fabric-channel-join chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-channel-join) for a complete list of available configuration options.
 
-```
-ansible-playbook platforms/hyperledger-fabric/configuration/add-new-channel.yaml --extra-vars "@path-to-network.yaml"
-```
+1. **Create channel for Hyperledger Fabric 2.2.x**
 
----
-**NOTE:** Make sure that the `channel_status` label was set as `new` when the network is deployed for the first time. If you have additional applications, please deploy them as well.
+    Execute the following command to create the channel for Hyperledger Fabric 2.2.x:
+    ```bash
+    # Obtain the file channel.tx and place it in fabric-channel-create/files
+    cd ./fabric-channel-create/files
+    kubectl --namespace <genesis-namespace> get configmap <new-channel-name>-channeltx -o jsonpath='{.data.<new-channel-name>-channeltx_base64}' > channeltx.json
+
+    # Create channel
+    cd ../..
+    helm install <new-channel-name> ./fabric-channel-create --namespace <namespace> --values <values-file.yaml>
+    ```
+    Replace the following placeholders:
+
+	- `<new-channel-name>`: Release name must be the new channel name.
+	- `<genesis-namespace>`: The Kubernetes namespace where `fabric-genesis` was installed.
+    - `<namespace>`: The Kubernetes namespace of the organization creating the new channel.
+	- `<values-file.yaml>`: The path to a YAML file containing the new channel configuration values.
+    Refer to the [fabric-channel-create chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-channel-create) for a complete list of available configuration options.
+
+
+    Execute the following command for each Peer which is to join the new Channel:
+    ```bash
+    cd ./fabric-channel-join/files
+    kubectl --namespace <genesis-namespace> get configmap <new-channel-name>-<participant-name>-anchortx -o jsonpath='{.data.<new-channel-name>-<participant-name>-anchortx_base64}' > anchortx.json
+
+    # Join channel
+    cd ../..
+    helm install <release-name> ./fabric-channel-join --namespace <namespace> --values <values-file.yaml>
+    ```
+    Replace the following placeholders:
+
+    - `<new-channel-name>`: Release name must be the new channel name.
+	- `<genesis-namespace>`: The Kubernetes namespace where `fabric-genesis` was installed.
+    - `<participant-name>`: The participating organization name.
+	- `<release-name>`: The desired name for the join-channel release.
+	- `<namespace>`: The Kubernetes namespace where corresponding peer exists.
+	- `<values-file.yaml>`: The path to a YAML file containing the join-channel configuration values.
+    Refer to the [fabric-channel-join chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-channel-join) for a complete list of available configuration options.

docs/source/guides/fabric/add-new-peer.md

@@ -3,9 +3,10 @@
 [//]: # (SPDX-License-Identifier: Apache-2.0)
 [//]: # (##############################################################################################)
 
-# Add a new peer to an existing Hyperledger Fabric organization
+# Add a new peer to an existing organization
+
+This guide explains how to add a new **general** (non-anchor) peer to an existing organization in a Hyperledger Fabric network using two methods:
 
-This guide explains how to add a new general (non-anchor) peer to an existing organization in a Hyperledger Fabric network using two methods:
 1. Using the `add-peer.yaml` playbook: This method involves running an Ansible playbook that automates the process of adding a new peer to the network.
 
 1. Using `helm install`: This method involves using the `helm install` commands to directly add a new peer to the network.
@@ -35,7 +36,7 @@ This guide explains how to add a new general (non-anchor) peer to an existing or
         - `org_status: existing`
 		- Organization details (name, CA address, MSP ID, etc.)
 		- Orderer information, if you are going to install/upgrade the existing chaincodes.
-	  - Existing peer(s) should have `peerstatus: existing`
+	- Existing peer(s) should have `peerstatus: existing`
     - Refer to the [networkyaml-fabric.md](../networkyaml-fabric.md) guide for details on editing the configuration file.
 
     Snippet from `network.channels` section below:
@@ -71,7 +72,7 @@ This guide explains how to add a new general (non-anchor) peer to an existing or
 
 ## Method 2: Using `helm install`
 
-1. **Update the Peer values.yaml file**
+1. **Update the fabric-peernode values.yaml file**
 
     Following changes are must in the `values.yaml` file for a new peer to be added to the network:
 
@@ -82,38 +83,59 @@ This guide explains how to add a new general (non-anchor) peer to an existing or
     Refer to the [fabric-peernode chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-peernode) for a complete list of available configuration options.
 
 1. **Install the fabric-peernode chart**
+
+    Ensure the Orderer tls certificate is in `fabric-peernode/files`
+
+    ```bash
+    # Get the orderer.crt from Kubernetes
+    cd ./platforms/hyperledger-fabric/charts/fabric-peernode/files
+    kubectl --namespace supplychain-net get configmap orderer-tls-cacert -o jsonpath='{.data.cacert}' > orderer.crt
+    ```
 
     Execute the following command to install the Peer chart:
 	```bash
-	helm repo add bevel https://hyperledger.github.io/bevel
-	helm install <release-name> bevel/fabric-peernode --namespace <namespace> --values <values-file.yaml>
+    cd ../..
+	helm dependency update ./fabric-peernode
+	helm install <release-name> ./fabric-peernode --namespace <namespace> --values <values-file.yaml>
 	```
 	Replace the following placeholders:
 
 	- `<release-name>`: The desired name for the Peer release.
 	- `<namespace>`: The Kubernetes namespace where the Peer should be deployed.
 	- `<values-file.yaml>`: The path to a YAML file containing the new peer configuration values.
 
-1. **Join the channel**
+1. **Update the fabric-channel-join values.yaml file**
 
     After the peer has started, we need to join the channel. The channel should already exist in the network.
+    Following changes are must in the `values.yaml` file for a new peer to join an existing channel:
+
+    - `peer.name: <new peer name>`
+	- `peer.type: general`
+	- `peer.address: <new peer address>`
+    - `peer.localMspId: <existing org MSP>`
+    - `peer.channelName: <existing channel name>`
+    - `peer.ordererAddress: <existing orderer grpc address>` the Orderer Address to which the peer should connect.
+
+    Refer to the [fabric-channel-join chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-channel-join) for a complete list of available configuration options.
+
+1. **Join the channel**
 
     Execute the following command to join the channel:
 	```bash
-	helm repo add bevel https://hyperledger.github.io/bevel
-	helm install <release-name> bevel/fabric-channel-join --namespace <namespace> --values <values-file.yaml>
+	# From platforms/hyperledger-fabric/charts directory
+	helm install <release-name> ./fabric-channel-join --namespace <namespace> --values <values-file.yaml>
 	```
 	Replace the following placeholders:
 
 	- `<release-name>`: The desired name for the join channel release.
 	- `<namespace>`: The Kubernetes namespace must be same as the namespace of the Peer release.
-	- `<values-file.yaml>`: The path to a YAML file containing the join channel configuration values.
-
-    Refer to the [fabric-channel-join chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-channel-join) for a complete list of available configuration options.
+	- `<values-file.yaml>`: The path to a YAML file containing the updated join channel configuration values.
 
 ## Additional Notes
+
+- The `peerstatus` is _optional_ when the network is deployed for the first time but is _mandatory_ for addition of new peer.
 
--  The `peerstatus` is _optional_ when the network is deployed for the first time but is _mandatory_ for addition of new peer.
+- Currently, only a `general` or non-anchor peer can be added.
 
 - Chaincode Installation: Use the same `network.yaml` if you need to install chaincode on the new peers.
 

platforms/hyperledger-fabric/charts/fabric-channel-join/templates/join_channel.yaml

@@ -12,6 +12,7 @@ metadata:
   annotations:
     "helm.sh/hook": post-install
     "helm.sh/hook-weight": "0"
+    "helm.sh/hook-delete-policy": "before-hook-creation"
   labels:
     app.kubernetes.io/name: channel-join-{{ .Release.Name }}
     app.kubernetes.io/component: fabric-channel-join-job

platforms/hyperledger-fabric/charts/fabric-genesis/README.md

@@ -122,6 +122,7 @@ List of Channels you want to create the artifacts for.
 
 | Name   | Description  | Default Value |
 |--------|---------|-------------|
+| `settings.generateGenesis` |  Flag to generate the syschannel genesis for Fabric 2.2.x | `true` |
 | `settings.removeConfigMapOnDelete` |  Flag to delete the genesis ConfigMap when uninstalling the release | `true` |
 
 ## License

platforms/hyperledger-fabric/charts/fabric-genesis/templates/genesis-job-cleanup.yaml

@@ -2,9 +2,9 @@
 apiVersion: batch/v1
 kind: Job
 metadata:
-  name: {{ include "fabric-genesis.name" . }}-cleanup
+  name: {{ .Release.Name }}-cleanup
   labels:
-    app.kubernetes.io/name: fabric-genesis-job-cleanup
+    app.kubernetes.io/name: {{ .Release.Name }}-cleanup
     app.kubernetes.io/component: genesis-job-cleanup
     app.kubernetes.io/part-of: {{ include "fabric-genesis.fullname" . }}
     app.kubernetes.io/namespace: {{ .Release.Namespace }}
@@ -20,7 +20,7 @@ spec:
   template:
     metadata:
       labels:
-        app.kubernetes.io/name: fabric-genesis-job-cleanup
+        app.kubernetes.io/name: {{ .Release.Name }}-cleanup
         app.kubernetes.io/component: genesis-job-cleanup
         app.kubernetes.io/part-of: {{ include "fabric-genesis.fullname" . }}
         app.kubernetes.io/namespace: {{ .Release.Namespace }}