Helm Chart for Ethereum Adapter Service

• helm 3
• These mandatory configuration values:
  • RPC Address - The URL of the quorum node, e.g. http://quorum-node-0-rpc:8545
  • Smart Contract Address - The address of the smart contract, e.g. 0x1783aBc71903919382EFca91
  • Smart Contract Abi
  • Org Account JSON - The confidential private key and address in JSON format, e.g. {"privateKey":"0x1234567890abcdef", "address":"0x0987654321AbCdEf"}

• Here is a full list of all configuration values.
• The values.yaml file shows the raw view of all configuration values.

By default, this helm chart installs the Ethereum Adapter Service at an internal ClusterIP Service listening at port 3000. This is to prevent exposing the service to the internet by accident!

It is recommended to put non-sensitive configuration values in an configuration file and pass sensitive/secret values via commandline.

1. Create configuration file, e.g. my-config.yaml

   config:
     rpcAddress: "rpcAddress_value"
     smartContractAddress: "smartContractAddress_value"
     smartContractAbi: "smartContractAbi_value"

2. Install via helm to namespace default either by passing sensitive Org Account JSON value in JSON format as escaped string

   helm upgrade my-release-name ./ethadapter \
       --install \
       --values my-config.yaml \
       --set-string secrets.orgAccountJson="\{ \"key\": \"value\" \}"

3. or pass sensitive Org Account JSON value in JSON format as base64 encoded string

   helm upgrade my-release-name ./ethadapter \
       --install \
       --values my-config.yaml \
       --set-string secrets.orgAccountJsonBase64="eyAia2V5IjogInZhbHVlIiB9"

In order to expose the service directly by an own dedicated Load Balancer, just add service.type with value LoadBalancer to your config file (in order to override the default value which is ClusterIP).

Please note: At AWS using service.type = LoadBalancer is not recommended any more, as it creates a Classic Load Balancer. Use AWS Load Balancer Controller with an ingress instead. A full sample is provided later in the docs. Using an Application Load Balancer (managed by AWS LB Controller) increases security (e.g. by using a Web Application Firewall for your http based traffic) and provides more features like hostname, pathname routing or built-in authentication mechanism via OIDC or AWS Cognito.

Configuration file my-config.yaml

service:
  type: LoadBalancer

config:
  rpcAddress: "rpcAddress_value"
  smartContractAddress: "smartContractAddress_value"
  smartContractAbi: "smartContractAbi_value"

There are more configuration options available like customizing the port and configuring the Load Balancer via annotations (e.g. for configuring SSL Listener).

Also note: Annotations are very specific to your environment/cloud provider, see Kubernetes Service Reference for more information. For Azure, take a look here.

Sample for AWS (SSL and listening on port 4567 instead 3000 which is the default):

service:
  type: LoadBalancer
  port: 4567
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: http
    service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "4567"
    # https://docs.aws.amazon.com/de_de/elasticloadbalancing/latest/classic/elb-security-policy-table.html
    service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy: "ELBSecurityPolicy-TLS-1-2-2017-01"

# further config

Note: You need the AWS Load Balancer Controller installed and configured properly.

