ملفات البيان الإضافية في Helm

نشر كائنات Kubernetes مخصصة إلى جانب مخطط Helm الخاص بـ ClickStack باستخدام additionalManifests

إصدار المخطط 2.x فقط

تتوفر ميزة additionalManifests فقط في مخطط Helm المبني على subchart بإصدار v2.x.

تتيح لك القيمة additionalManifests نشر أي كائنات Kubernetes إلى جانب مخطط ClickStack. استخدمها مع الموارد التي لا يوفّر لها المخطط قوالب بشكل مضمّن، مثل NetworkPolicy وHorizontalPodAutoscaler وServiceAccount وPodMonitor وكائنات Ingress المخصصة أو أي كائن آخر من كائنات واجهة برمجة تطبيقات Kubernetes.

​

كيف يعمل

كل عنصر في additionalManifests هو تعريف كامل لمورد في Kubernetes. ويقوم المخطط بما يلي:

1. المرور على كل عنصر في القائمة
2. تحويل العنصر إلى YAML (toYaml)
3. تقييم تعبيرات القوالب في ملف YAML الناتج باستخدام Helm tpl

يمكن أن تشير تعبيرات القوالب إلى:

• .Release.Name, .Release.Namespace
• include "clickstack.fullname" . ودوال المساعدة الأخرى الخاصة بالمخطط
• .Values.*

additionalManifests:
  - apiVersion: v1
    kind: ConfigMap
    metadata:
      name: '{{ include "clickstack.fullname" . }}-custom'
    data:
      release: '{{ .Release.Name }}'

​

قيود ملف values

يُضبط additionalManifests في ملف values، وتُحلَّل ملفات values بصيغة YAML قبل تشغيل tpl.

• يجب أن يكون أي {{ ... }} في ملف values داخل سلسلة نصية محاطة بعلامتَي اقتباس
• لا تُعد كتل القوالب البنيوية صالحة في YAML الخاص بملفات values (على سبيل المثال، {{- include ... | nindent ... }} بمفردها)
• بالنسبة إلى الحقول غير النصية (على سبيل المثال، أرقام المنافذ)، استخدم قيَمًا حرفية أو منافذ مُسمّاة
• إذا كنت بحاجة إلى قوالب بنيوية، فاستخدم قالب wrapper chart بدلًا من ملف values خام

# Valid in values.yaml
name: '{{ include "clickstack.fullname" . }}-app'

# Invalid in values.yaml (unquoted template expression)
name: {{ include "clickstack.fullname" . }}-app

# Invalid in values.yaml (structural template block)
labels:
  {{- include "clickstack.labels" . | nindent 2 }}

​

دوال المساعدة المتاحة لـ المخطط

تُعرَّف دوال المساعدة هذه في templates/_helpers.tpl:

المساعدة	الوصف	الاستخدام في ملف values
clickstack.name	اسم المخطط (مقتطع إلى 63 حرفًا)	آمن في القيم scalar الموضوعة بين علامتي اقتباس
clickstack.fullname	اسم مؤهل بـ Release	آمن في القيم scalar الموضوعة بين علامتي اقتباس
clickstack.chart	اسم المخطط + الإصدار	آمن في القيم scalar الموضوعة بين علامتي اقتباس
clickstack.selectorLabels	كتلة labels الخاصة بـ selector	لقوالب wrapper مخطط فقط
clickstack.labels	كتلة labels القياسية	لقوالب wrapper مخطط فقط
clickstack.mongodb.fullname	اسم MongoDB CR	آمن في القيم scalar الموضوعة بين علامتي اقتباس
clickstack.clickhouse.fullname	اسم ClickHouse CR	آمن في القيم scalar الموضوعة بين علامتي اقتباس
clickstack.otel.fullname	اسم OTel collector	آمن في القيم scalar الموضوعة بين علامتي اقتباس

​

أمثلة

​

ServiceAccount

additionalManifests:
  - apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: '{{ include "clickstack.fullname" . }}'
      namespace: '{{ .Release.Namespace }}'
      labels:
        app.kubernetes.io/name: '{{ include "clickstack.name" . }}'
        app.kubernetes.io/instance: '{{ .Release.Name }}'
      annotations:
        eks.amazonaws.com/role-arn: "arn:aws:iam::123456789:role/my-role"

​

NetworkPolicy

قيّد حركة المرور الواردة إلى جرابات HyperDX:

additionalManifests:
  - apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: '{{ include "clickstack.fullname" . }}-allow-ingress'
    spec:
      podSelector:
        matchLabels:
          app.kubernetes.io/name: '{{ include "clickstack.name" . }}'
          app.kubernetes.io/instance: '{{ .Release.Name }}'
      policyTypes:
        - Ingress
      ingress:
        - from:
            - namespaceSelector:
                matchLabels:
                  kubernetes.io/metadata.name: ingress-nginx
          ports:
            - protocol: TCP
              port: 3000
            - protocol: TCP
              port: 8000

