Getting Started with Helm Charts (ScalarDL Ledger and Auditor with TLS by Using cert-manager / Auditor Mode)

This tutorial explains how to get started with ScalarDL Ledger and ScalarDL Auditor with TLS configurations by using Helm Charts and cert-manager on a Kubernetes cluster as a test environment. Before starting, you should already have a Mac or Linux environment for testing. In addition, although this tutorial mentions using minikube, the steps described should work in any Kubernetes cluster.

Requirements

• You need to have a license key (trial license or commercial license) for ScalarDL. If you don't have a license key, please contact us.
• You need to use ScalarDL 3.9 or later, which supports TLS.

注記

To make Byzantine-fault detection with auditing work properly, ScalarDL Ledger and ScalarDL Auditor should be deployed and managed in different administrative domains. However, in this tutorial, we will deploy ScalarDL Ledger and ScalarDL Auditor in the same Kubernetes cluster to make the test easier.

What you'll create

In this tutorial, you'll deploy the following components on a Kubernetes cluster in the following way:

+-----------------------------------------------------------------------------------------------------------------------------+
| [Kubernetes Cluster]                                                                                                        |
|                                             [Pod]                                      [Pod]                   [Pod]        |
|                                                                                                                             |
|                                           +-------+                                 +---------+                             |
|                                     +---> | Envoy | ---+                      +---> | Ledger  | ---+                        |
|                                     |     +-------+    |                      |     +---------+    |                        |
|                                     |                  |                      |                    |                        |
|                      +---------+    |     +-------+    |     +-----------+    |     +---------+    |     +---------------+  |
|                +---> | Service | ---+---> | Envoy | ---+---> |  Service  | ---+---> | Ledger  | ---+---> |  PostgreSQL   |  |
|                |     | (Envoy) |    |     +-------+    |     | (Ledger)  |    |     +---------+    |     | (For Ledger)  |  |
|                |     +---------+    |                  |     +-----------+    |                    |     +---------------+  |
|    [Pod]       |                    |     +-------+    |                      |     +---------+    |                        |
|                |                    +---> | Envoy | ---+                      +---> | Ledger  | ---+                        |
|  +--------+    |                          +-------+                                 +---------+                             |
|  | Client | ---+                                                                                                            |
|  +--------+    |                          +-------+                                 +---------+                             |
|                |                    +---> | Envoy | ---+                      +---> | Auditor | ---+                        |
|                |                    |     +-------+    |                      |     +---------+    |                        |
|                |                    |                  |                      |                    |                        |
|                |     +---------+    |     +-------+    |     +-----------+    |     +---------+    |     +---------------+  |
|                +---> | Service | ---+---> | Envoy | ---+---> |  Service  | ---+---> | Auditor | ---+---> |  PostgreSQL   |  |
|                      | (Envoy) |    |     +-------+    |     | (Auditor) |    |     +---------+    |     | (For Auditor) |  |
|                      +---------+    |                  |     +-----------+    |                    |     +---------------+  |
|                                     |     +-------+    |                      |     +---------+    |                        |
|                                     +---> | Envoy | ---+                      +---> | Auditor | ---+                        |
|                                           +-------+                                 +---------+                             |
|                                                                                                                             |
|  +--------------------------------------------------------------------------+    +---------------------+                    |
|  | cert-manager (create private key and certificate for Envoy and ScalarDL) |    | Issuer (Private CA) |                    |
|  +--------------------------------------------------------------------------+    +---------------------+                    |
|                                                                                                                             |
+-----------------------------------------------------------------------------------------------------------------------------+

cert-manager automatically creates the following private key and certificate files for TLS connections.

                                                           +----------------------+
                                                     +---> | For Scalar Envoy     |
                                                     |     +----------------------+
                                                     |     | tls.key              |
                                                     |     | tls.crt              |
                                                     |     +----------------------+
                                                     |     
+-------------------------+                          |     +----------------------+
| Issuer (Self-signed CA) | ---(Sign certificates)---+---> | For ScalarDL Ledger  |
+-------------------------+                          |     +----------------------+
| tls.key                 |                          |     | tls.key              |
| tls.crt                 |                          |     | tls.crt              |
| ca.crt                  |                          |     +----------------------+
+-------------------------+                          |     
                                                     |     +----------------------+
                                                     +---> | For ScalarDL Auditor |
                                                           +----------------------+
                                                           | tls.key              |
                                                           | tls.crt              |
                                                           +----------------------+

Scalar Helm Charts automatically mount each private key and certificate file for Envoy and ScalarDL as follows to enable TLS in each connection. You'll manually mount a root CA certificate file on the client.

                                                                            +------------------------------------------------+      +--------------------------------------+
                                             +-------(Normal request)-----> | Envoy for ScalarDL Ledger                      | ---> | ScalarDL Ledger                      |
                                             |                              +------------------------------------------------+      +--------------------------------------+
                                             |   +---(Recovery request)---> | tls.key                                        | ---> | tls.key                              |
                                             |   |                          | tls.crt                                        |      | tls.crt                              |
                                             |   |                          | ca.crt (to verify tls.crt of ScalarDL Ledger)  |      | ca.crt (to check health)             |
                                             |   |                          +------------------------------------------------+      +--------------------------------------+
