# 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](/vi/docs/self-host/requirements), 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](/vi/docs/self-host/airgapped#7-chép-ảnh-vào-registry-nội-bộ))
và tệp giấy phép `license.json`.

## 1. Namespace

```bash
kubectl create namespace dataxland
```

Mỗ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`:

```bash
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` |

```bash
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

```bash
kubectl -n dataxland create secret generic dataxland-license --from-file=license.json=./license.json
```

Chư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](/vi/docs/self-host/license).

## 4. Values cho production

Tệp `values-prod.yaml` tối thiểu (ví dụ trên AWS):

```yaml
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: letsencrypt
```

Nhữ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](/vi/docs/self-host/requirements#object-storage-theo-đám-mây).

## 5. Cài

```bash
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

```bash
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:

1. Mở `https://dataxland.corp.example`.
2. **Đă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.
3. 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.
4. 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:

```bash
kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status
```

## Dù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.

```yaml
# 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: false
```

```bash
helm install dataxland <đường dẫn chart> -n dataxland -f values-trial.yaml
kubectl -n dataxland port-forward svc/dataxland-web 3000:3000
```

Khô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`.

```yaml
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:

```yaml
networkPolicy:
  enabled: true
  ingressControllerNamespace: ingress-nginx
  ingressControllerLabels: {app.kubernetes.io/name: ingress-nginx}
  monitoringNamespace: monitoring
```

Chart 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):

```yaml
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:

```yaml
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](/vi/docs/self-host/license#theo-dõi-hạn)).

## Liên quan

- [Chế độ cách ly mạng](/vi/docs/self-host/airgapped)
- [Nâng cấp và sao lưu](/vi/docs/self-host/upgrade-backup)
- [Giấy phép](/vi/docs/self-host/license)