​

HorizontalPodAutoscaler

additionalManifests:
  - apiVersion: autoscaling/v2
    kind: HorizontalPodAutoscaler
    metadata:
      name: '{{ include "clickstack.fullname" . }}-hpa'
    spec:
      scaleTargetRef:
        apiVersion: apps/v1
        kind: Deployment
        name: '{{ include "clickstack.fullname" . }}-app'
      minReplicas: 2
      maxReplicas: 10
      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 75

​

PodMonitor (Prometheus Operator)

additionalManifests:
  - apiVersion: monitoring.coreos.com/v1
    kind: PodMonitor
    metadata:
      name: '{{ include "clickstack.fullname" . }}'
      labels:
        release: prometheus
    spec:
      selector:
        matchLabels:
          app.kubernetes.io/name: '{{ include "clickstack.name" . }}'
          app.kubernetes.io/instance: '{{ .Release.Name }}'
      podMetricsEndpoints:
        - port: app
          interval: 30s

​

AWS ALB Ingress

عند استخدام AWS Load Balancer Controller، عطِّل Ingress المدمج لـ nginx في المخطط وعرِّف Ingress مخصصًا لـ ALB:

hyperdx:
  ingress:
    enabled: false

additionalManifests:
  - apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: '{{ include "clickstack.fullname" . }}-alb'
      annotations:
        alb.ingress.kubernetes.io/scheme: internet-facing
        alb.ingress.kubernetes.io/target-type: ip
        alb.ingress.kubernetes.io/certificate-arn: "arn:aws:acm:us-east-1:123456789:certificate/abc-123"
        alb.ingress.kubernetes.io/listen-ports: '[{\"HTTPS\":443}]'
        alb.ingress.kubernetes.io/ssl-redirect: "443"
        alb.ingress.kubernetes.io/group.name: clickstack
        alb.ingress.kubernetes.io/healthcheck-path: /api/health
    spec:
      ingressClassName: alb
      rules:
        - host: clickstack.example.com
          http:
            paths:
              - path: /
                pathType: Prefix
                backend:
                  service:
                    name: '{{ include "clickstack.fullname" . }}-app'
                    port:
                      name: app

للاطلاع على مثال كامل لإعداد ALB، بما في ذلك Ingress الداخلي لـ OTel collector وHPA، راجع قيم المثال الخاصة بـ ALB.

​

TargetGroupBinding

في سيناريوهات ALB التي تتطلب موارد TargetGroupBinding مُعرَّفة صراحةً:

additionalManifests:
  - apiVersion: elbv2.k8s.aws/v1beta1
    kind: TargetGroupBinding
    metadata:
      name: '{{ include "clickstack.fullname" . }}-tgb'
    spec:
      serviceRef:
        name: '{{ include "clickstack.fullname" . }}-app'
        port: app
      targetGroupARN: "arn:aws:elasticloadbalancing:us-east-1:123456789:targetgroup/my-tg/abc123"
      targetType: ip

​

متقدم: قوالب wrapper مخطط

إذا كنت بحاجة إلى دوال مساعدة هيكلية مثل include "clickstack.labels" . | nindent 4، فقم بتصييرها من قالب wrapper مخطط (templates/*.yaml) بدلًا من وضع هذه الكتل مباشرةً في ملفات values.

مثال على مقتطف من قالب wrapper مخطط:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "clickstack.fullname" . }}-extra
  labels:
    {{- include "clickstack.labels" . | nindent 4 }}
data:
  appPort: "{{ .Values.hyperdx.ports.app }}"

​

نصائح

​

خطافات Helm

يُعرَض كل إدخال في additionalManifests كمستند YAML منفصل. يمكنك إضافة التعليقات التوضيحية لخطافات Helm للتحكم في ترتيب التثبيت/الترقية:

additionalManifests:
  - apiVersion: batch/v1
    kind: Job
    metadata:
      name: post-install-job
      annotations:
        helm.sh/hook: post-install
        helm.sh/hook-delete-policy: hook-succeeded
    spec:
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: migrate
              image: my-migration-image:latest
              command: ["./migrate.sh"]

​

ترتيب CRD

إذا كانت ملفات البيان الإضافية لديك تتضمن موارد مخصصة (مثل PodMonitor)، فيجب أن تكون تعريفات الموارد المخصصة (CRDs) موجودة بالفعل في العنقود قبل التثبيت/الترقية.

​

دمج موارد متعددة

additionalManifests عبارة عن قائمة. تُعرَض العناصر وفق ترتيبها في القائمة، ويصبح كل عنصر مستند YAML مستقلًا.

​

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

• دليل Helm الرئيسي - التثبيت الأساسي
• دليل التهيئة - مفاتيح API والأسرار وIngress
• عمليات النشر على Cloud - إعدادات GKE وEKS وAKS
• مستودع مخططات Helm لـ ClickStack - الشيفرة المصدرية للمخططات ومرجع values