+---------------------------------------+    |   |
| Client                                | ---+   |
+---------------------------------------+    |   +------------------------------------------------------------------------------------------------------------------------------+
| ca.crt (to verify tls.crt of Envoy)   |    |                                                                                                                                  |
+---------------------------------------+    |                                                                                                                                  |
                                             |                              +------------------------------------------------+      +--------------------------------------+    |
                                             +-------(Normal request)-----> | Envoy for ScalarDL Auditor                     | ---> | ScalarDL Auditor                     | ---+
                                                                            +------------------------------------------------+      +--------------------------------------+
                                                                            | tls.key                                        |      | tls.key                              |
                                                                            | tls.crt                                        |      | tls.crt                              |
                                                                            | ca.crt (to verify tls.crt of ScalarDL Auditor) |      | ca.crt (to check health)             |
                                                                            +------------------------------------------------+      | ca.crt (to verify tls.crt of Envoy)  |
                                                                                                                                    +--------------------------------------+

The following connections exist amongst the ScalarDL-related components:

• Client - Envoy for ScalarDL Ledger: When you execute a ScalarDL API function, the client accesses Envoy for ScalarDL Ledger.
• Client - Envoy for ScalarDL Auditor: When you execute a ScalarDL API function, the client accesses Envoy for ScalarDL Auditor.
• Envoy for ScalarDL Ledger - ScalarDL Ledger: Envoy works as an L7 (gRPC) load balancer in front of ScalarDL Ledger.
• Envoy for ScalarDL Auditor - ScalarDL Auditor: Envoy works as an L7 (gRPC) load balancer in front of ScalarDL Auditor.
• ScalarDL Auditor - Envoy for ScalarDL Ledger (ScalarDL Ledger): When ScalarDL needs to run the recovery process to keep data consistent, ScalarDL Auditor runs the request against ScalarDL Ledger via Envoy.

Step 1. Start a Kubernetes cluster and install tools

You need to prepare a Kubernetes cluster and install some tools (kubectl, helm, cfssl, and cfssljson). For more details on how to install them, see Getting Started with Scalar Helm Charts.

Step 2. Start the PostgreSQL containers

ScalarDL Ledger and ScalarDL Auditor must use some type of database system as a backend database. In this tutorial, you'll use PostgreSQL.

You can deploy PostgreSQL on the Kubernetes cluster as follows:

1. Add the Bitnami helm repository.

   helm repo add bitnami https://charts.bitnami.com/bitnami

2. Deploy PostgreSQL for Ledger.

   helm install postgresql-ledger bitnami/postgresql \
     --set auth.postgresPassword=postgres \
     --set primary.persistence.enabled=false \
     -n default

3. Deploy PostgreSQL for Auditor.

   helm install postgresql-auditor bitnami/postgresql \
     --set auth.postgresPassword=postgres \
     --set primary.persistence.enabled=false \
     -n default

4. Check if the PostgreSQL containers are running.

   kubectl get pod -n default

   [Command execution result]

   NAME                   READY   STATUS    RESTARTS   AGE
   postgresql-auditor-0   1/1     Running   0          11s
   postgresql-ledger-0    1/1     Running   0          16s

Step 3. Create a working directory

You'll create some configuration files and private key and certificate files locally. Be sure to create a working directory for those files.

1. Create a working directory.

   mkdir -p ${HOME}/scalardl-test/

Step 4. Deploy cert-manager and issuer resource

This tutorial uses cert-manager to issue and manage private keys and certificates. You can deploy cert-manager on the Kubernetes cluster as follows:

1. Add the Jetstack helm repository.

   helm repo add jetstack https://charts.jetstack.io

2. Deploy cert-manager.

   helm install cert-manager jetstack/cert-manager \
     --create-namespace \
     --set installCRDs=true \
     -n cert-manager

3. Check if the cert-manager containers are running.

   kubectl get pod -n cert-manager

   [Command execution result]

   NAME                                      READY   STATUS    RESTARTS   AGE
   cert-manager-6dc66985d4-6lvtt             1/1     Running   0          26s
   cert-manager-cainjector-c7d4dbdd9-xlrpn   1/1     Running   0          26s
   cert-manager-webhook-847d7676c9-ckcz2     1/1     Running   0          26s

4. Change the working directory to ${HOME}/scalardl-test/.

   cd ${HOME}/scalardl-test/

