AWS Blockchain Templates was discontinued on April 30, 2019. No further updates to this service or this supporting documentation will be made. For the best Managed Blockchain experience on AWS, we recommend that you use [ Amazon Managed Blockchain (AMB)](https://aws.amazon.com/managed-blockchain/). To learn more about getting started with Amazon Managed Blockchain, see our [ workshop on Hyperledger Fabric](https://catalog.us-east-1.prod.workshops.aws/workshops/008da2cb-8454-42d0-877b-bc290bff7fcf/en-US), or our [blog on deploying an Ethereum node](https://aws.amazon.com/blogs/database/deploy-an-ethereum-node-on-amazon-managed-blockchain/). If you have questions about AMB or require further support, [contact Support](https://console.aws.amazon.com/support/home#/case/create?issueType=technical) or your AWS account team. # AWS Blockchain Templates and Features This section provides links for you to begin creating a blockchain network right away, as well as information about configuration options and prerequisites for setting up the network on AWS. The following templates are available: + [AWS Blockchain Template for Ethereum](https://docs.aws.amazon.com/blockchain-templates/latest/developerguide/blockchain-templates-ethereum.html) + [AWS Blockchain Template for Hyperledger Fabric](https://docs.aws.amazon.com/blockchain-templates/latest/developerguide/blockchain-templates-hyperledger.html) AWS Blockchain Templates is available in the following Regions: + US West (Oregon) Region (us-west-2) + US East (N. Virginia) Region (us-east-1) + US East (Ohio) Region (us-east-2) **Note** Running a template in a Region not listed above launches resources in the US East (N. Virginia) Region (us-east-1). # Using the AWS Blockchain Template for Ethereum AWS Blockchain Template for Ethereum Ethereum is a blockchain framework that runs smart contracts using Solidity, an Ethereum-specific language. Homestead is the most recent release of Ethereum. For more information, see the [Ethereum Homestead Documentation](http://www.ethdocs.org/en/latest/) and the [Solidity](https://solidity.readthedocs.io/en/v0.4.21/#) documentation. ## Links to Launch See [Getting Started with AWS Blockchain Templates](https://aws.amazon.com/blockchain/templates/getting-started/) for links to launch CloudFormation in specific Regions using the Ethereum templates. ## Ethereum Options When you configure the Ethereum network using the template, you make choices that determine the subsequent requirements: + [Choosing the Container Platform](#blockchain-ethereum-platform) + [Choosing a Private or Public Ethereum Network](#blockchain-private-public) + [Changing the Default Accounts and Mnemonic Phrase](#blockchain-ethereum-mnemonic) ### Choosing the Container Platform AWS Blockchain Templates use Docker containers stored in Amazon ECR to deploy blockchain software. The AWS Blockchain Template for Ethereum offers two choices for the **Container Platform **: + **ecs**—Specifies that Ethereum runs on an Amazon ECS cluster of Amazon EC2 instances. + **docker-local**—Specifies that Ethereum runs on a single EC2 instance. #### Using the Amazon ECS Container Platform With Amazon ECS, you create your Ethereum network on an ECS cluster composed of multiple EC2 instances, with an Application Load Balancer and related resources. For more information about using the Amazon ECS configuration, see the [Getting Started with AWS Blockchain Templates](blockchain-templates-getting-started.md) tutorial. The following diagram depicts an Ethereum network created using the template with the ECS container platform option: ![\[AWS diagram showing VPC with public and private subnets, load balancers, and Ethereum nodes in ECS containers.\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/images/ethereum-ecs-arch.png) #### Using the Docker-Local Platform Alternatively, you can launch Ethereum containers within a single Amazon EC2 instance. All containers run on a single EC2 instance. This is a simplified setup. The following diagram depicts an Ethereum network created using the template with the docker-local container platform option: ![\[Diagram of Ethereum network on AWS with VPC, EC2 instance, containers, and ECR registry.\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/images/ethereum-docker-local-arch.png) ### Choosing a Private or Public Ethereum Network Choosing an **Ethereum Network ID** value other than 1–4 creates private Ethereum nodes that run within a network that you define, using the private network parameters that you specify. When you choose an **Ethereum Network ID** from 1–4, the Ethereum nodes that you create are joined to the public Ethereum network. You can ignore private network settings and their defaults. If you choose to join Ethereum nodes to the public Ethereum network, ensure that the appropriate services in your network are internet-accessible. ### Changing the Default Accounts and Mnemonic Phrase A mnemonic phrase is a random set of words that you can use to generate Ethereum wallets (that is, private/public key pairs) for associated accounts on any network. The mnemonic phrase can be used to access Ether for associated accounts. We created a default mnemonic associated with the default accounts that the Ethereum template uses. **Warning** Use the default accounts and associated mnemonic phrase for testing purposes only. Do not send real Ether using the default set of accounts because anyone with access to the mnemonic phrase can access or steal Ether from the accounts. Instead, specify custom accounts for production purposes. The mnemonic phrase associated with the default account is `outdoor father modify clever trophy abandon vital feel portion grit evolve twist`. ## Prerequisites When you set up your Ethereum network using the AWS Blockchain Template for Ethereum, the minimum requirements listed below must be satisfied. The template requires the AWS components listed for each of the following categories: **Topics** + [ ### Prerequisites for Accessing Ethereum Resources ](#blockchain-ethereum-prereq-access) + [ ### IAM Prerequisites ](#blockchain-ethereum-prereq-iam) + [ ### Security Group Prerequisites ](#blockchain-ethereum-prereq-sec) + [ ### VPC Prerequisites ](#blockchain-ethereum-prereq-vpc) + [ ### Example IAM Permissions for the EC2 Instance Profile and ECS Role ](#blockchain-ethereum-iam-examples) ### Prerequisites for Accessing Ethereum Resources | Prerequisite | For ECS Platform | For Docker-Local | | --- | --- | --- | | An Amazon EC2 key pair that you can use to access EC2 instances. The key must exist in the same Region as the ECS cluster and other resources. | ✔ | ✔ | | An internet-facing component, such as a bastion host or an internet-facing load balancer, with an internal address from which traffic is allowed into the Application Load Balancer. This is required with the ECS platform because the template creates an internal load balancer for security reasons. This is required with the docker-local platform when the EC2 instance is in a private subnet, which we recommend. For information about configuring a bastion host, see [Create a Bastion Host](blockchain-template-getting-started-prerequisites.md#blockchain-templates-bastion-host). | ✔ | ✔ (with private subnet) | ### IAM Prerequisites | Prerequisite | For ECS Platform | For Docker-Local | | --- | --- | --- | | An IAM principal (user or group) that has permissions to work with all related services. | ✔ | ✔ | | An Amazon EC2 instance profile with appropriate permissions for EC2 instances to interact with other services. For more information, see [To create an EC2 instance profile](blockchain-template-getting-started-prerequisites.md#create-ec2-role). | ✔ | ✔ | | An IAM role with permissions for Amazon ECS to interact with other services. For more information, see [Creating the ECS Role and Permissions](#blockchain-ethereum-ecs-role). | ✔ | | ### Security Group Prerequisites | Prerequisite | For ECS Platform | For Docker-Local | | --- | --- | --- | | A security group for EC2 instances, with the following requirements: | ✔ | ✔ | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/blockchain-templates-ethereum.html) | ✔ | ✔ | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/blockchain-templates-ethereum.html) | ✔ | ✔ | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/blockchain-templates-ethereum.html) | ✔ | | | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/blockchain-templates-ethereum.html) | | ✔ | | A security group for the Application Load Balancer, with the following requirements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/blockchain-templates-ethereum.html) | ✔ | | ### VPC Prerequisites | Prerequisite | For ECS Platform | For Docker-Local | | --- | --- | --- | | An Elastic IP address, which is used for accessing Ethereum services. | ✔ | ✔ | | A subnet to run EC2 instances. We strongly recommend a private subnet. | ✔ | ✔ | | Two publicly accessible subnets. Each subnet must be in different Availability Zones from each other, with one in the same Availability Zone as the subnet for EC2 instances. | ✔ | | ### Example IAM Permissions for the EC2 Instance Profile and ECS Role You specify an EC2 instance profile ARN as one of the parameters when you use the template. If you use the ECS container platform, you also specify an ECS role ARN. The permissions policies attached to these roles allow the AWS resources and instances in your cluster to interact with other AWS resources. For more information, see [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *IAM User Guide*. Use the policy statements and procedures below as a starting point for creating permissions. #### Example Permissions Policy for the EC2 Instance Profile The following permissions policy demonstrates allowed actions for the EC2 instance profile when you choose the ECS container platform. The same policy statements can be used in a docker-local container platform, with `ecs` context keys removed to limit access. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecs:CreateCluster", "ecs:DeregisterContainerInstance", "ecs:DiscoverPollEndpoint", "ecs:Poll", "ecs:RegisterContainerInstance", "ecs:StartTelemetrySession", "ecs:Submit*", "ecr:GetAuthorizationToken", "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage", "logs:CreateLogStream", "logs:PutLogEvents", "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem", "dynamodb:PutItem", "dynamodb:DeleteItem", "dynamodb:GetItem", "dynamodb:Scan", "dynamodb:Query", "dynamodb:UpdateItem" ], "Resource": "*" } ] } ``` #### Creating the ECS Role and Permissions For the permissions attached to the ECS role, we recommend that you start with the **AmazonEC2ContainerServiceRole** permissions policy. Use the following procedure to create a role and attach this permissions policy. Use the IAM console to view the most up-to-date permissions in this policy. **To create the IAM role for Amazon ECS** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles**, **Create Role**. 1. Under **Select type of trusted entity**, choose **AWS service**. 1. For **Choose the service that will use this role**, choose **Elastic Container Service**. 1. Under **Select your use case**, choose **Elastic Container Service**, **Next:Permissions**. ![\[AWS console interface for creating a role, with Elastic Container Service selected as the use case.\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/images/ecs-role.png) 1. For **Permissions policy**, leave the default policy (**AmazonEC2ContainerServiceRole**) selected, and choose **Next:Review**. 1. For **Role name**, enter a value that helps you identify the role, such as *ECSRoleForEthereum*. For **Role Description**, enter a brief summary. Note the role name for later. 1. Choose **Create role**. 1. Select the role that you just created from the list. If your account has many roles, you can search for the role name. ![\[AWSIAM console showing a role named "ECSRoleForEtherum" with its description.\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/images/ecs-role-list.png) 1. Copy the **Role ARN** value and save it so that you can copy it again. You need this ARN when you create the Ethereum network. ![\[AWSIAM role summary page showing role ARN, description, and attached policies.\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/images/ecs-role-arn.png) ## Connecting to Ethereum Resources After the root stack that you create with the template shows **CREATE\$1COMPLETE**, you can connect to Ethereum resources using the CloudFormation console. How you connect depends on the container platform that you choose, ECS or docker-local: + **ECS**—The **Output** tab of the root stack provides links to services running on the Application Load Balancer. These URLs are not directly accessible for security reasons. To connect, you can set up and use a *bastion host* to proxy connections to them. For more information, see [Proxy Connections Using a Bastion Host](#ethereum-create-bastion-host) below. + **docker-local**—You connect using the IP address of the EC2 instance hosting Ethereum services as listed below. Use the EC2 console to find the *ec2-IP-address* of the instance that the template created. + **EthStats**—Use http://*ec2-IP-address* + **EthExplorer**—Use http://*ec2-IP-address*:8080 + **EthJsonRpc**—Use http://*ec2-IP-address*:8545 If you specified a public subnet for **Ethereum Network Subnet ID** (**List of VPC Subnets to use** within the template), you can connect directly. Your client must be a trusted source of inbound traffic for SSH (port 22), as well as the ports listed. This is determined by the **EC2 Security Group** that you specified using the AWS Blockchain Template for Ethereum. If you specified a private subnet, you can set up and use a *bastion host* to proxy connections to these addresses. For more information, see [Proxy Connections Using a Bastion Host](#ethereum-create-bastion-host) below. ### Proxy Connections Using a Bastion Host With some configurations, Ethereum services may not be publicly available. In those cases, you can connect to Ethereum resources through a *bastion host*. For more information about bastion hosts, see [Linux Bastion Host Architecture](https://docs.aws.amazon.com/quickstart/latest/linux-bastion/architecture.html) in the *Linux Bastion Host Quick Start Guide*. The bastion host is an EC2 instance. Make sure that the following requirements are met: + The EC2 instance for the bastion host is within a public subnet with Auto-assign Public IP enabled and that has an internet gateway. + The bastion host has the key pair that allows ssh connections. + The bastion host is associated with a security group that allows inbound SSH traffic from the clients that connect. + The security group assigned to the Ethereum hosts (for example, the Application Load Balancer if ECS is the container platform, or the host EC2 instance if docker-local is the container platform) allows inbound traffic on all ports from sources within the VPC. With a bastion host set up, ensure that the clients that connect use the bastion host as a proxy. The following example demonstrates setting up a proxy connection using Mac OS. Replace *BastionIP* with the IP address of the bastion host EC2 instance and *MySshKey.pem* with the key pair file that you copied to the bastion host. On the command line, type the following: ``` ssh -i mySshKey.pem ec2-user@BastionIP -D 9001 ``` This sets up port forwarding for port 9001 on the local machine to the bastion host. Next, configure your browser or system to use SOCKS proxy for `localhost:9001`. For example, using Mac OS, select **System Preferences**, **Network**, **Advanced**, select **SOCKS proxy**, and type **localhost:9001**. Using FoxyProxy Standard with Chrome, select **More Tools**, **Extensions**. Under **FoxyProxy Standard**, select **Details**, **Extension options**, **Add New Proxy**. Select **Manual Proxy Configuration**. For **Host or IP Address** type **localhost** and for **Port** type **9001**. Select **SOCKS proxy?**, **Save**. You should now be able to connect to the Ethereum host addresses listed in the template output. # Using the AWS Blockchain Template for Hyperledger Fabric AWS Blockchain Template for Hyperledger Fabric Hyperledger Fabric is a blockchain framework that runs smart contracts called chaincode, which are written in Go. You can create a private network with Hyperledger Fabric, limiting the peers that can connect to and participate in the network. For more information about Hyperledger Fabric, see the [Hyperledger Fabric](https://hyperledger-fabric.readthedocs.io/en/release-1.1/) documentation. For more information about chaincode, see the [Chaincode for Developers](https://hyperledger-fabric.readthedocs.io/en/release-1.1/chaincode4ade.html) topic in the [Hyperledger Fabric](https://hyperledger-fabric.readthedocs.io/en/release-1.1/) documentation. The AWS Blockchain Template for Hyperledger Fabric only supports a *docker-local* container platform, meaning the Hyperledger Fabric containers are deployed on a single EC2 instance. ## Links to Launch See [Getting Started with AWS Blockchain Templates](https://aws.amazon.com/blockchain/templates/getting-started/) for links to launch CloudFormation in specific Regions using the Hyperledger Fabric templates. ## AWS Blockchain Template for Hyperledger Fabric Components The AWS Blockchain Template for Hyperledger Fabric creates an EC2 instance with Docker, and launches a Hyperledger Fabric network using containers on that instance. The network includes one order service and three organizations, each with one peer service. The template also launches a Hyperledger Explorer container, which allows you to browse blockchain data. A PostgreSQL server container is launched to support Hyperledger Explorer. The following diagram depicts a Hyperledger Fabric network created using the template: ![\[AWS architecture diagram showing EC2 instance with containers in a VPC, connected to ECR and S3.\]](http://docs.aws.amazon.com/blockchain-templates/latest/developerguide/images/hyperledger-docker-local-arch.png) ## Prerequisites Before you launch a Hyperledger Fabric network using template, make sure that the following requirements are satisfied: + The IAM principle (user or group) that you use must have permission to work with all related services. + You must have access to a key pair that you can use to access EC2 instances (for example, using SSH). The key must exist in the same region as the instance. + You must have an EC2 instance profile with a permissions policy attached that allows access to Amazon S3 and to Amazon Elastic Container Registry (Amazon ECR) to pull containers. For an example permissions policy, see [Example IAM Permissions for the EC2 Instance Profile](#blockchain-hyperledger-ec2profile). + You must have a Amazon VPC network with a public subnet, or a private subnet with a NAT Gateway and Elastic IP address so that Amazon S3, CloudFormation, and Amazon ECR can be accessed. + You must have an EC2 security group with inbound rules that allow SSH traffic (port 22) from the IP addresses that need to connect to the instance using SSH, and the same for clients that need to connect to Hyperledger Explorer (port 8080). ### Example IAM Permissions for the EC2 Instance Profile You specify an EC2 instance profile ARN as one of the parameters when you use the AWS Blockchain Template for Hyperledger Fabric. Use the following policy statement as a starting point for the permissions policy attached to that EC2 role and instance profile. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecr:GetAuthorizationToken", "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:GetRepositoryPolicy", "ecr:DescribeRepositories", "ecr:ListImages", "ecr:DescribeImages", "ecr:BatchGetImage", "s3:Get*", "s3:List*" ], "Resource": "*" } ] } ``` ------ ## Connecting to Hyperledger Fabric Resources After the root stack that you create with the template shows **CREATE\$1COMPLETE**, you can connect to Hyperledger Fabric resources on the EC2 instance. If you specified a public subnet, you can connect to the EC2 instance as would any other EC2 instance. For more information, see [Connecting to Your Linux Instance Using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html) in the *Amazon EC2 User Guide*. If you specified a private subnet, you can set up and use a *bastion host* to proxy connections to Hyperledger Fabric resources. For more information, see [Proxy Connections Using a Bastion Host](blockchain-templates-ethereum.md#ethereum-create-bastion-host) below. **Note** You may notice that the template allocates a public IP address to the EC2 instance hosting Hyperledger Fabric services; however, this IP address is not publicly accessible because routing policies in the private subnet you specify do not allow traffic between this IP address and public sources. ### Proxy Connections Using a Bastion Host With some configurations, Hyperledger Fabric services may not be publicly available. In those cases, you can connect to Hyperledger Fabric resources through a *bastion host*. For more information about bastion hosts, see [Linux Bastion Host Architecture](https://docs.aws.amazon.com/quickstart/latest/linux-bastion/architecture.html) in the *Linux Bastion Host Quick Start Guide*. The bastion host is an EC2 instance. Make sure that the following requirements are met: + The EC2 instance for the bastion host is within a public subnet with Auto-assign Public IP enabled and that has an internet gateway. + The bastion host has the key pair that allows ssh connections. + The bastion host is associated with a security group that allows inbound SSH traffic from the clients that connect. + The security group assigned to the Hyperledger Fabric hosts (for example, the Application Load Balancer if ECS is the container platform, or the host EC2 instance if docker-local is the container platform) allows inbound traffic on all ports from sources within the VPC. With a bastion host set up, ensure that the clients that connect use the bastion host as a proxy. The following example demonstrates setting up a proxy connection using Mac OS. Replace *BastionIP* with the IP address of the bastion host EC2 instance and *MySshKey.pem* with the key pair file that you copied to the bastion host. On the command line, type the following: ``` ssh -i mySshKey.pem ec2-user@BastionIP -D 9001 ``` This sets up port forwarding for port 9001 on the local machine to the bastion host. Next, configure your browser or system to use SOCKS proxy for `localhost:9001`. For example, using Mac OS, select **System Preferences**, **Network**, **Advanced**, select **SOCKS proxy**, and type **localhost:9001**. Using FoxyProxy Standard with Chrome, select **More Tools**, **Extensions**. Under **FoxyProxy Standard**, select **Details**, **Extension options**, **Add New Proxy**. Select **Manual Proxy Configuration**. For **Host or IP Address** type **localhost** and for **Port** type **9001**. Select **SOCKS proxy?**, **Save**. You should now be able to connect to the Hyperledger Fabric host addresses listed in the template output.