1. Enable ingress
2. Add host, path /* and pathType ImplementationSpecific
3. Add annotations for AWS LB Controller
4. A SSL certificate at AWS Certificate Manager (either for the hostname, here ethadapter.mydomain.com or wildcard *.mydomain.com)

Configuration file my-config.yaml

ingress:
  enabled: true
  # Let AWS LB Controller handle the ingress (default className is alb)
  # Note: Use className instead of annotation 'kubernetes.io/ingress.class' which is deprecated since 1.18
  # For Kubernetes >= 1.18 it is required to have an existing IngressClass object.
  # See: https://kubernetes.io/docs/concepts/services-networking/ingress/#deprecated-annotation
  className: alb
  hosts:
    - host: ethadapter.mydomain.com
      # Path must be /* for ALB to match all paths
      paths:
        - path: /*
          pathType: ImplementationSpecific
  # For full list of annotations for AWS LB Controller, see https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.3/guide/ingress/annotations/
  annotations:
    # The ARN of the existing SSL Certificate at AWS Certificate Manager
    alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:REGION:ACCOUNT_ID:certificate/CERTIFICATE_ID
    # The name of the ALB group, can be used to configure a single ALB by multiple ingress objects
    alb.ingress.kubernetes.io/group.name: default
    # Specifies the HTTP path when performing health check on targets.
    alb.ingress.kubernetes.io/healthcheck-path: /check
    # Specifies the port used when performing health check on targets. 
    alb.ingress.kubernetes.io/healthcheck-port: traffic-port
    # Specifies the HTTP status code that should be expected when doing health checks against the specified health check path.
    alb.ingress.kubernetes.io/success-codes: "200"
    # Listen on HTTPS protocol at port 3000 at the ALB
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":3000}]'
    # Allow access from a specific IP address only, e.g. from the NAT Gateway of your EPI Cluster
    alb.ingress.kubernetes.io/inbound-cidrs: 8.8.8.8/32 
    # Use internet facing
    alb.ingress.kubernetes.io/scheme: internet-facing
    # Use most current (as of Dec 2021) encryption ciphers
    alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS-1-2-Ext-2018-06
    # Use target type IP which is the case if the service type is ClusterIP
    alb.ingress.kubernetes.io/target-type: ip

config:
  rpcAddress: "rpcAddress_value"
  smartContractAddress: "smartContractAddress_value"
  smartContractAbi: "smartContractAbi_value"

Run helm upgrade --helm for full list of options.

1. Install to other namespace

   You can install into other namespace than default by setting the --namespace parameter, e.g.

   helm upgrade my-release-name ./ethadapter \
       --install \
       --namespace=my-namespace \
       --values my-config.yaml \
       --set-string secrets.orgAccountJson="\{ \"key\": \"value\" \}"

2. Wait until installation has finished successfully and the deployment is up and running.

   Provide the --wait argument and time to wait (default is 5 minutes) via --timeout

   helm upgrade my-release-name ./ethadapter \
       --install \
       --wait --timeout=600s \
       --values my-config.yaml \
       --set-string secrets.orgAccountJson="\{ \"key\": \"value\" \}"

1. Error: admission webhook "vingress.elbv2.k8s.aws" denied the request: invalid ingress class: IngressClass.networking.k8s.io "alb" not found

   Description: This error only applies to Kubernetes >= 1.18 and indicates that no matching IngressClass object was found.

   Solution: Either declare an appropriate IngressClass or omit className and add annotation kubernetes.io/ingress.class

   Further information:

   • Kubernetes IngressClass
   • AWS Load Balancer controller documentation

See Helm Debugging Templates

mkdir -p ./testresults
rm -rf ./testresults/*
# https://github.com/helm/helm/issues/5618
echo ""
echo "Default values and secret passed as String"
helm template test-ethadapter ./ethadapter --values ./tests/data/default.yaml --set-string secrets.orgAccountJson="\{ \"key\": \"value\" \}" > ./tests/results/result_default.yaml

echo ""
echo "Default values and secret passed as base64 encoded String"
helm template test-ethadapter ./ethadapter --values ./tests/data/default.yaml --set-string secrets.orgAccountJsonBase64="eyAia2V5IjogInZhbHVlIiB9" > ./tests/results/result_default_base64.yaml

echo ""
echo "LoadBalancer"
helm template test-ethadapter ./ethadapter --values ./tests/data/loadbalancer.yaml --set-string secrets.orgAccountJsonBase64="eyAia2V5IjogInZhbHVlIiB9" > ./tests/results/result_loadbalancer.yaml

echo ""
echo "LoadBalancer and annotations"
helm template test-ethadapter ./ethadapter --values ./tests/data/loadbalancer_annotations.yaml --set-string secrets.orgAccountJsonBase64="eyAia2V5IjogInZhbHVlIiB9" > ./tests/results/result_loadbalancer_annotations.yaml

echo ""
echo "Ingress via AWS LB Controller"
helm template test-ethadapter ./ethadapter --values ./tests/data/aws_lb_controller_ingress.yaml --set-string secrets.orgAccountJsonBase64="eyAia2V5IjogInZhbHVlIiB9" > ./tests/results/result_aws_lb_controller_ingress.yaml