5. Create a custom values file for private CA (private-ca-custom-values.yaml).

   cat << 'EOF' > ${HOME}/scalardl-test/private-ca-custom-values.yaml
   apiVersion: cert-manager.io/v1
   kind: Issuer
   metadata:
     name: self-signed-issuer
   spec:
     selfSigned: {}
   ---
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: self-signed-ca-cert
   spec:
     isCA: true
     commonName: self-signed-ca
     secretName: self-signed-ca-cert-secret
     privateKey:
       algorithm: ECDSA
       size: 256
     issuerRef:
       name: self-signed-issuer
       kind: Issuer
       group: cert-manager.io
   ---
   apiVersion: cert-manager.io/v1
   kind: Issuer
   metadata:
     name: self-signed-ca
   spec:
     ca:
       secretName: self-signed-ca-cert-secret
   EOF

6. Deploy self-signed CA.

   kubectl apply -f ./private-ca-custom-values.yaml

7. Check if the issuer resources are True.

   kubectl get issuer

   [Command execution result]

   NAME                 READY   AGE
   self-signed-ca      True    6s
   self-signed-issuer   True    6s

Step 5. Create database schemas for ScalarDL Ledger and ScalarDL Auditor by using Helm Charts

You'll deploy two ScalarDL Schema Loader pods on the Kubernetes cluster by using Helm Charts. The ScalarDL Schema Loader will create the database schemas for ScalarDL Ledger and Auditor in PostgreSQL.

1. Add the Scalar Helm Charts repository.

   helm repo add scalar-labs https://scalar-labs.github.io/helm-charts

2. Create a custom values file for ScalarDL Schema Loader for Ledger (schema-loader-ledger-custom-values.yaml).

   cat << 'EOF' > ${HOME}/scalardl-test/schema-loader-ledger-custom-values.yaml
   schemaLoading:
     schemaType: "ledger"
     databaseProperties: |
       scalar.db.contact_points=jdbc:postgresql://postgresql-ledger.default.svc.cluster.local:5432/postgres
       scalar.db.username=${env:SCALAR_DL_LEDGER_POSTGRES_USERNAME}
       scalar.db.password=${env:SCALAR_DL_LEDGER_POSTGRES_PASSWORD}
       scalar.db.storage=jdbc
     secretName: "schema-ledger-credentials-secret"
   EOF

3. Create a custom values file for ScalarDL Schema Loader for Auditor (schema-loader-auditor-custom-values.yaml).

   cat << 'EOF' > ${HOME}/scalardl-test/schema-loader-auditor-custom-values.yaml
   schemaLoading:
     schemaType: "auditor"
     databaseProperties: |
       scalar.db.contact_points=jdbc:postgresql://postgresql-auditor.default.svc.cluster.local:5432/postgres
       scalar.db.username=${env:SCALAR_DL_AUDITOR_POSTGRES_USERNAME}
       scalar.db.password=${env:SCALAR_DL_AUDITOR_POSTGRES_PASSWORD}
       scalar.db.storage=jdbc
     secretName: "schema-auditor-credentials-secret"
   EOF

4. Create a secret resource named schema-ledger-credentials-secret that includes a username and password for PostgreSQL for ScalarDL Ledger.

   kubectl create secret generic schema-ledger-credentials-secret \
     --from-literal=SCALAR_DL_LEDGER_POSTGRES_USERNAME=postgres \
     --from-literal=SCALAR_DL_LEDGER_POSTGRES_PASSWORD=postgres \
     -n default

5. Create a secret resource named schema-auditor-credentials-secret that includes a username and password for PostgreSQL for ScalarDL Auditor.

   kubectl create secret generic schema-auditor-credentials-secret \
     --from-literal=SCALAR_DL_AUDITOR_POSTGRES_USERNAME=postgres \
     --from-literal=SCALAR_DL_AUDITOR_POSTGRES_PASSWORD=postgres \
     -n default

6. Set the chart version of ScalarDL Schema Loader.

   SCALAR_DL_VERSION=3.9.1
   SCALAR_DL_SCHEMA_LOADER_CHART_VERSION=$(helm search repo scalar-labs/schema-loading -l | grep -F "${SCALAR_DL_VERSION}" | awk '{print $2}' | sort --version-sort -r | head -n 1)

7. Deploy ScalarDL Schema Loader for ScalarDL Ledger.

   helm install schema-loader-ledger scalar-labs/schema-loading -f ${HOME}/scalardl-test/schema-loader-ledger-custom-values.yaml --version ${SCALAR_DL_SCHEMA_LOADER_CHART_VERSION} -n default

8. Deploy ScalarDL Schema Loader for ScalarDL Auditor.

   helm install schema-loader-auditor scalar-labs/schema-loading -f ${HOME}/scalardl-test/schema-loader-auditor-custom-values.yaml --version ${SCALAR_DL_SCHEMA_LOADER_CHART_VERSION} -n default

