Setup

Overview

  1. (Optional) Configure environment

  2. Create QLDB Ledger

  3. Configure IAM user/role permissions for ledger

  4. Install library

Steps

  1. (Optional) Configure Environment

This library needs to be informed of the QLDB Ledger to write against on your AWS environment. There are several ways to configure the Ledger setting.

Before you start a Python shell, export theLEDGER environment variable,

export LEDGER='ledger-name'
python

Alternatively, configure the variable directly in a Python script

import os

os.environ['LEDGER'] = 'ledger=name'

The environment variable LEDGER should point to the QLDB ledger so the application knows to which ledger to write. If you do not configure the LEDGER environment variable, you will need to pass in the ledger name to the Document object. See below for more information.

  1. Create a QLDB Ledger

Boto3 Client

The easiest way to create a ledger is through a boto3 client,

from boto3 import client

qldb = client('qldb')
qldb.create_ledger(Name='ledger', PermissionsMode='STANDARD', DeletionProtection=False)

.. note:: This will only create the ledger if you have your AWS credentials configured and the necessary permissions with QLDB. See here for a working example of an appropriate IAM policy

CloudFormation

A QLDB CloudFormation template is also available in the /scripts/cf/ directory of this project’s Github. A script has been provided to post this template to CloudFormation, assuming your AWS CLI has been authenticated and configured. Clone the repository and then from the project root, execute the following script and specify the <ledger-name> to create a ledger on the QLDB service,

./scripts/cf/stack --ledger <ledger-name>

This method has the advantage of provisioning an IAM policy and role scoped to the ledger being created. These resources can be used by applications and users to gain access to the QLDB ledger instance. Once they are created, log into the AWS console and add the policy to your account.

.. note:: The <ledger-name> must match the value of the LEDGER environment variable. The name of the ledger that is stood up on AWS is passed to the library through this environment variable. If the two do not match, then you will need to construct documents with the ledger name passed in to match the actual ledger name, i.e. doc = Document(table='table', ledger='ledger').

.. note:: This script has other optional arguments detailed in the comments of the script itself.

  1. Configure User Permissions

In production, you will want to limit the permissions of the application client to the ledger and table to which it is authorized to read and write. For the purposes of using this library locally, you can add a blanket policy to your user account by following the instructions here.

If you are configuring an application role to use this library for a particular ledger and table, you will need to scope the permissions using this reference.

See here for a full working example of an appropriate IAM policy.

  1. Install qldb-orm

pip install qldb-orm