Skip to content

Commit

Permalink
[docs] Updated for latest release
Browse files Browse the repository at this point in the history
Signed-off-by: sownak.roy <[email protected]>
  • Loading branch information
sownak.roy authored and suvajit-sarkar committed Jul 3, 2024
1 parent fb1913c commit d5efd51
Show file tree
Hide file tree
Showing 16 changed files with 132 additions and 60 deletions.
6 changes: 3 additions & 3 deletions docs/mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion docs/source/concepts/ansible.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
10 changes: 8 additions & 2 deletions docs/source/concepts/features.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions docs/source/concepts/gitops.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/source/concepts/sequence-diagram.md
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
Expand Down
4 changes: 4 additions & 0 deletions docs/source/concepts/vault.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 3 additions & 7 deletions docs/source/getting-started/configure-prerequisites.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion docs/source/getting-started/prerequisites-machine.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
42 changes: 27 additions & 15 deletions docs/source/getting-started/prerequisites.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
25 changes: 19 additions & 6 deletions docs/source/getting-started/run-bevel.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion docs/source/guides/networkyaml-corda.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ The fields under `docker` section are
| password | Password or Access token required for login |

!!! note
Please follow [these instructions](../getting-started/configure-prerequisites.md#docker) to build and store the docker images before running the Ansible playbooks.
Please follow [these instructions](../getting-started/configure-prerequisites.md#docker-images) to build and store the docker images before running the Ansible playbooks.

<a name="network_services"></a>
network_services
Expand Down
2 changes: 1 addition & 1 deletion docs/source/guides/networkyaml-fabric.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ The fields under `docker` section are

!!! tip

Please follow [these instructions](../getting-started/configure-prerequisites.md#docker) to build and store the docker images before running the Ansible playbooks.
Please follow [these instructions](../getting-started/configure-prerequisites.md#docker-images) to build and store the docker images before running the Ansible playbooks.

<a name="consensus"></a>
consensus
Expand Down
2 changes: 1 addition & 1 deletion docs/source/guides/networkyaml-indy.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ The fields under `docker` section are

!!! tip

Please follow [these instructions](../getting-started/configure-prerequisites.md#docker) to build and store the docker images before running the Ansible playbooks.
Please follow [these instructions](../getting-started/configure-prerequisites.md#docker-images) to build and store the docker images before running the Ansible playbooks.

<a name="name"></a>
name
Expand Down
Loading

0 comments on commit d5efd51

Please sign in to comment.