9. Check if the ScalarDL Schema Loader pods are deployed with the status Completed.

   kubectl get pod -n default

   [Command execution result]

   NAME                                         READY   STATUS      RESTARTS   AGE
   postgresql-auditor-0                         1/1     Running     0          2m56s
   postgresql-ledger-0                          1/1     Running     0          3m1s
   schema-loader-auditor-schema-loading-dvc5r   0/1     Completed   0          6s
   schema-loader-ledger-schema-loading-mtllb    0/1     Completed   0          10s

   If the status of the ScalarDL Schema Loader pods are ContainerCreating or Running, wait for the STATUS column for those pods to show as Completed.

Step 6. Deploy ScalarDL Ledger and ScalarDL Auditor on the Kubernetes cluster by using Helm Charts

1. Set your license key and certificate as environment variables. If you don't have a license key, please contact us. For details about the value of <CERT_PEM_FOR_YOUR_SCALAR_DL_LEDGER_LICENSE_KEY> and <CERT_PEM_FOR_YOUR_SCALAR_DL_AUDITOR_LICENSE_KEY>, see How to Configure a Product License Key.

   SCALAR_DL_LEDGER_LICENSE_KEY='<YOUR_SCALAR_DL_LEDGER_LICENSE_KEY>'
   SCALAR_DL_LEDGER_LICENSE_CHECK_CERT_PEM='<CERT_PEM_FOR_YOUR_SCALAR_DL_LEDGER_LICENSE_KEY>'
   SCALAR_DL_AUDITOR_LICENSE_KEY='<YOUR_SCALAR_DL_AUDITOR_LICENSE_KEY>'
   SCALAR_DL_AUDITOR_LICENSE_CHECK_CERT_PEM='<CERT_PEM_FOR_YOUR_SCALAR_DL_AUDITOR_LICENSE_KEY>'

2. Create a custom values file for ScalarDL Ledger (scalardl-ledger-custom-values.yaml).

   cat << 'EOF' > ${HOME}/scalardl-test/scalardl-ledger-custom-values.yaml
   envoy:
   
     tls:
       downstream:
         enabled: true
         certManager:
           enabled: true
           issuerRef:
             name: self-signed-ca
           dnsNames:
             - envoy.scalar.example.com
       upstream:
         enabled: true
         overrideAuthority: "ledger.scalardl.example.com"
   
   ledger:
   
     image:
       repository: "ghcr.io/scalar-labs/scalardl-ledger-byol"
   
     ledgerProperties: |
       ### Storage configurations
       scalar.db.storage=jdbc
       scalar.db.contact_points=jdbc:postgresql://postgresql-ledger.default.svc.cluster.local:5432/postgres
       scalar.db.username=${env:SCALAR_DL_LEDGER_POSTGRES_USERNAME}
       scalar.db.password=${env:SCALAR_DL_LEDGER_POSTGRES_PASSWORD}
   
       ### Ledger configurations
       scalar.dl.ledger.proof.enabled=true
       scalar.dl.ledger.auditor.enabled=true
       scalar.dl.ledger.authentication.method=hmac
       scalar.dl.ledger.authentication.hmac.cipher_key=${env:SCALAR_DL_LEDGER_HMAC_CIPHER_KEY}
       scalar.dl.ledger.servers.authentication.hmac.secret_key=${env:SCALAR_DL_LEDGER_HMAC_SECRET_KEY}
   
       ### TLS configurations
       scalar.dl.ledger.server.tls.enabled=true
       scalar.dl.ledger.server.tls.cert_chain_path=/tls/scalardl-ledger/certs/tls.crt
       scalar.dl.ledger.server.tls.private_key_path=/tls/scalardl-ledger/certs/tls.key
   
       ### License key configurations
       scalar.dl.licensing.license_key=${env:SCALAR_DL_LEDGER_LICENSE_KEY}
       scalar.dl.licensing.license_check_cert_pem=${env:SCALAR_DL_LEDGER_LICENSE_CHECK_CERT_PEM}
   
     tls:
       enabled: true
       overrideAuthority: "ledger.scalardl.example.com"
       certManager:
         enabled: true
         issuerRef:
           name: self-signed-ca
         dnsNames:
           - ledger.scalardl.example.com
   
     secretName: "ledger-credentials-secret"
   EOF

