هلم چارت Genpack

این چارت هلم (Helm Chart) که توسط کوبیت (Kubit) طراحی شده، به‌عنوان یک چارت عمومی و قابل‌سفارشی‌سازی برای استقرار آسان اپلیکیشن‌های کانتینری مورد استفاده قرار می‌گیرد.

با استفاده از اطلاعات پیکربندی وارد شده، پک اپراتور (Pack Operator) کوبیچی به‌صورت خودکار تمامی منابع موردنیاز کوبرنیتیز را (مانند Deployment، Service، ConfigMap و ...) ایجاد کرده و آن‌ها را به‌طور مداوم با وضعیت مطلوب (spec) همگام (sync) نگه می‌دارد.

برای استفاده از این چارت، موارد زیر باید در محیط شما فراهم باشد:

• کوبرنیتیز نسخه 1.20 به بالا
• ابزار Helm نسخه 3 به بالا
• پشتیبانی از PV Provisioner در زیرساخت (در صورت استفاده از Volumes)

ابتدا مخزن هلم مربوط به کوبیت را اضافه کنید:

helm repo add kubit-packs https://repo.sabz.dev/artifactory/kubit-packs

برای نصب چارت با نام نسخه (Release) دلخواه مثلاً my-release در فضای‌نام (namespace) my-namespace:

helm install -n my-namespace my-release kubit-packs/genpack -f my-values.yaml

این دستور چارت genpack را روی کلاستر با پارامترهای داده‌شده نصب می‌کند و مقادیر موردنظر شما را از فایل my-values.yaml برای استفاده در فایل کانفیگ می‌خواند.
مقادیر قابل پیکربندی در بخش پارامترها آورده شده‌اند.

نکته: برای مشاهده لیست تمام نسخه‌های منتشرشده از دستور helm list استفاده کنید.

برای حذف نسخه نصب‌شده (my-release) و تمام منابع وابسته:

helm delete -n my-namespace my-release

این دستور تمام بخش‌ها و منابع ایجادشده توسط این چارت را حذف کرده و نسخه را پاک می‌کند.

جدول زیر بخش‌های اصلی قابل پیکربندی در چارت genpack را نمایش می‌دهد:

بخش: global.*

این بخش شامل متغیرها و تنظیمات مشترک بین تمام منابع چارت است، مانند:

• آدرس رجیستری تصاویر (Image Registry)
• کلید و مقادیر خصوصی (سکرت) مشترک (Shared Secrets)
• متغیرهای پیکربندی (ConfigMap)
• گواهی‌ها و مجوزهای ورود
• اطلاعات ورود به پایگاه داده یا سرویس‌های وابسته

global:
  commonImageRegistry: docker.sabz.dev
  commonImagePullSecrets:
    - name: docker-sabz-dev-registry
  sharedConfigs:
    POSTGRES_HOST: postgresql
    POSTGRES_PORT: 5432
    psk_conf: |
      TLSConnect=psk
      TLSAccept=psk
  sharedSecrets:
    POSTGRES_USER: user
    POSTGRES_PASSWORD: encrypted-password
#...

بخش: gonbad.*

بخش gonbad مهم‌ترین بخش و آبجکت اصلی در فایل پیکربندی values.yaml است. بر اساس مقادیر موجود در این فایل ورک‌لودها و مانیفست‌ها ایجاد می‌شوند. مهم‌ترین زیرمجموعه‌ی آن، بخش workloads است که برای ساده‌سازی ساخت و پیکربندی منابع مختلف کوبرنیتیز منابع مختلف کوبرنیتیز (مانند Deployment، Service، Ingress و ...) به کار می‌رود.

gonbad:
  workloads:
    server:
      kind: deployment
      replicaCount: 1
      service:
        type: NodePort
      containers:
        server:
          image:
            repository: zabbix/zabbix-server-pgsql
            tag: ubuntu-5.2.0
          ports:
            10051:
              name: server
              nodePort: 30051
            10052:
              enabled: false
              name: jmx

    web:
      kind: deployment
      replicaCount: 3
      containers:
        web:
          image:
            repository: zabbix/zabbix-web-nginx-pgsql
            tag: ubuntu-5.2.0
          ports:
            8080:
              name: http
            3040:
              name: metrics
              scrapePath: /metrics

      hostAliases:
        - ip: 1.2.3.4
          hostnames:
            - app1.local
            - app2.local

  ingresses:
    web:
      workloadName: web
      servicePort: http
      hosts:
        - host: zabbix.example.com

