الانتقال إلى المحتوى الرئيسي
يغطي هذا الدليل الترحيل من مخطط Helm لـ ClickStack ذي القوالب المضمّنة (v1.x) إلى المعمارية المعتمدة على المخططات الفرعية (v2.x). هذا تغيير جذري يستبدل موارد Kubernetes المُعدّة يدويًا بموارد مخصصة يديرها المشغّل لكل من MongoDB وClickHouse، ويستخدم مخطط Helm الرسمي لـ OpenTelemetry Collector.
تغيير جذريالمخطط v2.x غير متوافق مع v1.x بأثر رجعي. الترقية الموضعية باستخدام helm upgrade غير مدعومة. نوصي بإجراء تثبيت جديد إلى جانب عملية النشر الحالية وترحيل البيانات، بدلًا من محاولة تنفيذ ترقية موضعية.

​
المتطلبات الأساسية

  • خذ نسخة احتياطية من بياناتك قبل الترقية (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 مضمّن + خدمة + PVCMongoDB Kubernetes Operator (MCK) يدير مورد MongoDBCommunity مخصّصًا (CR)
ClickHouseمورد Deployment مضمّن + خدمة + ConfigMaps + PVCsClickHouse 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.passwordhyperdx.secrets.MONGODB_PASSWORD
clickhouse.config.users.appUserPasswordhyperdx.secrets.CLICKHOUSE_APP_PASSWORD
clickhouse.config.users.otelUserPasswordhyperdx.secrets.CLICKHOUSE_PASSWORD
تجاوزات متغيرات البيئة otel.*hyperdx.config.* (غير حساسة) وhyperdx.secrets.* (حساسة)

​
ConfigMap وSecret الموحَّدان

تمر جميع متغيرات البيئة الآن عبر موردين ثابتَي الاسم تتم مشاركتهما بين Deployment HyperDX و OTel collector عبر envFrom:
  • clickstack-config ConfigMap — يُعبَّأ من hyperdx.config
  • clickstack-secret Secret — يُعبَّأ من 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)

​
تثبيت جديد مقابل الترقية الموضعية

بالنسبة إلى التثبيت الجديد، لا حاجة إلى أي خطوات خاصة. تعمل القيم الافتراضية مباشرةً. بالنسبة إلى الترقية الموضعية لإصدار موجود، انتبه إلى ما يلي:
  1. سيُثبَّت المشغّلان (MCK وClickHouse Operator) كعمليتَي نشر جديدتين في مساحة الاسم الخاصة بك
  2. سيحذف Helm موردَي Deployment الحاليَّين لـ MongoDB وClickHouse (لأنهما لم يعودا موجودين ضمن قوالب مخطط)
  3. سينشئ المشغّلان موارد StatefulSet جديدة لإدارة MongoDB وClickHouse
  4. لن يُعاد استخدام PVCs من المخطط القديم تلقائيًا بواسطة موارد StatefulSet التي يديرها المشغّلان
نوصي بإجراء تثبيت جديد إلى جانب عملية النشر الحالية وترحيل البيانات، بدلًا من إجراء ترقية موضعية.

​
الخطوات التالية

آخر تعديل في ٢٥ يونيو ٢٠٢٦