3. Create a custom values file for ScalarDL Auditor (scalardl-auditor-custom-values.yaml).

   cat << 'EOF' > ${HOME}/scalardl-test/scalardl-auditor-custom-values.yaml
   envoy:
   
     tls:
       downstream:
         enabled: true
         certManager:
           enabled: true
           issuerRef:
             name: self-signed-ca
           dnsNames:
             - envoy.scalar.example.com
       upstream:
         enabled: true
         overrideAuthority: "auditor.scalardl.example.com"
   
   
   auditor:
   
     image:
       repository: "ghcr.io/scalar-labs/scalardl-auditor-byol"
   
     auditorProperties: |
       ### Storage configurations
       scalar.db.storage=jdbc
       scalar.db.contact_points=jdbc:postgresql://postgresql-auditor.default.svc.cluster.local:5432/postgres
       scalar.db.username=${env:SCALAR_DL_AUDITOR_POSTGRES_USERNAME}
       scalar.db.password=${env:SCALAR_DL_AUDITOR_POSTGRES_PASSWORD}
   
       ### Auditor configurations
       scalar.dl.auditor.ledger.host=scalardl-ledger-envoy.default.svc.cluster.local
       scalar.dl.auditor.authentication.method=hmac
       scalar.dl.auditor.authentication.hmac.cipher_key=${env:SCALAR_DL_AUDITOR_HMAC_CIPHER_KEY}
       scalar.dl.auditor.servers.authentication.hmac.secret_key=${env:SCALAR_DL_AUDITOR_HMAC_SECRET_KEY}
   
       ### TLS configurations
       scalar.dl.auditor.server.tls.enabled=true
       scalar.dl.auditor.server.tls.cert_chain_path=/tls/scalardl-auditor/certs/tls.crt
       scalar.dl.auditor.server.tls.private_key_path=/tls/scalardl-auditor/certs/tls.key
       scalar.dl.auditor.tls.enabled=true
       scalar.dl.auditor.tls.ca_root_cert_path=/tls/scalardl-ledger/certs/ca.crt
       scalar.dl.auditor.tls.override_authority=envoy.scalar.example.com
   
       ### License key configurations
       scalar.dl.licensing.license_key=${env:SCALAR_DL_AUDITOR_LICENSE_KEY}
       scalar.dl.licensing.license_check_cert_pem=${env:SCALAR_DL_AUDITOR_LICENSE_CHECK_CERT_PEM}
   
     tls:
       enabled: true
       overrideAuthority: "auditor.scalardl.example.com"
       certManager:
         enabled: true
         issuerRef:
           name: self-signed-ca
         dnsNames:
           - auditor.scalardl.example.com
   
     secretName: "auditor-credentials-secret"
   EOF

4. Create a secret resource named ledger-credentials-secret that includes credentials and a license key.

   kubectl create secret generic ledger-credentials-secret \
   --from-literal=SCALAR_DL_LEDGER_POSTGRES_USERNAME=postgres \
   --from-literal=SCALAR_DL_LEDGER_POSTGRES_PASSWORD=postgres \
   --from-literal=SCALAR_DL_LEDGER_HMAC_CIPHER_KEY=ledger-hmac-cipher-key \
   --from-literal=SCALAR_DL_LEDGER_HMAC_SECRET_KEY=scalardl-hmac-secret-key \
   --from-literal=SCALAR_DL_LEDGER_LICENSE_KEY="${SCALAR_DL_LEDGER_LICENSE_KEY}" \
   --from-file=SCALAR_DL_LEDGER_LICENSE_CHECK_CERT_PEM=<(echo ${SCALAR_DL_LEDGER_LICENSE_CHECK_CERT_PEM} | sed 's/\\n/\
   /g') \
   -n default

5. Create a secret resource named auditor-credentials-secret that includes credentials and a license key.

   kubectl create secret generic auditor-credentials-secret \
   --from-literal=SCALAR_DL_AUDITOR_POSTGRES_USERNAME=postgres \
   --from-literal=SCALAR_DL_AUDITOR_POSTGRES_PASSWORD=postgres \
   --from-literal=SCALAR_DL_AUDITOR_HMAC_CIPHER_KEY=auditor-hmac-cipher-key \
   --from-literal=SCALAR_DL_AUDITOR_HMAC_SECRET_KEY=scalardl-hmac-secret-key \
   --from-literal=SCALAR_DL_AUDITOR_LICENSE_KEY="${SCALAR_DL_AUDITOR_LICENSE_KEY}" \
   --from-file=SCALAR_DL_AUDITOR_LICENSE_CHECK_CERT_PEM=<(echo ${SCALAR_DL_AUDITOR_LICENSE_CHECK_CERT_PEM} | sed 's/\\n/\
   /g') \
   -n default

6. Create a secret resource named auditor-keys to disable the digital-signature authentication method. In this tutorial, you'll use the hmac authentication method instead of digital-signature.

   kubectl create secret generic auditor-keys \
     --from-literal=tls.key=dummy-data-to-disable-digital-signature-method \
     --from-literal=certificate=dummy-data-to-disable-digital-signature-method \
     -n default

   Note: If you use hmac as an authentication method, you have to create a dummy secret auditor-key to disable digital-signature on the Helm Chart side.

7. Set the chart version of ScalarDL Ledger and ScalarDL Auditor.

   SCALAR_DL_LEDGER_CHART_VERSION=$(helm search repo scalar-labs/scalardl -l | grep -v -e "scalar-labs/scalardl-audit" | grep -F "${SCALAR_DL_VERSION}" | awk '{print $2}' | sort --version-sort -r | head -n 1)
   SCALAR_DL_AUDITOR_CHART_VERSION=$(helm search repo scalar-labs/scalardl-audit -l | grep -F "${SCALAR_DL_VERSION}" | awk '{print $2}' | sort --version-sort -r | head -n 1)

