يغطي هذا الدليل الترحيل من مخطط Helm لـ ClickStack ذي القوالب المضمّنة (v1.x) إلى المعمارية المعتمدة على المخططات الفرعية (v2.x). هذا تغيير جذري يستبدل موارد Kubernetes المُعدّة يدويًا بموارد مخصصة يديرها المشغّل لكل من MongoDB وClickHouse، ويستخدم مخطط Helm الرسمي لـ OpenTelemetry Collector.
المتطلبات الأساسية
- خذ نسخة احتياطية من بياناتك قبل الترقية (MongoDB, ClickHouse PVCs)
- راجع تجاوزات
values.yamlالحالية — فقد نُقلت معظم المفاتيح أو أُعيدت تسميتها
التثبيت على مرحلتين
يعتمد الـ مخطط بالإصدار v2.x عملية تثبيت على مرحلتين. يجب تثبيت Operators (التي تسجّل CRDs) قبل الـ مخطط الرئيسي (الذي ينشئ CRs):
# Phase 1: Install operators and CRDs
helm install clickstack-operators clickstack/clickstack-operators
# Phase 2: Install ClickStack
helm install my-clickstack clickstack/clickstackألغِ التثبيت بترتيب عكسي:
helm uninstall my-clickstack
helm uninstall clickstack-operatorsاستدامة البيانات
لا يزيل الأمر helm uninstall عناصر PersistentVolumeClaims التي يُنشئها مشغّلا MongoDB وClickHouse. وهذا مقصود لتجنّب فقدان البيانات عن طريق الخطأ. لتنظيف PVCs بعد إلغاء التثبيت، راجع:
فئة التخزين
أُزيل كلٌّ من global.storageClassName وglobal.keepPVC. تُضبط فئة التخزين الآن مباشرةً ضمن CR spec الخاص بكل مشغّل:
mongodb:
spec:
statefulSet:
spec:
volumeClaimTemplates:
- spec:
storageClassName: "fast-ssd"
clickhouse:
keeper:
spec:
dataVolumeClaimSpec:
storageClassName: "fast-ssd"
cluster:
spec:
dataVolumeClaimSpec:
storageClassName: "fast-ssd"ما الذي تغيّر
| المكوّن | قبل (v1.x) | بعد (v2.x) |
|---|---|---|
| MongoDB | مورد Deployment مضمّن + خدمة + PVC | MongoDB Kubernetes Operator (MCK) يدير مورد MongoDBCommunity مخصّصًا (CR) |
| ClickHouse | مورد Deployment مضمّن + خدمة + ConfigMaps + PVCs | ClickHouse Operator يدير الموردين المخصّصين ClickHouseCluster وKeeperCluster (CRs) |
| OTEL Collector | مورد Deployment مضمّن + خدمة (كتلة otel.*) |
مخطط Helm الرسمي لـ OpenTelemetry Collector (المخطط الفرعي otel-collector:) |
| قيم HyperDX | مفاتيح مسطّحة ضمن hyperdx.* إضافةً إلى tasks: وappUrl في المستوى الأعلى |
أُعيد تنظيمها حسب نوع مورد K8s ضمن hyperdx.* (انظر أدناه) |
| hdx-oss-v2 | مخطط قديم متوقّف الاستخدام | أُزيل بالكامل |
إعادة تنظيم قيم HyperDX
أصبحت الكتلة hyperdx: منظَّمة الآن وفقًا لنوع مورد Kubernetes:
hyperdx:
ports: # Shared port numbers (Deployment, Service, ConfigMap, Ingress)
api: 8000
app: 3000
opamp: 4320
frontendUrl: "http://localhost:3000" # Replaces the removed appUrl
config: # → clickstack-config ConfigMap (non-sensitive env vars)
APP_PORT: "3000"
HYPERDX_LOG_LEVEL: "info"
secrets: # → clickstack-secret Secret (sensitive env vars)
HYPERDX_API_KEY: "..."
CLICKHOUSE_PASSWORD: "otelcollectorpass"
CLICKHOUSE_APP_PASSWORD: "hyperdx"
MONGODB_PASSWORD: "hyperdx"
deployment: # K8s Deployment spec (image, replicas, probes, etc.)
service: # K8s Service spec (type, annotations)
ingress: # K8s Ingress spec (host, tls, annotations)
podDisruptionBudget: # K8s PDB spec
tasks: # K8s CronJob specs (previously top-level tasks:)أهم التغييرات
| قبل (v1.x) | بعد (v2.x) |
|---|---|
appUrl |
أُزيل. استخدم hyperdx.frontendUrl (القيمة الافتراضية: http://localhost:3000) |
tasks.* (على المستوى الأعلى) |
hyperdx.tasks.* |
mongodb.password |
hyperdx.secrets.MONGODB_PASSWORD |
clickhouse.config.users.appUserPassword |
hyperdx.secrets.CLICKHOUSE_APP_PASSWORD |
clickhouse.config.users.otelUserPassword |
hyperdx.secrets.CLICKHOUSE_PASSWORD |
تجاوزات متغيرات البيئة otel.* |
hyperdx.config.* (غير حساسة) وhyperdx.secrets.* (حساسة) |
ConfigMap وSecret الموحَّدان
تمر جميع متغيرات البيئة الآن عبر موردين ثابتَي الاسم تتم مشاركتهما بين Deployment HyperDX و OTel collector عبر envFrom:
clickstack-configConfigMap — يُعبَّأ منhyperdx.configclickstack-secretSecret — يُعبَّأ منhyperdx.secrets
لم يعد هناك ConfigMap منفصل مخصّص لـ OTel. ويقرأ كلا عبئي العمل من المصدرين نفسيهما.
ترحيل MongoDB
القيم التي أُزيلت
لم تعد قيم mongodb.* التالية متوفّرة:
# REMOVED — do not use
mongodb:
image: "..."
port: 27017
strategy: ...
nodeSelector: {}
tolerations: []
livenessProbe: ...
readinessProbe: ...
persistence:
enabled: true
dataSize: 10Giالقيم الجديدة
تتم الآن إدارة MongoDB بواسطة المشغّل MCK عبر مورد مخصص MongoDBCommunity. ويُولَّد قسم المواصفات في المورد المخصص كما هو من mongodb.spec:
mongodb:
enabled: true
spec:
members: 1
type: ReplicaSet
version: "5.0.32"
security:
authentication:
modes: ["SCRAM"]
users:
- name: hyperdx
db: hyperdx
passwordSecretRef:
name: '{{ include "clickstack.mongodb.fullname" . }}-password'
roles:
- name: dbOwner
db: hyperdx
- name: clusterMonitor
db: admin
scramCredentialsSecretName: '{{ include "clickstack.mongodb.fullname" . }}-scram'
additionalMongodConfig:
storage.wiredTiger.engineConfig.journalCompressor: zlibتُضبط كلمة مرور MongoDB في hyperdx.secrets.MONGODB_PASSWORD (وليس mongodb.password). ويُشار إليها تلقائيًا في Secret كلمة المرور وقالب mongoUri.
لإضافة تخزين دائم، أضِف كتلة statefulSet داخل mongodb.spec:
mongodb:
spec:
statefulSet:
spec:
volumeClaimTemplates:
- metadata:
name: data-volume
spec:
accessModes: ["ReadWriteOnce"]
storageClassName: "your-storage-class"
resources:
requests:
storage: 10Giيُضبط المخطط الفرعي لمشغّل MCK تحت mongodb-operator: (وليس mongodb-kubernetes:). راجع وثائق MCK للاطلاع على جميع حقول CRD المتاحة.
الترحيل إلى ClickHouse
القيم المُزالة
لم تعد قيم clickhouse.* التالية موجودة:
# REMOVED — do not use
clickhouse:
image: "..."
terminationGracePeriodSeconds: 90
resources: {}
livenessProbe: ...
readinessProbe: ...
startupProbe: ...
nodeSelector: {}
tolerations: []
service:
type: ClusterIP
annotations: {}
persistence:
enabled: true
dataSize: 10Gi
logSize: 5Gi
config:
clusterCidrs: [...]
users:
appUserPassword: "..."
otelUserPassword: "..."
otelUserName: "..."القيم الجديدة
تُدار ClickHouse الآن بواسطة ClickHouse Operator عبر الموارد المخصصة ClickHouseCluster وKeeperCluster. ويُعرَض قسم spec في كلٍّ منهما حرفيًا انطلاقًا من values:
clickhouse:
enabled: true
port: 8123
nativePort: 9000
prometheus:
enabled: true
port: 9363
keeper:
spec:
replicas: 1
dataVolumeClaimSpec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 5Gi
cluster:
spec:
replicas: 1
shards: 1
keeperClusterRef:
name: '{{ include "clickstack.clickhouse.keeper" . }}'
dataVolumeClaimSpec:
accessModes: ["ReadWriteOnce"]
resources:
requests:
storage: 10Gi
settings:
extraUsersConfig:
users:
app:
password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_APP_PASSWORD }}'
otelcollector:
password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_PASSWORD }}'
extraConfig:
max_connections: 4096
keep_alive_timeout: 64
max_concurrent_queries: 100أصبحت بيانات اعتماد مستخدم ClickHouse الآن تُستمد من hyperdx.secrets (وليس من clickhouse.config.users). ويشير تعريف العنقود إليها باستخدام تعبيرات القوالب.
تتم تهيئة المخطط الفرعي ClickHouse Operator ضمن clickhouse-operator:. تكون webhooks وcert-manager معطّلتين افتراضيًا. راجع دليل تهيئة المشغّل للاطلاع على جميع حقول CRD المتاحة.
ترحيل OTel collector
القيم المُزالة
لم تعد كتلة otel: بأكملها موجودة:
# REMOVED — do not use
otel:
enabled: true
image: ...
replicas: 1
resources: {}
clickhouseEndpoint: ...
clickhouseUser: ...
clickhousePassword: ...
clickhouseDatabase: "default"
opampServerUrl: ...
port: 13133
nativePort: 24225
grpcPort: 4317
httpPort: 4318
healthPort: 8888
env: []
customConfig: ...القيم الجديدة
يُنشر الآن OTel collector عبر مخطط Helm الرسمي لـ OpenTelemetry Collector باعتباره المخطط الفرعي otel-collector:. ولا توجد طبقة otel: التفافية للمخطط الأب — اضبط المخطط الفرعي مباشرةً.
تُشارَك متغيرات البيئة (نقطة نهاية ClickHouse، وعنوان URL لـ OpAMP، وما إلى ذلك) عبر clickstack-config ConfigMap الموحّد وclickstack-secret Secret. ويكون extraEnvsFrom الخاص بالمخطط الفرعي مُوصّلًا مسبقًا:
otel-collector:
enabled: true
mode: deployment
image:
repository: docker.clickhouse.com/clickhouse/clickstack-otel-collector
tag: ""
extraEnvsFrom:
- configMapRef:
name: clickstack-config
- secretRef:
name: clickstack-secret
ports:
otlp:
enabled: true
containerPort: 4317
servicePort: 4317
otlp-http:
enabled: true
containerPort: 4318
servicePort: 4318لضبط الموارد (سابقًا otel.resources):
otel-collector:
resources:
requests:
memory: "128Mi"
cpu: "100m"
limits:
memory: "256Mi"
cpu: "200m"لتعيين عدد النسخ المتماثلة (سابقًا otel.replicas):
otel-collector:
replicaCount: 3لضبط nodeSelector/tolerations (سابقًا otel.nodeSelector/otel.tolerations):
otel-collector:
nodeSelector:
node-role: monitoring
tolerations:
- key: monitoring
operator: Equal
value: otel
effect: NoScheduleراجع مخطط Helm الخاص بـ OpenTelemetry Collector للاطلاع على جميع قيم المخطط الفرعي المتاحة.
القيم التي لم تتغير
لا تتأثر الأقسام التالية بعملية الترحيل هذه:
global.*(imageRegistry, imagePullSecrets)
تثبيت جديد مقابل الترقية الموضعية
بالنسبة إلى التثبيت الجديد، لا حاجة إلى أي خطوات خاصة. تعمل القيم الافتراضية مباشرةً.
بالنسبة إلى الترقية الموضعية لإصدار موجود، انتبه إلى ما يلي:
- سيُثبَّت المشغّلان (MCK وClickHouse Operator) كعمليتَي نشر جديدتين في مساحة الاسم الخاصة بك
- سيحذف Helm موردَي Deployment الحاليَّين لـ MongoDB وClickHouse (لأنهما لم يعودا موجودين ضمن قوالب مخطط)
- سينشئ المشغّلان موارد StatefulSet جديدة لإدارة MongoDB وClickHouse
- لن يُعاد استخدام PVCs من المخطط القديم تلقائيًا بواسطة موارد StatefulSet التي يديرها المشغّلان
نوصي بإجراء تثبيت جديد إلى جانب عملية النشر الحالية وترحيل البيانات، بدلًا من إجراء ترقية موضعية.
الخطوات التالية
- دليل Helm الرئيسي - التثبيت الأساسي مع v2.x
- دليل الإعداد - مفاتيح واجهة برمجة التطبيقات، والأسرار، وموارد Ingress
- ملفات البيان الإضافية - كائنات Kubernetes مخصّصة
- مستودع مخططات Helm الخاصة بـ ClickStack - الشيفرة المصدرية للمخطط ومرجع values