Helm (v1.x)

يمكن العثور على مخطط Helm الخاص بـ ClickStack هنا، وهو الطريقة الموصى بها لعمليات النشر في بيئة الإنتاج.

يوفّر مخطط Helm افتراضيًا جميع المكوّنات الأساسية، بما في ذلك:

• ClickHouse
• HyperDX
• جامع OpenTelemetry (OTel)
• MongoDB (لحالة التطبيق الدائمة)

ومع ذلك، يمكن تخصيصه بسهولة ليتكامل مع عملية نشر ClickHouse قائمة — على سبيل المثال، مستضافة على ClickHouse Cloud.

يدعم المخطط أفضل ممارسات Kubernetes القياسية، بما في ذلك:

• إعدادات خاصة بكل بيئة عبر values.yaml
• حدود الموارد والتوسعة على مستوى الـ pod
• إعداد TLS وIngress
• إدارة الأسرار وإعداد المصادقة

• تجارب إثبات المفهوم
• بيئات الإنتاج

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

• Helm v3+
• عنقود Kubernetes (يُوصى بالإصدار v1.20+)
• kubectl مُعَدّ للتعامل مع عنقودك

أضف مستودع Helm لـ ClickStack

أضف مستودع Helm لـ ClickStack:

helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
helm repo update

تثبيت ClickStack

لتثبيت chart الخاص بـ ClickStack باستخدام القيم الافتراضية:

helm install my-clickstack clickstack/clickstack

تحقّق من التثبيت

تحقّق من التثبيت:

kubectl get pods -l "app.kubernetes.io/name=clickstack"

عندما تصبح جميع وحدات الـPod جاهزة، تابع.

إعادة توجيه المنافذ

تتيح إعادة توجيه المنافذ الوصول إلى HyperDX وإعداده. أمّا المستخدمون الذين ينشرون في بيئات الإنتاج، فينبغي لهم بدلًا من ذلك إتاحة الخدمة عبر مورد Ingress أو موازن تحميل لضمان وصول شبكي مناسب، وإنهاء TLS، وقابلية التوسع. وتُعد إعادة توجيه المنافذ أنسب للتطوير المحلي أو للمهام الإدارية لمرة واحدة، وليست مناسبة للبيئات طويلة الأمد أو عالية التوافر.

kubectl port-forward \
  pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
  8080:3000

الانتقال إلى واجهة المستخدم

زُر http://localhost:8080 للوصول إلى واجهة HyperDX.

أنشئ مستخدمًا بإدخال اسم مستخدم وكلمة مرور يستوفيان المتطلبات.

عند النقر على Create، ستُنشأ مصادر البيانات لمثيل ClickHouse الذي نُشر باستخدام مخطط Helm.

تخصيص القيم (اختياري)

يمكنك تخصيص الإعدادات باستخدام خيارات --set. على سبيل المثال:

helm install my-clickstack clickstack/clickstack --set key=value

بدلًا من ذلك، حرِّر ملف values.yaml. لاسترجاع القيم الافتراضية:

helm show values clickstack/clickstack > values.yaml

مثال للإعداد:

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

helm install my-clickstack clickstack/clickstack -f values.yaml

استخدام Kubernetes Secrets (اختياري)

للتعامل مع البيانات الحساسة مثل مفاتيح API أو بيانات اعتماد قاعدة البيانات، استخدم Kubernetes Secrets. توفّر مخططات Helm الخاصة بـ HyperDX ملفات secrets افتراضية يمكنك تعديلها وتطبيقها على الـ cluster لديك.

استخدام secrets مُعدّة مسبقًا

يتضمّن مخطط Helm قالب secret افتراضيًا موجودًا في charts/clickstack/templates/secrets.yaml. يوفّر هذا الملف بنية أساسية لإدارة secrets.

إذا كنت بحاجة إلى تطبيق secret يدويًا، فعدّل قالب secrets.yaml المرفق ثم طبّقه:

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