در مثال بالا:

• دو ورک‌لود تعریف شده: یکی به نام server و دیگری web، هر کدام با image و پورت‌های خاص خود.
• برای ورک‌لود web یک Ingress نیز تعریف شده است که از طریق دامنه zabbix.example.com قابل دسترسی خواهد بود.
• پورت‌ها می‌توانند دارای ویژگی‌هایی مانند scrapePath (برای متریک‌ها) و nodePort باشند.
• می‌توان از hostAliases برای نگاشت نام‌های دامنه محلی استفاده کرد.

بخش: gonbad.workloads.*

در سیستم Gonbad، پنج نوع ورک‌لود (Workload) تعریف‌پذیر هستند. ساده‌ترین نوع، ورک‌لود از نوع simple است که فقط با مشخص‌کردن یک image، یک دیپلویمنت (Deployment) ساده تک‌کانتینری ایجاد می‌کند.

در مقابل، ورک‌لود از نوع deployment نیاز به حداقل یک بخش container دارد و می‌تواند شامل چندین کانتینر نیز باشد. این نوع از ورک‌لود امکان کنترل دقیق و تنظیمات پیشرفته را بر روی جزئیات اجرای ورک‌لود مشخص‌شده فراهم می‌کند.

انواع دیگر ورک‌لودها شامل:

• statefulset: مناسب برای اپلیکیشن‌هایی با وضعیت پایدار و وابسته به ذخیره‌سازی
• daemonset: برای اجرای یک پاد روی تمام نودهای کلاستر
• cronjob: برای اجرای زمان‌بندی‌شده‌ی وظایف خاص

برای آشنایی با هر نوع، می‌توانید به بخش‌های زیر مراجعه کنید:

• ورک‌لود Simple
• ورک‌لود Deployment
• ورک‌لود Statefulset
• ورک‌لود Daemonset
• ورک‌لود Cronjob

برای تعریف یک ورک‌لود از نوع خاص، کافی‌ست مقدار gonbad.workload.<name>.kind را روی مقدار مورد نظر مانند simple قرار دهید.

هر ورک‌لود آبجکتی با یک نام (name) منحصربه‌فرد است. این نام به‌عنوان کلید (key) آن آبجکت در فایل values.yaml استفاده می‌شود.

یک وروک‌لود simple با نام foo بدین شکل تعریف می‌شود:

gonbad:
  workloads:
    foo:
      kind: simple
      #...

پارامترهای قابل تنظیم برای ورک‌لود نوع simple:

یک وروک‌لود deployment با نام bar بدین شکل تعریف می‌شود:

gonbad:
  workloads:
    bar:
      kind: deployment
      #...

یک ورک‌لود deployment می‌تواند داری چند کانتینر (container) باشد.

پارامترهای قابل تنظیم برای ورک‌لود نوع deployment:

/* مثال‌های مجاز را در بخش k8s.label regex ببینید.

یک وروک‌لود statefulset با نام bar بدین شکل تعریف می‌شود:

gonbad:
  workloads:
    rex:
      kind: statefulset
      #...
      volumeClaimTemplates:
        data-vol:
          size: 10Gi
        log-vol:
          size: 1Gi
    #...

یک ورک‌لود statefulset می‌تواند شامل چندین کانتینر (container) باشد.

پارامترهای قابل تنظیم برای ورک‌لود نوع statefulset:

/* مثال‌های مجاز labeling را در k8s.label regex و annotations را در k8s.annotation regex ببینید.

یک ورک‌لود daemonset با نام jaz بدین صورت تعریف می‌شود:

gonbad:
  workloads:
    jaz:
      kind: daemonset
      #...

یک ورک‌لود daemonset می‌تواند چندین کانتینر (container) داشته‌باشد.

پارامترهای قابل تنظیم برای ورک‌لود نوع daemonset:

/* مثال‌های مجاز labeling را در k8s.label regex و annotations را در k8s.annotation regex ببینید.

A cronjob workload name baz looks like:

gonbad:
  workloads:
    baz:
      kind: cronjob
      schedule: '0 */2 * * *'
      #...

