Add files via upload

SyedMuhamadYasir · Jun 30, 2023 · 7154f75 · 7154f75
1 parent f7b331a
commit 7154f75
Show file tree

Hide file tree

Showing 3 changed files with 362 additions and 0 deletions.
diff --git a/configuration/secret-managers/set-up-aws-ssm.md b/configuration/secret-managers/set-up-aws-ssm.md
@@ -0,0 +1,133 @@
+---
+id: set-up-aws-ssm
+title: Set up AWS SSM (Systems Manager)
+description: "Set up AWS SSM (Systems Manager) for Polygon Edge."
+keywords:
+  - docs
+  - polygon
+  - edge
+  - aws
+  - ssm
+  - secrets
+  - manager
+---
+
+## Overview
+
+Currently, the Polygon Edge is concerned with keeping 2 major runtime secrets:
+* The **validator private key** used by the node, if the node is a validator
+* The **networking private key** used by libp2p, for participating and communicating with other peers
+
+For additional information, please read through the [Managing Private Keys Guide](/docs/edge/configuration/manage-private-keys)
+
+The modules of the Polygon Edge **should not need to know how to keep secrets**. Ultimately, a module should not care if
+a secret is stored on a far-away server or locally on the node's disk.
+
+Everything a module needs to know about secret-keeping is **knowing to use the secret**, **knowing which secrets to get
+or save**. The finer implementation details of these operations are delegated away to the `SecretsManager`, which of course is an abstraction.
+
+The node operator that's starting the Polygon Edge can now specify which secrets manager they want to use, and as soon
+as the correct secrets manager is instantiated, the modules deal with the secrets through the mentioned interface -
+without caring if the secrets are stored on a disk or on a server.
+
+This article details the necessary steps to get the Polygon Edge up and running with
+[AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html).
+
+:::info previous guides
+It is **highly recommended** that before going through this article, articles on [**Local Setup**](/docs/edge/get-started/set-up-ibft-locally)
+and [**Cloud Setup**](/docs/edge/get-started/set-up-ibft-on-the-cloud) are read.
+:::
+
+
+## Prerequisites
+### IAM Policy
+User needs to create an IAM Policy that allows read/write operations for AWS Systems Manager Parameter Store.
+After successfully creating IAM Policy, the user needs to attach it to the EC2 instance that is running the Polygon Edge server.
+The IAM Policy should look something like this:
+```json
+{
+  "Version": "2012-10-17",
+  "Statement" : [
+    {
+      "Effect" : "Allow",
+      "Action" : [
+        "ssm:PutParameter",
+        "ssm:DeleteParameter",
+        "ssm:GetParameter"
+      ],
+      "Resource" : [
+        "arn:aws:ssm:<aws_region>:<aws_account_id>:parameter<ssm-parameter-path>*"
+      ]
+    }
+  ]
+}
+```
+More information on AWS SSM IAM Roles you can find in the [AWS docs](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html).
+
+Required information before continuing:
+* **Region** (the region in which Systems Manager and nodes reside)
+* **Parameter Path** (arbitrary path that the secret will be placed in, for example `/polygon-edge/nodes`)
+
+## Step 1 - Generate the secrets manager configuration
+
+In order for the Polygon Edge to be able to seamlessly communicate with the AWS SSM, it needs to parse an already
+generated config file, which contains all the necessary information for secret storage on AWS SSM.
+
+To generate the configuration, run the following command:
+
+```bash
+polygon-edge secrets generate --type aws-ssm --dir <PATH> --name <NODE_NAME> --extra region=<REGION>,ssm-parameter-path=<SSM_PARAM_PATH>
+```
+
+Parameters present:
+* `PATH` is the path to which the configuration file should be exported to. Default `./secretsManagerConfig.json`
+* `NODE_NAME` is the name of the current node for which the AWS SSM configuration is being set up as. It can be an arbitrary value. Default `polygon-edge-node`
+* `REGION` is the region in which the AWS SSM resides. This has to be the same region as the node utilizing AWS SSM.
+* `SSM_PARAM_PATH` is the name of the path that the secret will be stored in. For example if `--name node1` and `ssm-parameter-path=/polygon-edge/nodes`
+are specified, the secret will be stored as `/polygon-edge/nodes/node1/<secret_name>`
+
+:::caution Node names
+Be careful when specifying node names.
+
+The Polygon Edge uses the specified node name to keep track of the secrets it generates and uses on the AWS SSM.
+Specifying an existing node name can have consequences of failing to write secret to AWS SSM.
+
+Secrets are stored on the following base path: `SSM_PARAM_PATH/NODE_NAME`
+:::
+
+## Step 2 - Initialize secret keys using the configuration
+
+Now that the configuration file is present, we can initialize the required secret keys with the configuration
+file set up in step 1, using the `--config`:
+
+```bash
+polygon-edge secrets init --config <PATH>
+```
+
+The `PATH` param is the location of the previously generated secrets manager param from step 1.
+
+:::info IAM Policy
+This step will fail if IAM Policy that allows read/write operations is not configured correctly and/or not attached to the EC2 instance running this command. 
+:::
+
+## Step 3 - Generate the genesis file
+
+The genesis file should be generated in a similar manner to the [**Local Setup**](/docs/edge/get-started/set-up-ibft-locally)
+and [**Cloud Setup**](/docs/edge/get-started/set-up-ibft-on-the-cloud) guides, with minor changes.
+
+Since AWS SSM is being used instead of the local file system, validator addresses should be added through the `--ibft-validator` flag:
+```bash
+polygon-edge genesis --ibft-validator <VALIDATOR_ADDRESS> ...
+```
+
+## Step 4 - Start the Polygon Edge client
+
+Now that the keys are set up, and the genesis file is generated, the final step to this process would be starting the
+Polygon Edge with the `server` command.
+
+The `server` command is used in the same manner as in the previously mentioned guides, with a minor addition - the `--secrets-config` flag:
+```bash
+polygon-edge server --secrets-config <PATH> ...
+```
+
+The `PATH` param is the location of the previously generated secrets manager param from step 1.
diff --git a/configuration/secret-managers/set-up-gcp-secrets-manager.md b/configuration/secret-managers/set-up-gcp-secrets-manager.md
@@ -0,0 +1,117 @@
+---
+id: set-up-gcp-secrets-manager
+title: Set up GCP Secrets Manager
+description: "Set up GCP Secrets Manager for Polygon Edge."
+keywords:
+  - docs
+  - polygon
+  - edge
+  - gcp
+  - secrets
+  - manager
+---
+
+## Overview
+
+Currently, the Polygon Edge is concerned with keeping 2 major runtime secrets:
+* The **validator private key** used by the node, if the node is a validator
+* The **networking private key** used by libp2p, for participating and communicating with other peers
+
+For additional information, please read through the [Managing Private Keys Guide](/docs/edge/configuration/manage-private-keys)
+
+The modules of the Polygon Edge **should not need to know how to keep secrets**. Ultimately, a module should not care if
+a secret is stored on a far-away server or locally on the node's disk.
+
+Everything a module needs to know about secret-keeping is **knowing to use the secret**, **knowing which secrets to get
+or save**. The finer implementation details of these operations are delegated away to the `SecretsManager`, which of course is an abstraction.
+
+The node operator that's starting the Polygon Edge can now specify which secrets manager they want to use, and as soon
+as the correct secrets manager is instantiated, the modules deal with the secrets through the mentioned interface -
+without caring if the secrets are stored on a disk or on a server.
+
+This article details the necessary steps to get the Polygon Edge up and running with [GCP Secret Manager](https://cloud.google.com/secret-manager).
+
+:::info previous guides
+It is **highly recommended** that before going through this article, articles on [**Local Setup**](/docs/edge/get-started/set-up-ibft-locally)
+and [**Cloud Setup**](/docs/edge/get-started/set-up-ibft-on-the-cloud) are read.
+:::
+
+
+## Prerequisites
+### GCP Billing Account
+In order to utilize GCP Secrets Manager, the user has to have [Billing Account](https://console.cloud.google.com/) enabled on the GCP portal.
+New Google accounts on GCP platform are provided with some funds to get started, as a king of free trial.
+More info [GCP docs](https://cloud.google.com/free)
+
+### Secrets Manager API
+The user will need to enable the GCP Secrets Manager API, before he can use it.
+This can be done via [Secrets Manager API portal](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com).
+More info: [Configuring Secret Manger](https://cloud.google.com/secret-manager/docs/configuring-secret-manager)
+
+### GCP Credentials
+Finally, the user needs to generate new credentials that will be used for authentication.
+This can be done by following the instructions posted [here](https://cloud.google.com/secret-manager/docs/reference/libraries).   
+The generated json file containing credentials, should be transferred to each node that needs to utilize GCP Secrets Manager.
+
+Required information before continuing:
+* **Project ID** (the project id defined on GCP platform)
+* **Credentials File Location** (the path to the json file containing the credentials)
+
+## Step 1 - Generate the secrets manager configuration
+
+In order for the Polygon Edge to be able to seamlessly communicate with the GCP SM, it needs to parse an already
+generated config file, which contains all the necessary information for secret storage on GCP SM.
+
+To generate the configuration, run the following command:
+
+```bash
+polygon-edge secrets generate --type gcp-ssm --dir <PATH> --name <NODE_NAME> --extra project-id=<PROJECT_ID>,gcp-ssm-cred=<GCP_CREDS_FILE>
+```
+
+Parameters present:
+* `PATH` is the path to which the configuration file should be exported to. Default `./secretsManagerConfig.json`
+* `NODE_NAME` is the name of the current node for which the GCP SM configuration is being set up as. It can be an arbitrary value. Default `polygon-edge-node`
+* `PROJECT_ID` is the ID of the project the user has defined in GCP console during account setup and Secrets Manager API activation.
+* `GCP_CREDS_FILE` is the path to the json file containing credentials which will allow read/write access to the Secrets Manager.
+
+:::caution Node names
+Be careful when specifying node names.
+
+The Polygon Edge uses the specified node name to keep track of the secrets it generates and uses on the GCP SM.
+Specifying an existing node name can have consequences of failing to write secret to GCP SM.
+
+Secrets are stored on the following base path: `projects/PROJECT_ID/NODE_NAME`
+:::
+
+## Step 2 - Initialize secret keys using the configuration
+
+Now that the configuration file is present, we can initialize the required secret keys with the configuration
+file set up in step 1, using the `--config`:
+
+```bash
+polygon-edge secrets init --config <PATH>
+```
+
+The `PATH` param is the location of the previously generated secrets manager param from step 1.
+
+## Step 3 - Generate the genesis file
+
+The genesis file should be generated in a similar manner to the [**Local Setup**](/docs/edge/get-started/set-up-ibft-locally)
+and [**Cloud Setup**](/docs/edge/get-started/set-up-ibft-on-the-cloud) guides, with minor changes.
+
+Since GCP SM is being used instead of the local file system, validator addresses should be added through the `--ibft-validator` flag:
+```bash
+polygon-edge genesis --ibft-validator <VALIDATOR_ADDRESS> ...
+```
+
+## Step 4 - Start the Polygon Edge client
+
+Now that the keys are set up, and the genesis file is generated, the final step to this process would be starting the
+Polygon Edge with the `server` command.
+
+The `server` command is used in the same manner as in the previously mentioned guides, with a minor addition - the `--secrets-config` flag:
+```bash
+polygon-edge server --secrets-config <PATH> ...
+```
+
+The `PATH` param is the location of the previously generated secrets manager param from step 1.
diff --git a/configuration/secret-managers/set-up-hashicorp-vault.md b/configuration/secret-managers/set-up-hashicorp-vault.md
@@ -0,0 +1,112 @@
+---
+id: set-up-hashicorp-vault
+title: Set up Hashicorp Vault
+description: "Set up the Hashicorp Vault for Polygon Edge."
+keywords:
+  - docs
+  - polygon
+  - edge
+  - hashicorp
+  - vault
+  - secrets
+  - manager
+---
+
+## Overview
+
+Currently, the Polygon Edge is concerned with keeping 2 major runtime secrets:
+* The **validator private key** used by the node, if the node is a validator
+* The **networking private key** used by libp2p, for participating and communicating with other peers
+
+:::warning
+The validator private key is unique to each validator node. The same key is <b>not</b> to be shared across all validators, as this may compromise the security of your chain.
+:::
+
+For additional information, please read through the [Managing Private Keys Guide](/docs/edge/configuration/manage-private-keys)
+
+The modules of the Polygon Edge **should not need to know how to keep secrets**. Ultimately, a module should not care if 
+a secret is stored on a far-away server or locally on the node's disk.
+
+Everything a module needs to know about secret-keeping is **knowing to use the secret**, **knowing which secrets to get 
+or save**. The finer implementation details of these operations are delegated away to the `SecretsManager`, which of course is an abstraction.
+
+The node operator that's starting the Polygon Edge can now specify which secrets manager they want to use, and as soon 
+as the correct secrets manager is instantiated, the modules deal with the secrets through the mentioned interface - 
+without caring if the secrets are stored on a disk or on a server.
+
+This article details the necessary steps to get the Polygon Edge up and running with a [Hashicorp Vault](https://www.vaultproject.io/) server.
+
+:::info previous guides
+It is **highly recommended** that before going through this article, articles on [**Local Setup**](/docs/edge/get-started/set-up-ibft-locally) 
+and [**Cloud Setup**](/docs/edge/get-started/set-up-ibft-on-the-cloud) are read.
+:::
+
+
+## Prerequisites
+
+This article assumes that a functioning instance of the Hashicorp Vault server **is already set up**.
+
+Additionally, it is required that the Hashicorp Vault server being used for the Polygon Edge should have **enabled KV storage**.
+
+Required information before continuing:
+* **The server URL** (the API URL of the Hashicorp Vault server)
+* **Token** (access token used for access to the KV storage engine)
+
+## Step 1 - Generate the secrets manager configuration
+
+In order for the Polygon Edge to be able to seamlessly communicate with the Vault server, it needs to parse an already
+generated config file, which contains all the necessary information for secret storage on Vault.
+
+To generate the configuration, run the following command:
+
+```bash
+polygon-edge secrets generate --dir <PATH> --token <TOKEN> --server-url <SERVER_URL> --name <NODE_NAME>
+```
+
+Parameters present:
+* `PATH` is the path to which the configuration file should be exported to. Default `./secretsManagerConfig.json`
+* `TOKEN` is the access token previously mentioned in the [prerequisites section](/docs/edge/configuration/secret-managers/set-up-hashicorp-vault#prerequisites)
+* `SERVER_URL` is the URL of the API for the Vault server, also mentioned in the [prerequisites section](/docs/edge/configuration/secret-managers/set-up-hashicorp-vault#prerequisites)
+* `NODE_NAME` is the name of the current node for which the Vault configuration is being set up as. It can be an arbitrary value. Default `polygon-edge-node`
+
+:::caution Node names
+Be careful when specifying node names.
+
+The Polygon Edge uses the specified node name to keep track of the secrets it generates and uses on the Vault instance.
+Specifying an existing node name can have consequences of data being overwritten on the Vault server.
+
+Secrets are stored on the following base path: `secrets/node_name`
+:::
+
+## Step 2 - Initialize secret keys using the configuration
+
+Now that the configuration file is present, we can initialize the required secret keys with the configuration 
+file set up in step 1, using the `--config`:
+
+```bash
+polygon-edge secrets init --config <PATH>
+```
+
+The `PATH` param is the location of the previously generated secrets manager param from step 1.
+
+## Step 3 - Generate the genesis file
+
+The genesis file should be generated in a similar manner to the [**Local Setup**](/docs/edge/get-started/set-up-ibft-locally)
+and [**Cloud Setup**](/docs/edge/get-started/set-up-ibft-on-the-cloud) guides, with minor changes.
+
+Since Hashicorp Vault is being used instead of the local file system, validator addresses should be added through the `--ibft-validator` flag:
+```bash
+polygon-edge genesis --ibft-validator <VALIDATOR_ADDRESS> ...
+```
+
+## Step 4 - Start the Polygon Edge client
+
+Now that the keys are set up, and the genesis file is generated, the final step to this process would be starting the 
+Polygon Edge with the `server` command.
+
+The `server` command is used in the same manner as in the previously mentioned guides, with a minor addition - the `--secrets-config` flag:
+```bash
+polygon-edge server --secrets-config <PATH> ...
+```
+
+The `PATH` param is the location of the previously generated secrets manager param from step 1.