Cài bằng Helm
Cài DataxLand lên Kubernetes bằng Helm chart, gồm Secret bí mật, Secret giấy phép, values tối thiểu cho production, kiểm tra sau khi cài, bản dùng thử với Postgres và MinIO trong cụm, External Secrets, NetworkPolicy và ServiceMonitor.
Trang này dùng tên bản cài dataxland, namespace dataxland và tên miền dataxland.corp.example. Thay bằng giá trị của bạn.
Trước khi bắt đầu, cần có: hạ tầng theo Yêu cầu và cỡ máy, Helm 3, kubectl trỏ vào cụm, và
từ DataxLand: chart, tên kho ảnh, quyền kéo ảnh (hoặc gói ảnh offline)
và tệp giấy phép license.json.
1. Namespace
kubectl create namespace dataxlandMỗi namespace chỉ chứa một bản cài: Service của api luôn tên là api (ảnh web gọi sẵn địa chỉ http://api:8000).
Nếu kho ảnh cần đăng nhập, tạo Secret kéo ảnh rồi khai báo ở imagePullSecrets:
kubectl -n dataxland create secret docker-registry dataxland-pull \
--docker-server=ghcr.io --docker-username=<tên> --docker-password=<token>2. Secret bí mật
Chart không chứa giá trị bí mật nào. Tạo một Secret, mỗi khóa trùng tên một biến môi trường:
| Khóa | Bắt buộc | Nội dung |
|---|---|---|
DX_POSTGRES_URL | có | Chuỗi kết nối database dx, ví dụ postgresql://dx:<mật khẩu>@pg.corp.example:5432/dx?sslmode=require |
DX_DUCKLAKE_CATALOG_PASSWORD | có | Mật khẩu của user Postgres (dùng cho database dx_lake) |
DX_SESSION_SECRET | có | Chuỗi ngẫu nhiên, ký phiên đăng nhập |
DX_SECRET_KEY | có | Chuỗi ngẫu nhiên, mã hóa bí mật đã lưu (mật khẩu nguồn, token) |
DX_DELEGATION_SIGNING_KEY | có | Chuỗi ngẫu nhiên, ký token ủy quyền ngắn hạn giữa các dịch vụ |
DX_BACKUP_ENCRYPTION_KEY | có | 32 byte, base64 url-safe, mã hóa bản sao lưu |
DX_DUCKLAKE_S3_KEY_ID, DX_DUCKLAKE_S3_SECRET | có | Khóa object storage |
DX_SMTP_PASSWORD | không | Mật khẩu SMTP |
DX_BACKUP_S3_KEY_ID, DX_BACKUP_S3_SECRET | không | Khóa riêng cho bucket sao lưu, nếu khác khóa kho |
DX_METRICS_TOKEN | không | Bắt buộc token khi đọc /metrics |
| Khóa API model | tùy model | Tên biến theo api_key_env của model. Danh mục mặc định hiện dùng DEEPSEEK_API_KEY |
kubectl -n dataxland create secret generic dataxland-env \
--from-literal=DX_POSTGRES_URL='postgresql://dx:<mật khẩu>@pg.corp.example:5432/dx?sslmode=require' \
--from-literal=DX_DUCKLAKE_CATALOG_PASSWORD='<mật khẩu>' \
--from-literal=DX_SESSION_SECRET="$(openssl rand -hex 32)" \
--from-literal=DX_SECRET_KEY="$(openssl rand -hex 32)" \
--from-literal=DX_DELEGATION_SIGNING_KEY="$(openssl rand -hex 32)" \
--from-literal=DX_BACKUP_ENCRYPTION_KEY="$(openssl rand -base64 32 | tr '+/' '-_')" \
--from-literal=DX_DUCKLAKE_S3_KEY_ID='<key id>' \
--from-literal=DX_DUCKLAKE_S3_SECRET='<secret>'Mật khẩu Postgres có ký tự đặc biệt thì phải mã hóa URL trong DX_POSTGRES_URL.
Lưu ngay DX_SECRET_KEY và DX_BACKUP_ENCRYPTION_KEY ra hai nơi (kho bí mật của công ty và một bản ngoại tuyến). Mất
DX_SECRET_KEY thì phải nối lại mọi nguồn dữ liệu; mất DX_BACKUP_ENCRYPTION_KEY thì mọi bản sao lưu không giải mã được.
3. Secret giấy phép
kubectl -n dataxland create secret generic dataxland-license --from-file=license.json=./license.jsonChưa có giấy phép thì bản cài vẫn chạy nhưng ở chế độ chỉ đọc. Xem Giấy phép.
4. Values cho production
Tệp values-prod.yaml tối thiểu (ví dụ trên AWS):
image:
repositoryPrefix: <tên do DataxLand cung cấp>
imagePullSecrets:
- name: dataxland-pull
deployment:
publicUrl: https://dataxland.corp.example
superAdmins: [admin@corp.example]
extraEnv:
DX_SMTP_HOST: smtp.corp.example
DX_SMTP_PORT: "587"
DX_SMTP_USER: dataxland
DX_SMTP_FROM: dataxland@corp.example
license:
existingSecret: dataxland-license
secrets:
existingSecret: dataxland-env
postgres:
external:
host: pg.corp.example
database: dx
catalogDatabase: dx_lake
user: dx
objectStorage:
endpoint: s3.ap-southeast-1.amazonaws.com
region: ap-southeast-1
urlStyle: vhost
lakeBucket: dx-lake
tenantKeys: "off"
backup:
bucket: dx-backups
persistence:
storageClass: efs-rwx
size: 100Gi
ingress:
className: nginx
host: dataxland.corp.example
annotations:
cert-manager.io/cluster-issuer: letsencryptNhững khóa hay cần đổi:
| Khóa | Ý nghĩa |
|---|---|
deployment.publicUrl | Địa chỉ người dùng mở, bắt buộc |
deployment.superAdmins | Email quản trị toàn bản cài |
deployment.signupMode | invite (mặc định), approval hoặc open |
deployment.timezone | Múi giờ cho ngày nghiệp vụ và giờ sao lưu, mặc định Asia/Ho_Chi_Minh |
deployment.extraEnv | Biến môi trường thêm cho api, worker, mcp (SMTP, kênh thông báo) |
image.registry, image.repositoryPrefix, image.tag | Kho ảnh; image.tag trống thì dùng phiên bản của chart |
image.digests | Ghim ảnh theo digest, ví dụ {api: sha256:..., web: sha256:...} |
objectStorage.lakePrefix | Tiền tố trong bucket kho, khi dùng chung bucket |
ingress.tls.secretName | Secret chứa chứng chỉ; trống thì dùng dataxland-tls (cert-manager tạo) |
ingress.mcp.enabled, ingress.mcp.host | Mở máy chủ MCP ra ngoài, ví dụ mcp.dataxland.corp.example |
ingress.api.enabled, ingress.api.host | Mở thẳng /v1 của api, chỉ khi cần callback OAuth hoặc webhook |
api.autoscaling.enabled, web.autoscaling.enabled | Bật HPA |
mcp.enabled | Tắt máy chủ MCP nếu không dùng |
Object storage trên GCP, Azure hay on-prem: xem bảng ở Yêu cầu và cỡ máy.
5. Cài
helm install dataxland <đường dẫn chart> -n dataxland -f values-prod.yaml
kubectl -n dataxland get pods -w<đường dẫn chart> là thư mục hoặc tệp .tgz của chart DataxLand cung cấp cùng bản phát hành. Lần cài đầu, các thành phần tự
tạo schema Postgres; từ lần nâng cấp sau, Job migrate làm việc này trước khi cuộn bản mới.
Helm in ghi chú sau khi cài, kèm cảnh báo nếu thiếu giấy phép, đang dùng Postgres hoặc MinIO trong cụm, hoặc Secret do chart tự tạo.
6. Kiểm tra và đăng nhập
kubectl -n dataxland port-forward svc/api 8000:8000
curl -s http://localhost:8000/readyz/readyz kiểm Postgres, catalog và object storage. Khi trả thành công:
- Mở
https://dataxland.corp.example. - Đăng ký bằng email trong
deployment.superAdmins. Email này không cần mã mời và bắt buộc bật xác thực hai lớp. - Vào Quản trị → Vận hành, mục Triển khai và giấy phép: xem trạng thái giấy phép, mức dùng và chế độ cách ly.
- Tạo workspace đầu tiên rồi mời người dùng.
Xem trạng thái giấy phép từ dòng lệnh:
kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-statusDùng thử với Postgres và MinIO trong cụm
Để thử trên một cụm nhỏ, chart có thể chạy Postgres và MinIO ngay trong cụm. Hai thành phần này chỉ để dùng thử: một bản, không sao lưu, không HA.
# values-trial.yaml
deployment:
publicUrl: http://localhost:3000
superAdmins: [admin@corp.example]
license:
existingSecret: dataxland-license
postgres:
bundled:
enabled: true
minio:
bundled: true
objectStorage:
tenantKeys: minio
persistence:
accessMode: ReadWriteOnce
size: 10Gi
api:
replicas: 1
web:
replicas: 1
ingress:
enabled: falsehelm install dataxland <đường dẫn chart> -n dataxland -f values-trial.yaml
kubectl -n dataxland port-forward svc/dataxland-web 3000:3000Không đặt secrets.existingSecret thì chart tự tạo Secret dataxland-env với khóa ngẫu nhiên, giữ qua các lần nâng cấp. Bản
dùng thử vẫn cần tệp giấy phép; không có thì bản cài chỉ đọc.
Bí mật từ External Secrets Operator
Nếu bí mật nằm trong kho bí mật (AWS Secrets Manager, Google Secret Manager, Azure Key Vault, Vault) và cụm đã có External
Secrets Operator, chart tạo ExternalSecret thay cho Secret tạo tay. Đích vẫn là Secret dataxland-env.
secrets:
existingSecret: ""
externalSecret:
enabled: true
secretStoreRef: {name: cloud-secrets, kind: ClusterSecretStore}
refreshInterval: 1h
data:
DX_SECRET_KEY: dataxland/prod/secret-key
DX_POSTGRES_URL: {key: dataxland-app, property: DX_POSTGRES_URL}Mỗi khóa trong data là tên biến; giá trị là remoteKey trong kho, hoặc một remoteRef đầy đủ (key, property) khi nhiều
biến nằm trong một bí mật JSON. Liệt kê đủ các khóa bắt buộc ở mục 2.
NetworkPolicy
Cần CNI hỗ trợ NetworkPolicy. Bật:
networkPolicy:
enabled: true
ingressControllerNamespace: ingress-nginx
ingressControllerLabels: {app.kubernetes.io/name: ingress-nginx}
monitoringNamespace: monitoringChart chặn mọi kết nối vào, rồi chỉ cho: ingress controller vào web và mcp (và api nếu bật ingress.api), các pod của
bản cài gọi nhau, Prometheus trong monitoringNamespace đọc cổng chỉ số 9464 đến 9466.
Giới hạn kết nối ra (bắt buộc khi cách ly mạng):
networkPolicy:
enabled: true
egress:
restrict: true
dnsNamespace: kube-system
allowCIDRs: [10.0.0.0/16]
allowPorts: [5432, 443, 587]Khi restrict: true, pod chỉ được gọi DNS, các pod cùng bản cài và các dải trong allowCIDRs (Postgres, object storage, model
AI, SMTP, database nguồn). allowPorts trống nghĩa là mọi cổng tới các dải đó.
ServiceMonitor
Với Prometheus Operator:
serviceMonitor:
enabled: true
interval: 30s
labels: {release: prometheus}Chart thu /metrics của api (cổng 9464), worker (9465), mcp (9466). Nếu đặt DX_METRICS_TOKEN, ServiceMonitor của chart
không tự gửi token; thêm cấu hình xác thực cho Prometheus của bạn. Bộ luật cảnh báo Prometheus đi kèm bản phát hành; hãy nạp
thêm cảnh báo giấy phép sắp hết hạn (xem Giấy phép).
Liên quan
Yêu cầu và cỡ máy
Hạ tầng cần có trước khi tự host DataxLand (Kubernetes, Postgres 16, object storage tương thích S3, ổ dùng chung, ingress và TLS), tài nguyên mặc định của từng thành phần và cách chọn object storage theo đám mây.
Terraform tham khảo (AWS, GCP, Azure)
Module Terraform mẫu dựng mạng, cụm Kubernetes có quản lý, Postgres, object storage, ổ dùng chung và kho bí mật rồi cài Helm chart DataxLand trên AWS, GCP hoặc Azure; là mẫu tham khảo, chưa chạy trên tài khoản thật.