8. Deploy ScalarDL Ledger.

   helm install scalardl-ledger scalar-labs/scalardl -f ${HOME}/scalardl-test/scalardl-ledger-custom-values.yaml --version ${SCALAR_DL_LEDGER_CHART_VERSION} -n default

9. Deploy ScalarDL Auditor.

   helm install scalardl-auditor scalar-labs/scalardl-audit -f ${HOME}/scalardl-test/scalardl-auditor-custom-values.yaml --version ${SCALAR_DL_AUDITOR_CHART_VERSION} -n default

10. Check if the ScalarDL Ledger and ScalarDL Auditor pods are deployed.

    kubectl get pod -n default

    [Command execution result]

    NAME                                         READY   STATUS      RESTARTS   AGE
    postgresql-auditor-0                         1/1     Running     0          14m
    postgresql-ledger-0                          1/1     Running     0          14m
    scalardl-auditor-auditor-5b885ff4c8-fwkpf    1/1     Running     0          18s
    scalardl-auditor-auditor-5b885ff4c8-g69cb    1/1     Running     0          18s
    scalardl-auditor-auditor-5b885ff4c8-nsmnq    1/1     Running     0          18s
    scalardl-auditor-envoy-689bcbdf65-5mn6v      1/1     Running     0          18s
    scalardl-auditor-envoy-689bcbdf65-fpq8j      1/1     Running     0          18s
    scalardl-auditor-envoy-689bcbdf65-lsz2t      1/1     Running     0          18s
    scalardl-ledger-envoy-547bbf7546-n7p5x       1/1     Running     0          26s
    scalardl-ledger-envoy-547bbf7546-p8nwp       1/1     Running     0          26s
    scalardl-ledger-envoy-547bbf7546-pskpb       1/1     Running     0          26s
    scalardl-ledger-ledger-6db5dc8774-5zsbj      1/1     Running     0          26s
    scalardl-ledger-ledger-6db5dc8774-vnmrw      1/1     Running     0          26s
    scalardl-ledger-ledger-6db5dc8774-wpjvs      1/1     Running     0          26s
    schema-loader-auditor-schema-loading-dvc5r   0/1     Completed   0          11m
    schema-loader-ledger-schema-loading-mtllb    0/1     Completed   0          11m

    If the ScalarDL Ledger and ScalarDL Auditor pods are deployed properly, the STATUS column for those pods will be displayed as Running.

11. Check if the ScalarDL Ledger and ScalarDL Auditor services are deployed.

    kubectl get svc -n default

    [Command execution result]

    NAME                             TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                         AGE
    kubernetes                       ClusterIP   10.96.0.1        <none>        443/TCP                         47d
    postgresql-auditor               ClusterIP   10.107.9.78      <none>        5432/TCP                        15m
    postgresql-auditor-hl            ClusterIP   None             <none>        5432/TCP                        15m
    postgresql-ledger                ClusterIP   10.108.241.181   <none>        5432/TCP                        15m
    postgresql-ledger-hl             ClusterIP   None             <none>        5432/TCP                        15m
    scalardl-auditor-envoy           ClusterIP   10.100.61.202    <none>        40051/TCP,40052/TCP             55s
    scalardl-auditor-envoy-metrics   ClusterIP   10.99.6.227      <none>        9001/TCP                        55s
    scalardl-auditor-headless        ClusterIP   None             <none>        40051/TCP,40053/TCP,40052/TCP   55s
    scalardl-auditor-metrics         ClusterIP   10.108.1.147     <none>        8080/TCP                        55s
    scalardl-ledger-envoy            ClusterIP   10.101.191.116   <none>        50051/TCP,50052/TCP             61s
    scalardl-ledger-envoy-metrics    ClusterIP   10.106.52.103    <none>        9001/TCP                        61s
    scalardl-ledger-headless         ClusterIP   None             <none>        50051/TCP,50053/TCP,50052/TCP   61s
    scalardl-ledger-metrics          ClusterIP   10.99.122.106    <none>        8080/TCP                        61s

    If the ScalarDL Ledger and ScalarDL Auditor services are deployed properly, you can see private IP addresses in the CLUSTER-IP column.

注記

The CLUSTER-IP values for scalardl-ledger-headless, scalardl-auditor-headless, postgresql-ledger-hl, and postgresql-auditor-hl are None since they have no IP addresses.

Step 7. Start a client container

You'll use the CA certificate file in a client container. Therefore, you'll need to create a secret resource and mount it to the client container.

1. Create a secret resource named client-ca-cert.

   kubectl create secret generic client-ca-cert --from-file=ca.crt=<(kubectl get secret self-signed-ca-cert-secret -o "jsonpath={.data['ca\.crt']}" | base64 -d) -n default

