## Requirements - A recent Kubernetes Cluster (at least version 1.23). If you are in a development environment, consider using the kubernetes cluster that is built into Docker desktop. For more information, see the [Docker documentation](https://docs.docker.com/desktop/kubernetes/). - The cluster needs to be able to provision `PersistentVolumes` using Kubernetes' `PersistentVolumeClaims`. - A file system that can be mounted read-write by a single node to allow Kubernetes' `ReadWriteOnce` access mode. - Helm version v3 or higher. The current Helm chart is version `17.8.1`. :::callout{intent="note" title="Telemetry"} To help us improve Weaviate and understand community usage trends, Weaviate collects telemetry data by default. To learn more or opt-out, click [here](../monitoring-and-logging/telemetry.md). ::: ## Weaviate Helm chart :::callout{intent="note" title="Important: Set the correct Weaviate version"} As a best practice, explicitly set the Weaviate version in the Helm chart. Set the version in your `values.yaml` file or [overwrite the default value](#deploy-install-the-helm-chart) during deployment. ::: To install the Weaviate chart on your Kubernetes cluster, follow these steps: ### Verify tool setup and cluster access ```bash # Check if helm is installed helm version # Make sure `kubectl` is configured correctly and you can access the cluster. # For example, try listing the pods in the currently configured namespace. kubectl get pods ``` ### Get the Helm Chart Add the Weaviate helm repo that contains the Weaviate helm chart. ```bash helm repo add weaviate https://weaviate.github.io/weaviate-helm helm repo update ``` Get the default `values.yaml` configuration file from the Weaviate helm chart: ```bash helm show values weaviate/weaviate > values.yaml ``` ### Modify values.yaml To customize the Helm chart for your environment, edit the [`values.yaml`](https://github.com/weaviate/weaviate-helm/blob/master/weaviate/values.yaml) file. The default `yaml` file is extensively documented to help you configure your system. #### Replication The default configuration defines one Weaviate replica cluster. #### Local models Local models, such as `text2vec-transformers`, `qna-transformers`, and `img2vec-neural` are disabled by default. To enable a model, set the model's `enabled` flag to `true`. #### Resource limits Starting in Helm chart version 17.0.1, constraints on module resources are commented out to improve performance. To constrain resources for specific modules, add the constraints in your `values.yaml` file. #### gRPC service configuration Starting in Helm chart version 17.0.0, the gRPC service is enabled by default. If you use an older Helm chart, edit your `values.yaml` file to enable gRPC. Check that the `enabled` field is set to `true` and the `type` field to `LoadBalancer`. These settings allow you to access the [gRPC API](https://weaviate.io/blog/grpc-performance-improvements) from outside the Kubernetes cluster. ```yaml grpcService: enabled: true # ⬅️ Make sure this is set to true name: weaviate-grpc ports: - name: grpc protocol: TCP port: 50051 type: LoadBalancer # ⬅️ Set this to LoadBalancer (from NodePort) ``` #### Authentication and authorization :::callout{intent="tip"} Weaviate Helm charts automatically generate random username/password values each time Weaviate is deployed to Kubernetes, this means that when Weaviate is deployed with Helm charts internode communication is always secured. ::: An example configuration for authentication: ```yaml authentication: apikey: enabled: true allowed_keys: - readonly-key - secr3tk3y users: - readonly@example.com - admin@example.com anonymous_access: enabled: false oidc: enabled: true issuer: https://auth.wcs.api.weaviate.io/auth/realms/SeMI username_claim: email groups_claim: groups client_id: wcs authorization: admin_list: enabled: true users: - someuser@weaviate.io - admin@example.com readonly_users: - readonly@example.com ``` In this example, the key `readonly-key` will authenticate a user as the `readonly@example.com` identity, and `secr3tk3y` will authenticate a user as `admin@example.com`. OIDC authentication is also enabled, with WCD as the token issuer/identity provider. Thus, users with WCD accounts could be authenticated. This configuration sets `someuser@weaviate.io` as an admin user, so if `someuser@weaviate.io` were to authenticate, they will be given full (read and write) privileges. :::callout{intent="warning"} Connecting to Weaviate Cloud (WCD) using OIDC is deprecated and should not be used. Please use [API key authentication](../manage-clusters/connect.md#connect-with-an-api-programmatically) instead. ::: For further, general documentation on authentication and authorization configuration, see: - [Authentication](../authorization-and-authentication/deploy-configuration-authentication.md) - [Authorization](../authorization-and-authentication/deploy-configuration-authorization.md) #### Run as non-root user By default, weaviate runs as the root user. To run as a non-privileged user, edit the settings in the `containerSecurityContext` section. The `init` container always runs as root to configure the node. Once the system is started, it run a non-privileged user if you have one configured. ### Deploy (install the Helm chart) You can deploy the helm charts as follows: ```bash # Create a Weaviate namespace kubectl create namespace weaviate # Deploy helm upgrade --install \ "weaviate" \ weaviate/weaviate \ --namespace "weaviate" \ --values ./values.yaml ``` The above assumes that you have permissions to create a new namespace. If you have only namespace-level permissions, you can skip creating a new namespace and adjust the namespace argument on `helm upgrade` according to the name of your pre-configured namespace. Optionally, you can provide the `--create-namespace` parameter which will create the namespace if not present. ### Updating the installation after the initial deployment The above command (`helm upgrade...`) is idempotent. In other words, you can run it multiple times after adjusting your desired configuration without causing any unintended changes or side effects. ### Upgrading to `1.25` or higher from pre-`1.25` :::callout{intent="warning" title="Important"} ::: To upgrade to `1.25` or higher from a pre-`1.25` version, you must delete the deployed `StatefulSet`, update the helm chart to version `17.0.0` or higher, and re-deploy Weaviate. See the [1.25 migration guide for Kubernetes](../deploy-migration/weaviate-1-25.md) for more details. ## Additional Configuration Help - [Cannot list resource "configmaps" in API group when deploying Weaviate k8s setup on GCP](https://stackoverflow.com/questions/58501558/cannot-list-resource-configmaps-in-api-group-when-deploying-weaviate-k8s-setup) - [Error: UPGRADE FAILED: configmaps is forbidden](https://stackoverflow.com/questions/58501558/cannot-list-resource-configmaps-in-api-group-when-deploying-weaviate-k8s-setup) ### Using EFS with Weaviate In some circumstances, you may wish, or need, to use EFS (Amazon Elastic File System) with Weaviate. And we note in the case of AWS Fargate, you must create the [PV (persistent volume)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) manually, as the PVC will NOT create a PV for you. To use EFS with Weaviate, you need to: - Create an EFS file system. - Create an EFS access point for every Weaviate replica. - All of the Access Points must have a different root-directory so that Pods do not share the data, otherwise it will fail. - Create EFS mount targets for each subnet of the VPC where Weaviate is deployed. - Create StorageClass in Kubernetes using EFS. - Create Weaviate Volumes, where each volume has a different AccessPoint for VolumeHandle(as mentioned above). - Deploy Weaviate. This code is an example of a PV for `weaviate-0` Pod: ```yaml apiVersion: v1 kind: PersistentVolume metadata: name: weaviate-0 spec: capacity: storage: 8Gi volumeMode: Filesystem accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Delete storageClassName: "efs-sc" csi: driver: efs.csi.aws.com volumeHandle: :: claimRef: namespace: name: weaviate-data-weaviate-0 ``` For more, general information on running EFS with Fargate, we recommend reading [this AWS blog](https://aws.amazon.com/blogs/containers/running-stateful-workloads-with-amazon-eks-on-aws-fargate-using-amazon-efs/). ### Using Azure file CSI with Weaviate The provisioner `file.csi.azure.com` is **not supported** and will lead to file corruptions. Instead, make sure the storage class defined in values.yaml is from provisioner `disk.csi.azure.com`, for example: ```yaml storage: size: 32Gi storageClassName: managed ``` you can get the list of available storage classes in your cluster with: ``` kubectl get storageclasses ``` ## Troubleshooting - If you see `No private IP address found, and explicit IP not provided`, set the pod subnet to be in an valid ip address range of the following: ``` 10.0.0.0/8 100.64.0.0/10 172.16.0.0/12 192.168.0.0/16 198.19.0.0/16 ``` ### Set `CLUSTER_HOSTNAME` if it may change over time In some systems, the cluster hostname may change over time. This is known to create issues with a single-node Weaviate deployment. To avoid this, set the `CLUSTER_HOSTNAME` environment variable in the `values.yaml` file to the cluster hostname. ```yaml env: CLUSTER_HOSTNAME: "node-1" ``` ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=` scopes the answer to a mounted version when the portal publishes more than one. The response is `text/markdown`: the answer followed by a `# Sources` list of the portal pages it was grounded in. Status codes are the contract: - `200` — the answer; `402` — the portal owner’s plan or answer credits are exhausted (surface this to your operator; do NOT retry); `429` — you are rate-limited; back off for the `Retry-After` seconds; `503` — the answer lane is temporarily unavailable; fall back to crawling the `.md` pages. For the full corpus map read `llms.txt` at the site root; for the tool surface (search + page fetch as MCP tools) see `/mcp`.