Skip to content

Commit

Permalink
Loading
Loading status checks…
Merge pull request #2596 from hyperledger/develop
Browse files Browse the repository at this point in the history 
[chore] release 1.1 merge
@sownak
sownak authored Jul 4, 2024

Unverified

No user is associated with the committer email.
Learn about vigilant mode
2 parents 2cb4d29 + d5efd51 commit c62e8fe
Showing 995 changed files with 31,593 additions and 48,164 deletions.
162 changes: 162 additions & 0 deletions .github/workflows/aws_corda_deploy.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
##############################################################################################
# Copyright Accenture. All Rights Reserved.
#
# SPDX-License-Identifier: Apache-2.0
##############################################################################################

##############################################################################################
# Workflow: Deploy Hyperledger Bevel's CORDA DLT Platform to an EKS Cluster.

# Prerequisites:
# 1. An accessible EKS Cluster
# 2. A Vault instance accessible from GitHub Runner
# 3. A completed network.yaml file stored in GitHub Secrets

# Workflow Overview:
# 1. This GitHub Actions workflow automates the seamless deployment of "BEVEL's CORDA" platform to an EKS cluster.
# 2. Utilizing secure environment variables, the workflow manages sensitive information related to AWS, Docker, Cluster, Vault, and Git.
# 3. The workflow dynamically customizes a network configuration file by substituting placeholders with values derived from environment variables.
# 4. It uses tool Ansible to deploy the platform.
##############################################################################################

# Name of the workflow
name: Deploy or Reset Corda Network to an EKS Cluster

# Triggers for the workflow
on:
# Manually trigger the workflow through the GitHub Actions UI
workflow_dispatch:
inputs:
action:
description: 'Choose action: Deploy or Reset'
required: true
default: 'deploy'
type: choice
options:
- 'deploy'
- 'reset'
paths-ignore:
- 'docs/**'
- '**/charts/**'
- '**/releases/**'

# Jobs to be executed
jobs:
deployment:
runs-on: ubuntu-latest
permissions:
contents: write
environment: Bevel-AWS-Deployment
env:
AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}" # AWS Access Key ID
AWS_SECRET_ACCESS_KEY: "${{ secrets.AWS_SECRET_ACCESS_KEY }}" # AWS Secret Access Key
AWS_REGION: "${{ secrets.AWS_REGION }}" # EKS cluster zone
CLUSTER_CONTEXT: "${{ secrets.CLUSTER_CONTEXT }}" # Context name for the EKS cluster
KUBECONFIG: "${{ secrets.ENCODED_KUBECONFIG }}" # Provide Kubernetes configuration file in encoded base64 format
DOCKER_URL: "${{ secrets.DOCKER_URL }}" # URL of the Docker registry
DOCKER_USERNAME: "${{ secrets.DOCKER_USERNAME }}" # Docker registry username
DOCKER_PASSWORD: "${{ secrets.DOCKER_PASSWORD }}" # Docker registry password
EXTERNAL_URL_SUFFIX: "${{ secrets.EXTERNAL_URL_SUFFIX }}" # Suffix for external URLs
GIT_USER_NAME: "${{ secrets.GIT_USER_NAME }}" # Git username for Git operations
GIT_EMAIL_ADDR: "${{ secrets.GIT_EMAIL_ADDR }}" # Git email address for Git operations
GIT_TOKEN: "${{ secrets.GIT_TOKEN }}" # Git token with required permissions for authentication
GIT_BRANCH: "${{ vars.GIT_BRANCH }}" # Git branch to be used in the deployment
GIT_PRIVATE_SSH_KEY: "${{ secrets.GIT_PRIVATE_SSH_KEY }}" # Private SSH key for Git authentication in encoded base64 format
VAULT_ADDR: "${{ secrets.VAULT_ADDR }}" # Vault Server DNS name
VAULT_TOKEN: "${{ secrets.VAULT_TOKEN }}" # Token for authentication with Vault

# Steps to be executed within the job
steps:
# Checkout the repository code
- name: Checkout Repository
uses: actions/[email protected]

# Java installation
- name: Install java
uses: actions/setup-java@v2
with:
distribution: 'adopt'
java-version: '8'

# Configure AWS credentials
- name: AWS Setup
uses: aws-actions/configure-aws-credentials@v2
with:
aws-access-key-id: "${{ env.AWS_ACCESS_KEY_ID }}"
aws-secret-access-key: "${{ env.AWS_SECRET_ACCESS_KEY }}"
aws-region: "${{ env.AWS_REGION }}"

