Project: Vald (App Definition and Development / Database)
File: configuration.md

This page introduces best practices for setting up values for the Vald Helm Chart. Before reading, please read the overview of Vald Helm Chart in . <div class="notice"> This page shows the notable fields in Vald Helm Chart.<BR> It is highly recommended to verify before deployment. </div> It is highly recommended to specify the Vald version. You can specify the image version by setting `image.tag` field in each component (`[component].image.tag`) or `defaults` section. ```yaml defaults: image: tag: v1.5.6 ``` or you can use the older image only for a target component, e.g., the agent, ```yaml agent: image: tag: v1.5.5 ``` The default logging levels and formats are configured in `defaults.logging.level` and `defaults.logging.format`. You can also specify them in each component section (`[component].logging`). ```yaml defaults: logging: level: info format: raw ``` You can specify log level `debug` and JSON format for lb-gateway by the followings: ```yaml gateway: lb: logging: level: debug format: json ``` The logging level is defined in . Each Vald component has several types of servers. They can be configured by specifying the values in `defaults.server_config`. Examples: ```yaml defaults: server_config: servers: grpc: enabled: true host: 0.0.0.0 port: 8081 servicePort: 8081 server: mode: GRPC ... ``` In addition, they can be overwritten by setting each `[component].serverconfig`, e.g., `gateway.lb.serverconfig` is following. ```yaml gateway: lb: server_config: servers: rest: enabled: true host: 0.0.0.0 port: 8080 servicePort: 8080 server: mode: REST ... ``` gRPC server should be enabled because all Vald components use gRPC to communicate with others. The API specs are placed in . REST server is optional. The swagger specs are placed in . There are two built-in health check servers: liveness and readiness. They are used as servers for . The liveness health server is disabled by default due to the liveness probe may accidentally kill the Vald Agent component. ```yaml agent: server_config: healths: liveness: enabled: false ``` The metrics server enables easier debugging and monitoring of Vald components. There are two types of metrics servers: pprof and Prometheus. pprof server is implemented using Go's `net/http/pprof` package. You can use to analyze the exported profile result. Prometheus server is a exporter. It is required to set the `observability` section on each Vald component to enable the monitoring using Prometheus. Please refer to the next section. The observability features are useful for monitoring Vald components. These settings can be enabled by setting the `defaults.observability.enabled` field to the value `true` or by overriding it in each component (`[component].observability.enabled`). And also, enable each feature by setting the value `true` on its `enabled` field. If observability features are enabled, the metrics will be collected periodically. The duration can be set on `observability.collector.duration`. Please refer to for more detail. Vald Agent NGT uses as a core library for searching vectors. The behaviors of NGT can be configured by setting `agent.ngt` field object. The important parameters are the followings: `agent.ngt.dimension` `agent.ngt.distance_type`

Users should configure these parameters first to fit their use case. For further details, please read . Vald Agent NGT has a feature to start indexing automatically. The behavior of this feature can be configured with these parameters: `agent.ngt.autoindexduration_limit` `agent.ngt.autoindexcheck_duration` `agent.ngt.autoindexlength` <div class="notice"> While the Vald Agent NGT is in the process of creating indexes, it will ignore all search requests to the target pods. </div> <div class="warning"> When deploying Vald Index Manager, the above parameters should be set much longer than the Vald Index Manager settings (Please refer to the Vald Index Manager section).<BR> E.g., set agent.ngt.autoindexdurationlimit to "720h" and agent.ngt.autoindexcheckduration to "24h".<BR> This is because the Vald Index Manager accurately grasps the index information of each Vald Agent NGT and controls the execution timing of indexing.<BR><BR> When the setting parameter of Vald Agent NGT is shorter than the setting value of Vald Index Manager, Vald Agent NGT may start indexing by itself without the execution command from Vald Index Manager. If this happens, the Index Manager may not function properly. </div> Vald Agent Faiss uses as a core library for searching vectors. The behaviors of Faiss can be configured by setting `agent.faiss` field object. The important parameters are the followings: `agent.faiss.dimension` `agent.faiss.distance_type` `agent.faiss.m` `agent.faiss.metric_type` `agent.faiss.nbitsperidx` `agent.faiss.nlist` Users should configure these parameters first to fit their use case. For further details, please read . Vald Agent Faiss has a feature to start indexing automatically. The behavior of this feature can be configured with these parameters: `agent.faiss.autoindexduration_limit` `agent.faiss.autoindexcheck_duration` `agent.faiss.autoindexlength` <div class="notice"> While the Vald Agent Faiss is in the process of creating indexes, it will ignore all search requests to the target pods. </div> <div class="warning"> When deploying Vald Index Manager, the above parameters should be set much longer than the Vald Index Manager settings (Please refer to the Vald Index Manager section) or minus value.<BR> E.g., set agent.faiss.autoindexdurationlimit to "720h" or "-1h" and agent.faiss.autoindexcheckduration to "24h" or "-1h".<BR> This is because the Vald Index Manager accurately grasps the index information of each Vald Agent Faiss and controls the execution timing of indexing.<BR><BR> When the setting parameter of Vald Agent Faiss is shorter than the setting value of Vald Index Manager, Vald Agent Faiss may start indexing by itself without the execution command from Vald Index Manager. If this happens, the Index Manager may not function properly. </div> Because the Vald Agent pod places indexes on memory, termination of agent pods causes loss of indexes. It is important to set the resource requests and limits appropriately to avoid terminating the Vald Agent pods. Requesting 40% of cluster memory for agent pods is highly recommended. Also, it is highly recommended not to set the resource limits for the Vald Agent pods. Pod priorities are also useful for saving agent pods from eviction. By default, very high priority is set to agent pods in the Chart. helps to estimate the

