Open Menu
Sextant
 
DAML

Installation Instructions

Prerequisites

The following CLI tools are required

  • aws
  • eksctl
  • kubectl

You will need sufficient privileges on AWS to create and assign IAM policies, and roles.

You will also need an EKS cluster. Our recommendation is that you create a dedicated 4 node EKS cluster which will allow you to install Sextant for DAML and then use this to deploy a Sawtooth network using PBFT consensus on it.

If you are not familiar with how to create an EKS cluster instructions can be found in EKS Cluster Basics

For persistent maintenance of Sextant for DAML data, a postgresql database is required.

Deploying the operator

Sextant for DAML is packaged as a Kubernetes Operator.

Setup Service Accounts

Two service accounts are involved in any given Sextant for DAML installation. The default service account, and the service account for the operator.

Sextant for DAML itself runs under the default service account, but since it is an AWS Marketplace metered product it requires certain IAM privileges to be assigned to its service account to operate.

Step 1

Make sure that your cluster is associated to OIDC ID provider (IdP) in AWS. If you have not already done this, it may be accomplished via the following command:

eksctl utils associate-iam-oidc-provider \
    --cluster <CLUSTER_NAME> \
    --region <REGION_NAME> \
    --approve

NOTE if this command fails try --name (now deprecated) in place of --cluster or update your version of eksctl.

Step 2

Make sure that your cluster's default service account is allowed to set up metered products. If you have not already done this, it may be accomplished via the following commands.

First check to see whether you have already created the marketplace-register-usage policy. For example, if you have previous installed Sextant for DAML on another cluster using the same AWS credentials this policy should exist.

aws iam list-policies | grep marketplace-register-usage

If this is successful, note the ARN of the policy and go to Step 3. Otherwise create the marketplace-register-usage policy via the following command and note its ARN:

aws iam create-policy --policy-name "marketplace-register-usage" --policy-document '{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "aws-marketplace:RegisterUsage"
                ],
                "Resource": "*"
            }
        ]
    }'

Step 3

Now we need to attach this policy to the default service account using eksctl.

eksctl create iamserviceaccount --cluster=<CLUSTER_NAME> --name=default --namespace=<SERVICE_ACCOUNT_NAMESPACE> --attach-policy-arn=<POLICY_ARN>

Note you may be asked to rerun this command with --override-existing-serviceaccounts set and finally with --approve as well.

You may specify --attach-policy-arn as many times as necessary to attach any other permissions you require.

Step 4

Finally we need to create the service account for the sextant-operator itself

kubectl apply -f https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/service_account.yaml

Setup RBAC

The sextant-operator requires various kubernetes RBAC permissions assigned to it's service account in order to do its work. Create those roles and apply them to the sextant-operator service account via the following commands:

kubectl apply -f https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/role.yaml
kubectl apply -f https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/role_binding.yaml
kubectl apply -f https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/cluster_role.yaml
kubectl apply -f https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/cluster_role_binding.yaml

Setup the CRD

Next we define the Sextant CRD (Custom Resource Definition) via the following command:

kubectl apply -f https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/blockchaintp_v1alpha1_sextant_crd.yaml

Deploy the operator

You now need to deploy the Sextant for DAML operator itself.

kubectl apply -f https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/aws_operator_sfd.yaml

The sextant-operator should now be running in the default namespace.

Create a Sextant for DAML Instance

A Sextant for DAML instance (custom resource) may be created in one of two ways:

With a local postgres db pod

Download the local example to a YAML file of your choice.

curl https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/example_sextant_cr_local_db.yaml -o my_sextant_with_local_db.yaml

Edit your YAML file changing the value of metadata.name to the name of your Sextant for DAML resource.

Finally apply your YAML file to the kubernetes cluster

kubectl apply -f my_sextant_with_local_db.yaml

Using a remote database

Download the remote example to a YAML file of your choice.

curl https://sextant-resources.s3.amazonaws.com/sextant-operator/BTP2.0/example_sextant_cr_remote_db.yaml -o my_sextant_with_remote_db.yaml

Edit your YAML file changing the value of metadata.name to the name of your Sextant for DAML resource and changing the spec.database details to match your postgresql access details.

Finally apply your YAML file to the kubernetes cluster

kubectl apply -f my_sextant_with_remote_db.yaml

Expose the Sextant for DAML pod for access

Exposing the Sextant for DAML pod for access from outside the Kubernetes cluster may be accomplished in one of two ways, in both cases replacing example-sextant with whatever you named your Sextant for DAML resource:

On an ad hoc basis

Using kubectl port-forward. This is good for temporarily accessing your Sextant for DAML instance. In this case you want to forward some available local port to port 80 on the Sextant for DAML pod. For example -

kubectl port-forward pods/example-sextant 8080:80

On a permanent basis

For a more permanent solution use a LoadBalancer or other ingress, pointing to port 80 on the Sextant for DAML pod. For example -

kubectl expose pod/example-sextant --type=LoadBalancer --port=80 --target-port=80

Getting the Sextant for DAML hostname

Assuming that if you opted to use a LoadBalancer to enable you to access your Sextant for DAML instance on a permanent basis then use the following command to obtain its hostname.

kubectl get all -o wide | grep LoadBalancer

Alternatively you can run this command.

kubectl get all -o wide --output json | awk '/hostname/{print $2}'

In both cases the hostname is the string ending in .elb.amazonaws.com.

Getting the initial Sextant for DAML credentials

On startup a Sextant for DAML instance creates a default user and generates an initial password for that user. In order to retrieve these credentials execute the following command, replacing example-sextant with whatever you named your Sextant for DAML resource.

kubectl describe pod/example-sextant | grep INITIAL_
INTIAL_USER:        admin
INITIAL_PASSWORD:   nkf7798435nsfdfdsg$sdfds

Use these credentials to log in to your Sextant for DAML instance, accessing it via the Sextant for DAML hostname obtained above.

Finding the Kubernetes API Address on Amazon EKS

If you are using a Kubernetes management server to access your EKS clusters, such as Rancher, these systems provide a proxy to the kubernetes API server which will not work with Sextant for DAML. In order to find the address of an EKS Kubernetes API server execute the following command:

aws eks describe-cluster --name <CLUSTER_NAME> --region <REGION_NAME> --output json | jq '.cluster.endpoint'