qdrant-operator 0.2.1__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/PKG-INFO +137 -2
  2. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/README.md +135 -1
  3. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/pyproject.toml +2 -1
  4. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/pyproject.toml.orig +2 -1
  5. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/container.py +18 -0
  6. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/domain.py +899 -8
  7. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/handlers.py +124 -0
  8. qdrant_operator-0.3.1/src/qdrant_operator/jwt_adapter.py +29 -0
  9. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/kubernetes_adapter.py +39 -2
  10. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/ports.py +65 -0
  11. qdrant_operator-0.3.1/src/qdrant_operator/qdrant_adapter.py +225 -0
  12. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/s3_adapter.py +2 -1
  13. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/usecases.py +531 -0
  14. qdrant_operator-0.2.1/src/qdrant_operator/qdrant_adapter.py +0 -124
  15. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/LICENSE +0 -0
  16. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/__init__.py +0 -0
  17. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/helm_adapter.py +0 -0
  18. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/main.py +0 -0
  19. {qdrant_operator-0.2.1 → qdrant_operator-0.3.1}/src/qdrant_operator/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: qdrant-operator
3
- Version: 0.2.1
3
+ Version: 0.3.1
4
4
  Summary: Kubernetes operator for Qdrant vector database
5
5
  Keywords: kubernetes,operator,qdrant,kopf,vector-database
6
6
  Author: Mohamed Tahrioui
@@ -23,6 +23,7 @@ Requires-Dist: httpx>=0.28.0
23
23
  Requires-Dist: aioboto3>=13.0.0
24
24
  Requires-Dist: croniter>=5.0.0
25
25
  Requires-Dist: loguru>=0.7.3
26
+ Requires-Dist: pyjwt>=2.9
26
27
  Requires-Python: >=3.12
27
28
  Project-URL: Homepage, https://github.com/4thel00z/qdrant-operator
28
29
  Project-URL: Repository, https://github.com/4thel00z/qdrant-operator