2. Create a manifest file for a client pod (scalardl-client-pod.yaml).

   cat << 'EOF' > ${HOME}/scalardl-test/scalardl-client-pod.yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: "scalardl-client"
   spec:
     containers:
       - name: scalardl-client
         image: eclipse-temurin:8-jdk
         command: ['sleep']
         args: ['inf']
         env:
           - name: SCALAR_DL_VERSION
             value: SCALAR_DL_CLIENT_POD_SCALAR_DL_VERSION
         volumeMounts:
           - name: "client-ca-cert"
             mountPath: "/certs/"
             readOnly: true
     volumes:
       - name: "client-ca-cert"
         secret:
           secretName: "client-ca-cert"
     restartPolicy: Never
   EOF

3. Set the ScalarDL version in the manifest file.

   sed -i s/SCALAR_DL_CLIENT_POD_SCALAR_DL_VERSION/${SCALAR_DL_VERSION}/ ${HOME}/scalardl-test/scalardl-client-pod.yaml

4. Deploy the client pod.

   kubectl apply -f ${HOME}/scalardl-test/scalardl-client-pod.yaml -n default

5. Check if the client container is running.

   kubectl get pod scalardl-client -n default

   [Command execution result]

   NAME              READY   STATUS    RESTARTS   AGE
   scalardl-client   1/1     Running   0          4s

Step 8. Run ScalarDL sample contracts in the client container

The following explains the minimum steps needed to run sample contracts. For more details about ScalarDL Ledger and ScalarDL Auditor, see the following:

• Getting Started with ScalarDL
• Getting Started with ScalarDL Auditor

1. Run bash in the client container.

   kubectl exec -it scalardl-client -n default -- bash

   The commands in the following steps must be run in the client container.

2. Install the git, curl, and unzip commands in the client container.

   apt update && apt install -y git curl unzip

3. Clone the ScalarDL Java Client SDK git repository.

   git clone https://github.com/scalar-labs/scalardl-java-client-sdk.git

4. Change the working directory to scalardl-java-client-sdk/.

   cd scalardl-java-client-sdk/

   pwd

   [Command execution result]

   /scalardl-java-client-sdk

5. Change the branch to the version you're using.

   git checkout -b v${SCALAR_DL_VERSION} refs/tags/v${SCALAR_DL_VERSION}

6. Build the sample contracts.

   ./gradlew assemble

7. Download the CLI tools for ScalarDL from ScalarDL Java Client SDK Releases.

   curl -OL https://github.com/scalar-labs/scalardl-java-client-sdk/releases/download/v${SCALAR_DL_VERSION}/scalardl-java-client-sdk-${SCALAR_DL_VERSION}.zip

8. Unzip the scalardl-java-client-sdk-${SCALAR_DL_VERSION}.zip file.

   unzip ./scalardl-java-client-sdk-${SCALAR_DL_VERSION}.zip

9. Create a configuration file named client.properties to access ScalarDL Ledger and ScalarDL Auditor on the Kubernetes cluster.

   cat << 'EOF' > client.properties
   # Ledger configuration
   scalar.dl.client.server.host=scalardl-ledger-envoy.default.svc.cluster.local
   scalar.dl.client.tls.enabled=true
   scalar.dl.client.tls.ca_root_cert_path=/certs/ca.crt
   scalar.dl.client.tls.override_authority=envoy.scalar.example.com
   
   # Auditor configuration
   scalar.dl.client.auditor.enabled=true
   scalar.dl.client.auditor.host=scalardl-auditor-envoy.default.svc.cluster.local
   scalar.dl.client.auditor.tls.enabled=true
   scalar.dl.client.auditor.tls.ca_root_cert_path=/certs/ca.crt
   scalar.dl.client.auditor.tls.override_authority=envoy.scalar.example.com
   
   # Client configuration
   scalar.dl.client.authentication_method=hmac
   scalar.dl.client.entity.id=client
   scalar.dl.client.entity.identity.hmac.secret_key=scalardl-hmac-client-secert-key
   EOF

10. Register the client secret.

    ./scalardl-java-client-sdk-${SCALAR_DL_VERSION}/bin/scalardl register-secret --config ./client.properties

11. Register the sample contract StateUpdater.

    ./scalardl-java-client-sdk-${SCALAR_DL_VERSION}/bin/scalardl register-contract --config ./client.properties --contract-id StateUpdater --contract-binary-name com.org1.contract.StateUpdater --contract-class-file ./build/classes/java/main/com/org1/contract/StateUpdater.class

12. Register the sample contract StateReader.

    ./scalardl-java-client-sdk-${SCALAR_DL_VERSION}/bin/scalardl register-contract --config ./client.properties --contract-id StateReader --contract-binary-name com.org1.contract.StateReader --contract-class-file ./build/classes/java/main/com/org1/contract/StateReader.class

13. Register the contract ValidateLedger to execute a validate request.

    ./scalardl-java-client-sdk-${SCALAR_DL_VERSION}/bin/scalardl register-contract --config ./client.properties --contract-id validate-ledger --contract-binary-name com.scalar.dl.client.contract.ValidateLedger --contract-class-file ./build/classes/java/main/com/scalar/dl/client/contract/ValidateLedger.class