# Set up BEVEL's Corda network configuration file
- name: BEVEL's Corda Network Configuration file Setup
run: |
# Prepare network configuration file for deployment
mkdir -p build/
cp "./platforms/r3-corda/configuration/samples/workflow/network-proxy-corda.yaml" "build/network-corda.yaml"
NETWORK_CONF_FILE="build/network-corda.yaml"
# Decode and store private SSH key
echo "${{ env.GIT_PRIVATE_SSH_KEY }}" | base64 --decode > /home/runner/private_ssh_key
# Define placeholder values for the network configuration file
declare -A placeholders=(
["NETWORK_VERSION"]="4.9"
["FLUX_SUFFIX"]="corda"
["PORT_RANGE_FROM"]=15010
["PORT_RANGE_TO"]=15090
["DOCKER_URL"]="${{ env.DOCKER_URL }}"
["DOCKER_USERNAME"]="${{ env.DOCKER_USERNAME }}"
["DOCKER_PASSWORD"]="${{ env.DOCKER_PASSWORD }}"
["USER_DIRECTORY"]="$(pwd)"
["EXTERNAL_URL_SUFFIX"]="${{ env.EXTERNAL_URL_SUFFIX }}"
["AWS_ACCESS_KEY"]="${{ env.AWS_ACCESS_KEY_ID }}"
["AWS_SECRET_KEY"]="${{ env.AWS_SECRET_ACCESS_KEY }}"
["AWS_REGION"]="${{ env.AWS_REGION}}"
["CLUSTER_CONTEXT"]="${{ env.CLUSTER_CONTEXT }}"
["CLUSTER_CONFIG"]="/home/runner/.kube/build_config/kubeconfig"
["VAULT_ADDR"]="${{ env.VAULT_ADDR }}"
["VAULT_ROOT_TOKEN"]="${{ env.VAULT_TOKEN }}"
["GIT_USERNAME"]="${{ env.GIT_USER_NAME }}"
["GIT_TOKEN"]="${{ env.GIT_TOKEN }}"
["GIT_EMAIL_ADDR"]="${{ env.GIT_EMAIL_ADDR }}"
["GIT_BRANCH"]="${{ env.GIT_BRANCH }}"
["PRIVATE_KEY_PATH"]="/home/runner/private_ssh_key"
)
# Replace placeholders in the network configuration file
for placeholder in "${!placeholders[@]}"; do
sed -i "s#${placeholder}#${placeholders[$placeholder]}#g" "$NETWORK_CONF_FILE"
done
# Deploy BEVEL's Corda Platform
- name: Deploy BEVEL's Corda Platform
run: |
# Setup Kubernetes configuration
mkdir -p /home/runner/.kube/build_config
echo "${{ env.KUBECONFIG }}" | base64 --decode > /home/runner/.kube/build_config/kubeconfig
export KUBECONFIG="/home/runner/.kube/build_config/kubeconfig"
# Configure Git user settings
git config --global user.email "${{ env.GIT_EMAIL_ADDR }}"
git config --global user.name "${{ env.GIT_USER_NAME }}"
# Install required tools and Ansible collections
mkdir -p ~/bin
export PATH=$PATH:~/bin
pip3 install openshift=='0.13.1'
pip install ansible jmespath jinja2-time
ansible-galaxy collection install -r platforms/shared/configuration/requirements.yaml
# Set reset variable
if [ "${{ github.event.inputs.action }}" == "reset" ]; then
reset=true
else
reset=false
fi
# Deploy the BEVEL's corda DLT platform
ansible-playbook platforms/shared/configuration/site.yaml \
-i platforms/shared/inventory/ansible_provisioners \
-e @build/network-corda.yaml \
-e 'ansible_python_interpreter=/usr/bin/python3' -e "reset=$reset"
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -40,4 +40,5 @@
*_custom.tpl
**/charts/*.tgz
**/files/*.json
**/files/*.crt
requirements.lock
4 changes: 4 additions & 0 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
@@ -50,6 +50,10 @@ RUN rm /etc/apt/apt.conf.d/docker-clean
RUN mkdir /etc/ansible/
RUN /bin/echo -e "[ansible_provisioners:children]\nlocal\n[local]\nlocalhost ansible_connection=local" > /etc/ansible/hosts

RUN curl -LO https://storage.googleapis.com/kubernetes-release/release/v1.27.0/bin/linux/amd64/kubectl
RUN chmod +x ./kubectl
RUN mv ./kubectl /usr/local/bin

# Install krew for bevel-operator-fabric
RUN (set -x; cd "$(mktemp -d)" && \
OS="$(uname | tr '[:upper:]' '[:lower:]')" && \
10 changes: 5 additions & 5 deletions Dockerfile.jdk8
View file
Original file line number Diff line number Diff line change
@@ -3,13 +3,11 @@
#
# SPDX-License-Identifier: Apache-2.0
##############################################################################################

# USAGE:
# docker build . -t bevel-build
# docker run -v $(pwd):/home/bevel/ bevel-build

FROM ubuntu:20.04

# Create working directory
WORKDIR /home/
ENV OPENSHIFT_VERSION='0.13.1'
@@ -37,13 +35,17 @@ RUN apt-get update && apt-get install -y \
apt-get clean && \
ln -s /usr/bin/python3 /usr/bin/python && \
rm -rf /var/lib/apt/lists/*
RUN npm install -g ajv-cli
RUN npm install -g ajv-cli
RUN apt-get update && apt-get install -y python3-venv

RUN rm /etc/apt/apt.conf.d/docker-clean
RUN mkdir /etc/ansible/
RUN /bin/echo -e "[ansible_provisioners:children]\nlocal\n[local]\nlocalhost ansible_connection=local" > /etc/ansible/hosts

RUN curl -LO https://storage.googleapis.com/kubernetes-release/release/v1.27.0/bin/linux/amd64/kubectl
RUN chmod +x ./kubectl
RUN mv ./kubectl /usr/local/bin

# Copy the provisional script to build container
COPY ./run.sh /home
COPY ./reset.sh /home
@@ -58,6 +60,4 @@ ENV PATH=/root/bin:/root/.local/bin/:$PATH

#path to mount the repo
VOLUME /home/bevel/


CMD ["/home/run.sh"]
87 changes: 55 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -16,74 +16,97 @@
- [Hyperledger Indy](#hyperledger-indy)
- [Quorum](#quorum)
- [Hyperledger Besu](#hyperledger-besu)
- [Substrate](#substrate)
- [Contact](#contact)
- [Contributing](#contributing)
- [Initial Committers](#initial-committers)
- [Sponsor](#sponsor)

## Short Description
An automation framework for rapidly and consistently deploying production-ready Distributed Ledger Technology (DLT) platforms.
An automation framework and helm charts for rapidly and consistently deploying production-ready Distributed Ledger Technology (DLT) platforms.

## Scope of Project
Hyperledger Bevel delivers an automation framework for rapidly and consistently deploying production-ready DLT platforms to cloud infrastructure.
Hyperledger Bevel is an automation framework for rapidly and consistently deploying production-ready DLT platforms to cloud infrastructure.

![What is Hyperledger Bevel?](./docs/images/hyperledger-bevel-overview.png "What is Hyperledger Bevel?")

Hyperledger Bevel is an accelerator/tool that helps developers rapidly set up and deploy secure, scalable and production-ready DLT network(s) that also allows new organizations to be easily on-boarded on the network. Bevel facilitates a safe and secure way of deploying and operating different DLT platforms.

It includes:
- Helm charts to deploy different DLT nodes and to generate the related crypto/identities.
- Helm charts for various operational features like adding new nodes, and deploying smart contracts.
- Helm charts to deploy Hyperledger Cacti connectors for Fabric, Quorum and Besu networks.
- Ansible playbooks and modular role definitions to automate the deployment of Helm charts.
- Ansible playbooks and roles to automate deployment of Hyperledger fabric using bevel-operator-fabric(Kubernetes operator for managing Hyperledger Fabric networks).
- Integrated CD using GitOps so that once the network is set up, all changes can be done via git PRs/merges.
- Configuration for Ambassador Edge Stack, HAProxy (for Hyperledger Fabric) and Isto Ingress (for Substrate) to act as Ingress Controller.
- Helm charts to **deploy** different DLT nodes and to generate the related crypto/identities.
- Helm charts for various **operational features** like adding new nodes, and deploying smart contracts.
- Helm charts to deploy Hyperledger **Cacti connectors** for Fabric, Quorum and Besu networks.
- **Ansible playbooks** and modular role definitions to automate the deployment of Helm charts.
- Ansible playbooks and roles to automate deployment of Hyperledger fabric using **bevel-operator-fabric** (Kubernetes operator for managing Hyperledger Fabric networks).
- Integrated CD using **GitOps** so that once the network is set up, all changes can be done via git PRs/merges.
- Configuration for Ambassador Edge Stack, HAProxy (for Hyperledger Fabric) and Istio Ingress (for Substrate) to act as Ingress Controller.

Hyperledger Bevel currently supports R3 Corda OS and Enterprise, Hyperledger Fabric, Hyperledger Indy, Hyperledger Besu, Quorum and Substrate. Other DLT platforms can easily be added.

### Getting Started
## Getting Started

To get started with the framework quickly, follow our [Getting Started guidelines](https://hyperledger-bevel.readthedocs.io/en/latest/gettingstarted.html).

Detailed operator and developer documentation is available on [our ReadTheDocs site](https://hyperledger-bevel.readthedocs.io/en/latest/index.html).

The documentation can also be built locally be following instructions in the `docs` folder.

### Hyperledger Fabric
For Hyperledger Fabric, we use the official Docker containers provided by that project. A number of different Ansible scripts will allow you to either create a new network (across clouds) or join an existing network.
## Hyperledger Fabric
For Hyperledger Fabric, there are two ways to deploy the network.

![Hyperledger Bevel - Fabric](./docs/images/hyperledger-bevel-fabric.png "Hyperledger Bevel for Hyperledger Fabric")
- Using `helm install`: Follow the [Fabric Charts readme](./platforms/hyperledger-fabric/charts/README.md).
- Using Ansible: A number of different Ansible scripts will allow you to either create a new network (across clouds) or join an existing network.

### Corda Enterprise
For Corda Enterprise, we build Docker containers from the Corda source with licensed jars. A number of different Ansible scripts will allow you to either create a new network (across clouds) or join an existing network.
![Hyperledger Bevel - Fabric](./docs/images/hyperledger-bevel-fabric.png "Hyperledger Bevel for Hyperledger Fabric")

![Hyperledger Bevel - Corda Enterprise](./docs/images/hyperledger-bevel-corda-ent.png "Hyperledger Bevel for Corda Enterprise")
## Corda Enterprise
For Corda Enterprise, there are two ways to deploy the network.

### Corda Opensource
For Corda Opensource, we build Docker containers from the Corda source. A number of different Ansible scripts will allow you to either create a new network (across clouds) or join an existing network.
- Using `helm install`: Follow the [Corda Enterprise Charts readme](./platforms/r3-corda-ent/charts/README.md).
- Using Ansible: A number of different Ansible scripts will allow you to either create a new network (across clouds) or join an existing network.

![Hyperledger Bevel - Corda](./docs/images/hyperledger-bevel-corda.png "Hyperledger Bevel for Corda")
![Hyperledger Bevel - Corda Enterprise](./docs/images/hyperledger-bevel-corda-ent.png "Hyperledger Bevel for Corda Enterprise")

### Hyperledger Indy
For Hyperledger Indy, we build Docker containers from our source code. A number of different Ansible scripts will allow you to create a new network (across clouds).
## Corda Opensource
For Corda Opensource, there are two ways to deploy the network.

- Using `helm install`: Follow the [Corda Charts readme](./platforms/r3-corda/charts/README.md).
- Using Ansible: A number of different Ansible scripts will allow you to either create a new network (across clouds) or join an existing network.

![Hyperledger Bevel - Corda](./docs/images/hyperledger-bevel-corda.png "Hyperledger Bevel for Corda")

## Hyperledger Indy
For Hyperledger Indy, there are two ways to deploy the network.

- Using `helm install`: Follow the [Indy Charts readme](./platforms/hyperledger-indy/charts/README.md).
- Using Ansible: A number of different Ansible scripts will allow you to create a new network (across clouds).

![Hyperledger Bevel - Indy](./docs/images/hyperledger-bevel-indy.png "Hyperledger Bevel for Hyperledger Indy")

### Quorum
For Quorum, we use the official Docker containers provided by Quorum. A number of different Ansible scripts will allow you to either create a new network (across clouds) with choice of Consensus (between IBFT and RAFT) and a transaction Manager.
## Quorum
For Quorum, there are two ways to deploy the network.

- Using `helm install`: Follow the [Quorum Charts readme](./platforms/quorum/charts/README.md).
- Using Ansible: A number of different Ansible scripts will allow you to either create a new network (across clouds) with choice of Consensus and a transaction Manager.

![Hyperledger Bevel - Quorum](./docs/images/hyperledger-bevel-quorum.png "Hyperledger Bevel for Quorum")

## Hyperledger Besu
For Hyperledger Besu, there are two ways to deploy the network.

- Using `helm install`: Follow the [Besu Charts readme](./platforms/hyperledger-besu/charts/README.md).
- Using Ansible: A number of different Ansible scripts will allow you to create a new network (across clouds).

![Hyperledger Bevel - Quorum](./docs/images/hyperledger-bevel-quorum.png "Hyperledger Bevel for Quorum")
![Hyperledger Bevel - Besu](./docs/images/hyperledger-bevel-besu.png "Hyperledger Bevel for Hyperledger Besu")

### Hyperledger Besu
For Hyperledger Besu, we use the official Docker containers provided by that project. A number of different Ansible scripts will allow you to create a new network (across clouds).
## Substrate
For Substrate, there are two ways to deploy the network.

![Hyperledger Bevel - Besu](./docs/images/hyperledger-bevel-besu.png "Hyperledger Bevel for Hyperledger Besu")
- Using `helm install`: Follow the [Substrate Charts readme](./platforms/substrate/charts/README.md).
- Using Ansible: A number of different Ansible scripts will allow you to create a new network (across clouds).

### Substrate
For Substrate, we use the official Docker containers provided by that project. A number of different Ansible scripts will allow you to create a new network (across clouds).
![Hyperledger Bevel - Substrate](./docs/images/hyperledger-bevel-substrate.png "Hyperledger Bevel for Substrate")

![Hyperledger Bevel - Substrate](./docs/images/hyperledger-bevel-substrate.png "Hyperledger Bevel for Substrate")
## Contact
We welcome your questions & feedback on our [Discord channel](https://discord.com/channels/905194001349627914/941739691336679454). [Please join our Discord first](https://discord.gg/hyperledger).

@@ -92,8 +115,8 @@ We welcome contributions to Hyperledger Bevel in many forms, and there’s alway

Please review [contributing](./CONTRIBUTING.md) guidelines to get started.

# Build
If you are not using the provided Jenkins automation scripts, you can run the provisioning scripts within a docker runtime independent from your target Kubernetes cluster.
## Build
If you are not using the provided Jenkins automation scripts, you can run the provisioning scripts within a docker runtime independent of your target Kubernetes cluster.
```
# Build provisioning image
docker build . -t ghcr.io/hyperledger/bevel-build
7 changes: 3 additions & 4 deletions docs/mkdocs.yml
View file
Original file line number Diff line number Diff line change
@@ -92,18 +92,18 @@ nav:
- Concepts:
- Sequence Diagram: concepts/sequence-diagram.md
- Features: concepts/features.md
- Ansible: concepts/ansible.md
- Gitops: concepts/gitops.md
- Helm: concepts/helm.md
- Kubernetes: concepts/kubernetes.md
- Ansible: concepts/ansible.md
- Gitops: concepts/gitops.md
- Vault: concepts/vault.md
- Getting Started:
- Pre-requisites: getting-started/prerequisites.md
- Ansible Contoller: getting-started/prerequisites-machine.md
- Configure pre-requisites: getting-started/configure-prerequisites.md
- Running: getting-started/run-bevel.md
- Tutorials:
- Tutorial List: tutorials/index.md
- Tutorials: tutorials/index.md
- Developer pre-requisites: tutorials/dev-prereq.md
- Deploy using Docker: tutorials/docker-deploy.md
- Deploy using Machine: tutorials/machine-deploy.md
@@ -136,7 +136,6 @@ nav:
- guides/fabric/upgrade-network-1.4.x-2.2.x.md
- guides/fabric/upgrade-network.md
- Corda Operations:
- guides/corda/add-cenm-console.md
- guides/corda/add-cordapps.md
- guides/corda/add-new-notary.md
- guides/corda/add-new-org.md
Binary file removed docs/source/_static/NetworkYamlFabric1.png
View file
Binary file not shown.
6 changes: 5 additions & 1 deletion docs/source/concepts/ansible.md
View file
Original file line number Diff line number Diff line change
@@ -3,10 +3,14 @@
[//]: # (SPDX-License-Identifier: Apache-2.0)
[//]: # (##############################################################################################)

# **Ansible**
# Ansible

[Ansible](https://docs.ansible.com/ansible/latest/index.html) is an open-source automation tool that simplifies the process of managing IT infrastructure and automating repetitive tasks. It is designed to make complex configuration and deployment processes easier, faster, and more consistent. Ansible is agentless, meaning it doesn't require any software to be installed on the managed hosts, making it lightweight and easy to set up.

!!! tip

With 1.1 Release, Ansible is optional and can be used only for large deployment automation.

With Ansible, you can define your infrastructure as code using simple, human-readable YAML files called "playbooks." Playbooks describe the desired state of your systems, specifying which tasks should be performed and in what order. These tasks can range from simple tasks like copying files or installing packages to more complex tasks like configuring services or managing cloud resources.

Here's how Ansible works in a nutshell:
10 changes: 8 additions & 2 deletions docs/source/concepts/features.md
View file
Original file line number Diff line number Diff line change
@@ -19,14 +19,20 @@ The setup of a Distributed Ledger Technology (DLT) network doesn't hinge on mana
## One touch/command deployment
With just one Ansible playbook — aptly named [site.yaml](https://github.com/hyperledger/bevel/tree/main/platforms/shared/configuration/site.yaml), you can orchestrate the creation of an entire Distributed Ledger Technology (DLT) network. Brace yourself for efficiency gains as this streamlined process significantly slashes the time typically spent configuring and managing the network components of Corda, Besu, Fabric or other supported DLT networks.

## Security through Vault
In the realm of identity-based security, HashiCorp Vault takes centre stage within Hyperledger Bevel. Especially in the complex terrain of managing secrets across multiple clouds, the dynamic capabilities of HashiCorp Vault shine through. With Vault at its core, Hyperledger Bevel ensures the secure storage and precise control of access to critical elements like tokens, passwords, certificates, and encryption keys. This robust approach safeguards machines, applications, and sensitive data within a multi-cloud environment.
## Security through Vault (Optional)
In the realm of identity-based security, HashiCorp Vault takes centre stage within Hyperledger Bevel. Especially in the complex terrain of managing secrets across multiple clouds, the dynamic capabilities of HashiCorp Vault shine through. With Vault at its core, Hyperledger Bevel ensures the secure storage and precise control of access to critical elements like tokens, passwords, certificates, and encryption keys. This robust approach safeguards machines, applications, and sensitive data within a multi-cloud environment. Now **optional** for development environments.

## Sharing a Network.yaml file without disclosing any confidentiality
Unlocking a new level of efficiency, Hyperledger Bevel empowers organizations to initiate a Distributed Ledger Technology (DLT) or Blockchain network swiftly. Leveraging a configured [network.yaml](../guides/networkyaml-fabric.md) file, the setup process is not only streamlined but sets the stage for seamless collaboration.

Here's the game-changer: this [network.yaml](../guides/networkyaml-fabric.md) file can be easily shared with new organizations looking to join the DLT/Blockchain network. The brilliance lies in the ability to reuse this file without compromising the confidentiality of the initial organization's sensitive data.

## Helm Chart Support
Simplifies deployment of DLT networks with Helm charts. Specially for development environments, only `helm install` commands can be used to setup a DLT network in few minutes.

## GitOps Optionality
Provides flexibility by making GitOps deployment optional for development environments. This gives the developers a faster access to the DLT environment without the complexities of configuring GitOps.

## How is it different from other BaaS?
- Hyperledger Bevel deployment scripts can be reused across cloud providers like AWS, Azure, GCP, DigitalOcean and OpenShift
- Can deploy networks and smart contracts across different DLT/Blockchain platforms
4 changes: 4 additions & 0 deletions docs/source/concepts/gitops.md
View file
Original file line number Diff line number Diff line change
@@ -7,6 +7,10 @@

[GitOps](https://www.weave.works/technologies/gitops/) is a modern approach to managing and deploying applications in Kubernetes clusters. It leverages the version control system Git as the source of truth for defining the desired state of your infrastructure and applications. Flux is a popular tool used to implement GitOps workflows, enabling automatic synchronization of changes from Git repositories to Kubernetes clusters.

!!! tip

With 1.1 Release, GitOps is optional for small development environments.

## Features

1. Source of Truth: In GitOps, the Git repository serves as the single source of truth for your infrastructure and application configurations. All desired states are declared and versioned in Git.
4 changes: 2 additions & 2 deletions docs/source/concepts/sequence-diagram.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Bevel Sequence Diagram

It is important to understand the sequence and flow for Bevel as this will determine how you confgure your networking.
When using Ansible automation in Bevel, it is important to understand the sequence and flow as this will determine how you confgure your networking.

!!! tip

Do not use 127.0.0.1 or localhost to configure any services like Kubernetes or Vault
Do not use 127.0.0.1 or localhost to configure any services like Kubernetes or Vault.

``` mermaid
sequenceDiagram
4 changes: 4 additions & 0 deletions docs/source/concepts/vault.md
View file
Original file line number Diff line number Diff line change
@@ -7,6 +7,10 @@

[HashiCorp Vault](https://www.vaultproject.io/) is an open-source tool designed to manage secrets and protect sensitive data in modern computing environments. It provides a secure and centralized way to store, access, and distribute secrets such as passwords, API keys, encryption keys, and other confidential information. Vault is especially useful in cloud-native and distributed systems where securing secrets is crucial.

!!! tip

With 1.1 Release, Hahsicorp Vault is optional for development environments, and Cloud KMS integration is on the roadmap.

Hyperledger Bevel relies on Hashicorp Vault for managing all secrets like public and private certificates, passwords to repos or databases etc. which are used in a DLT/Blockchain network during the lifecycle of a deployment, and it is a prerequisite that the Vault is installed and unsealed prior to deployment of a DLT/Blockchain network.

## Core Features
10 changes: 3 additions & 7 deletions docs/source/getting-started/configure-prerequisites.md
View file
Original file line number Diff line number Diff line change
@@ -6,10 +6,9 @@
# Configure Common Pre-requisites

- [GitOps Authentication](#gitops-authentication)
- [Vault Initialization and unseal](#vaultunseal)
- [Docker Images](#docker)
- [Unseal Hashicorp Vault](#unseal-hashicorp-vault)
- [Docker Images](#docker-images)

<a name = "gitops-authentication"></a>
## GitOps Authentication

For synchronizing the Git repo with the cluster, Hyperledger Bevel configures Flux for each cluster. The authentication can be via SSH or HTTPS.
@@ -34,7 +33,6 @@ The above command generates an SSH key-pair: **gitops** (private key) and **gito

And add the public key contents (starts with **ssh-rsa**) as an Access Key (with read-write permissions) in your Github repository by following [this guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).

<a name = "vaultunseal"></a>
## Unseal Hashicorp Vault

The [Hashicorp Vault](../concepts/vault.md) must be initialised and unsealed. Complete the following steps to unseal and access the Vault.
@@ -43,7 +41,7 @@ The [Hashicorp Vault](../concepts/vault.md) must be initialised and unsealed. Co

!!! important

Vault version should be > **1.13.1**
Vault version should be > **1.13.1** and <= **1.15.2**

* Set the environment Variable **VAULT_ADDR** as the Vault service.

@@ -83,8 +81,6 @@ The [Hashicorp Vault](../concepts/vault.md) must be initialised and unsealed. Co
It is recommended to use Vault auto-unseal using Cloud KMS for Production Systems. And also, rotate the root token regularly.
<a name = "docker"></a>
## Docker Images
Hyperledger Bevel provides pre-built docker images which are available on [GitHub Repo](https://github.com/orgs/hyperledger/packages?repo_name=bevel). Ensure that the versions/tags you need are available. If not, [ask a question](../contributing/asking-a-question.md).
2 changes: 1 addition & 1 deletion docs/source/getting-started/prerequisites-machine.md
View file
Original file line number Diff line number Diff line change
@@ -11,7 +11,7 @@

## Ansible

Hyperledger Bevel configuration is essentially Ansible scripts, so install Ansible on the machine from which you will deploy the DLT/Blockchain network. This can be a local machine as long as Ansible commands can run on it.
Hyperledger Bevel automation is essentially Ansible scripts, so install Ansible on the machine from which you will deploy the DLT/Blockchain network. This can be a local machine as long as Ansible commands can run on it.

As per our [sequence diagram](../concepts/sequence-diagram.md), this machine (also called **Ansible Controller**) should have connectivity to the Kubernetes cluster(s) and the Hashicorp Vault service(s). And it is essential to install the [git client](https://git-scm.com/download) on the Ansible Controller.

42 changes: 27 additions & 15 deletions docs/source/getting-started/prerequisites.md
View file
Original file line number Diff line number Diff line change
@@ -7,53 +7,65 @@

Following are the common prerequisite software/client/platforms etc. needed before you can start deploying/operating blockchain networks using Hyperledger Bevel.

## Git Repository
[GitOps](../concepts/gitops.md) is a key concept for Hyperledger Bevel, so a Git repository is needed for Bevel (this can be a [GitHub](https://github.com/) repository as well).
Fork or import the [Bevel GitHub repo](https://github.com/hyperledger/bevel) to this Git repository.
## Helm

The Operator should have a user created on this repo with read-write access to the Git Repository.
[Helm](../concepts/helm.md) is a crucial tool for managing Kubernetes applications, simplifying the deployment and management of Kubernetes manifests. For Hyperledger Bevel, Helm charts are used to streamline the deployment of DLT networks, ensuring consistency and efficiency.

!!! tip
To install Helm, follow the official [Helm installation guide](https://helm.sh/docs/intro/install/). Ensure the version is compatible with your Kubernetes setup.

Install Git Client Version > **2.31.0**
!!! tip

Install Helm Version > **v3.6.2**

## Kubernetes

Hyperledger Bevel deploys the DLT/Blockchain network on [Kubernetes](https://kubernetes.io/) clusters; hence, at least one Kubernetes cluster should be available.
Bevel recommends one Kubernetes cluster per organization for production-ready projects.
Also, a user needs to make sure that the Kubernetes clusters can support the number of pods and persistent volumes that will be created by Bevel.

Bevel recommends one Kubernetes cluster per organization for production-ready projects. Also, a user needs to make sure that the Kubernetes clusters can support the number of pods and persistent volumes that will be created by Bevel.

!!! tip

For the current release Bevel has been tested on Amazon EKS with Kubernetes version **1.23**.
For the current release Bevel has been tested on Amazon EKS with Kubernetes version **1.28**.

Bevel has been tested on Kubernetes >= 1.19 and <= 1.23
Bevel has been tested on Kubernetes >= 1.19 and <= 1.28

!!! warning Icon Filename
Also, install kubectl Client version as per Kubernetes version **v1.23.0**
Also, install kubectl Client version as per Kubernetes version **v1.28.0**

Please follow respective Cloud provider instructions, like [ for Amazon](https://aws.amazon.com/eks/getting-started/) to set-up your required Kubernetes cluster(s).
Please follow respective Cloud provider instructions, like [for Amazon](https://aws.amazon.com/eks/getting-started/) to set-up your required Kubernetes cluster(s).
To connect to Kubernetes cluster(s), you will also need kubectl Command Line Interface (CLI). Refer [here](https://kubernetes.io/docs/tasks/tools/install-kubectl/) for installation instructions, although Hyperledger Bevel configuration code (Ansible scripts) installs this automatically.

## Git Repository

Release 1.1 onwards, [GitOps](../concepts/gitops.md) is a optional concept for Hyperledger Bevel. Although, for Production-ready deployment with Ansible automation, GitOps is needed for Bevel.

Fork or import the [Bevel GitHub repo](https://github.com/hyperledger/bevel) to your own Git repository. The Operator should have a user created on this repo with read-write access to the Git Repository.

!!! tip

Install Git Client Version > **2.31.0**

## HashiCorp Vault
In this current release, [Hashicorp Vault](https://www.vaultproject.io/) is mandatory for Hyperledger Bevel as the certificate and key storage solution; hence, at least one Vault server should be available. Bevel recommends one Vault per organization for production-ready projects.

Release 1.1 onwards, [Hashicorp Vault](https://www.vaultproject.io/) is optional for Hyperledger Bevel as the certificate and key storage solution. But, for Production-ready deployment with Ansible automation, at least one Vault server should be available. Bevel recommends one Vault per organization for production-ready projects.

Follow [official instructions](https://developer.hashicorp.com/vault/docs/install) to deploy Vault in your environment.

!!! tip

The recommended approach is to create one Vault deployment on one VM and configure the backend as cloud storage.

!!! warning

Vault version should be **1.13.1**
Vault version should be <= **1.15.2**


## Internet Domain

Hyperledger Bevel uses [Ambassador Edge Stack](https://www.getambassador.io/products/edge-stack/api-gateway) or [HAProxy Ingress Controller](https://haproxy-ingress.github.io/) for inter-cluster communication. So, for the Kubernetes services to be available outside the specific cluster, at least one DNS Domain is required. This domain name can then be sub-divided across multiple clusters and the domain-resolution configured for each.
Although for production implementations, each organization (and thereby each cluster), must have one domain name.

!!! tip
!!! note

If single cluster is being used for all organizations in a dev/POC environment, then domain name is not needed.

25 changes: 19 additions & 6 deletions docs/source/getting-started/run-bevel.md
View file
Original file line number Diff line number Diff line change
@@ -4,19 +4,32 @@
[//]: # (##############################################################################################)
# Run Bevel

Once your [pre-requisites](./prerequisites.md) are [configured](./configure-prerequisites.md), it's time to take the next step. Fork the [Hyperledger Bevel GitHub](https://github.com/hyperledger/bevel) repository and unlock the potential of this powerful tool for your Distributed Ledger Technology (DLT) deployment.
Once your [pre-requisites](./prerequisites.md) are [configured](./configure-prerequisites.md), it's time to take the next step.

Now, let's explore two user-friendly methods for using Hyperledger Bevel:
There are three user-friendly methods for using Hyperledger Bevel:

- [Using the **bevel-build** Docker container as Ansible controller.](#bevel-build)
- [Using your own machine as Ansible controller.](#own-machine)
- [Using Helm Charts](#using-helm-charts)
- [Using the **bevel-build** Docker container as Ansible controller.](#using-docker-container)
- [Using your own machine as Ansible controller.](#using-own-machine)

## Using Helm Charts

Release 1.1 onwards, Bevel can be used without Ansible automation. If you want to create a small development network, using the Helm charts will be simpler and faster. For production-ready networks or complex networks with multiple organisations, the below two options are recommended.

Follow the respective Helm chart documentation to setup your network:

* [R3 Corda Opensource Charts](https://github.com/hyperledger/bevel/tree/main/platforms/r3-corda/charts)
* [R3 Corda Enterprise Charts](https://github.com/hyperledger/bevel/tree/main/platforms/r3-corda-ent/charts)
* [Hyperledger Fabric Charts](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts)
* [Hyperledger Indy Charts](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-indy/charts)
* [Quorum Charts](https://github.com/hyperledger/bevel/tree/main/platforms/quorum/charts)
* [Hyperledger Besu Charts](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-besu/charts)
* [Substrate Charts](https://github.com/hyperledger/bevel/tree/main/platforms/substrate/charts)

<a name = "bevel-build"></a>
## Using Docker container

Follow [this tutorial](../tutorials/docker-deploy.md) for how to deploy from the docker container.

<a name = "own-machine"></a>
## Using Own machine

Using own machine as Ansible Controller needs these [additional pre-requisites](./prerequisites-machine.md).
133 changes: 5 additions & 128 deletions docs/source/guides/besu/add-new-member-org.md
View file
Original file line number Diff line number Diff line change
@@ -35,137 +35,13 @@ The `network.yaml` file should contain the specific `network.organization` detai

Make sure that the genesis flie is provided in base64 encoding. Also, if you are adding node to the same cluster as of another node, make sure that you add the ambassador ports of the existing node present in the cluster to the network.yaml

For reference, sample `network.yaml` file looks like below for IBFT consensus (but always check the latest network-besu-new-memberorg.yaml at `platforms/hyperledger-besu/configuration/samples`):
For reference, sample `network-besu-new-memberorg.yaml` file [here](https://github.com/hyperledger/bevel/blob/main/platforms/hyperledger-besu/configuration/samples/network-besu-new-memberorg.yaml)

```yaml
--8<-- "platforms/hyperledger-besu/configuration/samples/network-besu-new-memberorg.yaml:1:152"
```
---
# This is a sample configuration file for Hyperledger Besu network which has 4 nodes.
# All text values are case-sensitive
network:
# Network level configuration specifies the attributes required for each organization
# to join an existing network.
type: besu
version: 22.10.2 #this is the version of Besu docker image that will be deployed.
#Environment section for Kubernetes setup
env:
type: "dev" # tag for the environment. Important to run multiple flux on single cluster
proxy: ambassador # value has to be 'ambassador' as 'haproxy' has not been implemented for besu
## Any additional Ambassador ports can be given below, this is valid only if proxy='ambassador'
# These ports are enabled per cluster, so if you have multiple clusters you do not need so many ports
# This sample uses a single cluster, so we have to open 4 ports for each Node. These ports are again specified for each organization below
ambassadorPorts:
portRange: # For a range of ports
from: 15010
to: 15043
# ports: 15020,15021 # For specific ports
retry_count: 20 # Retry count for the checks on Kubernetes cluster
external_dns: enabled # Should be enabled if using external-dns for automatic route configuration
# Docker registry details where images are stored. This will be used to create k8s secrets
# Please ensure all required images are built and stored in this registry.
# Do not check-in docker_password.
docker:
url: "ghcr.io/hyperledger"
username: "docker_username"
password: "docker_password"
# Following are the configurations for the common Besu network
config:
consensus: "ibft" # Options are "ibft", "ethash" and "clique".
## Certificate subject for the root CA of the network.
# This is for development usage only where we create self-signed certificates and the truststores are generated automatically.
# Production systems should generate proper certificates and configure truststores accordingly.
subject: "CN=DLT Root CA,OU=DLT,O=DLT,L=London,C=GB"
transaction_manager: "tessera" # Transaction manager is "tessera"
# This is the version of "tessera" docker image that will be deployed
tm_version: "21.7.3"
# TLS can be True or False for the tessera tm
tm_tls: True
# Tls trust value
tm_trust: "ca-or-tofu" # Options are: "ca-or-tofu", "ca", "tofu"
## File location where the base64 encoded genesis file is located.
genesis: "/home/user/bevel/build/besu_genesis" # Location where genesis file will be fetched
## Transaction Manager nodes public addresses should be provided.
# - "https://node.test.besu.blockchain-develop.com"
# The above domain name is formed by the (http or https)://(peer.name).(org.external_url_suffix):(ambassador tessera node port)
tm_nodes:
- "https://carrier.test.besu.blockchaincloudpoc-develop.com"
- "https://manufacturer.test.besu.blockchaincloudpoc-develop.com"
- "https://store.test.besu.blockchaincloudpoc-develop.com"
- "https://warehouse.test.besu.blockchaincloudpoc-develop.com"
# Besu rpc public address list for existing validator and member nodes
# - "http://noderpc.test.besu.blockchaincloudpoc-develop.com"
# The above domain name is formed by the (http)://(peer.name)rpc.(org.external_url_suffix):(ambassador node rpc port)
besu_nodes:
- "http://validatorrpc.test.besu.blockchaincloudpoc-develop.com"
- "http://carrierrpc.test.besu.blockchaincloudpoc-develop.com"
- "http://manufacturerrpc.test.besu.blockchaincloudpoc-develop.com"
- "http://storerpc.test.besu.blockchaincloudpoc-develop.com"
# Allows specification of one or many organizations that will be connecting to a network.
organizations:
# Specification for the 1st organization. Each organization should map to a VPC and a separate k8s cluster for production deployments
- organization:
name: neworg
type: member
# Provide the url suffix that will be added in DNS recordset. Must be different for different clusters
# This is not used for Besu as Besu does not support DNS hostnames currently. Here for future use
external_url_suffix: test.besu.blockchaincloudpoc-develop.com
cloud_provider: aws # Options: aws, azure, gcp
aws:
access_key: "aws_access_key" # AWS Access key, only used when cloud_provider=aws
secret_key: "aws_secret_key" # AWS Secret key, only used when cloud_provider=aws
region: "aws_region" # AWS Region where cluster and EIPs are created
# Kubernetes cluster deployment variables. The config file path and name has to be provided in case
# the cluster has already been created.
k8s:
context: "cluster_context"
config_file: "cluster_config"
# Hashicorp Vault server address and root-token. Vault should be unsealed.
# Do not check-in root_token
vault:
url: "vault_addr"
root_token: "vault_root_token"
secret_path: "secretsv2"
# Git Repo details which will be used by GitOps/Flux.
# Do not check-in git_access_token
gitops:
git_protocol: "https" # Option for git over https or ssh
git_url: "https://github.com/<username>/bevel.git" # Gitops https or ssh url for flux value files
branch: "develop" # Git branch where release is being made
release_dir: "platforms/hyperledger-besu/releases/dev" # Relative Path in the Git repo for flux sync per environment.
chart_source: "platforms/hyperledger-besu/charts" # Relative Path where the Helm charts are stored in Git repo
git_repo: "github.com/<username>/bevel.git" # Gitops git repository URL for git push
username: "git_username" # Git Service user who has rights to check-in in all branches
password: "git_access_token" # Git Server user access token (Optional for ssh; Required for https)
email: "git_email" # Email to use in git config
private_key: "path_to_private_key" # Path to private key file which has write-access to the git repo (Optional for https; Required for ssh)
# The participating nodes are named as peers
services:
peers:
- peer:
name: newOrg
subject: "O=Neworg,OU=Neworg,L=51.50/-0.13/London,C=GB" # This is the node subject. L=lat/long is mandatory for supplychain sample app
geth_passphrase: 12345 # Passphrase to be used to generate geth account
lock: false # Sets Besu node to lock or unlock mode. Can be true or false
p2p:
port: 30303
ambassador: 15020 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15021 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
tm_nodeport:
port: 15022 # Port exposed on ambassador service must be same
ambassador: 15022
tm_clientport:
port: 8888

```
Three new sections are added to the network.yaml
Three new sections are added to the network.yaml

| Field | Description |
|-------------|----------------------------------------------------------|
@@ -185,3 +61,4 @@ ansible-playbook platforms/shared/configuration/add-new-organization.yaml --extr

## Verify network deployment
For instructions on how to troubleshoot network, read [our troubleshooting guide](../../references/troubleshooting.md)

178 changes: 4 additions & 174 deletions docs/source/guides/besu/add-new-validator-node.md
View file
Original file line number Diff line number Diff line change
@@ -30,183 +30,12 @@ The `network.yaml` file should contain the specific `network.organization` detai
**NOTE**: Make sure that the genesis flie is provided in base64 encoding. Also, if you are adding node to the same cluster as of another node, make sure that you add the ambassador ports of the existing node present in the cluster to the network.yaml

---
For reference, sample `network.yaml` file looks like below for IBFT consensus (but always check the latest network-besu-new-validatornode.yaml at `platforms/hyperledger-besu/configuration/samples`):
For reference, sample `network-besu-new-validatornode.yaml` file [here](https://github.com/hyperledger/bevel/blob/main/platforms/hyperledger-besu/configuration/samples/network-besu-new-validatornode.yaml)

```yaml
--8<-- "platforms/hyperledger-besu/configuration/samples/network-besu-new-validatornode.yaml:1:201"
```
---
# This is a sample configuration file to add a new validator node to existing network.
# This DOES NOT support proxy=none
# All text values are case-sensitive
network:
# Network level configuration specifies the attributes required for each organization to join an existing network.
type: besu
version: 21.10.6 #this is the version of Besu docker image that will be deployed.
#Environment section for Kubernetes setup
env:
type: "dev" # tag for the environment. Important to run multiple flux on single cluster
proxy: ambassador # value has to be 'ambassador' as 'haproxy' has not been implemented for besu
## Any additional Ambassador ports can be given below, this is valid only if proxy='ambassador'
# These ports are enabled per cluster, so if you have multiple clusters you do not need so many ports
# This sample uses a single cluster, so we have to open 4 ports for each Node.
# These ports are again specified for each organization below
ambassadorPorts:
portRange: # For a range of ports
from: 15010
to: 15043
# ports: 15020,15021 # For specific ports
retry_count: 20 # Retry count for the checks on Kubernetes cluster
external_dns: enabled # Should be enabled if using external-dns for automatic route configuration
# Docker registry details where images are stored. This will be used to create k8s secrets
# Please ensure all required images are built and stored in this registry.
# Do not check-in docker_password.
docker:
url: "ghcr.io/hyperledger"
username: "docker_username"
password: "docker_password"
# Following are the configurations for the common Besu network
config:
consensus: "ibft" # Options are "ibft", "ethash" and "clique".
## Certificate subject for the root CA of the network.
# This is for development usage only where we create self-signed certificates
# and the truststores are generated automatically.
# Production systems should generate proper certificates and configure truststores accordingly.
subject: "CN=DLT Root CA,OU=DLT,O=DLT,L=London,C=GB"
transaction_manager: "tessera" # Transaction manager is "tessera"
# This is the version of "tessera" docker image that will be deployed
tm_version: "21.7.3"
# TLS can be True or False for the tessera tm
tm_tls: True
# Tls trust value
tm_trust: "ca-or-tofu" # Options are: "ca-or-tofu", "ca", "tofu"
## File location where the base64 encoded genesis file is located.
genesis: "/home/user/bevel/build/besu_genesis"
## Transaction Manager nodes public addresses should be provided.
# - "https://node.test.besu.blockchain-develop.com"
# The above domain name is formed by the (http or https)://(peer.name).(org.external_url_suffix):(ambassador tm node port)
tm_nodes:
- "https://carrier.test.besu.blockchaincloudpoc-develop.com"
- "https://manufacturer.test.besu.blockchaincloudpoc-develop.com"
- "https://store.test.besu.blockchaincloudpoc-develop.com"
- "https://warehouse.test.besu.blockchaincloudpoc-develop.com"
# Besu rpc public address list for existing validator and member nodes
# - "http://noderpc.test.besu.blockchaincloudpoc-develop.com"
# The above domain name is formed by the (http)://(peer.name)rpc.(org.external_url_suffix):(ambassador node rpc port)
besu_nodes:
- "http://validator1rpc.test.besu.blockchaincloudpoc-develop.com"
- "http://validator2rpc.test.besu.blockchaincloudpoc-develop.com"
- "http://validator3rpc.test.besu.blockchaincloudpoc-develop.com"
- "http://validator4rpc.test.besu.blockchaincloudpoc-develop.com"
- "https://carrierrpc.test.besu.blockchaincloudpoc-develop.com"
- "https://manufacturerrpc.test.besu.blockchaincloudpoc-develop.com"
- "https://storerpc.test.besu.blockchaincloudpoc-develop.com"
- "https://warehouserpc.test.besu.blockchaincloudpoc-develop.com"
# Allows specification of one or many organizations that will be connecting to a network.
organizations:
# Specification for the 1st organization. Each organization should map to a VPC and a separate k8s cluster for production deployments
- organization:
name: supplychain
type: validator
# Provide the url suffix that will be added in DNS recordset. Must be different for different clusters
# This is not used for Besu as Besu does not support DNS hostnames currently. Here for future use
external_url_suffix: test.besu.blockchaincloudpoc-develop.com
cloud_provider: aws # Options: aws, azure, gcp
aws:
access_key: "aws_access_key" # AWS Access key, only used when cloud_provider=aws
secret_key: "aws_secret_key" # AWS Secret key, only used when cloud_provider=aws
region: "aws_region" # AWS Region where cluster and EIPs are created
# Kubernetes cluster deployment variables. The config file path and name has to be provided in case
# the cluster has already been created.
k8s:
context: "cluster_context"
config_file: "cluster_config"
# Hashicorp Vault server address and root-token. Vault should be unsealed.
# Do not check-in root_token
vault:
url: "vault_addr"
root_token: "vault_root_token"
secret_path: "secretsv2"
# Git Repo details which will be used by GitOps/Flux.
# Do not check-in git_access_token
gitops:
git_protocol: "https" # Option for git over https or ssh
git_url: "https://github.com/<username>/bevel.git" # Gitops https or ssh url for flux value files
branch: "develop" # Git branch where release is being made
release_dir: "platforms/hyperledger-besu/releases/dev" # Relative Path in the Git repo for flux sync per environment.
chart_source: "platforms/hyperledger-besu/charts" # Relative Path where the Helm charts are stored in Git repo
git_repo: "github.com/<username>/bevel.git" # Gitops git repository URL for git push
username: "git_username" # Git Service user who has rights to check-in in all branches
password: "git_access_token" # Git Server user access token (Optional for ssh; Required for https)
email: "git_email" # Email to use in git config
private_key: "path_to_private_key" # Path to private key file which has write-access to the git repo (Optional for https; Required for ssh)
# As this is a validator org, it is hosting a few validators as services
services:
validators:
- validator:
name: validator1
status: existing # needed to know which validator node exists
bootnode: true # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15020 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15021 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- validator:
name: validator2
status: existing # needed to know which validator node exists
bootnode: true # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15012 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15013 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- validator:
name: validator3
status: existing # needed to know which validator node exists
bootnode: false # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15014 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15015 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- validator:
name: validator4
status: existing # needed to know which validator node exists
bootnode: false # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15016 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15017 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- validator:
name: validator5
status: new # needed to know which validator node exists
bootnode: false # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15018 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15019 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546

```
Three new sections are added to the network.yaml

| Field | Description |
@@ -224,3 +53,4 @@ The [add-validator.yaml](https://github.com/hyperledger/bevel/tree/main/platform
```
ansible-playbook platforms/hyperledger-besu/configuration/add-validator.yaml --extra-vars "@path-to-network.yaml"
```

229 changes: 3 additions & 226 deletions docs/source/guides/besu/add-new-validator-org.md
View file
Original file line number Diff line number Diff line change
@@ -30,234 +30,12 @@ The `network.yaml` file should contain the specific `network.organization` detai
**NOTE**: Make sure that the genesis flie is provided in base64 encoding. Also, if you are adding node to the same cluster as of another node, make sure that you add the ambassador ports of the existing node present in the cluster to the network.yaml

---
For reference, sample `network.yaml` file looks like below for IBFT consensus (but always check the latest network-besu-new-validatororg.yaml at `platforms/hyperledger-besu/configuration/samples`):
For reference, sample `network-besu-new-validatororg.yaml` file [here](https://github.com/hyperledger/bevel/blob/main/platforms/hyperledger-besu/configuration/samples/network-besu-new-validatororg.yaml)

```yaml
--8<-- "platforms/hyperledger-besu/configuration/samples/network-besu-new-validatororg.yaml:1:155"
```
---
# This is a sample configuration file to add a new validator organization to existing network.
# This DOES NOT support proxy=none
# All text values are case-sensitive
network:
# Network level configuration specifies the attributes required for each organization to join an existing network.
type: besu
version: 21.10.6 #this is the version of Besu docker image that will be deployed.
#Environment section for Kubernetes setup
env:
type: "dev" # tag for the environment. Important to run multiple flux on single cluster
proxy: ambassador # value has to be 'ambassador' as 'haproxy' has not been implemented for besu
## Any additional Ambassador ports can be given below, this is valid only if proxy='ambassador'
# These ports are enabled per cluster, so if you have multiple clusters you do not need so many ports
# This sample uses a single cluster, so we have to open 4 ports for each Node.
# These ports are again specified for each organization below
ambassadorPorts:
portRange: # For a range of ports
from: 15010
to: 15043
# ports: 15020,15021 # For specific ports
retry_count: 20 # Retry count for the checks on Kubernetes cluster
external_dns: enabled # Should be enabled if using external-dns for automatic route configuration
# Docker registry details where images are stored. This will be used to create k8s secrets
# Please ensure all required images are built and stored in this registry.
# Do not check-in docker_password.
docker:
url: "ghcr.io/hyperledger"
username: "docker_username"
password: "docker_password"
# Following are the configurations for the common Besu network
config:
consensus: "ibft" # Options are "ibft", "ethash" and "clique".
## Certificate subject for the root CA of the network.
# This is for development usage only where we create self-signed certificates and the truststores are generated automatically.
# Production systems should generate proper certificates and configure truststores accordingly.
subject: "CN=DLT Root CA,OU=DLT,O=DLT,L=London,C=GB"
transaction_manager: "tessera" # Transaction manager is "tessera"
# This is the version of "tessera" docker image that will be deployed
tm_version: "21.7.3"
# TLS can be True or False for the tessera tm
tm_tls: True
# Tls trust value
tm_trust: "ca-or-tofu" # Options are: "ca-or-tofu", "ca", "tofu"
## File location where the base64 encoded genesis file is located.
genesis: "/home/user/bevel/build/besu_genesis"
## Transaction Manager nodes public addresses should be provided.
# - "https://node.test.besu.blockchain-develop.com"
# The above domain name is formed by the (http or https)://(peer.name).(org.external_url_suffix):(ambassador tessera node port)
tm_nodes:
- "https://carrier.test.besu.blockchaincloudpoc-develop.com"
- "https://manufacturer.test.besu.blockchaincloudpoc-develop.com"
- "https://store.test.besu.blockchaincloudpoc-develop.com"
- "https://warehouse.test.besu.blockchaincloudpoc-develop.com"
# Besu rpc public address list for existing validator and member nodes
# - "http://noderpc.test.besu.blockchaincloudpoc-develop.com"
# The above domain name is formed by the (http)://(peer.name)rpc.(org.external_url_suffix):(ambassador node rpc port)
besu_nodes:
- "http://validator1rpc.test.besu.blockchaincloudpoc-develop.com"
- "http://validator2rpc.test.besu.blockchaincloudpoc-develop.com"
- "http://validator3rpc.test.besu.blockchaincloudpoc-develop.com"
- "http://validator4rpc.test.besu.blockchaincloudpoc-develop.com"
- "https://carrierrpc.test.besu.blockchaincloudpoc-develop.com"
- "https://manufacturerrpc.test.besu.blockchaincloudpoc-develop.com"
- "https://storerpc.test.besu.blockchaincloudpoc-develop.com"
- "https://warehouserpc.test.besu.blockchaincloudpoc-develop.com"
# Allows specification of one or many organizations that will be connecting to a network.
organizations:
# Specification for the 1st organization. Each organization should map to a VPC and a separate k8s cluster for production deployments
- organization:
name: supplychain
type: validator
# Provide the url suffix that will be added in DNS recordset. Must be different for different clusters
# This is not used for Besu as Besu does not support DNS hostnames currently. Here for future use
external_url_suffix: test.besu.blockchaincloudpoc-develop.com
cloud_provider: aws # Options: aws, azure, gcp
aws:
access_key: "aws_access_key" # AWS Access key, only used when cloud_provider=aws
secret_key: "aws_secret_key" # AWS Secret key, only used when cloud_provider=aws
region: "aws_region" # AWS Region where cluster and EIPs are created
# Kubernetes cluster deployment variables. The config file path and name has to be provided in case
# the cluster has already been created.
k8s:
context: "cluster_context"
config_file: "cluster_config"
# Hashicorp Vault server address and root-token. Vault should be unsealed.
# Do not check-in root_token
vault:
url: "vault_addr"
root_token: "vault_root_token"
secret_path: "secretsv2"
# Git Repo details which will be used by GitOps/Flux.
# Do not check-in git_access_token
gitops:
git_protocol: "https" # Option for git over https or ssh
git_url: "https://github.com/<username>/bevel.git" # Gitops https or ssh url for flux value files
branch: "develop" # Git branch where release is being made
release_dir: "platforms/hyperledger-besu/releases/dev" # Relative Path in the Git repo for flux sync per environment.
chart_source: "platforms/hyperledger-besu/charts" # Relative Path where the Helm charts are stored in Git repo
git_repo: "github.com/<username>/bevel.git" # Gitops git repository URL for git push
username: "git_username" # Git Service user who has rights to check-in in all branches
password: "git_access_token" # Git Server user access token (Optional for ssh; Required for https)
email: "git_email" # Email to use in git config
private_key: "path_to_private_key" # Path to private key file which has write-access to the git repo (Optional for https; Required for ssh)
# As this is a validator org, it is hosting a few validators as services
services:
validators:
- validator:
name: validator1
status: existing # needed to know which validator node exists
bootnode: true # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15020 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15021 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- validator:
name: validator2
status: existing # needed to know which validator node exists
bootnode: true # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15012 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15013 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- validator:
name: validator3
status: existing # needed to know which validator node exists
bootnode: false # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15014 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15015 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- validator:
name: validator4
status: existing # needed to know which validator node exists
bootnode: false # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15016 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15017 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- organization:
name: supplychain2
type: validator
# Provide the url suffix that will be added in DNS recordset. Must be different for different clusters
external_url_suffix: test.besu.blockchaincloudpoc-develop.com
cloud_provider: aws # Options: aws, azure, gcp
aws:
access_key: "aws_access_key" # AWS Access key, only used when cloud_provider=aws
secret_key: "aws_secret_key" # AWS Secret key, only used when cloud_provider=aws
region: "aws_region" # AWS Region where cluster and EIPs are created
# Kubernetes cluster deployment variables. The config file path and name has to be provided in case
# the cluster has already been created.
k8s:
context: "cluster_context"
config_file: "cluster_config"
# Hashicorp Vault server address and root-token. Vault should be unsealed.
# Do not check-in root_token
vault:
url: "vault_addr"
root_token: "vault_root_token"
secret_path: "secretsv2"
# Git Repo details which will be used by GitOps/Flux.
# Do not check-in git_access_token
gitops:
git_protocol: "https" # Option for git over https or ssh
git_url: "https://github.com/<username>/bevel.git" # Gitops https or ssh url for flux value files
branch: "develop" # Git branch where release is being made
release_dir: "platforms/hyperledger-besu/releases/dev" # Relative Path in the Git repo for flux sync per environment.
chart_source: "platforms/hyperledger-besu/charts" # Relative Path where the Helm charts are stored in Git repo
git_repo: "github.com/<username>/bevel.git" # Gitops git repository URL for git push
username: "git_username" # Git Service user who has rights to check-in in all branches
password: "git_access_token" # Git Server user password/token (Optional for ssh; Required for https)
email: "git@email.com" # Email to use in git config
private_key: "path_to_private_key" # Path to private key file which has write-access to the git repo (Optional for https; Required for ssh)
# As this is a validator org, it is hosting a few validators as services
services:
validators:
- validator:
name: validator5
status: new # needed to know which validator node exists
bootnode: true # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15026 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15027 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546
- validator:
name: validator6
status: new # needed to know which validator node exists
bootnode: true # true if the validator node is used also a bootnode for the network
p2p:
port: 30303
ambassador: 15028 #Port exposed on ambassador service (use one port per org if using single cluster)
rpc:
port: 8545
ambassador: 15029 #Port exposed on ambassador service (use one port per org if using single cluster)
ws:
port: 8546

```
Three new sections are added to the network.yaml

| Field | Description |
@@ -276,4 +54,3 @@ The [add-validator.yaml](https://github.com/hyperledger/bevel/tree/main/platform
ansible-playbook platforms/hyperledger-besu/configuration/add-validator.yaml --extra-vars "@path-to-network.yaml" --extra-vars "add_new_org='true'"
```


36 changes: 9 additions & 27 deletions docs/source/guides/besu/setup-cactus-connector.md
View file
Original file line number Diff line number Diff line change
@@ -27,33 +27,14 @@ Refer [this guide](../networkyaml-besu.md) for details on editing the configurat

When editing the configuration file (`network.yaml`) to deploy the cactus connector, both validators and peers from validator and member organizations should have the `cactus_connector` field. To enable the cactus connector for a peer or validator, set the value as `enabled`. If a particular peer or validator does not want to support the cactus connector feature, set the `cactus_connector` field as `disabled`. A sample for the same is shared below:

network:
organizations:
- organization: supplychain
type: validator
..
..
services:
validators:
- validator:
name: validator1
..
..
cactus_connector: enabled # set to enabled to create a cactus connector for Besu otherwise set it to disabled
- organization: carrier
type: member
..
..
services:
peers:
- peer:
name: carrier
..
..
cactus_connector: disabled # set to enabled to create a cactus connector for Besu otherwise set it to disabled

For reference, see `network-besu-v22.yaml` file [here](https://github.com/hyperledger/bevel/blob/develop/platforms/hyperledger-besu/configuration/samples/network-besu-v22.yaml).
```yaml
--8<-- "platforms/hyperledger-besu/configuration/samples/network-besu.yaml:127:132"
..
--8<-- "platforms/hyperledger-besu/configuration/samples/network-besu.yaml:187:193"
..
```

For reference, see `network-besu.yaml` file [here](https://github.com/hyperledger/bevel/blob/develop/platforms/hyperledger-besu/configuration/samples/network-besu.yaml).


<a name = "run_network"></a>
@@ -64,3 +45,4 @@ The [setup-cactus-connector.yaml](https://github.com/hyperledger/bevel/blob/deve
```
ansible-playbook platforms/hyperledger-besu/configuration/setup-cactus-connector.yaml --extra-vars "@path-to-network.yaml"
```

17 changes: 5 additions & 12 deletions docs/source/guides/besu/setup-onchain-permissioning.md
View file
Original file line number Diff line number Diff line change
@@ -24,18 +24,9 @@

2. To enable and use onchain permissioning, set the `network.permissioning.enabled` parameter to `true` in the Besu network configuration file. Below is a sample configuration for reference:

```yaml
network:
type: besu
version: 21.10.6
permissioning:
enabled: true # Set to false if onchain permissioning is not required
env:...
docker:...
config:...
organizations:...
```

```yaml
--8<-- "platforms/hyperledger-besu/configuration/samples/network-besu.yaml:11:18"
```
For reference, use sample configuration defined in the [network-besu.yaml](https://github.com/hyperledger/bevel/blob/develop/platforms/hyperledger-besu/configuration/samples/network-besu.yaml) file.

**Step 2: Deploy Besu network.**
@@ -98,3 +89,5 @@ truffle migrate --reset --network besu

By following these steps, we will be able to successfully deploy a Besu Onchain Permissioning Network.
Post network bootstrap permissioing smartcontract can be installed. Smartcontract installation steps can be found [here](https://besu.hyperledger.org/en/stable/private-networks/tutorials/permissioning/onchain/#11-clone-the-contracts-and-install-dependencies)


149 changes: 0 additions & 149 deletions docs/source/guides/corda/add-cenm-console.md
View file

This file was deleted.

15 changes: 8 additions & 7 deletions docs/source/guides/corda/add-new-notary.md
View file
Original file line number Diff line number Diff line change
@@ -10,7 +10,6 @@ To overcome this, we have created an Ansible playbook. The playbook will update

`run flagDay` command must be run after the network parameters update deadline is over (+10 minutes by default). And this command must be run during downtime as it will trigger Corda node restart.


- [Prerequisites](#prerequisites)
- [Deploy new Notary Service](#deploy-new-notary-service)
- [Run playbook](#run-playbook)
@@ -20,20 +19,22 @@ To overcome this, we have created an Ansible playbook. The playbook will update
## Prerequisites
To add a new Notary organization, Corda Idman and Networkmap services should already be running. The public certificates and NetworkTrustStore from Idman and Networkmap should be available and specified in the configuration file.

---
**NOTE**: Addition of a new Notary organization has been tested on an existing network which is created by Bevel. Networks created using other methods may be suitable but this has not been tested by Bevel team.

---
!!! note
Addition of a new Notary organization has been tested on an existing network which is created by Bevel. Networks created using other methods may be suitable but this has not been tested by Bevel team.

<a name = "deploy-new-notary-service"></a>
## Deploy new Notary Service

Deploy the additional notary/notaries as separate organizations by following the guidance on [how to add new organizations here](./add-new-org.md). A sample network.yaml for adding new notary orgs can be found [here](https://github.com/hyperledger/bevel/tree/develop/platforms/r3-corda-ent/configuration/samples).
Deploy the additional notary/notaries as separate organizations by following the guidance on [how to add new organizations here](./add-new-org.md). A sample network.yaml for adding new notary orgs can be found [here](https://github.com/hyperledger/bevel/blob/main/platforms/r3-corda-ent/configuration/samples/network-addNotary.yaml).

```yaml
--8<-- "platforms/r3-corda-ent/configuration/samples/network-addNotary.yaml:1:306"
```

<a name = "run-playbook"></a>
## Run Playbook

After the new notary is running, execute the playbook `platforms/r3-corda-ent/configuration/add-notaries.yaml` with the same configuration file as used in previous step.
After the new notary is running, execute the playbook [add-notaries.yaml] (https://github.com/hyperledger/bevel/blob/main/platforms/r3-corda-ent/configuration/add-notaries.yaml) with the same configuration file as used in previous step. This can be done using the following command

```
ansible-playbook platforms/r3-corda-ent/configuration/add-notaries.yaml --extra-vars "@path-to-new-network.yaml"
137 changes: 10 additions & 127 deletions docs/source/guides/corda/add-new-org.md
View file
Original file line number Diff line number Diff line change
@@ -14,10 +14,8 @@
## Prerequisites
To add a new organization, Corda Doorman/Idman and Networkmap services should already be running. The public certificates from Doorman/Idman and Networkmap should be available and specified in the configuration file.

---
**NOTE**: Addition of a new organization has been tested on an existing network which is created by Bevel. Networks created using other methods may be suitable but this has not been tested by Bevel team.

---
!!! note
Addition of a new organization has been tested on an existing network which is created by Bevel. Networks created using other methods may be suitable but this has not been tested by Bevel team.

<a name = "create_config_file"></a>
## Create Configuration File
@@ -26,138 +24,23 @@ Refer [this guide](../networkyaml-corda.md) for details on editing the configura

The `network.yaml` file should contain the specific `network.organization` details along with the network service information about the networkmap and doorman service.

---
**NOTE**: Make sure the doorman and networkmap service certificates are in plain text and not encoded in base64 or any other encoding scheme, along with correct paths to them mentioned in network.yaml.

---
For reference, sample `network.yaml` file looks like below (but always check the latest at `platforms/r3-corda/configuration/samples`):

```
network:
# Network level configuration specifies the attributes required for each organization
# to join an existing network.
type: corda
version: 4.0
#enabled flag is frontend is enabled for nodes
frontend: enabled
#Environment section for Kubernetes setup
env:
type: "env_type" # tag for the environment. Important to run multiple flux on single cluster
proxy: ambassador # value has to be 'ambassador' as 'haproxy' has not been implemented for Corda
ambassadorPorts: # Any additional Ambassador ports can be given here, this is valid only if proxy='ambassador'
portRange: # For a range of ports
from: 15010
to: 15043
# ports: 15020,15021 # For specific ports
retry_count: 20 # Retry count for the checks
external_dns: enabled # Should be enabled if using external-dns for automatic route configuration
# Docker registry details where images are stored. This will be used to create k8s secrets
# Please ensure all required images are built and stored in this registry.
# Do not check-in docker_password.
docker:
url: "docker_url"
username: "docker_username"
password: "docker_password"
# Remote connection information for doorman and networkmap (will be blank or removed for hosting organization)
network_service:
- service:
type: doorman
uri: https://doorman.test.corda.blockchaincloudpoc.com:8443
certificate: home_dir/platforms/r3-corda/configuration/build/corda/doorman/tls/ambassador.crt
- service:
type: networkmap
uri: https://networkmap.test.corda.blockchaincloudpoc.com:8443
certificate: home_dir/platforms/r3-corda/configuration/build/corda/networkmap/tls/ambassador.crt
# Allows specification of one or many organizations that will be connecting to a network.
# If an organization is also hosting the root of the network (e.g. doorman, membership service, etc),
# then these services should be listed in this section as well.
organizations:
# Specification for the new organization. Each organization maps to a VPC and a separate k8s cluster
- organization:
name: neworg
country: US
state: New York
location: New York
subject: "O=Neworg,OU=Neworg,L=New York,C=US"
type: node
external_url_suffix: test.corda.blockchaincloudpoc.com
cloud_provider: aws # Options: aws, azure, gcp
aws:
access_key: "aws_access_key" # AWS Access key, only used when cloud_provider=aws
secret_key: "aws_secret_key" # AWS Secret key, only used when cloud_provider=aws
# Kubernetes cluster deployment variables. The config file path and name has to be provided in case
# the cluster has already been created.
k8s:
region: "cluster_region"
context: "cluster_context"
config_file: "cluster_config"
# Hashicorp Vault server address and root-token. Vault should be unsealed.
# Do not check-in root_token
vault:
url: "vault_addr"
root_token: "vault_root_token"
!!! note
Make sure the doorman and networkmap service certificates are in plain text and not encoded in base64 or any other encoding scheme, along with correct paths to them mentioned in network.yaml.

# Git Repo details which will be used by GitOps/Flux.
# Do not check-in git_access_token
gitops:
git_protocol: "https" # Option for git over https or ssh
git_url: "gitops_ssh_url" # Gitops https or ssh url for flux value files like "https://github.com/hyperledger/bevel.git"
branch: "gitops_branch" # Git branch where release is being made
release_dir: "gitops_release_dir" # Relative Path in the Git repo for flux sync per environment.
chart_source: "gitops_charts" # Relative Path where the Helm charts are stored in Git repo
git_repo: "gitops_repo_url" # Gitops git repository URL for git push like "github.com/hyperledger/bevel.git"
username: "git_username" # Git Service user who has rights to check-in in all branches
password: "git_access_token" # Git Server user access token (Optional for ssh; Required for https)
email: "git_email" # Email to use in git config
private_key: "path_to_private_key" # Path to private key file which has write-access to the git repo (Optional for https; Required for ssh)
services:
peers:
- peer:
name: neworg
subject: "O=Neworg,OU=Neworg,L=New York,C=US"
type: node
p2p:
port: 10002
targetPort: 10002
ambassador: 10070 #Port for ambassador service (use one port per org if using single cluster)
rpc:
port: 10003
targetPort: 10003
rpcadmin:
port: 10005
targetPort: 10005
dbtcp:
port: 9101
targetPort: 1521
dbweb:
port: 8080
targetPort: 81
springboot:
targetPort: 20001
port: 20001
expressapi:
targetPort: 3000
port: 3000
For reference, sample `network.yaml` file [here] (https://github.com/hyperledger/bevel/blob/main/platforms/r3-corda/configuration/samples/network-cordav2.yaml) but always check the latest `network.yaml` file.

```yaml
--8<-- "platforms/r3-corda/configuration/samples/network-cordav2.yaml:1:223"
```

<a name = "run_network"></a>
## Run playbook

The [add-new-organization.yaml](https://github.com/hyperledger/bevel/tree/main/platforms/shared/configuration/add-new-organization.yaml) playbook is used to add a new organization to the existing network. This can be done using the following command
The [add-new-organization.yaml](https://github.com/hyperledger/bevel/blob/main/platforms/shared/configuration/add-new-organization.yaml) playbook is used to add a new organization to the existing network. This can be done using the following command

```
ansible-playbook platforms/shared/configuration/add-new-organization.yaml --extra-vars "@path-to-network.yaml"
```

---
**NOTE:** If you have CorDapps and applications, please deploy them as well.

!!! note
If you have CorDapps and applications, please deploy them as well.
136 changes: 78 additions & 58 deletions docs/source/guides/fabric/add-cli.md
View file
Original file line number Diff line number Diff line change
@@ -3,66 +3,86 @@
[//]: # (SPDX-License-Identifier: Apache-2.0)
[//]: # (##############################################################################################)

<a name = "adding-cli-to-existing-network-in-fabric"></a>
# Adding cli to Hyperledger Fabric
# Add CLI to a Peer

- [Prerequisites](#prerequisites)
- [Modifying configuration file](#create_config_file)
- [Running playbook to deploy Hyperledger Fabric network](#run_network)
This guide explains how to add a CLI to an existing Hyperledger Fabric network using two methods:

1. Using the `add-cli.yaml` playbook: This method involves running an Ansible playbook that automates the process of adding a CLI to the network.

<a name = "prerequisites"></a>
## Prerequisites
To add cli 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.

---
**NOTE**: Addition of cli has been tested on an existing network which is created by Bevel. Networks created using other methods may be suitable but this has not been tested by Bevel team.

---

<a name = "create_config_file"></a>
## Modifying Configuration File

Refer [this guide](../networkyaml-fabric.md) for details on editing the configuration file.

While modifying the configuration file(`network.yaml`) for adding cli, all the existing organizations should have `org_status` tag as `existing` and the new organization should have `org_status` tag as `new` under `network.channels` e.g.

network:
channels:
- channel:
..
..
participants:
- organization:
..
..
org_status: new # new for new organization(s)
- organization:
..
..
org_status: existing # existing for old organization(s)
1. Using `helm install`: This method involves using the helm install command to directly install the CLI chart.

and under `network.organizations` as

network:
organizations:
- organization:
..
..
org_status: new # new for new organization(s)
- organization:
..
..
org_status: existing # existing for old organization(s)

The `network.yaml` file should contain the specific `network.organization` details along with the orderer information.


<a name = "run_network"></a>
## Run playbook

The [add-cli.yaml](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/configuration/add-cli.yaml) playbook is used to add cli to the existing network. This can be done using the following command
## Prerequisites

```
ansible-playbook platforms/shared/configuration/add-cli.yaml --extra-vars "@path-to-network.yaml"
```
- A fully configured Fabric network with Orderers and Peers.
- Corresponding crypto materials present in Hashicorp Vault or Kubernetes secrets.
- Hyperledger Bevel configured.

## Method 1: Using the `add-cli.yaml` playbook

1. **Update Configuration File**

- Edit the `network.yaml` file to include the new organization with the following details:
- `org_status: new`
- Organization details (name, MSP ID, etc.)
- Orderer information
- Existing organizations should have `org_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-organization.yaml:65:139"
```

and from `network.organizations` section below:

```yaml
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-organization.yaml:143:155"
..
..
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-organization.yaml:406:414"
..
..
```

1. **Run Playbook**

Execute the following command to run the `add-cli.yaml` playbook:

```
ansible-playbook platforms/hyperledger-fabric/configuration/add-cli.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 the CLI to the specified organization in the existing Fabric network.

## Method 2: Using `helm install`

1. **Update the fabric-cli values.yaml file**

The `values.yaml` file allows you to configure various aspects of the CLI, including:

- The peer to which the CLI should connect.
- The storage class and size for the CLI's persistent volume claim.
- The local MSP ID of the organization.
- The TLS status of the peer.
- The GRPC Port of the peer.
- The Orderer Address to which the CLI should connect.

Refer to the [fabric-cli chart documentation](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/charts/fabric-cli) for a complete list of available configuration options.

1. **Install the CLI Chart**

Execute the following command to install the CLI chart:
```bash
# From platforms/hyperledger-fabric/charts directory
helm install <release-name> ./fabric-cli --namespace <namespace> --values <values-file.yaml>
```
Replace the following placeholders:

- `<release-name>`: The desired name for the CLI release.
- `<namespace>`: The Kubernetes namespace where the CLI should be deployed.
- `<values-file.yaml>`: The path to a YAML file containing the CLI configuration values.

## Additional Notes
- The `add-cli.yaml playbook` and `helm install` method has been tested on networks created by Bevel. Networks created using other methods may be suitable, but this has not been tested by the Bevel team.
- Ensure that the network.yaml file contains the specific network.organization details along with the orderer information.
207 changes: 159 additions & 48 deletions docs/source/guides/fabric/add-new-channel.md
View file
Original file line number Diff line number Diff line change
@@ -3,69 +3,180 @@
[//]: # (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](#create_config_file)
- [Running playbook to deploy Hyperledger Fabric network](#run_network)
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.

2. 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. **Add a defined channel with genesis or channeltx generated in basic deployment**

**Update Configuration File**

- Edit the `network.yaml` file to include a channel with the following details:
- Organization details (name, CA address, MSP ID, etc.)
- Orderer information
- 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-fabricv2.yaml:63:165"
```

**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 channel to the existing Fabric network.

2. **Add a new channel by generating a new genesis or channeltx in an existing network**

**Update Configuration File**

- Edit the `network.yaml` file to include a new channel with the following details:
- `channel_status: new`
- 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:63:227"
```

!!! 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.

**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" -e genererate_configtx=true
```
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.

---
**NOTE**: Do not try to add a new organization as a part of this operation. Use only existing organization for new channel addition.
## Method 2: Using `helm install`

---
1. **Update the fabric-genesis values.yaml file**

<a name = "create_config_file"></a>
## Modifying Configuration File
Following changes are must in the `values.yaml` file for a new channel to be added to the network:

Refer [this guide](../networkyaml-fabric.md) for details on editing the configuration file.
- `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.

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.
1. **Generate the new channel artifacts**

network:
channels:
- channel:
channel_status: existing
..
..
participants:
- organization:
..
..
- organization:
..
..
- channel:
channel_status: new
..
..
participants:
- organization:
..
..
- organization:
..
..
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

#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
```

The `network.yaml` file should contain the specific `network.organization` details along with the orderer information.
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:

- `<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.

For reference, see `network-fabric-add-channel.yaml` file [here](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/configuration/samples).
1. **Create channel for Hyperledger Fabric 2.5.x**

<a name = "run_network"></a>
## Run playbook
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:

The [add-new-channel.yaml](https://github.com/hyperledger/bevel/tree/main/platforms/shared/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
- `<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.

```
ansible-playbook platforms/hyperledger-fabric/configuration/add-new-channel.yaml --extra-vars "@path-to-network.yaml"
```
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:

---
**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.
- `<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.

1. **Create channel for Hyperledger Fabric 2.2.x**

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.
45 changes: 16 additions & 29 deletions docs/source/guides/fabric/add-new-orderer-org.md
View file
Original file line number Diff line number Diff line change
@@ -7,17 +7,16 @@
# Adding a new Orderer organization in Hyperledger Fabric

- [Prerequisites](#prerequisites)
- [Modifying configuration file](#create_config_file)
- [Running playbook to deploy Hyperledger Fabric network](#run_network)

- [Modifying Configuration File](#modifying-configuration-file)
- [Run playbook](#run-playbook)

<a name = "prerequisites"></a>
## Prerequisites
To add a new Orderer organization, a fully configured Fabric network must be present already setup, 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.

---
**NOTE**: Addition of a new Orderer organization has been tested on an existing network which is created by Bevel. Networks created using other methods may be suitable but this has not been tested by Bevel team.
Addition of new Orderer organization only works with Fabric 2.2.2 and RAFT Service.
Addition of new Orderer organization only works with Fabric 2.2.2, 2.5.4 and RAFT Service.

---

@@ -28,38 +27,26 @@ Refer [this guide](../networkyaml-fabric.md) for details on editing the configur

While modifying the configuration file(`network.yaml`) for adding new orderer organization, all the existing organizations should have `org_status` tag as `existing` and the new organization should have `org_status` tag as `new` under `network.channels` e.g.

network:
channels:
- channel:
..
..
participants:
- organization:
..
..
org_status: new # new for new organization(s)
- organization:
..
..
org_status: existing # existing for old organization(s)

```yaml
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-ordererorg.yaml:64:138"
```

and under `network.organizations` as

network:
organizations:
- organization:
..
..
org_status: new # new for new organization(s)
- organization:
..
..
org_status: existing # existing for old organization(s)
```yaml
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-ordererorg.yaml:145:154"
..
..
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-ordererorg.yaml:230:239"
..
..
```

The `network.yaml` file should contain the specific `network.organization` details along with the orderer information.


For reference, see `network-fabric-add-ordererorg.yaml` file [here](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/configuration/add-orderer-organization.yaml).
For reference, see `network-fabric-add-ordererorg.yaml` file [here](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/configuration/samples/network-fabric-add-ordererorg.yaml).

<a name = "run_network"></a>
## Run playbook
38 changes: 17 additions & 21 deletions docs/source/guides/fabric/add-new-orderer-peer.md
View file
Original file line number Diff line number Diff line change
@@ -6,10 +6,9 @@
<a name = "adding-new-orderer-to-existing-organization-in-a-running-fabric-network"></a>
# Adding a new RAFT orderer to existing Orderer organization in Hyperledger Fabric

- [Prerequisites](#prerequisites)
- [Modifying Configuration File](#modifying-configuration-file)
- [Run playbook](#run-playbook)
- [Chaincode Installation](#chaincode-installation)
- [Prerequisites](#prerequisites)
- [Modifying Configuration File](#modifying-configuration-file)
- [Run playbook](#run-playbook)


<a name = "prerequisites"></a>
@@ -31,24 +30,21 @@ For generic instructions on the Fabric configuration file, refer [this guide](..

While modifying the configuration file(`network.yaml`) for adding new peer, all the existing orderers should have `status` tag as `existing` and the new orderers should have `status` tag as `new` under `network.organizations` as

network:
organizations:
- organization:
org_status: existing # org_status must be existing when adding peer
..
..
services:
orderers:
- orderer:
..
..
status: new # new for new peers(s)
- orderer:
..
..
status: existing # existing for existing peers(s)
```yaml

--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabricv2-raft-add-orderer.yaml:126:135"
..
..
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabricv2-raft-add-orderer.yaml:174:174"
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabricv2-raft-add-orderer.yaml:185:220"

```
and under `network.orderers` the new orderer must be added.

```yaml
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabricv2-raft-add-orderer.yaml:42:66"
```
The `network.yaml` file should contain the specific `network.organization` details.

Ensure the following is considered when adding the new orderer on a different cluster:
42 changes: 15 additions & 27 deletions docs/source/guides/fabric/add-new-org.md
View file
Original file line number Diff line number Diff line change
@@ -7,8 +7,8 @@
# Adding a new organization in Hyperledger Fabric

- [Prerequisites](#prerequisites)
- [Modifying configuration file](#create_config_file)
- [Running playbook to deploy Hyperledger Fabric network](#run_network)
- [Modifying Configuration File](#modifying-configuration-file)
- [Run playbook](#run-playbook)


<a name = "prerequisites"></a>
@@ -27,38 +27,26 @@ Refer [this guide](../networkyaml-fabric.md) for details on editing the configur

While modifying the configuration file(`network.yaml`) for adding new organization, all the existing organizations should have `org_status` tag as `existing` and the new organization should have `org_status` tag as `new` under `network.channels` e.g.

network:
channels:
- channel:
..
..
participants:
- organization:
..
..
org_status: new # new for new organization(s)
- organization:
..
..
org_status: existing # existing for old organization(s)
```yaml
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-organization.yaml:65:139"
```

and under `network.organizations` as

network:
organizations:
- organization:
..
..
org_status: new # new for new organization(s)
- organization:
..
..
org_status: existing # existing for old organization(s)
```yaml
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-organization.yaml:144:155"
..
..
--8<-- "platforms/hyperledger-fabric/configuration/samples/network-fabric-add-organization.yaml:406:414"
..
..

```

The `network.yaml` file should contain the specific `network.organization` details along with the orderer information.


For reference, see `network-fabric-add-organization.yaml` file [here](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/configuration/samples).
For reference, see `network-fabric-add-organization.yaml` file [here](https://github.com/hyperledger/bevel/tree/main/platforms/hyperledger-fabric/configuration/samples/network-fabric-add-organization.yaml).

<a name = "run_network"></a>
## Run playbook
Loading

0 comments on commit c62e8fe

Please sign in to comment.