Add documents of ScalarDB Analytics with PostgreSQL

scalar-labs · Nov 15, 2023 · 72d18ce · 72d18ce
1 parent 13636e2
commit 72d18ce
Show file tree

Hide file tree

Showing 6 changed files with 227 additions and 1 deletion.
diff --git a/docs/configure-custom-values-file.md b/docs/configure-custom-values-file.md
@@ -3,6 +3,7 @@
 When you deploy Scalar products using Scalar Helm Charts, you must prepare your custom values file based on your environment. Please refer to the following documents for more details on how to a create custom values file for each product.
 
 * [ScalarDB Cluster](./configure-custom-values-scalardb-cluster.md)
+* [ScalarDB Analytics with PostgreSQL](./configure-custom-values-scalardb-analytics-postgresql.md)
 * [ScalarDL Ledger](./configure-custom-values-scalardl-ledger.md)
 * [ScalarDL Auditor](./configure-custom-values-scalardl-auditor.md)
 * [ScalarDL Schema Loader](./configure-custom-values-scalardl-schema-loader.md)

diff --git a/docs/configure-custom-values-scalardb-analytics-postgresql.md b/docs/configure-custom-values-scalardb-analytics-postgresql.md
@@ -0,0 +1,179 @@
+# Configure a custom values file for ScalarDB Analytics with PostgreSQL
+
+This document explains how to create your custom values file for the ScalarDB Analytics with PostgreSQL chart. For details on the parameters, see the [README](https://github.com/scalar-labs/helm-charts/blob/main/charts/scalardb-analytics-postgresql/README.md) of the ScalarDB Analytics with PostgreSQL chart.
+
+## Required configurations
+
+### Database configurations
+
+You must set `scalardbAnalyticsPostgreSQL.databaseProperties`. Please set `database.properties` to this parameter. For more details on the configurations of ScalarDB, see [ScalarDB Configurations](https://github.com/scalar-labs/scalardb/blob/master/docs/configurations.md).
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  databaseProperties: |
+    scalar.db.contact_points=localhost
+    scalar.db.username=${env:SCALAR_DB_USERNAME:-}
+    scalar.db.password=${env:SCALAR_DB_PASSWORD:-}
+    scalar.db.storage=cassandra
+```
+
+### Namespaces configurations
+
+You must set `schemaImporter.namespaces`. Please set all namespaces that includes tables you want to read via ScalarDB Analytics with PostgreSQL.
+
+```yaml
+schemaImporter:
+  namespaces:
+    - namespace1
+    - namespace2
+    - namespace3
+```
+
+## Optional configurations
+
+### Resource configurations (recommended in production environments)
+
+To control pod resources by using requests and limits in Kubernetes, you can use `scalardbAnalyticsPostgreSQL.resources`.
+
+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](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  resources:
+    requests:
+      cpu: 1000m
+      memory: 2Gi
+    limits:
+      cpu: 2000m
+      memory: 4Gi
+```
+
+### Secret configurations (recommended in production environments)
+
+To use environment variables to set some properties (e.g., credentials) in `scalardbAnalyticsPostgreSQL.databaseProperties`, you can use `scalardbAnalyticsPostgreSQL.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](./use-secret-for-credentials.md).
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  secretName: "scalardb-analytics-postgresql-credentials-secret"
+```
+
+### Affinity configurations (recommended in production environments)
+
+To control pod deployment by using affinity and anti-affinity in Kubernetes, you can use `scalardbAnalyticsPostgreSQL.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](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/).
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  affinity:
+    podAntiAffinity:
+      requiredDuringSchedulingIgnoredDuringExecution:
+        - labelSelector:
+            matchExpressions:
+              - key: app.kubernetes.io/name
+                operator: In
+                values:
+                  - scalardb-analytics-postgresql
+              - key: app.kubernetes.io/app
+                operator: In
+                values:
+                  - scalardb-analytics-postgresql
+          topologyKey: kubernetes.io/hostname
+```
+
+### SecurityContext configurations (default value is recommended)
+
+To set SecurityContext and PodSecurityContext for ScalarDB Analytics with PostgreSQL pods, you can use `scalardbAnalyticsPostgreSQL.securityContext`, `scalardbAnalyticsPostgreSQL.podSecurityContext`, and `schemaImporter.securityContext`.
+
+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](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/).
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  podSecurityContext:
+    fsGroup: 201
+    seccompProfile:
+      type: RuntimeDefault
+  securityContext:
+    capabilities:
+      drop:
+        - ALL
+    runAsNonRoot: true
+    runAsUser: 999
+    allowPrivilegeEscalation: false
+
+schemaImporter:
+  securityContext:
+    capabilities:
+      drop:
+        - ALL
+    runAsNonRoot: true
+    allowPrivilegeEscalation: false
+```
+
+### Image configurations (default value is recommended)
+
+If you want to change the image repository, you can use `scalardbAnalyticsPostgreSQL.image.repository` and `schemaImporter.image.repository` to specify the container repository information of the ScalarDB Analytics with PostgreSQL and Schema Importer images that you want to pull.
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  image:
+    repository: <SCALARDB_ANALYTICS_WITH_POSTGRESQL_CONTAINER_IMAGE>
+
+schemaImporter:
+  image:
+    repository: <SCHEMA_IMPORTER_CONTAINER_IMAGE>
+```
+
+### Replica configurations (optional based on your environment)
+
+You can specify the number of ScalarDB Analytics with PostgreSQL replicas (pods) by using `scalardbAnalyticsPostgreSQL.replicaCount`.
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  replicaCount: 3
+```
+
+### PostgreSQL database name configuration (optional based on your environment)
+
+You can specify the database name that you create in PostgreSQL. Schema Importer creates some object such a view of ScalarDB Analytics with PostgreSQL in this database.
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  postgresql:
+  databaseName: scalardb
+```
+
+### PostgreSQL superuser password configuration (optional based on your environment)
+
+You can specify the secret name that includes superuser password for PostgreSQL.
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  postgresql:
+  secretName: scalardb-analytics-postgresql-superuser-password
+```
+
+{% capture notice--info %}
+**Note**
+
+You must create a secret resource with this name (`scalardb-analytics-postgresql-superuser-password` by default) before you deploy ScalarDB Analytics with PostgreSQL. See [Prepare a secret resource](./how-to-deploy-scalardb-analytics-postgresql.md#prepare-a-secret-resource) for more details.
+{% endcapture %}
+
+### 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 `scalardbAnalyticsPostgreSQL.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](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/).
+
+```yaml
+scalardbAnalyticsPostgreSQL:
+  tolerations:
+    - effect: NoSchedule
+      key: scalar-labs.com/dedicated-node
+      operator: Equal
+      value: scalardb-analytics-postgresql
+```
diff --git a/docs/how-to-deploy-scalar-products.md b/docs/how-to-deploy-scalar-products.md
@@ -51,6 +51,7 @@ If you use a Kubernetes cluster other than EKS or AKS, you need to create a Secr
 Please refer to the following documents for more details on how to deploy each product.
 
 * [ScalarDB Cluster](./how-to-deploy-scalardb-cluster.md)