@@ -44,10 +45,11 @@ Description-Content-Type: text/markdown
44
45
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
45
46
  [![Kubernetes](https://img.shields.io/badge/kubernetes-%3E%3D1.26-326ce5.svg)](https://kubernetes.io/)
46
47
 
48
+ [Documentation](https://4thel00z.github.io/qdrant-operator/) •
47
49
  [Features](#features) •
48
50
  [Installation](#installation) •
49
51
  [Usage](#usage) •
50
- [Configuration](#configuration) •
52
+ [Configuration](#configuration)
51
53
 
52
54
  </div>
53
55
 
@@ -59,6 +61,10 @@ Description-Content-Type: text/markdown
59
61
  - **Automated Backups** - Per-node snapshots streamed to S3-compatible storage, with a manifest
60
62
  - **Scheduled Backups** - CronJob-style schedules with concurrency and retention policies
61
63
  - **Disaster Recovery** - Restore collections node-by-node from presigned URLs, with optional remapping
64
+ - **Declarative Collections** - `QdrantCollection` keeps vectors, payload indexes and aliases in Git and re-creates what was deleted by hand
65
+ - **Least-Privilege Tokens** - `QdrantAccessKey` signs Qdrant JWT tokens per collection and writes them into a Secret, renewing before expiry
66
+ - **Live Migrations** - `QdrantMigration` copies collections between clusters (or from Qdrant Cloud) without an S3 round trip
67
+ - **Admission Validation** - CEL rules on every CRD reject impossible specs before the operator sees them
62
68
  - **Async-First** - Built on kopf with fully async adapters for performance
63
69
 
64
70
  ## Installation
@@ -85,6 +91,16 @@ helm install qdrant-operator ./charts/qdrant-operator -n qdrant-system --create-
85
91
  kubectl get pods -l app.kubernetes.io/name=qdrant-operator
86
92
  ```
87
93
 
94
+ #### Upgrading
95
+
96
+ Helm installs the CRDs in `crds/` once and never updates them. Before `helm upgrade`, apply the
97
+ CRDs of the new version (they are attached to every GitHub release):
98
+
99
+ ```bash
100
+ kubectl apply -f manifests/crds/
101
+ helm upgrade qdrant-operator oci://ghcr.io/4thel00z/charts/qdrant-operator -n qdrant-system
102
+ ```
103
+
88
104
  ### Configuration
89
105
 
90
106
  Override default values:
@@ -221,6 +237,125 @@ spec:
221
237
  old_collection: new_collection
222
238
  ```
223
239
 
240
+ ### Declare a Collection
241
+
242
+ ```yaml
243
+ apiVersion: qdrant.io/v1alpha1
244
+ kind: QdrantCollection
245
+ metadata:
246
+ name: articles
247
+ namespace: default
248
+ spec:
249
+ clusterRef:
250
+ name: my-qdrant
251
+ collectionName: Articles # optional; Qdrant names may use characters Kubernetes names cannot
252
+ vectors:
253
+ - name: text
254
+ size: 768
255
+ distance: Cosine
256
+ memory: cold # Qdrant 1.19+; use onDisk: true on older releases
257
+ - name: image
258
+ size: 512
259
+ distance: Dot
260
+ sparseVectors:
261
+ - name: bm25
262
+ modifier: idf
263
+ replicationFactor: 2
264
+ optimizers: # Qdrant's own field names, passed through
265
+ indexing_threshold: 10000
266
+ payloadIndexes:
267
+ - field: tenant_id
268
+ type: keyword
269
+ params: {is_tenant: true}
270
+ - field: body
271
+ type: text
272
+ params: {tokenizer: word, lowercase: true}
273
+ aliases: [articles-live]
274
+ metadata: {owner: search-team} # merged into the collection's metadata
275
+ deletionPolicy: Retain # Delete drops the collection with the resource
276
+ ```
277
+
278
+ Custom sharding declares its keys in the same resource; keys are created when missing and never
279
+ dropped, because dropping one deletes its points:
280
+
281
+ ```yaml
282
+ spec:
283
+ shardingMethod: custom
284
+ shardNumber: 1 # shards per key
285
+ shardKeys:
286
+ - key: eu
287
+ - key: us
288
+ replicationFactor: 2
289
+ ```
290
+
291
+ A single entry without `name` is Qdrant's unnamed vector. Vector size and distance, `shardNumber`
292
+ and `shardingMethod` cannot change on a live collection; a mismatch puts the resource into
293
+ `phase: Degraded` with a `Ready=False` condition instead of silently ignoring the spec. Everything
294
+ else is patched in place, and only fields you declared are compared. Indexes and aliases the
295
+ operator did not create are left alone.
296
+
297
+ ### Issue a Scoped Token
298
+
299
+ Requires `spec.apiKey.jwtRbac: true` on the cluster (tokens are signed with the cluster's API key).
300
+
301
+ ```yaml
302
+ apiVersion: qdrant.io/v1alpha1
303
+ kind: QdrantAccessKey
304
+ metadata:
305
+ name: billing-reader
306
+ namespace: default
307
+ spec:
308
+ clusterRef:
309
+ name: my-qdrant
310
+ collections: # or: access: r | m for cluster-wide tokens
311
+ - name: invoices
312
+ access: r # r, rw, or prw (points only, no snapshots or indexes)
313
+ subject: billing-service
314
+ ttl: 720h
315
+ renewBefore: 24h # default: a third of ttl
316
+ secretName: billing-qdrant # default: metadata.name
317
+ ```
318
+
319
+ The Secret gets `token` and `url` keys and is garbage-collected with the resource. The token is
320
+ re-issued when the spec changes, the cluster's API key rotates, the Secret disappears, or
321
+ `renewBefore` is reached.
322
+
323
+ ### Migrate Between Clusters
324
+
325
+ ```yaml
326
+ apiVersion: qdrant.io/v1alpha1
327
+ kind: QdrantMigration
328
+ metadata:
329
+ name: cloud-to-k8s
330
+ namespace: default
331
+ spec:
332
+ source:
333
+ endpoint: # or: clusterRef: {name: old-qdrant}
334
+ url: https://xyz.eu-central.aws.cloud.qdrant.io:6333
335
+ apiKeySecretRef: {name: qdrant-cloud, key: api-key}
336
+ targetClusterRef:
337
+ name: my-qdrant
338
+ collections: [articles] # empty = all
339
+ collectionMapping:
340
+ articles: articles_v2
341
+ batchSize: 500
342
+ batchDelayMs: 0 # throttle
343
+ ensurePayloadIndexes: true # also on targets that already exist
344
+ target: # for collections the migration creates
345
+ replicationFactor: 2
346
+ # shardKey: tier-a # route every point to one shard key
347
+ # shardKeyField: tenant # or route by a payload field
348
+ ```
349
+
350
+ Points are scrolled from the source and upserted on the target, so the run is idempotent and a
351
+ one-node source can become a three-node target (shard counts follow the target unless set under
352
+ `target`). Missing target collections are created from the source configuration, including
353
+ payload indexes; existing targets must have the same vector sizes and distances. On a
354
+ custom-sharded target, each point keeps its source shard key (keys are created as they are met)
355
+ unless routed with `target.shardKey` / `target.shardKeyField`; an auto-sharded target receives
356
+ the points without shard keys. Progress and the scroll offset live in `status`, so a
357
+ run interrupted by an operator restart resumes where it stopped.
358
+
224
359
  ## Configuration
225
360
 
226
361
  ### Environment Variables
@@ -12,10 +12,11 @@
12
12
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
13
13
  [![Kubernetes](https://img.shields.io/badge/kubernetes-%3E%3D1.26-326ce5.svg)](https://kubernetes.io/)
14
14
 
15
+ [Documentation](https://4thel00z.github.io/qdrant-operator/) •
15
16
  [Features](#features) •
16
17
  [Installation](#installation) •
17
18
  [Usage](#usage) •
18
- [Configuration](#configuration) •
19
+ [Configuration](#configuration)
19
20
 
20
21
  </div>
21
22
 
@@ -27,6 +28,10 @@
27
28
  - **Automated Backups** - Per-node snapshots streamed to S3-compatible storage, with a manifest
28
29
  - **Scheduled Backups** - CronJob-style schedules with concurrency and retention policies
29
30
  - **Disaster Recovery** - Restore collections node-by-node from presigned URLs, with optional remapping
31
+ - **Declarative Collections** - `QdrantCollection` keeps vectors, payload indexes and aliases in Git and re-creates what was deleted by hand
32
+ - **Least-Privilege Tokens** - `QdrantAccessKey` signs Qdrant JWT tokens per collection and writes them into a Secret, renewing before expiry
33
+ - **Live Migrations** - `QdrantMigration` copies collections between clusters (or from Qdrant Cloud) without an S3 round trip
34
+ - **Admission Validation** - CEL rules on every CRD reject impossible specs before the operator sees them
30
35
  - **Async-First** - Built on kopf with fully async adapters for performance
31
36
 
32
37
  ## Installation
@@ -53,6 +58,16 @@ helm install qdrant-operator ./charts/qdrant-operator -n qdrant-system --create-
53
58
  kubectl get pods -l app.kubernetes.io/name=qdrant-operator
54
59
  ```
55
60
 
61
+ #### Upgrading
62
+
63
+ Helm installs the CRDs in `crds/` once and never updates them. Before `helm upgrade`, apply the
64
+ CRDs of the new version (they are attached to every GitHub release):
65
+
66
+ ```bash
67
+ kubectl apply -f manifests/crds/
68
+ helm upgrade qdrant-operator oci://ghcr.io/4thel00z/charts/qdrant-operator -n qdrant-system
69
+ ```
70
+
56
71
  ### Configuration
57
72
 
58
73
  Override default values:
@@ -189,6 +204,125 @@ spec:
189
204
  old_collection: new_collection
190
205
  ```
191
206
 
207
+ ### Declare a Collection
208
+
209
+ ```yaml
210
+ apiVersion: qdrant.io/v1alpha1
211
+ kind: QdrantCollection
212
+ metadata:
213
+ name: articles
214
+ namespace: default
215
+ spec:
216
+ clusterRef:
217
+ name: my-qdrant
218
+ collectionName: Articles # optional; Qdrant names may use characters Kubernetes names cannot
219
+ vectors:
220
+ - name: text
221
+ size: 768
222
+ distance: Cosine
223
+ memory: cold # Qdrant 1.19+; use onDisk: true on older releases
224
+ - name: image
225
+ size: 512
226
+ distance: Dot
227
+ sparseVectors:
228
+ - name: bm25
229
+ modifier: idf
230
+ replicationFactor: 2
231
+ optimizers: # Qdrant's own field names, passed through
232
+ indexing_threshold: 10000
233
+ payloadIndexes:
234
+ - field: tenant_id
235
+ type: keyword
236
+ params: {is_tenant: true}
237
+ - field: body
238
+ type: text
239
+ params: {tokenizer: word, lowercase: true}
240
+ aliases: [articles-live]
241
+ metadata: {owner: search-team} # merged into the collection's metadata
242
+ deletionPolicy: Retain # Delete drops the collection with the resource
243
+ ```
244
+
245
+ Custom sharding declares its keys in the same resource; keys are created when missing and never
246
+ dropped, because dropping one deletes its points:
247
+
248
+ ```yaml
249
+ spec:
250
+ shardingMethod: custom
251
+ shardNumber: 1 # shards per key
252
+ shardKeys:
253
+ - key: eu
254
+ - key: us
255
+ replicationFactor: 2
256
+ ```
257
+
258
+ A single entry without `name` is Qdrant's unnamed vector. Vector size and distance, `shardNumber`
259
+ and `shardingMethod` cannot change on a live collection; a mismatch puts the resource into
260
+ `phase: Degraded` with a `Ready=False` condition instead of silently ignoring the spec. Everything
261
+ else is patched in place, and only fields you declared are compared. Indexes and aliases the
262
+ operator did not create are left alone.
263
+
264
+ ### Issue a Scoped Token
265
+
266
+ Requires `spec.apiKey.jwtRbac: true` on the cluster (tokens are signed with the cluster's API key).
267
+
268
+ ```yaml
269
+ apiVersion: qdrant.io/v1alpha1
270
+ kind: QdrantAccessKey
271
+ metadata:
272
+ name: billing-reader
273
+ namespace: default
274
+ spec:
275
+ clusterRef:
276
+ name: my-qdrant
277
+ collections: # or: access: r | m for cluster-wide tokens
278
+ - name: invoices
279
+ access: r # r, rw, or prw (points only, no snapshots or indexes)
280
+ subject: billing-service
281
+ ttl: 720h
282
+ renewBefore: 24h # default: a third of ttl
283
+ secretName: billing-qdrant # default: metadata.name
284
+ ```
285
+
286
+ The Secret gets `token` and `url` keys and is garbage-collected with the resource. The token is
287
+ re-issued when the spec changes, the cluster's API key rotates, the Secret disappears, or
288
+ `renewBefore` is reached.
289
+
290
+ ### Migrate Between Clusters
291
+
292
+ ```yaml
293
+ apiVersion: qdrant.io/v1alpha1
294
+ kind: QdrantMigration
295
+ metadata:
296
+ name: cloud-to-k8s
297
+ namespace: default
298
+ spec:
299
+ source:
300
+ endpoint: # or: clusterRef: {name: old-qdrant}
301
+ url: https://xyz.eu-central.aws.cloud.qdrant.io:6333
302
+ apiKeySecretRef: {name: qdrant-cloud, key: api-key}
303
+ targetClusterRef:
304
+ name: my-qdrant
305
+ collections: [articles] # empty = all
306
+ collectionMapping:
307
+ articles: articles_v2
308
+ batchSize: 500
309
+ batchDelayMs: 0 # throttle
310
+ ensurePayloadIndexes: true # also on targets that already exist
311
+ target: # for collections the migration creates
312
+ replicationFactor: 2
313
+ # shardKey: tier-a # route every point to one shard key
314
+ # shardKeyField: tenant # or route by a payload field
315
+ ```
316
+
317
+ Points are scrolled from the source and upserted on the target, so the run is idempotent and a
318
+ one-node source can become a three-node target (shard counts follow the target unless set under
319
+ `target`). Missing target collections are created from the source configuration, including
320
+ payload indexes; existing targets must have the same vector sizes and distances. On a
321
+ custom-sharded target, each point keeps its source shard key (keys are created as they are met)
322
+ unless routed with `target.shardKey` / `target.shardKeyField`; an auto-sharded target receives
323
+ the points without shard keys. Progress and the scroll offset live in `status`, so a
324
+ run interrupted by an operator restart resumes where it stopped.
325
+
192
326
  ## Configuration
193
327
 
194
328
  ### Environment Variables
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "qdrant-operator"
3
- version = "0.2.1"
3
+ version = "0.3.1"
4
4
  description = "Kubernetes operator for Qdrant vector database"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -33,6 +33,7 @@ dependencies = [
33
33
  "aioboto3>=13.0.0",
34
34
  "croniter>=5.0.0",
35
35
  "loguru>=0.7.3",
36
+ "pyjwt>=2.9",
36
37
  ]
37
38
 
38
39
  [[project.authors]]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "qdrant-operator"
3
- version = "0.2.1"
3
+ version = "0.3.1"
4
4
  description = "Kubernetes operator for Qdrant vector database"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -28,6 +28,7 @@ dependencies = [
28
28
  "aioboto3>=13.0.0",
29
29
  "croniter>=5.0.0",
30
30
  "loguru>=0.7.3",
31
+ "pyjwt>=2.9",
31
32
  ]
32
33
 
33
34
  [dependency-groups]
@@ -4,17 +4,22 @@ from dataclasses import dataclass
4
4
  from dataclasses import field
5
5
 
6
6
  from qdrant_operator.helm_adapter import HelmAdapter
7
+ from qdrant_operator.jwt_adapter import JwtAdapter
7
8
  from qdrant_operator.kubernetes_adapter import KubernetesAdapter
8
9
  from qdrant_operator.qdrant_adapter import QdrantAdapter
9
10
  from qdrant_operator.s3_adapter import S3Adapter
10
11
  from qdrant_operator.usecases import DeleteBackupData
11
12
  from qdrant_operator.usecases import DeleteCluster
13
+ from qdrant_operator.usecases import DeleteCollection
12
14
  from qdrant_operator.usecases import ExecuteBackup
15
+ from qdrant_operator.usecases import ExecuteMigration
13
16
  from qdrant_operator.usecases import ExecuteRestore
14
17
  from qdrant_operator.usecases import ExpireBackup
18
+ from qdrant_operator.usecases import IssueAccessKey
15
19
  from qdrant_operator.usecases import ObserveCluster
16
20
  from qdrant_operator.usecases import ProcessSchedule
17
21
  from qdrant_operator.usecases import ReconcileCluster
22
+ from qdrant_operator.usecases import ReconcileCollection
18
23
 
19
24
 
20
25
  @dataclass
@@ -23,6 +28,7 @@ class Container:
23
28
  kubernetes: KubernetesAdapter = field(default_factory=KubernetesAdapter)
24
29
  storage: S3Adapter = field(default_factory=S3Adapter)
25
30
  qdrant: QdrantAdapter = field(default_factory=QdrantAdapter)
31
+ token: JwtAdapter = field(default_factory=JwtAdapter)
26
32
 
27
33
  def reconcile_cluster(self) -> ReconcileCluster:
28
34
  return ReconcileCluster(helm=self.helm)
@@ -47,3 +53,15 @@ class Container:
47
53
 
48
54
  def process_schedule(self) -> ProcessSchedule:
49
55
  return ProcessSchedule(kubernetes=self.kubernetes)
56
+
57
+ def reconcile_collection(self) -> ReconcileCollection:
58
+ return ReconcileCollection(qdrant=self.qdrant, kubernetes=self.kubernetes)
59
+
60
+ def delete_collection(self) -> DeleteCollection:
61
+ return DeleteCollection(qdrant=self.qdrant, kubernetes=self.kubernetes)
62
+
63
+ def issue_access_key(self) -> IssueAccessKey:
64
+ return IssueAccessKey(kubernetes=self.kubernetes, token=self.token)
65
+
66
+ def execute_migration(self) -> ExecuteMigration:
67
+ return ExecuteMigration(qdrant=self.qdrant, kubernetes=self.kubernetes)