14. Execute the contract StateUpdater.

    ./scalardl-java-client-sdk-${SCALAR_DL_VERSION}/bin/scalardl execute-contract --config ./client.properties --contract-id StateUpdater --contract-argument '{"asset_id": "test_asset", "state": 3}'

    This sample contract updates the state (value) of the asset named test_asset to 3.

15. Execute the contract StateReader.

    ./scalardl-java-client-sdk-${SCALAR_DL_VERSION}/bin/scalardl execute-contract --config ./client.properties --contract-id StateReader --contract-argument '{"asset_id": "test_asset"}'

    [Command execution result]

    Contract result:
    {
      "id" : "test_asset",
      "age" : 0,
      "output" : {
        "state" : 3
      }
    }

    Reference

    • If the asset data is not tampered with, running the execute-contract command to request contract execution will return OK as a result.

    • If the asset data is tampered with (for example, if the state value in the database is tampered with), running the execute-contract command to request contract execution will return a value other than OK (for example, INCONSISTENT_STATES) as a result. See the following as an example for how ScalarDL detects data tampering.

      [Command execution result (if the asset data is tampered with)]

      {
        "status_code" : "INCONSISTENT_STATES",
        "error_message" : "The results from Ledger and Auditor don't match"
      }

16. Execute a validation request for the asset.

    ./scalardl-java-client-sdk-${SCALAR_DL_VERSION}/bin/scalardl validate-ledger --config ./client.properties --asset-id "test_asset"

    [Command execution result]

    {
      "status_code" : "OK",
      "Ledger" : {
        "id" : "test_asset",
        "age" : 0,
        "nonce" : "3533427d-03cf-41d1-bf95-4d31eb0cb24d",
        "hash" : "FiquvtPMKLlxKf4VGoccSAGsi9ptn4ozYVVTwdSzEQ0=",
        "signature" : "MEYCIQDiiXqzw6K+Ml4uvn8rK43o5wHWESU3hoXnZPi6/OeKVwIhAM+tFBcapl6zg47Uq0Uc8nVNGWNHZLBDBGve3F0xkzTR"
      },
      "Auditor" : {
        "id" : "test_asset",
        "age" : 0,
        "nonce" : "3533427d-03cf-41d1-bf95-4d31eb0cb24d",
        "hash" : "FiquvtPMKLlxKf4VGoccSAGsi9ptn4ozYVVTwdSzEQ0=",
        "signature" : "MEUCIQDLsfUR2PmxSvfpL3YvHJUkz00RDpjCdctkroZKXE8d5QIgH73FQH2e11jfnynD00Pp9DrIG1vYizxDsvxUsMPo9IU="
      }
    }

    Reference

    • If the asset data is not tampered with, running the validate-ledger command to request validation will return OK as the result.

    • If the asset data is tampered with (for example, if the state value in the database is tampered with), running the validate-ledger command to request validation will return a value other than OK (for example, INVALID_OUTPUT) as a result. See the following as an example for how ScalarDL detects data tampering.

      [Command execution result (if the asset data is tampered with)]

      {
        "status_code" : "INCONSISTENT_STATES",
        "error_message" : "The results from Ledger and Auditor don't match"
      }

17. Exit from the client container.

    exit

Step 9. Delete all resources

After completing the ScalarDL Ledger and ScalarDL Auditor tests on the Kubernetes cluster, remove all resources.

1. Uninstall ScalarDL Ledger, ScalarDL Auditor, ScalarDL Schema Loader, and PostgreSQL.

   helm uninstall -n default scalardl-ledger schema-loader-ledger postgresql-ledger scalardl-auditor schema-loader-auditor postgresql-auditor

2. Remove the self-signed CA.

   kubectl delete -f ./private-ca-custom-values.yaml

3. Uninstall cert-manager.

   helm uninstall -n cert-manager cert-manager

4. Remove the client container.

   kubectl delete pod scalardl-client --grace-period 0 -n default

5. Remove the secret resources.

   kubectl delete secrets self-signed-ca-cert-secret schema-ledger-credentials-secret schema-auditor-credentials-secret scalardl-ledger-tls-cert scalardl-ledger-envoy-tls-cert scalardl-auditor-tls-cert scalardl-auditor-envoy-tls-cert ledger-credentials-secret auditor-credentials-secret client-ca-cert auditor-keys

6. Remove the namespace cert-manager.

   kubectl delete ns cert-manager

7. Remove the working directory and sample files (configuration files).

   cd ${HOME}

   rm -rf ${HOME}/scalardl-test/

Further reading

You can see how to get started with monitoring or logging for Scalar products in the following tutorials:

• Getting Started with Helm Charts (Monitoring using Prometheus Operator)
• Getting Started with Helm Charts (Logging using Loki Stack)
• Getting Started with Helm Charts (Scalar Manager)