Configure a custom values file for ScalarDB Cluster

This document explains how to create your custom values file for the ScalarDB Cluster chart. For details on the parameters, see the README of the ScalarDB Cluster chart.

Required configurations

Image configurations

You must set scalardbCluster.image.repository. Be sure to specify the ScalarDB Cluster container image so that you can pull the image from the container repository.

scalardbCluster:
  image:
    repository: <SCALARDB_CLUSTER_CONTAINER_IMAGE>

Database configurations

You must set scalardbCluster.scalardbClusterNodeProperties. Please set scalardb-cluster-node.properties to this parameter. For more details on the configurations of ScalarDB Cluster, see ScalarDB Cluster Configurations.

scalardbCluster:
  scalardbClusterNodeProperties: |
    scalar.db.cluster.membership.type=KUBERNETES
    scalar.db.cluster.membership.kubernetes.endpoint.namespace_name=${env:SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAMESPACE_NAME}
    scalar.db.cluster.membership.kubernetes.endpoint.name=${env:SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAME}
    scalar.db.contact_points=localhost
    scalar.db.username=${env:SCALAR_DB_USERNAME}
    scalar.db.password=${env:SCALAR_DB_PASSWORD}
    scalar.db.storage=cassandra

Note that you must always set the following three properties if you deploy ScalarDB Cluster in a Kubernetes environment by using Scalar Helm Chart. These properties are fixed values. Since the properties don't depend on individual environments, you can set the same values by copying the following values and pasting them in scalardbCluster.scalardbClusterNodeProperties.

scalardbCluster:
  scalardbClusterNodeProperties: |
    scalar.db.cluster.membership.type=KUBERNETES
    scalar.db.cluster.membership.kubernetes.endpoint.namespace_name=${env:SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAMESPACE_NAME}
    scalar.db.cluster.membership.kubernetes.endpoint.name=${env:SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAME}

Optional configurations

Resource configurations (recommended in production environments)

To control pod resources by using requests and limits in Kubernetes, you can use scalardbCluster.resources.

Note that it is recommended to set at least 2vCPU / 4GB memory if you use the bring-your-own-license (BYOL) containers. Also, if you use the pay-as-you-go (PAYG) containers that the AWS Marketplace provides, you will not be able to run any containers that exceed the 2vCPU / 4GB memory configuration in resources.limits. If you exceed this resource limitation, the pods will automatically stop.

You can configure requests and limits by using the same syntax as requests and limits in Kubernetes. For more details on requests and limits in Kubernetes, see Resource Management for Pods and Containers.

scalardbCluster:
  resources:
    requests:
      cpu: 2000m
      memory: 4Gi
    limits:
      cpu: 2000m
      memory: 4Gi

Secret configurations (recommended in production environments)

To use environment variables to set some properties (e.g., credentials) in scalardbCluster.scalardbClusterNodeProperties, you can use scalardbCluster.secretName to specify the Secret resource that includes some credentials.

For example, you can set credentials for a backend database (scalar.db.username and scalar.db.password) by using environment variables, which makes your pods more secure.

For more details on how to use a Secret resource, see How to use Secret resources to pass the credentials as the environment variables into the properties file.

scalardbCluster:
  secretName: "scalardb-cluster-credentials-secret"

Affinity configurations (recommended in production environments)

To control pod deployment by using affinity and anti-affinity in Kubernetes, you can use scalardbCluster.affinity.

You can configure affinity and anti-affinity by using the same syntax for affinity and anti-affinity in Kubernetes. For more details on configuring affinity in Kubernetes, see Assigning Pods to Nodes.

scalardbCluster:
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - scalardb-cluster
                - key: app.kubernetes.io/app
                  operator: In
                  values:
                    - scalardb-cluster
            topologyKey: kubernetes.io/hostname
          weight: 50

Prometheus and Grafana configurations (recommended in production environments)

To monitor ScalarDB Cluster pods by using kube-prometheus-stack, you can set scalardbCluster.grafanaDashboard.enabled, scalardbCluster.serviceMonitor.enabled, and scalardbCluster.prometheusRule.enabled to true. When you set these configurations to true, the chart deploys the necessary resources and kube-prometheus-stack starts monitoring automatically.