A cronjob workload can have multiple containers.

پارامترهای قابل تنظیم برای ورک‌لود نوع cronjob:

بخش: gonbad.staticFiles

برای اینکه بتوانید تک فایل‌های ایستایی مانند فایل‌های پیکربندی (مثلاً .zshrc یا sshd.config) را درون کانتینر mount کنید، ابتدا باید آن‌ها را در بخش gonbad.staticFiles تعریف کنید.

پس از تعریف، می‌توان از طریق gonbad.workloads.containers.fileMounts به آن‌ها ارجاع داد و در کانتینر قرارشان داد.

به عنوان مثال فرض کنیم بخواهیم دو فایل ایستا به نام‌های .zshrc و sshd.config تعریف کنیم:

gonbad:
  #...
  staticFiles:
    .zshrc: |
      alias ll="ls -alh"
      alias g="git"
    sshd.config: |
      Port: 23412
  #...

در این حالت، فایل‌ها به‌صورت خودکار به ConfigMap تبدیل می‌شوند و Gonbad وظیفه‌ی حفظ یکپارچگی و یکنواختی نام‌گذاری آن‌ها را بر عهده دارد.

بخش: gonbad.volumes

برای ایجاد PersistentVolumeClaim (PVC) و استفاده از آن، یا mount کردن Secrets و ConfigMaps در داخل پادها، ابتدا باید آن‌ها در بخش gonbad.volumes تعریف کنید. سپس از طریق containers.volumeMounts در داخل کانتینر مانت شوند.

انواع Volumeهای پشتیبانی‌شده عبارت‌اند از:

در ادامه توضیح هر یک را مشاهده می‌کنید.

بخش: gonbad.ingresses

برای ایجاد منابع Ingress در کوبرنیتیز، باید آن‌ها را در زیر بخش gonbad.ingresses تعریف کرد. هر تعریف اینگرس با یک نام مانند ing مشخص می‌شود.

نمونه‌ای از پارامترهای قابل تنظیم:

• workloadName فقط نام ریلیز را به صورت داخلی به نام سرویس اضافه می‌کند. این مقدار بررسی نمی‌کند که ورک‌لود موجود یا فعال است یا نه، برای دسترسی بیشر از مقدار workload.fullnameOverride استفاده کنید.
• می‌توان مقادیر global.ingress.annotations و global.ingress.tls را نیز به صورت سراسری تعریف کرد که با مقادیر محلی اینگرس‌ها ادغام می‌شوند.

بخش: gonbad.externalServices

برای ارجاع به سرویس‌هایی خارج از کلاستر کوبرنیتیز (مثلاً دیتابیس خارجی، API، یا DNS)، باید آن‌ها را در این بخش تعریف کنید.

توجه: برای تعریف معتبر یک سرویس خارجی، علاوه‌بر ports حتماً باید یکی از فیلدهای externalName یا externalIPs مقدار داشته باشند.

بخش: gonbad.prometheusRule

در این بخش می‌توان قوانین مانیتورینگ و هشدار Prometheus را تعریف کرد. این قابلیت به ویژه برای پروژه‌هایی که نیاز به پایش دقیق متریک‌ها دارند کاربرد دارد.

بخش: gonbad.rawResources

اگر بخواهید منابع دلخواه کوبرنیتیز را خارج از سازوکار تعریف خودکار Gonbad به‌صورت مستقیم تعریف کنید (مثلاً CRD خاص یا تعریف دستی Secret)، می‌توانید آن‌ها را در این بخش وارد کنید. این منابع بدون اعتبارسنجی توسط پک اپراتور پردازش می‌شوند.

/* مثال‌های مجاز labeling را در k8s.label regex و annotations را در k8s.annotation regex ببینید.

این آبجکت‌ها به‌طور مستقیم استفاده نمی‌شوند، بلکه به‌عنوان زیرمجموعه (sub-type) برای تعریف دقیق‌تر ورک‌لودها و منابع بالا استفاده می‌شوند.

بخش: deployment.strategy

این پارامترها تعیین می‌کنند که هنگام بروزرسانی یا اعمال مجدد یک workload، چه نوع استراتژی استقراری اعمال شود:

این بخش برای معرفی سکرتی (secret) است که به‌کمک آن، ایمیج‌ها از رجیستری‌های خصوصی دریافت می‌شوند.

بخش: workload.hpa

این بخش منجر به ایجاد منبع HorizontalPodAutoscaler برای workload مربوطه می‌شود و تنظیمات مقیاس‌پذیری را مشخص می‌کند.

بخش: workload.pdb

ایجاد منبع PodDisruptionBudget برای محافظت از تعداد حداقلی از پادها هنگام رخدادهایی مثل بروزرسانی نود یا قطع موقت:

بخش: workload.securityContext

pod.securityContext شامل تنظیمات امنیتی سطح پاد است که برای تمام کانتینرها در یک پاد اعمال می‌شود. توجه داشته باشید که اگر پارامتر معادلی در container.securityContext نیز تعریف شود، اولویت با تنظیمات کانتینر خواهد بود.

پارامترهای مجاز دیگر را با دستور kubectl explain pod.spec.securityContext دریافت کنید.

بخش: container.image

بخش: workload.container.env

در Gonbad، هر متغیر محیطی (env) در کانتینر می‌تواند به‌صورت مستقیم (مقدار رشته‌ای یا عددی) یا به‌صورت غیرمستقیم از منابعی مانند Secret، ConfigMap، منابع سیستم (fieldRef) یا منابع محدودیت منابع (resourceFieldRef) مقداردهی شود.

نکته: تنها یکی از فیلدهای value، secretRef، configMapRef، resourceFieldRef یا fieldRef باید تنظیم شود.

اولویت و ترتیب پردازش envها:

1. envهایی که order مشخص دارند (به جز order: -1)
2. envهای غیرترتیب‌دار از نوع secretRef، configMapRef، resourceFieldRef و fieldRef
3. envهای ساده‌ی دارای value که حاوی $(...) نیستند
4. envهای دارای value با $(...) (تمپلیتینگ کوبرنیتیز)
5. envهایی با order: -1 (در آخر اعمال می‌شوند)

نمونه:

...:
  env:
    NUMBER: 123456
    SIMPLE: 'simple env value'

    SENTRY_DSN:
      configMapKeyRef:
        name: app-configmap
        key: sentry-dsn

    POSTGRESQL_PASSWORD:
      secretKeyRef:
        name: postgresql
        key: password

    POD_MEMORY_LIMIT:
      resourceFieldRef:
        resource: limits.memory

    POD_IP:
      fieldRef:
        fieldPath: status.podIP

    SIMPLE_ORDERED:
      value: foo
      order: 1

    POD_MEMORY_LIMIT_ORDERED:
      resourceFieldRef:
        resource: limits.memory
      order: 2

    COMPLEX:
      value: foo-$(SIMPLE_ORDERED)-$(POD_MEMORY_LIMIT_ORDERED)

    ANOTHER_COMPLEX:
      value: bar-$(POD_ID)
      order: -1 # -1 means last

بخش: container.envFrom

با استفاده از این بخش می‌توان تمام key/value‌های موجود در یک Secret یا ConfigMap را به‌صورت یکجا به عنوان متغیرهای محیطی به کانتینر اضافه کرد. در هر تعریف فقط یکی از secretRef یا configMapRef باید مشخص شود.

بخش‌ها: container.startupProbe، container.livenessProbe، container.readinessProbe

هر کانتینر می‌تواند دارای سه نوع پروب باشد:

• Startup Probe: بررسی صحت اولیه اجرای کانتینر
• Liveness Probe: بررسی اینکه کانتینر هنوز زنده است
• Readiness Probe: بررسی آمادگی کانتینر برای دریافت ترافیک

ساختار همه آن‌ها یکسان است:

بخش: container.resources

با استفاده از این پارامترها می‌توان محدودیت‌ها و درخواست‌های منابع (CPU و RAM) را برای هر کانتینر تعریف کرد. با تعریف request منابع به صورت ذخیره می‌باشند و در صورتی که limit تعریف شود و منابع مورد استفاده از این محدودیت عبور کنند، کانتینر از کار می‌افتد.

بخش: container.ports

این قسمت برای تعریف پورت‌های در دسترس در کانتینر و تولید منابع مرتبط مثل Service، Ingress و ServiceMonitor استفاده می‌شود. کلیدها شماره پورت (مثلاً 8080 یا 16049/udp) و مقدار می‌تواند رشته (نام پورت)، null یا یک آبجکت با تنظیمات زیر باشد:

بخش: container.lifecycle

در این بخش می‌توان رفتار سیستم هنگام رویدادهای آغاز و پایان اجرای کانتینر را تعریف کرد. این رویدادها شامل:

• postStart: بلافاصله پس از ایجاد کانتینر اجرا می‌شود.
• preStop: بلافاصله پیش از حذف کانتینر (به‌دلیل API یا event مدیریتی) اجرا می‌شود.

در هر یک از این مراحل، تنها یکی از روش‌های exec (اجرای دستور)، httpGet (درخواست HTTP)، یا tcpSocket (ارتباط TCP) قابل استفاده است.

بخش: container.securityContext

تنظیمات امنیتی در سطح کانتینر. این پارامترها دسترسی‌ها، قابلیت ارتقاء سطح دسترسی، و ویژگی‌های سیستم‌عاملی کانتینر را کنترل می‌کنند. اگر تنظیمی هم در سطح pod و هم container انجام شود، مقدار container اولویت دارد.

📎 برای پارامترهای بیشتر، از دستور زیر در Kubernetes استفاده کنید:

kubectl explain pod.spec.containers.securityContext

بخش: statefulset.volumeClaimTemplates

برای هر پاد در یک StatefulSet، می‌توان به‌صورت خودکار یک Persistent Volume Claim (PVC) مجزا ایجاد کرد. این تعریف باید به‌صورت mapping باشد که کلید آن نام Volume و مقدار آن تنظیمات زیر است:

در این بخش چندین مثال ببینید تا با جنبه‌های مختلف پیاده‌سازی این چارت بیشتر آشنا شوید.

#!/usr/bin/env -S helm template hello-world-sample genpack -f
gonbad:
  workloads:
    web:
      kind: deployment
      replicaCount: 1
      containers:
        web:
          image:
            registry: docker.io # optional, defaults to ''
            repository: tutum/hello-world
            tag: latest # optional, defaults to latest
          ports:
            80:
              name: http
              scrapePath: /metrics # optional, will create a ServiceMonitor object

  ingresses:
    web:
      workloadName: web
      servicePort: http
      hosts:
        - host: hello-world.example.dev

#!/usr/bin/env -S helm template volume-sample genpack -f
gonbad:
  workloads:
    web:
      kind: deployment
      replicaCount: 1
      containers:
        web:
          image:
            repository: nginx
          ports:
            80: http
          volumeMounts:
            - name: www-vol
              mountPath: /var/lib/nginx/sites/default/
            - name: existing-pvc-vol
              mountPath: /var/lib/nginx/sites/another/
            - name: config-vol
              mountPath: /etc/nginx/

  ingresses:
    web:
      workloadName: web
      servicePort: http
      hosts:
        - host: example.dev

  volumes:
    www-vol:
      type: persistentVolumeClaim
      size: 10Gi
      accessMode: ReadWriteOnce
      storageClass: zfs-hdd

    existing-pvc-vol:
      type: existingPVC
      name: pvc-fullname
      readOnly: false

    config-vol:
      type: configMap
      name: nginx-configs

#!/usr/bin/env -S helm template nodeport-sample genpack -f
gonbad:
  workloads:
    nginx:
      kind: deployment
      service:
        type: NodePort
      containers:
        nginx:
          image:
            repository: nginx
          ports:
            80:
              name: http
              nodePort: 30080
            443:
              name: https
              nodePort: 30443

    coredns:
      kind: deployment
      service:
        type: NodePort
      containers:
        coredns:
          image:
            repository: coredns
          ports:
            53/tcp:
              nodePort: 30053
            53/udp:
              nodePort: 30053

#!/usr/bin/env -S helm template external-service-sample genpack -f
gonbad:
  externalServices:
    kuma:
      externalIPs:
        - 1.2.3.4
      ports:
        443:
          enabled: true
          name: https
          scrapePath: /metrics