طبّق مورد Secret على عنقودك:

kubectl apply -f secrets.yaml

إنشاء سر Kubernetes مخصص

إذا كنت تفضّل ذلك، يمكنك إنشاء سر Kubernetes مخصص يدويًا:

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

الإشارة إلى مورد secret

للإشارة إلى مورد secret في values.yaml:

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

عند استخدام ClickHouse Cloud، يجب على المستخدمين تعطيل مثيل ClickHouse الذي ينشره مخطط Helm وتحديد بيانات اعتماد Cloud:

# specify ClickHouse Cloud credentials
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # full https url
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# how to overwrite default connection
helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} \
  --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} \
  --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD}

بدلاً من ذلك، يمكنك استخدام ملف values.yaml:

clickhouse:
  enabled: false
  persistence:
    enabled: false
  config:
    users:
      otelUser: ${CLICKHOUSE_USER}
      otelUserPassword: ${CLICKHOUSE_PASSWORD}

otel:
  clickhouseEndpoint: ${CLICKHOUSE_URL}

hyperdx:
  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]

helm install my-clickstack clickstack/clickstack -f values.yaml
# or if installed...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

يثبّت هذا مخطط، افتراضيًا، أيضًا ClickHouse وجامع OTel. ومع ذلك، في بيئة production، يُنصح بإدارة ClickHouse وجامع OTel بشكل منفصل.

لتعطيل ClickHouse وجامع OTel، اضبط values التالية:

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

افتراضيًا، توجد مهمة واحدة في إعدادات الـمخطط على شكل cronjob، وهي مسؤولة عن التحقق مما إذا كان ينبغي إطلاق التنبيهات. وفيما يلي خيارات تهيئتها:

للترقية إلى إصدار أحدث:

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

للتحقق من إصدارات مخطط Helm المتاحة:

helm search repo clickstack

لإزالة النشر:

helm uninstall my-clickstack

سيؤدي هذا إلى إزالة جميع الموارد المرتبطة بالإصدار، لكن قد تظل البيانات الدائمة (إن وُجدت).

kubectl logs -l app.kubernetes.io/name=clickstack

helm install my-clickstack clickstack/clickstack --debug --dry-run

kubectl get pods -l app.kubernetes.io/name=clickstack

يخزّن ClickStack السمات في أعمدة Map(LowCardinality(String), String) افتراضيًا. هذا هو المخطط الموصى به لأعباء عمل Observability. وعند دمجه مع تسلسل map المقسّم إلى buckets وفهارس النص على مفاتيح map وقيمه، فإنه يوفّر عمليات بحث انتقائية من دون الكلفة الإضافية لإدخال كل مفتاح على حدة كما في JSON subcolumns الديناميكية.

يتوفر مخطط من النوع JSON في مرحلة بيتا للتقييم على أعباء العمل التي تتضمن مجموعة صغيرة ومستقرة من مفاتيح السمات. وهو غير موصى به كخيار افتراضي. راجع Map مقابل نوع JSON للاطلاع على المقارنة الكاملة ومتغيرات البيئة المطلوبة لتمكين دعم JSON.

• خيارات النشر (v1.x) - ClickHouse خارجي، وجامع OTel، وعمليات النشر المصغّرة
• دليل التهيئة (v1.x) - مفاتيح API، والأسرار، وإعداد Ingress
• عمليات النشر في Cloud (v1.x) - تهيئات GKE وEKS وAKS وأفضل الممارسات في بيئات الإنتاج

• Helm (v2.x) - دليل نشر الإصدار v2.x
• دليل الترقية - الترحيل من v1.x إلى v2.x

• دليل البدء في ClickStack - مقدمة إلى ClickStack
• مستودع مخططات Helm الخاص بـ ClickStack - الشفرة المصدرية للمخطط ومرجع القيم
• وثائق Kubernetes - مرجع Kubernetes
• وثائق Helm - مرجع Helm