+* [ScalarDB Analytics with PostgreSQL](./how-to-deploy-scalardb-analytics-postgresql.md)
 * [ScalarDL Ledger](./how-to-deploy-scalardl-ledger.md)
 * [ScalarDL Auditor](./how-to-deploy-scalardl-auditor.md)
 * [Scalar Manager](./how-to-deploy-scalar-manager.md)

diff --git a/docs/how-to-deploy-scalardb-analytics-postgresql.md b/docs/how-to-deploy-scalardb-analytics-postgresql.md
@@ -0,0 +1,29 @@
+# How to deploy ScalarDB Analytics with PostgreSQL
+
+This document explains how to deploy ScalarDB Analytics with PostgreSQL by using Scalar Helm Charts. For details on the custom values file for ScalarDB Analytics with PostgreSQL, see [Configure a custom values file for ScalarDB Analytics with PostgreSQL](./configure-custom-values-scalardb-analytics-postgresql.md).
+
+## Prepare a secret resource
+
+You must create a secret resource `scalardb-analytics-postgresql-superuser-password` that includes a superuser password for PostgreSQL before you deploy ScalarDB Analytics with PostgreSQL. Scalar Helm Chart mounts this secret resource and set environment variable `POSTGRES_PASSWORD` with the value of `<POSTGRESQL_PASSWORD>`.
+
+```console
+kubectl create secret generic scalardb-analytics-postgresql-superuser-password --from-literal=POSTGRES_PASSWORD=<POSTGRESQL_PASSWORD> -n <NAMESPACE>
+```
+
+## Deploy ScalarDB Analytics with PostgreSQL
+
+```console
+helm install <RELEASE_NAME> scalar-labs/scalardb-analytics-postgresql -n <NAMESPACE> -f /<PATH_TO_YOUR_CUSTOM_VALUES_FILE_FOR_SCALARDB_ANALYTICS_WITH_POSTGRESQL> --version <CHART_VERSION>
+```
+
+## Upgrade a ScalarDB Analytics with PostgreSQL deployment
+
+```console
+helm upgrade <RELEASE_NAME> scalar-labs/scalardb-analytics-postgresql -n <NAMESPACE> -f /<PATH_TO_YOUR_CUSTOM_VALUES_FILE_FOR_SCALARDB_ANALYTICS_WITH_POSTGRESQL> --version <CHART_VERSION>
+```
+
+## Delete a ScalarDB Analytics with PostgreSQL deployment
+
+```console
+helm uninstall <RELEASE_NAME> -n <NAMESPACE>
+```
diff --git a/docs/mount-files-or-volumes-on-scalar-pods.md b/docs/mount-files-or-volumes-on-scalar-pods.md
@@ -1,6 +1,6 @@
 # Mount any files or volumes on Scalar product pods
 