scalardbCluster:
  grafanaDashboard:
    enabled: true
    namespace: monitoring
  serviceMonitor:
    enabled: true
    namespace: monitoring
    interval: 15s
  prometheusRule:
    enabled: true
    namespace: monitoring

SecurityContext configurations (default value is recommended)

To set SecurityContext and PodSecurityContext for ScalarDB Cluster pods, you can use scalardbCluster.securityContext and scalardbCluster.podSecurityContext.

You can configure SecurityContext and PodSecurityContext by using the same syntax as SecurityContext and PodSecurityContext in Kubernetes. For more details on the SecurityContext and PodSecurityContext configurations in Kubernetes, see Configure a Security Context for a Pod or Container.

scalardbCluster:
  podSecurityContext:
    seccompProfile:
      type: RuntimeDefault
  securityContext:
    capabilities:
      drop:
        - ALL
    runAsNonRoot: true
    allowPrivilegeEscalation: false

TLS configurations (optional based on your environment)

You can enable TLS in:

• The communications between the ScalarDB Cluster node and clients.
• The communications between all ScalarDB Cluster nodes (the cluster's internal communications).

You have several options for certificate management:

1. Management of private key and certificate files
   1. Manage your private key and certificate files automatically by using cert-manager.
      • This method can reduce maintenance or operation costs. For example, cert-manager automatically renews certificates before they expire and Scalar Helm Chart automatically mounts private key and certificate files on the Scalar product pods.
      • You cannot use a CA that cert-manager does not support. You can see the supported issuers in the cert-manager documentation.
   2. Manage your private key and certificate files manually.
      • You can issue and manage your private key and certificate files on your own by using your preferred method.
      • You can use any certificate even if cert-manager does not support it.
      • You must update secret resources when certificates expire.
2. Kinds of certificates
   1. Use a trusted CA (signed certificate by third party).
      • You can use trusted certificates from a third-party certificate issuer.
      • You can encrypt packets.
      • You must pay costs to issue trusted certificates.
   2. Use self-signed certificates.
      • You can reduce costs to issue certificates.
      • Reliability of certificates is lower than a trusted CA, but you can encrypt packets.

In other words, you have the following four options:

1. Use a self-signed CA with automatic management.
2. Use a trusted CA with automatic management.
3. Use a self-signed CA with manual management.
4. Use a trusted CA with manual management.

You should consider which method to use based on your security requirements. For guidance and related documentation for each method, refer to the following decision tree:

Enable TLS

You can enable TLS in all ScalarDB Cluster connections by using the following configurations:

scalardbCluster:
  scalardbClusterNodeProperties: |
    ...(omit)...
    scalar.db.cluster.tls.enabled=true
    scalar.db.cluster.tls.ca_root_cert_path=/tls/scalardb-cluster/certs/ca.crt
    scalar.db.cluster.node.tls.cert_chain_path=/tls/scalardb-cluster/certs/tls.crt
    scalar.db.cluster.node.tls.private_key_path=/tls/scalardb-cluster/certs/tls.key
    scalar.db.cluster.tls.override_authority=<HOSTNAME_OF_YOUR_CERTIFICATE>
  tls:
    enabled: true

Use your private key and certificate files

You can set your private key and certificate files by using the following configurations:

scalardbCluster:
  tls:
    enabled: true
    caRootCertSecret: "scalardb-cluster-tls-ca"
    certChainSecret: "scalardb-cluster-tls-cert"
    privateKeySecret: "scalardb-cluster-tls-key"

In this case, you have to create secret resources that include private key and certificate files for ScalarDB Cluster as follows, replacing the contents in the angle brackets as described:

kubectl create secret generic scalardb-cluster-tls-ca --from-file=ca.crt=/<PATH_TO_YOUR_CA_CERTIFICATE_FILE_FOR_SCALARDB_CLUSTER> -n <NAMESPACE>
kubectl create secret generic scalardb-cluster-tls-cert --from-file=tls.crt=/<PATH_TO_YOUR_CERTIFICATE_FILE_FOR_SCALARDB_CLUSTER> -n <NAMESPACE>
kubectl create secret generic scalardb-cluster-tls-key --from-file=tls.key=/<PATH_TO_YOUR_PRIVATE_KEY_FILE_FOR_SCALARDB_CLUSTER> -n <NAMESPACE>

For more details on how to prepare private key and certificate files, see How to create private key and certificate files for Scalar products.

Use a trusted CA with cert-manager to manage your private key and certificate files

You can manage your private key and certificate files with cert-manager by using the following configurations, replacing the content in the angle brackets as described:

note

• If you want to use cert-manager, you must deploy cert-manager and prepare the Issuers resource. For details, see the cert-manager documentation, Installation and Issuer Configuration.
• By default, Scalar Helm Chart creates a Certificate resource that satisfies the certificate requirements of Scalar products. The default certificate configuration is recommended, but if you use a custom certificate configuration, you must satisfy the certificate requirements of Scalar products. For details, see How to create private key and certificate files for Scalar products.

scalardbCluster:
  tls:
    enabled: true
    certManager:
      enabled: true
      issuerRef:
        name: <YOUR_TRUSTED_CA>
      dnsNames:
        - cluster.scalardb.example.com

In this case, cert-manager issues your private key and certificate files by using your trusted issuer. You don't need to mount your private key and certificate files manually.

Use a self-signed CA with cert-manager to manage your private key and certificate files

You can manage your private key and self-signed certificate files with cert-manager by using the following configurations:

note

• If you want to use cert-manager, you must deploy cert-manager. For more details on how to deploy cert-manager, see the Installation in the cert-manager official document.
• By default, Scalar Helm Chart creates a Certificate resource that satisfies the certificate requirements of Scalar products. We recommend the default certificate configuration, but if you custom certificate configuration, you must satisfy the certificate requirements of Scalar products. See How to create private key and certificate files for Scalar products.

scalardbCluster:
  tls:
    enabled: true
    certManager:
      enabled: true
      selfSigned:
        enabled: true
      dnsNames:
        - cluster.scalardb.example.com

In this case, Scalar Helm Charts and cert-manager issue your private key and self-signed certificate files. You don't need to mount your private key and certificate files manually.

Set custom authority for TLS communications

You can set the custom authority for TLS communications by using scalardbCluster.tls.overrideAuthority. This value doesn't change what host is actually connected. This value is intended for testing but may safely be used outside of tests as an alternative to DNS overrides. For example, you can specify the hostname presented in the certificate chain file that you set by using scalardbCluster.tls.certChainSecret. This chart uses this value for startupProbe and livenessProbe.

scalardbCluster:
  tls:
    enabled: true
    overrideAuthority: "cluster.scalardb.example.com"

Set a root CA certificate for Prometheus Operator

If you set scalardbCluster.serviceMonitor.enabled=true and scalardbCluster.tls.enabled=true (in other words, if you monitor ScalarDB Cluster with TLS configuration by using Prometheus Operator), you must set the secret name to scalardbCluster.tls.caRootCertSecretForServiceMonitor.

scalardbCluster:
  tls:
    enabled: true
    caRootCertSecretForServiceMonitor: "scalardb-cluster-tls-ca-for-prometheus"

In this case, you have to create secret resources that include a root CA certificate for ScalarDB Cluster in the same namespace as Prometheus as follows:

kubectl create secret generic scalardb-cluster-tls-ca-for-prometheus --from-file=ca.crt=/path/to/your/ca/certificate/file -n <NAMESPACE_SAME_AS_PROMETHEUS>

Replica configurations (optional based on your environment)

You can specify the number of ScalarDB Cluster replicas (pods) by using scalardbCluster.replicaCount.

scalardbCluster:
  replicaCount: 3

Logging configurations (optional based on your environment)

To change the ScalarDB Cluster log level, you can use scalardbCluster.logLevel.

scalardbCluster:
  logLevel: INFO

GraphQL configurations (optional based on your environment)

To use the GraphQL feature in ScalarDB Cluster, you can set scalardbCluster.graphql.enabled to true to deploy some resources for the GraphQL feature. Note that you also need to set scalar.db.graphql.enabled=true in scalardbCluster.scalardbClusterNodeProperties when using the GraphQL feature.

scalardbCluster:
  graphql:
    enabled: true

Also, you can configure the Service resource that accepts GraphQL requests from clients.

scalardbCluster:
  graphql:
    service:
      type: ClusterIP
      annotations: {}
      ports:
        graphql:
          port: 8080
          targetPort: 8080
          protocol: TCP

SQL configurations (optional based on your environment)

To use the SQL feature in ScalarDB Cluster, there is no configuration necessary for custom values files. You can use the feature by setting scalar.db.sql.enabled=true in scalardbCluster.scalardbClusterNodeProperties.

Scalar Envoy configurations (optional based on your environment)

To use ScalarDB Cluster with indirect mode, you must enable Envoy as follows.

envoy:
  enabled: true

Also, you must set the Scalar Envoy configurations in the custom values file for ScalarDB Cluster. This is because clients need to send requests to ScalarDB Cluster via Scalar Envoy as the load balancer of gRPC requests if you deploy ScalarDB Cluster in a Kubernetes environment with indirect mode.

For more details on Scalar Envoy configurations, see Configure a custom values file for Scalar Envoy.

envoy:
  configurationsForScalarEnvoy: 
    ...

scalardbCluster:
  configurationsForScalarDbCluster: 
    ...

Taint and toleration configurations (optional based on your environment)

If you want to control pod deployment by using the taints and tolerations in Kubernetes, you can use scalardbCluster.tolerations.

You can configure taints and tolerations by using the same syntax as the tolerations in Kubernetes. For details on configuring tolerations in Kubernetes, see the official Kubernetes documentation Taints and Tolerations.

scalardbCluster:
  tolerations:
    - effect: NoSchedule
      key: scalar-labs.com/dedicated-node
      operator: Equal
      value: scalardb-cluster

Encryption configurations (optional based on your environment)

You can enable encryption at rest to protect the data in the backend databases. When you use the encryption feature, you have the following two deployment options:

1. Use HashiCorp Vault (HashiCorp Cloud Platform (HCP) Vault Dedicated) to manage and store the DEKs.
2. Use ScalarDB Cluster to manage the DEK, and store it in Kubernetes Secrets.

Use HashiCorp Vault

You can use HashiCorp Vault (HCP Vault Dedicated) to encrypt data as follows, replacing the contents in the angle brackets as described:

scalardbCluster:
  scalardbClusterNodeProperties: |
    ...(omit)...
    scalar.db.cluster.encryption.enabled=true
    scalar.db.cluster.encryption.type=vault
    scalar.db.cluster.encryption.vault.address=https://<FQDN_OR_IP_OF_VAULT_SERVER>:<PORT_OF_VAULT_SERVER>
    scalar.db.cluster.encryption.vault.token=<TOKEN_OF_VAULT>
    scalar.db.cluster.encryption.vault.transit_secrets_engine_path=<PATH_TO_TRANSIT_OF_VAULT>
  encryption:
    enabled: true
    type: "vault"

Use ScalarDB Cluster and Kubernetes Secrets

You can use ScalarDB Cluster and Kubernetes Secrets to encrypt data as follows, replacing the contents in the angle brackets as described:

scalardbCluster:
  scalardbClusterNodeProperties: |
    ...(omit)...
    scalar.db.cluster.encryption.enabled=true
    scalar.db.cluster.encryption.type=self
    scalar.db.cluster.encryption.self.kubernetes.secret.namespace_name=${env:SCALAR_DB_CLUSTER_ENCRYPTION_SELF_KUBERNETES_SECRET_NAMESPACE_NAME}
  encryption:
    enabled: true
    type: "self"

In this case, you don't need to replace ${env:SCALAR_DB_CLUSTER_ENCRYPTION_SELF_KUBERNETES_SECRET_NAMESPACE_NAME} since the Helm Chart for ScalarDB Cluster automatically sets the namespace information as an environment variable. Because of this, you can keep the value ${env:SCALAR_DB_CLUSTER_ENCRYPTION_SELF_KUBERNETES_SECRET_NAMESPACE_NAME} as is.