It is recommended to schedule agent pods on different nodes as much as possible. <div class="warning"> The affinity setting for Vald Agent is significant for the Vald cluster.<BR> Please DO NOT remove the default settings. </div> To achieve this, the following is set by default. ```yaml agent: affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: weight: 100 podAffinityTerm: topologyKey: kubernetes.io/hostname labelSelector: matchExpressions: key: app operator: In values: vald-agent-ngt ``` It can also be achieved by using . ```yaml agent: topologySpreadConstraints: topologyKey: node maxSkew: 1 whenUnsatisfiable: ScheduleAnyway labelSelector: matchLabels: app: vald-agent-ngt affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: [] # to disable default settings ``` Ingress for gateways can be configured by `gateway.{filter,lb}.ingress` field object. It is important to set your host to `gateway.{filter,lb}.ingress.host` field. `gateway.{filter,lb}.ingress.servicePort` should be `grpc` or `rest`. ```yaml gateway: lb: ingress: enabled: true host: vald.vdaas.org # Set correct hostname here servicePort: grpc ``` `gateway.lb.gatewayconfig.indexreplica` represents how many Vald Agent pods a vector will be inserted into. The maximum value of the index replica should be 30% of the Vald Agent pods deployed. ```yaml gateway: lb: gateway_config: index_replica: 3 // By setting the index replica to 3, the number of Vald Agent pods deployed should be more than 9 (3 / 0.3). ``` The gateway's resource requests and limits depend on the request traffic and available resources. If the request traffic varies largely, enabling HPA for the gateway and adjusting the resource requests is recommended. `gateway.lb.gateway_config.discoverer.duration` represents the frequency of sending requests to the discoverer. If the discoverer's CPU utilization is too high, make this value longer or reduce the number of LB gateway pods. ```yaml gateway: lb: gateway_config: discoverer: duration: 2s ``` Vald Discoverer gets the Node and Pod metrics from as described in . Vald's Helm deployment supports RBAC as default, and the default configuration is the following. ```yaml discoverer: clusterRole: enabled: true name: discoverer clusterRoleBinding: enabled: true name: discoverer serviceAccount: enabled: true name: vald ``` When `RBAC` is unavailable in your environment, or you would like to put some restrictions, please modify it and grant the permissions to the user executing the discoverer. Each configuration file is the following: The number of discoverer pods and resource limits can be estimated by the configurations of your LB gateways and index managers because its APIs are called by them. Discoverer CPU loads almost depend on API request traffic. ```bash (the number of LB gateways x its request frequency) + (the number of index managers x its request frequency). ``` Vald Index Manager controls the indexing timing for all Vald Agent pods in the Vald cluster. These parameters are related to the control process. ```yaml manager: index: indexer: agent_namespace: vald # namespace of agent pods to manage autoindexcheck_duration: "1m" autoindexduration_limit: "30m" autoindexlength: 100 autosaveindexdurationlimit: "3h" autosaveindexwaitduration: "10m" concurrency: 1 creationpoolsize: 10000 ``` Same as LB gateway, `manager.index.indexer.discoverer.duration` represents the frequency of sending requests to the discoverer. For further details, there are references to the Helm values in the Vald GitHub repository. <!-- TODO: add related document(pullugable options) -->