-You can mount any files or volumes on Scalar product pods when you use ScalarDB Server, ScalarDB Cluster, or ScalarDL Helm Charts (ScalarDL Ledger and ScalarDL Auditor).
+You can mount any files or volumes on Scalar product pods when you use ScalarDB Server, ScalarDB Cluster, ScalarDB Analytics with PostgreSQL or ScalarDL Helm Charts (ScalarDL Ledger and ScalarDL Auditor).
 
 ## Mount key and certificate files on a pod in ScalarDL Helm Charts
 
@@ -97,6 +97,7 @@ You can mount emptyDir to Scalar product pods by using the following keys in you
 * Keys
   * `scalardb.extraVolumes` / `scalardb.extraVolumeMounts` (ScalarDB Server)
   * `scalardbCluster.extraVolumes` / `scalardbCluster.extraVolumeMounts` (ScalarDB Cluster)
+  * `scalardbAnalyticsPostgreSQL.extraVolumes` / `scalardbAnalyticsPostgreSQL.extraVolumeMounts` (ScalarDB Analytics with PostgreSQL)
   * `ledger.extraVolumes` / `ledger.extraVolumeMounts` (ScalarDL Ledger)
   * `auditor.extraVolumes` / `auditor.extraVolumeMounts` (ScalarDL Auditor)
 

diff --git a/docs/use-secret-for-credentials.md b/docs/use-secret-for-credentials.md
@@ -57,6 +57,15 @@ SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAME
              scalar.db.password=${env:SCALAR_DB_PASSWORD}
              ...
          ```
+       * ScalarDB Analytics with PostgreSQL
+         ```yaml
+         scalardbAnalyticsPostgreSQL:
+           databaseProperties: |
+           ...
+           scalar.db.username=${env:SCALAR_DB_USERNAME}
+           scalar.db.password=${env:SCALAR_DB_PASSWORD}
+           ...
+         ```
        * ScalarDL Ledger (Go template syntax)
           ```yaml
           ledger:
@@ -98,6 +107,7 @@ SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAME
    * Keys
      * `scalardb.secretName` (ScalarDB Server)
      * `scalardbCluster.secretName` (ScalarDB Cluster)
+     * `scalardbAnalyticsPostgreSQL.secretName` (ScalarDB Analytics with PostgreSQL)
      * `ledger.secretName` (ScalarDL Ledger)
      * `auditor.secretName` (ScalarDL Auditor)
      * `schemaLoading.secretName` (ScalarDL Schema Loader)
@@ -112,6 +122,11 @@ SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAME
        scalardbCluster:
          secretName: "scalardb-cluster-credentials-secret"
        ```
+     * ScalarDB Analytics with PostgreSQL 
+       ```yaml
+       scalardbAnalyticsPostgreSQL:
+         secretName: scalardb-analytics-postgresql-credentials-secret
+       ```
      * ScalarDL Ledger
        ```yaml
        ledger: