گسترش عملکرد Kubernetes: راهنمای عملی برای تعاریف منابع سفارشی

Summarize this content to 400 words in Persian Lang
Kubernetes یک API قوی برای مدیریت خوشه شما ارائه می دهد. API از یک طراحی RESTful استفاده می‌کند که به شما امکان می‌دهد تا اقدامات معمولی مانند ایجاد، بازیابی، به‌روزرسانی، حذف، فهرست‌بندی، وصله‌سازی و تماشای منابع مختلف را در کلاستر انجام دهید.

API های Kubernetes به گروه های زیر تقسیم می شوند:

هسته گروه: این شامل گره ها، غلاف، فضاهای نام، خدمات، ConfigMaps و اسرار.

تحت عنوان گروه ها: این گروه ها قابلیت های مرتبط را دسته بندی می کنند. به عنوان مثال برنامه ها گروه شامل منابعی برای مدیریت استقرارها، مجموعه‌های حالت، مجموعه‌های دیمون و مجموعه‌های مشابه است، در حالی که دسته ای گروه مشاغل و کار های cron را انجام می دهد.

هر گروه ممکن است یک یا چند نسخه داشته باشد که مستقل از سایر گروه‌های API تکامل می‌یابد و هر نسخه درون گروه دارای یک یا چند منبع است.

به طور خلاصه:

گروه: منابع را بر اساس عملکرد یا مبدا دسته بندی می کند. این امکان گسترش آسان API را با افزودن گروه های جدید برای ویژگی های خاص فراهم می کند.

نسخه: نشان دهنده نسخه های API خاص در یک گروه. ممکن است در نسخه‌های مختلف ویژگی‌ها یا اصلاحات جدید در منابع موجود ارائه شود. نسخه‌سازی سازگاری و ارتقاء روان‌تر را تضمین می‌کند.

منبع type نامی است که در URL استفاده می شود (به عنوان مثال، پادها، فضاهای نام، خدمات).

نوع: نمایش عینی (شما طرح واره) یک نوع منبع را تعریف می کند.

مجموعه: به فهرستی از نمونه ها برای یک نوع منبع خاص اشاره دارد. انواع مجزای مجموعه با “فهرست” ضمیمه وجود دارد (به عنوان مثال، PodList، لیست خدمات).

منبع: یک نمونه جداگانه از یک نوع منبع، که معمولاً یک شی در خوشه شما را نشان می دهد.

منابع فرعی: برای انواع منابع خاص، عملکردهای اضافی به عنوان منابع فرعی در مسیر URI منبع در معرض دید قرار می گیرند.

برای دیدن همه منابع API موجود در خوشه: kubectl api-resources

kubectl api-resources

NAME SHORTNAMES APIVERSION NAMESPACED KIND
bindings v1 true Binding
configmaps cm v1 true ConfigMap
endpoints ep v1 true Endpoints
events ev v1 true Event
limitranges limits v1 true LimitRange
namespaces ns v1 false Namespace
nodes no v1 false Node
persistentvolumeclaims pvc v1 true PersistentVolumeClaim
persistentvolumes pv v1 false PersistentVolume
pods po v1 true Pod
…

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

سرور API تمام درخواست ها را مدیریت می کند.

به عنوان مثال، هنگامی که ما یک استقرار ایجاد می کنیم، kube-apiserver محتوای استقرار ما را تأیید می کند تا مطمئن شود که قالب مورد نیاز را برآورده می کند و از قوانین پیروی می کند. پس از تأیید اعتبار، اطلاعات استقرار را در فروشگاه داده خوشه ذخیره می کند، معمولاً غیره.

بسیاری از رفتارهای Kubernetes توسط برنامه هایی به نام کنترلرها که کلاینت های سرور API هستند پیاده سازی می شود. Kubernetes در حال حاضر با مجموعه ای از کنترلرهای داخلی عرضه می شود. به عنوان مثال ما می توانیم به kube-controller-manager ورود به سیستم pod برای دیدن اینکه کدام کنترلرها شروع شده اند. Deployment Controller یکی از آن هاست.

kubectl logs -n kube-system kube-controller-manager-sveltos-management-control-plane
…
I0531 15:34:16.026590 1 controllermanager.go:759] “Started controller” controller=”deployment-controller”

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

کنترل کننده استقرار دائماً به دنبال موارد استقرار است. در مورد ما، زمانی که یک Deployment جدید ایجاد کردیم، Deployment Controller از این تغییر آگاه شد و برای رسیدن به حالت دلخواه ما اقدام کرد. در این مورد، یک منبع ReplicaSet ایجاد کرد. کنترل کننده استقرار نیز بخش وضعیت استقرار را به روز کرد. این بخش پیشرفت در جهت دستیابی به وضعیت مطلوب را پیگیری می کند.

اشیاء

هر شی باید داده های زیر را داشته باشد.

TypeMeta شامل نوع و نسخه API است.

یک میدان تو در تو فراداده شامل:

فضای نام: فضای نام پیش‌فرض «پیش‌فرض» است. منابع گسترده خوشه ای این مجموعه فیلد را ندارند.

نام: رشته ای که به طور منحصر به فرد این شی را در فضای نام فعلی شناسایی می کند. این مقدار در مسیر هنگام بازیابی یک شی منفرد استفاده می شود.

uid: یک مقدار منحصر به فرد در زمان و مکان که برای تمایز بین اشیایی با نام یکسان که حذف شده و دوباره ساخته شده اند استفاده می شود.

منبع نسخه: رشته ای که نسخه داخلی این شی را مشخص می کند که می تواند توسط کلاینت ها برای تعیین زمان تغییر اشیاء استفاده شود.

ایجاد زمان مهر: رشته ای که تاریخ و زمان ایجاد یک شی را نشان می دهد.

حذف زمان مهر: رشته ای که نشان دهنده تاریخ و زمانی است که پس از آن این منبع حذف می شود.

برچسب ها: نقشه ای از کلیدها و مقادیر رشته ای که می تواند برای سازماندهی و دسته بندی اشیا استفاده شود.

حاشیه نویسی: نقشه ای از کلیدها و مقادیر رشته ای که می تواند توسط ابزارهای خارجی برای ذخیره و بازیابی فراداده دلخواه در مورد این شی مورد استفاده قرار گیرد.

یک فیلد شی تودرتو نامیده می شود مشخصات وضعیت مطلوب یک شی را نشان می دهد.

یک فیلد شی تودرتو نامیده می شود وضعیت وضعیت فعلی شی در سیستم را خلاصه می کند. API اعلامی Kubernetes تفکیک مسئولیت ها را اعمال می کند. شما وضعیت مورد نظر منبع (مشخصات) خود را اعلام می کنید. کنترلر Kubernetes وضعیت فعلی اشیاء Kubernetes را با وضعیت دلخواه اعلام شده شما هماهنگ نگه می دارد.

هنگام پوشش آشتی‌دهنده‌ها، موارد زیر را پوشش خواهیم داد:

چگونه Kubernetes از resourceVersion برای شناسایی تضادها هنگام به روز رسانی یک منبع استفاده می کند.
چرا deletionTimestamp، همراه با نهایی کننده ها، مهم است.
نحوه استفاده از برچسب ها برای پرس و جو از گروهی از اشیاء مرتبط (مثلاً همه پادهایی که از یک سرویس پشتیبان تهیه می کنند).
نحوه ارائه مجوزهای مختلف برای Spec و Status و نحوه کار تطبیق دهندگان.

گسترش API Kubernetes

هر سیستمی که موفق باشد باید با ظهور موارد استفاده جدید یا تغییر موارد موجود، رشد و تغییر کند. بنابراین، Kubernetes API Kubernetes را برای تغییر و رشد مداوم طراحی کرده است. دو راه برای گسترش API های Kubernetes وجود دارد:

این CustomResourceDefinition مکانیسم (CRD) به شما امکان می دهد تا به صورت اعلامی یک API سفارشی جدید را با گروه API، نوع و طرحی که شما مشخص می کنید، تعریف کنید. CRD به شما این امکان را می دهد که انواع جدیدی از منابع را برای خوشه خود بدون نوشتن و اجرای سرور API سفارشی ایجاد کنید. هنگامی که یک CustomResourceDefinition جدید ایجاد می کنید، سرور API Kubernetes یک مسیر منبع RESTful جدید برای هر نسخه مشخص شده ایجاد می کند.
این aggregation layer پشت سرور API اولیه قرار دارد که به عنوان یک پروکسی عمل می کند. این ترتیب API Aggregation (AA) نامیده می شود که به شما امکان می دهد با نوشتن و استقرار سرور API خود، پیاده سازی های تخصصی را برای منابع سفارشی خود ارائه دهید. سرور اصلی API درخواست ها را برای API های سفارشی که شما مشخص می کنید به سرور API شما واگذار می کند.

شما می توانید ثبت نام کنید extension API server با ایجاد یک APISservice ادعای یک مسیر URL در Kubernetes API. از آن نقطه به بعد، kube-aggregator هر درخواستی که به آن مسیر API ارسال شود، به APIService ثبت شده ارسال خواهد شد.

اکثر اوقات با اضافه کردن یک CustomResourceDefinition جدید مشکلی ندارید. مگر اینکه به اعتبارسنجی های سفارشی نیاز داشته باشید و از قبل برنامه ای داشته باشید که API شما را ارائه می دهد و به خوبی کار می کند، می توانید با CRD بروید. این آموزش به فرآیند ایجاد CustomResourceDefinitions می پردازد.

تعریف منابع سفارشی

برای معرفی منابع جدید، می توانید از CustomResourceDefinitions استفاده کنید.CRDs با اجازه دادن به کاربران برای ایجاد انواع جدیدی از منابع فراتر از مجموعه داخلی، قابلیت های Kubernetes را گسترش می دهد.

یک CustomResourceDefinition خود یک منبع Kubernetes است. بنابراین می‌توانید یک CustomResourceDefinition مانند سایر منابع Kubernetes ایجاد کنید.

بیشتر اعتبار سنجی را می توان در CRD با استفاده از اعتبار سنجی OpenAPI v3.0 و Common Expression Language مشخص کرد. هر گونه اعتبار سنجی دیگر با افزودن یک Webhook اعتبار سنجی پشتیبانی می شود.

در این بخش، ما عمیقاً به ایجاد و مدیریت تعاریف منابع سفارشی در Kubernetes خواهیم پرداخت.

Kubebuilder

Kubebuilder، چارچوبی توسط Kubernetes SIGs، ایجاد API های Kubernetes را با استفاده از تعاریف منابع سفارشی ساده می کند.

با نصب Kubebuilder، می توانید یک پروژه جدید ایجاد کنید. این مراحل برای من بود:

brew install kubebuilder
mkdir my-project
kubebuilder init –domain projectsveltos.io
kubebuilder create api –group app –version v1alpha1 –kind MyKind[^2]

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

گروه: این به عنوان یک شناسه منحصر به فرد برای مجموعه منابع سفارشی شما عمل می کند. برای جلوگیری از درگیری با گروه‌های Kubernetes موجود، توصیه می‌شود از زیر دامنه‌ای که کنترل می‌کنید (به عنوان مثال yourcompany.com) استفاده کنید.

نسخه: نسخه های Kubernetes از فرمت خاصی پیروی می کنند: vX.Y (اختیاری با آلفا یا بتا) و اعداد بالقوه اضافی. آلفا نشان دهنده یک ویژگی در حال توسعه است، در حالی که بتا نشان دهنده ثبات بیشتر است.

نوع: این نوع خاصی از منبع را در API شما تعریف می کند (به عنوان مثال، پایگاه داده، ConfigMap). اساساً منابع فردی را که مدیریت خواهید کرد نام می برد.

Kubebuilder از ابزاری به نام controller-gen برای ایجاد خودکار کدهای ضروری و فایل های پیکربندی استفاده می کند. این اتوماسیون متکی به نظرات ویژه ای است که در کد Go شما تعبیه شده است که به آن معروف است نظرات نشانگر.

دستورالعمل های فوق ایجاد شده است:

در پروژه های Kubebuilder، دو فایل کلیدی نقش های خاصی را ایفا می کنند:

groupversion_info.go: این فایل، همانطور که از نامش پیداست، اطلاعاتی در مورد گروه API و نسخه برای CRD شما دارد. معمولاً متغیری به نام GroupVersion را با گروه (مثلاً app.projectsveltos.io) و نسخه (مثلاً v1alpha1) تعریف می کند. این شناسه منحصر به فرد برای CRD شما در API Kubernetes ایجاد می کند.

mykind_types.go: این فایل جایی است که شما خود منبع واقعی را تعریف می کنید. این شامل ساختار CRD شما، از جمله فیلدهای آن و قوانین اعتبارسنجی است. این فایل اساساً داده‌هایی را که CRD شما در خوشه Kubernetes مدیریت می‌کند، توصیف می‌کند.

GroupVersion = schema.GroupVersion{Group: “app.projectsveltos.io”, Version: “v1alpha1”}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

در حالی که mykind_types.go جایی است که منبع ما تعریف شده است.

package v1alpha1

import (
metav1 “k8s.io/apimachinery/pkg/apis/meta/v1”
)

// EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN!
// NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized.

// MyKindSpec defines the desired state of MyKind
type MyKindSpec struct {
// INSERT ADDITIONAL SPEC FIELDS – desired state of cluster
// Important: Run “make” to regenerate code after modifying this file

// Foo is an example field of MyKind. Edit mykind_types.go to remove/update
Foo string `json:”foo,omitempty”`
}

// MyKindStatus defines the observed state of MyKind
type MyKindStatus struct {
// INSERT ADDITIONAL STATUS FIELD – define observed state of cluster
// Important: Run “make” to regenerate code after modifying this file
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// MyKind is the Schema for the mykinds API
type MyKind struct {
metav1.TypeMeta `json:”,inline”`
metav1.ObjectMeta `json:”metadata,omitempty”`

Spec MyKindSpec `json:”spec,omitempty”`
Status MyKindStatus `json:”status,omitempty”`
}

…

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اکنون، شما آماده هستید تا با تعریف کردن، رفتار API را سفارشی کنید MyKindSpec و MyKindStatus ساختارها در mykind_types.go. پس از تکمیل این تعاریف، اجرا کنید make manifests فایل CustomResourceDefinition را ایجاد می کند config/crd/bases/app.projectsveltos.io_mykinds.yaml.

من از مثال‌های عینی از پروژه‌های منبع باز برای نشان دادن مفاهیم (و نشانگرهایی) که بحث کردیم استفاده خواهم کرد.

اما ابتدا یک نیاز کلیدی برای کار با منابع سفارشی در Golang وجود دارد. کتابخانه Client-go که برای تعامل با Kubernetes API استفاده می‌شود، برای پیاده‌سازی به منابع (از جمله منابع سفارشی) نیاز دارد. زمان اجرا. شی رابط. این رابط تضمین می کند که اشیاء می توانند برای ارتباط با سرور API سریال شوند و از سریال خارج شوند. یکی از جنبه های حیاتی رابط کاربری Runtime.Object نیاز به روش های DeepCopy است. این روش ها یک کپی کامل از شی ایجاد می کنند.با گنجاندن // +kubebuilder:object:root=true نشانگر در کد خود، به Kubebuilder دستور می دهید تا به طور خودکار روش های لازم (از جمله DeepCopy) را برای پیاده سازی runtime.Object ایجاد کند.

مثال: CRD Cleaner

هنگامی که من k8s-cleaner را توسعه دادم، هدف ایجاد ابزاری بود که بتواند منابع استفاده نشده یا ناسالم را در سراسر خوشه شناسایی کند. سپس این ابزار می تواند آن منابع را در صورت نیاز حذف یا به روز کند.

انتخاب محدوده

یک تصمیم کلیدی طراحی شامل محدوده بود. از آنجایی که کاربران اصلی، مدیران پلتفرم هستند که کل خوشه را مدیریت می کنند، من یک را انتخاب کردم در سطح خوشه محدوده. این به مدیران اجازه می دهد تا منابع استفاده نشده (مثلاً ConfigMaps) را در همه فضاهای نام به طور موثر شناسایی کنند. این امر نیاز به استقرار پاک کننده های جداگانه برای هر فضای نام را حذف می کند و گردش کار آنها را ساده می کند.

با این حال، در حالی که گستره وسیع خوشه‌ای مزایای واضحی را برای مدیران پلتفرم ارائه می‌دهد، من همچنین به نیاز بالقوه کاربران برای تمرکز بر فضاهای نام خاص اذعان کردم. برای رفع این انعطاف‌پذیری، فیلتر فضای نام را به عنوان یک گزینه پیکربندی گنجانده‌ام. این به کاربران اجازه می دهد تا عملکرد پاک کننده را مطابق با نیازهای خاص خود سفارشی کنند. به‌عنوان یک گزینه پیکربندی، در داخل نمایش داده می‌شود مشخصات رشته.

کامنت نشانگر مورد استفاده برای تعریف یک محدوده کلستر برای کنترلر Cleaner است:

//+kubebuilder:resource:path=cleaners,scope=Cluster

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اگر تصمیم گرفتید که منابع شما باید به فضای نام اختصاص داشته باشند:

//+kubebuilder:resource:path=cleaners,scope=Namespaced

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

مشخصات

Spec نشان دهنده وضعیت مورد نظر، از جمله تنظیمات تعریف شده توسط کاربر و پیش فرض های سیستم است. بنابراین تمام مواردی که کاربر ممکن است نیاز داشته باشد را در Spec قرار دهید.

چشم انداز من این بود که کاربران را با توانایی های زیر توانمند کنم:

معیارها را تعریف کنید: به وضوح مشخص کنید که چه چیزی یک منبع استفاده نشده یا ناسالم را در زمینه خاص آنها تشکیل می دهد.

اسکن ها را برنامه ریزی کنید: تعیین کنید که کنترل کننده Cleaner چند وقت یکبار باید خوشه را برای منابعی که معیارهای پاکسازی شما را برآورده می کنند اسکن کند.

خودکار کردن اقدامات: اقدام مورد نظر (حذف یا به روز رسانی) را انتخاب کنید تا در منابع شناسایی شده انجام شود.

به یاد داشته باشید که برخی از فیلدها ممکن است اختیاری باشند و دارای مقدار پیش فرض باشند. استفاده کنید // +kubebuilder:default:= نشانگر برای تعیین مقدار پیش فرض.

// +kubebuilder:default:=Delete
Action Action `json:”action,omitempty”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اینجا، Delete اگر به صراحت توسط کاربر تعریف نشده باشد، اقدام پیش فرض است.

اضافه کردن اختیاری نشانگر در امتداد ساختار json حذف کردن تگ فیلدی که می خواهید اختیاری کنید.

// +optional
Transform string `json:”transform,omitempty”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

لیست کامل نشانگرهای اعتبارسنجی

منبع فرعی وضعیت

منبع فرعی وضعیت از طریق فعال می شود //+kubebuilder:subresource:status. این منبع فرعی یک نقطه پایانی اضافی را به طور خاص برای وضعیت نمونه پاک کننده شما در معرض نمایش می گذارد.

در Kubernetes، همانطور که قبلا توضیح داده شد، a resource یک موجودیت منطقی مانند Pod یا Deployment را نشان می دهد. هر منبع یک نقطه پایانی API مرتبط دارد. منبع فرعی وضعیت یک نقطه پایانی اختصاصی برای نظارت بر وضعیت فعلی و پیشرفت نمونه پاک کننده شما فراهم می کند.

توجه به این نکته مهم است که به‌روزرسانی‌های انجام شده در منبع اصلی پاک‌کننده مستقیماً بر وضعیت آن تأثیر نمی‌گذارد. به همین ترتیب، تغییرات در منبع فرعی وضعیت فقط بر اطلاعات وضعیت تأثیر می گذارد، نه پیکربندی اصلی. این جداسازی امکان به روز رسانی متمرکز را فراهم می کند.

از آنجایی که منبع فرعی وضعیت نقطه پایانی خود را دارد، می‌توانید از RBAC (کنترل دسترسی مبتنی بر نقش) برای مدیریت مستقل دسترسی به منبع پاک‌کننده و وضعیت آن استفاده کنید. این به شما امکان می دهد تعیین کنید چه کسی می تواند پیکربندی پاک کننده را مشاهده یا تغییر دهد و چه کسی می تواند پیشرفت آن را از طریق منبع فرعی وضعیت نظارت کند.

درک اینکه چه کسی Spec را تعریف می کند و چه کسی از وضعیت استفاده می کند هنگام طراحی یک CRD بسیار مهم است. این بخش‌ها نقش‌های مشخصی را در مدیریت منبع Cleaner شما ایفا می‌کنند.

بخش Spec به عنوان یک طرح اولیه برای وضعیت مطلوب منبع Cleaner شما عمل می کند. در این سناریو، مدیر پلتفرم Spec را با مشخص کردن معیارهای تمیز کردن، برنامه اسکن و اقدامات مورد نظر تعریف می کند. در اصل، Spec به کنترلر Cleaner می گوید که چه کاری انجام دهد.

بخش Status که به طور خودکار توسط کنترلر Cleaner به روز می شود، وضعیت فعلی منبع شما را نشان می دهد. اطلاعات ارزشمندی را برای مدیر پلتفرم فراهم می کند، مانند:

lastRunTime: مهر زمانی آخرین اجرای Cleaner.

پیام شکست (اختیاری): یک پیام خطای قابل خواندن توسط انسان در صورت عدم موفقیت آخرین اجرا.

nextScheduleTime: زمان برنامه ریزی شده برای اجرای Cleaner بعدی.

با نظارت بر منبع فرعی وضعیت، مدیر پلتفرم بینشی در مورد عملکرد پاک کننده به دست می آورد و می تواند خطاهای بالقوه تمیز کردن را شناسایی کند.

را ایجاد کنید

پس از انجام تعریف Spec و Status، فقط اجرا کنید make generate هدف. این به سادگی کنترل کننده-ژن را در پشت صحنه به درستی فراخوانی می کند.

این باعث ایجاد Cleaner CustomResourceDefinition می شود. استفاده کنید کوبکتل تا آن را در خوشه خود اعمال کنید.

Apiextension-Apiserver

پس از ارسال یک شی CustomResourceDefinition، apiextensions-apiserver داخل kube-apiserver بررسی می‌کند که آیا تداخلی وجود دارد و آیا منبع معتبر است یا خیر. سپس نتیجه را در وضعیت CRD گزارش می کند، به عنوان مثال:

kubectl get customresourcedefinitions cleaners.apps.projectsveltos.io -o yaml

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: cleaners.apps.projectsveltos.io
…
status:
acceptedNames:
kind: Cleaner
listKind: CleanerList
plural: cleaners
singular: cleaner
conditions:
– lastTransitionTime: “2024-05-31T12:32:39Z”
message: no conflicts found
reason: NoConflicts
status: “True”
type: NamesAccepted
– lastTransitionTime: “2024-05-31T12:32:39Z”
message: the initial names have been accepted
reason: InitialNamesAccepted
status: “True”
type: Established
storedVersions:
– v1alpha1

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

زبان عبارت رایج (CEL)

برای اطمینان از اینکه تنظیمات CRD شما به خوبی تعریف شده است، می توانید نظرات نشانگر را با Common Expression Language (CEL). از آنجایی که Kubernetes نسخه 1.25 پشتیبانی CEL را برای اعتبار سنجی در بتا معرفی کرد، اکنون می توانید عباراتی را برای اعتبارسنجی منابع سفارشی خود بنویسید.

نشانگر //+kubebuilder:validation:XValidation:rule می توان برای این محدوده استفاده کرد.

تغییرناپذیری

یک مثال رایج تغییر ناپذیری است. به عنوان مثال اگر من می خواستم رشته Cleaner.Spec.Schedule را تغییرناپذیر کنم

//+kubebuilder:validation:XValidation:rule=”self == oldSelf”,message=”Value is immutable”
Schedule string `json:”schedule”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

با آن، اگر من سعی کردم یک نمونه Cleaner را به روز کنم، آن را تغییر می داد برنامه در این زمینه، به روز رسانی با شکست مواجه خواهد شد

The Cleaner “list-pods-with-outdated-secret-data” is invalid: spec.schedule: Invalid value: “string”: Value is immutable

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

self یک کلمه کلیدی خاص در CEL است که به شیئی که نوع آن حاوی قانون است اشاره دارد. در مثال بالا، self به فیلد Schedule اشاره دارد. بنابراین من فقط فیلد Schedule را مجبور می کنم که تغییرناپذیر باشد.

لیست فقط ضمیمه

مثال رایج دیگر، فهرستی است که فقط پیوست است. به عنوان یک مثال فرضی، اگر ResourceSelectors به ​​این شکل طراحی شده باشد

//+kubebuilder:validation:XValidation:rule=”size(self) >= size(oldSelf)”,message=”this list is append only”
ResourceSelectors []ResourceSelector `json:”resourceSelectors”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

هر به روز رسانی که آن لیست را کاهش دهد با شکست مواجه خواهد شد

The Cleaner “list-pods-with-outdated-secret-data” is invalid: spec.resourcePolicySet.resourceSelectors: Invalid value: “array”: this list is append only

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

قالب نام

برای اجرای آن نمونه پاک‌تر با «پیشوند من» شروع می‌شود (معنی را به خاطر بسپارید خود )

// Cleaner is the Schema for the cleaners API
type Cleaner struct { //+kubebuilder:validation:XValidation:rule=self.metadata.name.startsWith(“my-prefix”)

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

ایجاد هر نمونه Cleaner با نام نادرست با شکست مواجه خواهد شد

The Cleaner “list-pods-with-outdated-secret-data-2” is invalid: : Invalid value: “object”: failed rule: self.metadata.name.startsWith(“my-prefix”)

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

وقتی با فیلدهای رشته ای در CRD سروکار دارید، می توانید از آن استفاده کنید +kubebuilder:validation:Pattern حاشیه نویسی برای اجرای یک قالب خاص با استفاده از عبارات منظم.به عنوان مثال، برای اطمینان از اینکه یک فیلد رشته ای به نام توضیحات با یک حرف یا زیرخط شروع می شود و فقط شامل حروف، اعداد و زیرخط است، می توانید از قطعه YAML زیر استفاده کنید:

// +kubebuilder:validation:Pattern=`^[A-Za-z_][A-Za-z0-9_]*$`
Description string `json:”description”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اگر فیلد رشته ای دارید که به قالب تاریخ و زمان معتبر نیاز دارد، معمولاً از RFC 3339 پیروی می کند، می توانید از +kubebuilder:validation:Format=”date-time” حاشیه نویسیبه عنوان مثال، برای اعتبارسنجی فیلدی به نام TimeOfX، قطعه YAML زیر اطمینان می‌دهد که به RFC 3339 پایبند است:

//+kubebuilder:validation:Format=”date-time”
TimeOfX string `json:”timeOfX”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

سپس “2024-06-03T15:29:48Z” یک مقدار معتبر خواهد بود، در حالی که “2024” نخواهد بود.

مقایسه رشته های مختلف

تصور کنید که یک Spec با

// +kubebuilder:validation:XValidation:rule=self.minReplicas <= self.replicas
type MyResourceSpec struct {
Replicas int `json:”replicas”`

MinReplicas int `json:”minReplicas”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نشانگر بالا اجبار می کند که minReplicas همیشه کمتر یا مساوی با replica ها باشد.

مثال: ClusterProfile CRD

من همچنین پروژه منبع باز دیگری به نام addon-controller را حفظ می کنم. این یک کنترل‌کننده Kubernetes است که مدیریت افزونه‌ها و برنامه‌ها را در چندین کلاستر ساده می‌کند. این از یک خوشه مدیریت مرکزی عمل می کند و افزونه ها و برنامه های کاربردی را در خوشه های مدیریت شده ای که نظارت می کند مدیریت می کند.

Sveltos دو تعریف منبع سفارشی را معرفی می کند: ClusterProfile و Profile. هر دوی این CRD به کاربران این امکان را می دهد که:

با استفاده از انتخابگر خوشه، زیر مجموعه ای از خوشه مدیریت شده را انتخاب کنید.
برنامه های افزودنی را که باید در آن خوشه ها مستقر شوند را فهرست کنید.

آنها دامنه های متمایز دارند اما برای پاسخگویی به نقش های مختلف کاربر:

ClusterProfiles: منبع گسترده خوشه ای. در تمام خوشه ها در هر فضای نامی اعمال می شود. ایده آل برای مدیران پلتفرم که ثبات جهانی را حفظ می کنند و تنظیماتی مانند شبکه، امنیت و تخصیص منابع را مدیریت می کنند.

Profiles: محدود به یک فضای نام خاص، اعطای کنترل گرانول به مدیران مستاجر. این جداسازی تضمین می‌کند که تیم‌ها، از خوشه مدیریت، خوشه‌های مدیریت‌شده خود را به‌طور مستقل و بدون تأثیر بر دیگران مدیریت کنند.

آنچه در Spec وجود دارد به خوبی تعریف شده است. بیایید برخی از نشانگرهای فیلد Spec را بررسی کنیم.

// HelmChartAction specifies action on an helm chart
// +kubebuilder:validation:Enum:=Install;Uninstall
type HelmChartAction string

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

این مشخص می کند که این فیلد (اسکالر) به مقدار محدود می شود دقیق مقادیر مشخص شده در اینجا، نصب و حذف نصب کنید.اگر بخواهم یک ClusterProfile با مقدار نادرست برای این فیلد ارسال کنم، پست با شکست مواجه خواهد شد

The ClusterProfile “deploy-kyverno” is invalid: spec.helmCharts[0].helmChartAction: Unsupported value: “Deploy”: supported values: “Install”, “Uninstall”

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

// RepositoryURL is the URL helm chart repository
// +kubebuilder:validation:MinLength=1
RepositoryURL string `json:”repositoryURL”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

این حداقل طول این رشته را مشخص می کند. اگر بخواهم یک ClusterProfile پست کنم و این قسمت را خالی بگذارم، پست با شکست مواجه خواهد شد

The ClusterProfile “deploy-kyverno” is invalid: spec.helmCharts[0].repositoryURL: Invalid value: “”: spec.helmCharts[0].repositoryURL in body should be at least 1 chars long

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نشانگرهای مختلف را می توان با هم استفاده کرد

// +kubebuilder:default:=100
// +kubebuilder:validation:Minimum=1
// +optional
Tier int32 `json:”tier,omitempty”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

یک چالش رایج شامل اطمینان از عدم وجود موارد تکراری در یک لیست است. در زمینه کنترل‌کننده‌های الحاقی، این موضوع هنگام واکشی منابع از خوشه مدیریت برای مقاصد الگو، مرتبط می‌شود. هر منبع واکشی شده توسط یک فیلد کلیدی منحصر به فرد به نام an شناسایی می شود مشخص کننده. این شناسه مشابه کلید فرهنگ لغت عمل می کند و امکان ایجاد یک ساختار انجمنی را فراهم می کند که در آن هر منبع به طور منحصر به فرد قابل دسترسی است.

// +listType=map
// +listMapKey=identifier
// +optional
TemplateResourceRefs []TemplateResourceRef `json:”templateResourceRefs,omitempty” patchStrategy:”merge” patchMergeKey:”identifier”`

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

listType=map: این حاشیه مشخص می کند که TemplateResourceRefs لیستی است که به عنوان یک نقشه در نظر گرفته می شود.
listMapKey=identifier: این حاشیه‌نویسی فیلد کلیدی را در هر آیتم فهرستی که برای نگاشت (شناسه) استفاده می‌شود، تعریف می‌کند.

به دنبال این تعریف، ساختار TemplateResourceRef ساختار هر آیتم را در لیست TemplateResourceRefs شرح می دهد:

type TemplateResourceRef struct {
// Resource references a Kubernetes instance in the management
// cluster to fetch and use during template instantiation.
Resource corev1.ObjectReference `json:”resource”`

// Identifier is how the resource will be referred to in the
// template
Identifier string `json:”identifier”`
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

هنگام تعریف منابع برای قالب در TemplateResourceRefs، هر منبع باید یک شناسه منحصر به فرد داشته باشد. تلاش برای ایجاد یک نمونه نمایه که از شناسه ای استفاده می کند که قبلاً به منبع دیگری در TemplateResourceRefs اختصاص داده شده است، رد می شود.

برای بهبود تجربه کاربر، وضعیت نمایه باید در درجه اول بر نمایش لیستی از خوشه های مدیریت شده که با یک نمایه خاص مطابقت دارند تمرکز کند. این یک نمای واضح از اینکه کدام خوشه های پروفایل را هدف قرار می دهد ارائه می دهد. همانطور که در بخش آشتی‌دهنده عمیق‌تر می‌شویم، نقش کنترل‌کننده پروفایل مشخص می‌شود: نظارت بر خوشه‌های مدیریت‌شده و شناسایی مطابقت‌های بالقوه برای پروفایل‌ها.

مهم است که اصل مالکیت واحد برای منابع، از جمله وضعیت نمایه را به خاطر بسپارید. ذخیره اطلاعات خطای استقرار مستقیماً در وضعیت نمایه ممکن است نشان دهد که کنترل کننده نمایه خود مسئول استقرار منابع در خوشه های مدیریت شده است. با این حال، این کنترلر نمایه را بیش از حد بارگذاری می کند، به خصوص اگر یک نمایه به طور بالقوه با ده ها خوشه مطابقت داشته باشد. برای مدیریت کارآمد، مسئولیت های استقرار باید به طور جداگانه انجام شود. بنابراین، کنترل‌کننده پروفایل بر عملکرد اصلی خود تمرکز می‌کند: تماشای خوشه‌ها و حفظ فهرستی از خوشه‌های مدیریت‌شده منطبق. این لیست در وضعیت نمایه منعکس می شود و دید واضحی را ارائه می دهد.

برای هر خوشه مدیریت شده که با یک نمونه نمایه مطابقت دارد، کنترلر نمایه یک نمونه ClusterSummary ایجاد می کند.

یک کنترلر جداگانه، کنترلر ClusterSummary، مسئولیت استقرار افزونه ها و برنامه های کاربردی را بر اساس اطلاعات موجود در ClusterSummary بر عهده می گیرد. منبع ClusterSummary یک بخش “وضعیت” را حفظ می کند که پیشرفت استقرار را منعکس می کند. این بخش شما را در مورد اینکه آیا افزونه‌ها و برنامه‌ها با موفقیت در کلاستر اجرا شده‌اند یا خطاهایی که ممکن است در طول فرآیند استقرار رخ داده باشد، مطلع می‌سازد.

ستون های چاپگر اضافی

قبلاً دیدیم که کاربران می توانند با استفاده از kubectl مشابه منابع داخلی با منابع سفارشی تعامل داشته باشند. این +kubebuilder:printcolumn نشانگر به شما امکان می دهد اطلاعات اضافی نمایش داده شده توسط kubectl get را تعریف کنید.

Sveltos از ثبت کلاسترهای مختلف (GKE، Civo و غیره) با آن پشتیبانی می کند. هنگامی که یک خوشه ثبت شد، Sveltos می تواند افزونه ها و برنامه های کاربردی را روی آن مستقر کند. SveltosCluster CRD (تعریف شده در SveltosCluster) ثبت خوشه با Sveltos را فعال می کند.

هنگام فهرست کردن یا دریافت منابع SveltosCluster موجود، دیدن آمادگی خوشه مدیریت شده و نسخه Kubernetes در یک نگاه مفید است. در اینجا نحوه رسیدن به آن آمده است:

//+kubebuilder:printcolumn:name=”Ready”,type=”boolean”,JSONPath=”.status.ready”,description=”Indicates whether cluster is ready to be managed by sveltos”
//+kubebuilder:printcolumn:name=”Version”,type=”string”,JSONPath=”.status.version”,description=”Kubernetes version associated with this Cluster”

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

kubectl get sveltoscluster -A
NAMESPACE NAME READY VERSION
mgmt mgmt true v1.29.1

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

اعتبار سنجی جغجغه ای

اگر بخواهید اعتبار جدیدی را به یک CRD که قبلاً معرفی و ارسال کرده اید اضافه کنید، چه باید کرد؟ اشیاء سفارشی موجود ممکن است با اعتبار سنجی جدید تضاد داشته باشند، بنابراین برای رسیدگی به آنها به برنامه ای نیاز دارید. مثل همیشه، Kubernetes به کمک می آید.

به شرطی که دروازه ویژگی را فعال کرده باشید، Kubernetes اعتبار سنجی را برای CustomResourceDefinitions پیاده سازی می کند. سرور API مایل است به‌روزرسانی‌های منابعی را که پس از به‌روزرسانی معتبر نیستند، بپذیرد، مشروط بر اینکه هر بخشی از منبعی که اعتبارسنجی آن انجام نشد، با عملیات به‌روزرسانی تغییر نکرده باشد. به عبارت دیگر، هر بخش نامعتبری از منبع که نامعتبر باقی می‌ماند، باید قبلاً اشتباه بوده باشد. شما نمی توانید از این مکانیسم برای به روز رسانی یک منبع معتبر استفاده کنید تا نامعتبر شود.

این ویژگی به نویسندگان CRD اجازه می دهد تا با اطمینان اعتبارات جدیدی را تحت شرایط خاص به طرح OpenAPIV3 اضافه کنند. کاربران می‌توانند با خیال راحت بدون ضربه زدن به نسخه شی یا شکستن جریان کار، به طرح جدید به‌روزرسانی شوند.

یک CustomResourceDefinition را حذف کنید

هنگامی که یک CustomResourceDefinition را حذف می کنید، سرور نقطه پایانی RESTful API را حذف می کند و تمام اشیاء سفارشی ذخیره شده در آن را حذف می کند.اگر بعداً همان CustomResourceDefinition را دوباره ایجاد کنید، خالی شروع می شود.

نتیجه

لطفاً توجه داشته باشید که منابع سفارشی به تنهایی به شما امکان ذخیره و بازیابی داده های ساخت یافته را می دهند. اگر فقط نیاز به ذخیره داده دارید، تعریف CRD تنها چیزی است که نیاز دارید. سپس با استفاده از یک مشتری REST، می توانید اشیاء ایجاد کنید یا اشیاء موجود از نوع معرفی شده را جستجو کنید.

هنگامی که یک منبع سفارشی را با یک کنترلر سفارشی ترکیب می کنید، عملکردهای جدیدی را اضافه می کنید.

همچنین توجه داشته باشید که همه کنترلرها نیازی به تعریف یک منبع سفارشی جدید ندارند. به عنوان مثال https://github.com/gianlucam76/claudie-sveltos-integration کنترل‌کننده‌ای است که Secrets Kubernetes ایجاد شده توسط Claudie را تماشا می‌کند و منبع SveltosCluster مربوطه را ایجاد می‌کند تا Sveltos بتواند به طور خودکار خوشه‌های ایجاد شده توسط Claudie را کشف کند.

یک نوع در یک گروه منحصر به فرد است. برای مثال سرویس نوعی در است هسته گروه و Knative serving.knative.dev گروه از آنجایی که ما در حال حاضر علاقه مند به ایجاد یک CustomResourceDefinition هستیم، به آن پاسخ مثبت دهید ایجاد منبع [y/n] و نه به ایجاد کنترلر [y/n]

kubectl api-resources

NAME                                SHORTNAMES   APIVERSION                                NAMESPACED   KIND
bindings                                         v1                                        true         Binding
configmaps                          cm           v1                                        true         ConfigMap
endpoints                           ep           v1                                        true         Endpoints
events                              ev           v1                                        true         Event
limitranges                         limits       v1                                        true         LimitRange
namespaces                          ns           v1                                        false        Namespace
nodes                               no           v1                                        false        Node
persistentvolumeclaims              pvc          v1                                        true         PersistentVolumeClaim
persistentvolumes                   pv           v1                                        false        PersistentVolume
pods                                po           v1                                        true         Pod
...

kubectl logs -n kube-system                         kube-controller-manager-sveltos-management-control-plane 
...
I0531 15:34:16.026590       1 controllermanager.go:759] "Started controller" controller="deployment-controller"

brew install kubebuilder
mkdir my-project
kubebuilder init --domain projectsveltos.io
kubebuilder create api --group app --version v1alpha1 --kind MyKind[^2]

    GroupVersion = schema.GroupVersion{Group: "app.projectsveltos.io", Version: "v1alpha1"}

package v1alpha1

import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!
// NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.

// MyKindSpec defines the desired state of MyKind
type MyKindSpec struct {
    // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
    // Important: Run "make" to regenerate code after modifying this file

    // Foo is an example field of MyKind. Edit mykind_types.go to remove/update
    Foo string `json:"foo,omitempty"`
}

// MyKindStatus defines the observed state of MyKind
type MyKindStatus struct {
    // INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
    // Important: Run "make" to regenerate code after modifying this file
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// MyKind is the Schema for the mykinds API
type MyKind struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   MyKindSpec   `json:"spec,omitempty"`
    Status MyKindStatus `json:"status,omitempty"`
}

...

//+kubebuilder:resource:path=cleaners,scope=Cluster

//+kubebuilder:resource:path=cleaners,scope=Namespaced

// +kubebuilder:default:=Delete
Action Action `json:"action,omitempty"`

// +optional
Transform string `json:"transform,omitempty"`

kubectl get customresourcedefinitions cleaners.apps.projectsveltos.io -o yaml

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: cleaners.apps.projectsveltos.io
...
status:
  acceptedNames:
    kind: Cleaner
    listKind: CleanerList
    plural: cleaners
    singular: cleaner
  conditions:
  - lastTransitionTime: "2024-05-31T12:32:39Z"
    message: no conflicts found
    reason: NoConflicts
    status: "True"
    type: NamesAccepted
  - lastTransitionTime: "2024-05-31T12:32:39Z"
    message: the initial names have been accepted
    reason: InitialNamesAccepted
    status: "True"
    type: Established
  storedVersions:
  - v1alpha1

//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Value is immutable"
Schedule string `json:"schedule"`

The Cleaner "list-pods-with-outdated-secret-data" is invalid: spec.schedule: Invalid value: "string": Value is immutable

//+kubebuilder:validation:XValidation:rule="size(self) >= size(oldSelf)",message="this list is append only"
ResourceSelectors []ResourceSelector `json:"resourceSelectors"`

The Cleaner "list-pods-with-outdated-secret-data" is invalid: spec.resourcePolicySet.resourceSelectors: Invalid value: "array": this list is append only

// Cleaner is the Schema for the cleaners API
type Cleaner struct { //+kubebuilder:validation:XValidation:rule=self.metadata.name.startsWith("my-prefix")

The Cleaner "list-pods-with-outdated-secret-data-2" is invalid: : Invalid value: "object": failed rule: self.metadata.name.startsWith("my-prefix")

// +kubebuilder:validation:Pattern=`^[A-Za-z_][A-Za-z0-9_]*$`
Description string `json:"description"`

//+kubebuilder:validation:Format="date-time"
TimeOfX string `json:"timeOfX"`

// +kubebuilder:validation:XValidation:rule=self.minReplicas <= self.replicas
type MyResourceSpec struct {
  Replicas int `json:"replicas"`

  MinReplicas int `json:"minReplicas"`

// HelmChartAction specifies action on an helm chart
// +kubebuilder:validation:Enum:=Install;Uninstall
type HelmChartAction string

The ClusterProfile "deploy-kyverno" is invalid: spec.helmCharts[0].helmChartAction: Unsupported value: "Deploy": supported values: "Install", "Uninstall"

// RepositoryURL is the URL helm chart repository
// +kubebuilder:validation:MinLength=1
RepositoryURL string `json:"repositoryURL"`

The ClusterProfile "deploy-kyverno" is invalid: spec.helmCharts[0].repositoryURL: Invalid value: "": spec.helmCharts[0].repositoryURL in body should be at least 1 chars long

// +kubebuilder:default:=100
// +kubebuilder:validation:Minimum=1
// +optional
Tier int32 `json:"tier,omitempty"`

// +listType=map
// +listMapKey=identifier
// +optional
TemplateResourceRefs []TemplateResourceRef `json:"templateResourceRefs,omitempty" patchStrategy:"merge" patchMergeKey:"identifier"`

type TemplateResourceRef struct {
  // Resource references a Kubernetes instance in the management
  // cluster to fetch and use during template instantiation.
  Resource corev1.ObjectReference `json:"resource"`

  // Identifier is how the resource will be referred to in the
  // template
  Identifier string `json:"identifier"`
}

//+kubebuilder:printcolumn:name="Ready",type="boolean",JSONPath=".status.ready",description="Indicates whether cluster is ready to be managed by sveltos"
//+kubebuilder:printcolumn:name="Version",type="string",JSONPath=".status.version",description="Kubernetes version associated with this Cluster"

kubectl get sveltoscluster -A
NAMESPACE   NAME   READY   VERSION
mgmt        mgmt   true    v1.29.1