vpc-cni وkube-proxy وcoredns وaws-ebs-csi-driver)، إلى جانب أدوار IAM ومفاتيح KMS والوسوم؛ أما existing-eks فلا يثبّت إلا الإضافات التي تحددها في install_addons. وعند استهداف Helm، يثبّت الأمر clicklink clctl init بعد ذلك طبقة المنصة اعتمادًا على المخرجات وحزمة المنصة، وتشمل: Karpenter، ووحدة تحكم AWS Load Balancer، وStorageClass، والمكوّنات ذات الإصدارات المثبّتة (راجع تهيئة الموصل من مخرجات Terraform). تتطلب الجذور Terraform 1.10+ أو OpenTofu 1.12+، ومزوّد AWS بالإصدار ~> 6.0. ويمكن استخدام tofu بدلًا من terraform في جميع الأوامر الواردة في هذه الصفحة.
قبل أن تبدأ
ستحتاج إلى ما يلي:- Terraform 1.10+ أو OpenTofu 1.12+، إلى جانب مزوّد AWS بالإصدار
~> 6.0. - هوية AWS تملك صلاحية إنشاء الموارد التي يتطلبها الجذر الذي اخترته وتعديلها.
- الأداة
curl، وأداة SHA-256 (sha256sumأوshasum)، والأداةcosign، وذلك لتنزيل أرشيف الإصدار والتحقق منه. - من خطوة التسجيل: قيمة
chart_repository_arnالتي يتطلبها كل جذر، إضافةً إلى نقطة نهاية الموصّل، ورمز التسجيل، وحزمة المنصة اللازمة لخطوة التسليم عبرinitفي النهاية.
production وexisting-vpc، حدّد مسبقًا كيف سيصل الجهاز الذي يشغّل clicklink clctl init وkubectl إلى واجهة برمجة تطبيقات EKS الخاصة، كأن يكون ذلك عبر شبكة VPN، أو مضيف bastion، أو شبكة مقترنة، أو إعادة توجيه منفذ عبر SSM.
اختر المجلد الجذري لـ Terraform المناسب لبيئتك
تُنتج الجذور الأربعة جميعها مُخرَجات
يخفّف
تمتد شبكة VPC عبر ثلاث مناطق (
لا يُعدِّل أيٌّ من الجذرين ما لم يُنشئه: جداول التوجيه، وبوابات NAT، ونقاط النهاية، وقواعد مجموعات الأمان، ومجموعات العقد، وقوالب الإطلاق، وتهيئة العنقود، ومفاتيح KMS. ويضع كلاهما وسمَي
clicklink نفسها، وتبقى عملية التسليم إلى clicklink clctl init واحدة أيًّا كان الجذر الذي تطبّقه.minimal
يخفّف minimal من متطلبات نقطة النهاية العامة، ونقاط نهاية الواجهات، وسجلات التدفق، ومدة الاحتفاظ بالسجلات، وحجم مجمّع العُقد الخاص بالنظام. وكل متغير مخفَّف موجود في كلا الجذرين بالاسم نفسه، لذا فإن رفع أحدها إلى قيمته في بيئة الإنتاج لا يتطلب سوى تعديل في terraform.tfvars ثم إعادة التطبيق. أما منطقة التوفر الوحيدة لعبء العمل وغياب مفاتيح KMS فهما أمران ثابتان: إذ لا يمكن للشبكات الفرعية تغيير منطقتها، ولا يحتوي الجذر على متغير لتشفير Secret في EKS. ولمعالجة ذلك، يجب تطبيق production بوصفه عنقودًا جديدًا.production
تمتد شبكة VPC عبر ثلاث مناطق (availability_zone_count، من 2 إلى 4) مع شبكة فرعية خاصة /19 وأخرى عامة /21 لكل منطقة، وبوابة NAT واحدة لكل منطقة، ونقطة نهاية بوابة S3، ونقاط نهاية من نوع interface لكل من ECR وSTS وEKS وEC2 وCloudWatch Logs وSSM وSQS وKMS وELB، بالإضافة إلى سجلات تدفق VPC. يتضمن عنقود EKS نقطة نهاية خاصة لواجهة برمجة التطبيقات، ومصادقة قائمة على access entries، وجميع أنواع سجلات طبقة التحكم ضمن مجموعة سجلات تابعة للوحدة الجذرية، وكائنات Secret مشفّرة بمفتاح KMS يديره العميل. يحصل العنقود على الإضافات المُدارة vpc-cni وkube-proxy وcoredns وaws-ebs-csi-driver، ومجموعة عقد نظام واحدة غير موسومة بـ taint وتحمل الوسم clickhouseGroup=system (من عقدتين إلى أربع عقد من نوع m7g.large افتراضيًا). كما تُنشئ الوحدة الجذرية موارد IAM الخاصة بـ Karpenter مع قائمة انتظار لأحداث المقاطعة ووسوم karpenter.sh/discovery، وأدوار IRSA لوحدة تحكم AWS Load Balancer ولمنفّذ الموصل، ومفاتيح KMS لوحدات تخزين EBS ولحاويات التخزين الكائني.existing-vpc وexisting-eks
لا يُعدِّل أيٌّ من الجذرين ما لم يُنشئه: جداول التوجيه، وبوابات NAT، ونقاط النهاية، وقواعد مجموعات الأمان، ومجموعات العقد، وقوالب الإطلاق، وتهيئة العنقود، ومفاتيح KMS. ويضع كلاهما وسمَي karpenter.sh/discovery=<cluster_name> وkubernetes.io/role/internal-elb=1 على الشبكات الفرعية الخاصة؛ كما يضع existing-vpc الوسم kubernetes.io/role/elb=1 على الشبكات الفرعية العامة، ويضع existing-eks وسمًا على مجموعة أمان العنقود.في حالة existing-vpc، يجب أن تتوفّر شبكة VPC مسبقًا على ما يلي:- تفعيل دعم DNS وأسماء المضيفين في DNS.
- من شبكتين إلى أربع شبكات فرعية خاصة موزعة على منطقتَي توافر على الأقل، مع تعطيل
map_public_ip_on_launch، وتوجيه حركة المرور إلى NAT gateway أو إلى نقاط نهاية من نوع الواجهة (interface endpoints) لخدمات ECR وSTS وEKS وEC2 وCloudWatch Logs وSSM وSQS وKMS وELB. أضف نقطة نهاية من نوع بوابة (gateway endpoint) لخدمة S3، وإلا فستمر حركة مرور التخزين الكائني عبر بوابات NAT. - لا تلزم الشبكات الفرعية العامة إلا إذا أردت موازنات أحمال متاحة للوصول من الإنترنت. اترك
public_subnet_idsفارغًا إذا لم تتضمن شبكة VPC طبقة عامة.
existing-eks، يجب أن يتوفر في العنقود مسبقًا ما يلي:- Kubernetes 1.34 أو أحدث.
- وضع المصادقة
APIأوAPI_AND_CONFIG_MAP. وفي حال كان العنقود يستخدمCONFIG_MAP، تعرض الخطة أمر التبديل. - مزوّد IAM OIDC لجهة الإصدار (issuer) الخاصة بالعنقود.
- شبكات فرعية خاصة في منطقتي توافر على الأقل، مع إمكانية الوصول الصادر إلى واجهات برمجة تطبيقات AWS عبر NAT أو نقاط نهاية الواجهة (interface endpoints). تستنتج الوحدة الجذرية هذه الشبكات افتراضيًا من الشبكات الفرعية للعنقود، مستبعدةً أي شبكة يصل جدول توجيهها إلى بوابة إنترنت. عيّن
private_subnet_idsإذا كانت الشبكات الفرعية للعنقود من نوع/28ومخصصة لطبقة التحكم فقط، أو إذا كان ينبغي وضع العقد في شبكات فرعية أخرى. - ألا يكون Karpenter مثبّتًا؛ إذ تُنشئ هذه الوحدة الجذرية موارد IAM الخاصة بـ Karpenter وقائمة انتظار المقاطعات. وتحمل قائمة الانتظار الاسم
<cluster_name>-clicklink، لذا لا يمكن أن تتعارض مع قائمة متبقية من تثبيت سابق لـ Karpenter أُزيل. - عقد نظام خالية من الـ taints وتحمل الوسوم المحددة في
system_node_selector(والقيمة الافتراضية هيclickhouseGroup=system). لا تُنشئ هذه الوحدة الجذرية أي مجموعة عقد.
terraform plan إذا كان أيٌّ من هذه العناصر مفقودًا.إذا كانت إحدى الإضافات المدرجة في install_addons مثبّتة بالفعل وتعمل كتثبيت مُدار ذاتيًا، فسيُرجع EKS الخطأ Conflicts found when trying to apply. اضبط addon_resolve_conflicts_on_create = "OVERWRITE" لتتولى الإضافة المُدارة إدارتها بدلًا منه، أو احذفها من install_addons.نزّل أرشيف إصدار Terraform وتحقّق من سلامته
تُوزَّع الجذور في أرشيف واحد لكل إصدار، ويتبع رقم إصداره إصدار الملف التنفيذي تحقّق من التوقيع باستخدام cosign قبل استخراج الملفات:ثم فُكَّ ضغطه:يُستخرج الأرشيف إلى دليل واحد يضم
clicklink. نزِّل أرشيف الإصدار الحالي مع قيمة التحقق الخاصة به وحزمة cosign:aws/production وaws/minimal وaws/existing-vpc وaws/existing-eks وaws/modules. وتشير وحدات الجذر إلى الوحدات عبر المسار ../modules، لذا احتفظ بالشجرة المستخرجة كاملةً ولا تنسخ أحد الجذور منها بمعزل عنها. قد تعرض ملفات README الخاصة بالجذور في الأرشيف خطوة التسليم عبر init دون الخيار --platform-bundle؛ غير أن الأمر المدعوم هو الوارد في تهيئة الموصل من مخرجات Terraform.هيّئ الجذر المحدد وطبّقه
من الدليل الجذري، انسخ ملف المتغيرات النموذجي واملأ قيمه:يتطلب كل جذر تحديد لا يحتوي الأرشيف على ملف قفل للمزوّدين، لكن الأمر
region وcluster_name وchart_repository_arn. يحدد cluster_name اسم العنقود، ويُستخدم بادئةً لاسم كل مورد، كما يمثل قيمة الوسم المستخدمة في الاكتشاف. في production وminimal وexisting-vpc يتكون من 3 إلى 32 محرفًا من الأحرف الصغيرة والأرقام والشرطات، على أن يبدأ بحرف ولا ينتهي بشرطة. أما في existing-eks فيأخذ اسم العنقود الذي تشغّله بالفعل، بحد أقصى 32 محرفًا. ويشير chart_repository_arn إلى مستودع ECR الخاص بمخطط عنقود ClickHouse، والذي يزوّدك به فريق حسابك عند التسجيل. كما تتطلب الجذور التي تُنشئ عنقودًا تحديد cluster_admin_principal_arns، وهي الجهات التي تُمنح صلاحيات مدير العنقود عبر عناصر الوصول في EKS. يجب أن تكون الهوية التي تشغّل الجذر ضمن هذه القائمة، وإلا فلن تتمكن من الوصول إلى العنقود لاحقًا، إذ لا يحصل منشئ العنقود على أي وصول ضمني. وفيما يلي متطلبات كل جذر:- يتطلب
minimalتحديدendpoint_public_access_cidrs، وهي قائمة السماح لعناوين IPv4 الخاصة بنقطة نهاية واجهة برمجة التطبيقات العامة. يجب أن تكون الشبكة التي تشغّل منهاinitوkubectlضمن هذه القائمة. يُرفض النطاق/0ما لم يُضبطallow_public_endpoint_from_anywhere = true. أما عند ضبطendpoint_public_access = falseفيمكن ترك القائمة فارغة، وتصبح نقطة النهاية خاصة فقط، كما هو الحال فيproduction. - يتطلب
existing-vpcتحديدvpc_idوprivate_subnet_ids. أماpublic_subnet_idsفهو اختياري، ويُستخدم لموازنات التحميل المكشوفة على الإنترنت. - لا يتطلب
existing-eksأي متغيرات إضافية. يحددinstall_addonsالإضافات المُدارة غير المتوفرة في العنقود، ويوفرebs_kms_key_arnمفتاحًا لوحدات تخزين الخدمة.
terraform providers lock ينشئه لك لتثبّته في نسختك. تُخزَّن الحالة محليًا افتراضيًا، ويتضمن الملف versions.tf كتلة backend "s3" مُعلَّقة توضّح شكل الحالة المشتركة.نقاط نهاية واجهة برمجة التطبيقات في
production وexisting-vpc خاصة. لذا شغّل init وkubectl من داخل شبكة VPC (عبر إعادة توجيه منفذ باستخدام SSM إلى عقدة نظام، أو عبر مضيف bastion، أو شبكة VPN، أو شبكة مقترنة)، أو فعّل الوصول العام بضبط endpoint_public_access = true مع تحديد قائمة سماح في endpoint_public_access_cidrs.هيّئ الموصل باستخدام مخرجات Terraform
صدِّر المخرجات، ثم مرِّرها إلى لا تدعم الجذور سوى هدف Helm. فعلى جهاز افتراضي (
init مع حزمة المنصة، على أن يتم ذلك من جهاز يشير سياق kube فيه إلى العنقود الجديد:--target systemd) يرفض init الخيار --platform-bundle، ولا يثبّت clicklink clctl platform approve --bundle إلا المكونات المثبّتة الإصدار، فيبقى العنقود بلا أي مزوّد للعُقد. لا تستخدم --target systemd إلا للموصلات التي تسجّل ClickHouse تشغّله بنفسك؛ فهو غير مدعوم مع هذه الجذور.يثبّت --platform-bundle ما لا تتضمنه الجذور: Karpenter مع EC2NodeClass ومجموعتَي العُقد clickhouse-server وclickhouse-keeper، ووحدة تحكم AWS Load Balancer، وفئة التخزين gp3-encrypted (مشفّرة بمفتاح EBS إن تضمّنته المخرجات)، ومكونات المنصة التي تثبّت الحزمة إصداراتها: وحدة تحكم اللقطات، وClickHouse operator، وجامعات المراقبة. والحزمة هي بيان المنصة الذي يولّده ClickHouse Cloud لبيئتك؛ يسلّمها إليك فريق حسابك أثناء الإعداد الأولي، ويحدّد قسم cluster: فيها إصدارات Karpenter ووحدة تحكم موازن التحميل. تتطلب هذه العلامة --target helm و--managed و--from-terraform. يُترك أي مكوّن موجود مسبقًا على حاله، لذا يمكن إعادة تشغيل الأمر بأمان، ويطبع init تقريرًا بما ثبّته وما تخطّاه وسبب ذلك. أما من دون هذه العلامة، فيسجّل init الموصل دون أن يثبّت أيًّا من هذه المكونات، ولا يستطيع العنقود تشغيل أي خدمة قبل تثبيتها. وتُحدِّث تحديثات المنصة اللاحقة وحدةَ تحكم اللقطات والمشغّل والجامعات؛ بينما يبقى Karpenter ووحدة تحكم موازن التحميل وفئة التخزين كما ثبّتها init.يقبل --from-terraform إما المستند الكامل الذي يطبعه terraform output -json أو الكائن المجرّد الناتج عن terraform output -json clicklink. يتضمن الإخراج clicklink هوية العنقود (account_id وregion وcluster_name وcluster_endpoint وcluster_ca)، ومزوّد OIDC، ومساحة أسماء الموصل، ودور IAM الخاص بالمنفّذ (executor_role_arn)، ومفتاح EBS، ودور عُقد Karpenter وطابوره، ودور وحدة تحكم موازن التحميل، وsystem_node_selector. يقرأ init هوية العنقود ومساحة أسماء الموصل من الملف، ويعيّن executor_role_arn تعليقًا توضيحيًا لـ IRSA على ServiceAccount pcm-executor الخاص بالموصل، ويطبّق محدِّد العُقد على حاويات الموصل. ولا تتشارك الخدمات المُدارة هذا الدور: إذ ينشئ clicklink clctl executor prepare دورًا مستقلًا لكل خدمة (CH-S3-<service>-<region>-00-Role افتراضيًا)، يُربط بالخدمة عند إنشائها؛ راجع نموذج الامتيازات.يرفض init أي علامة مثل --cluster-name أو --target-namespace تتعارض مع الملف، ويذكر كلتا القيمتين. احذف العلامة أو صحّح المخرجات. كما يرفض أي سياق kube لا يكون خادم API فيه هو cluster_endpoint، أو يشير معرّف EKS ARN فيه إلى عنقود آخر. ويحتوي الإخراج على الحقل schema، وقيمته حاليًا 1، ويرفض clctl أي ملف بقيمة schema لا يدعمها.أما بقية خطوات التسجيل فتتبع المسار القياسي الموضّح في الإعداد الأولي.مفاتيح KMS والأذونات المطلوبة
ينشئ كلٌّ منproduction وexisting-vpc ثلاثة مفاتيح KMS يديرها العميل مع تفعيل التدوير، وذلك لكائنات Secret في EKS ووحدات تخزين EBS وحاويات التخزين الكائني، ما لم تمرّر معرّفات ARN في kms. أما existing-eks فينشئ مفتاح التخزين ما لم تضبط storage_kms_key_arn، ويقبل ebs_kms_key_arn لوحدات تخزين الخدمات دون أن ينشئ مفتاحًا لها. ولا ينشئ minimal أي مفتاح؛ وفي غياب storage_kms_key_arn تظل حاوياته معتمدةً على SSE-S3. ويتضمّن كل مفتاح يُنشأ عبارةً واحدة خاصة بجذر الحساب تفوّض صلاحية الوصول إلى IAM. أما المفتاح الذي توفّره بنفسك، فيحتاج إلى التفويض نفسه، أو إلى الأذونات التالية في سياسة المفتاح الخاصة به:
تُرفق الوحدات الجذرية سياسات دور IAM لمفتاحَي كائنات Secret في EKS وEBS في كلتا الحالتين، كما تُرفق سياسة مفتاح التخزين الخاصة بالمنفّذ كلما احتوت الوحدة الجذرية على مفتاح تخزين؛ في حين يتولّى الأمر
executor prepare إرفاق سياسة دور كل خدمة. أما وحدات التخزين الجذرية لعُقد النظام، فتحتوي على الصور وسجلات kubelet، لا على بيانات الخدمات، وتستخدم مفتاح EBS الافتراضي للحساب.
إزالة البنية التحتية المُدارة بواسطة Terraform
يزيل الأمرterraform destroy كل ما أنشأته الوحدة الجذرية. وتدخل مفاتيح KMS المُنشأة فترة حذف مدتها 30 يومًا. أما مجموعات السجلات فتُحذف مع السجلات المحفوظة فيها، لذا صدِّر ما تحتاج إليه أولًا. ولا تُدرج المثيلات التي أطلقها Karpenter ولا وحدات التخزين التي أنشأها ClickHouse Operator ضمن حالة Terraform؛ لذا احذف خدماتك وأزل تثبيت Karpenter أولًا، وإلا فسيفشل حذف شبكة VPC ودور العقدة.
تُبقي الوحدة existing-eks العنقود كما هو، وتزيل الأدوار وقائمة انتظار المقاطعات وقواعدها وإدخال الوصول والوسوم التي أضافتها. أما الإضافات vpc-cni وkube-proxy وcoredns التي ثبّتتها فتُحرَّر من إدارة EKS، وتستمر وحدات pod التابعة لها في العمل. وإذا كانت قد ثبّتت إضافة مشغّل EBS CSI، فإنها تُزال مع الوحدة الجذرية، لأن دور IRSA الخاص بها يُحذف أيضًا. للإبقاء على المشغّل، أعد إنشاء الإضافة باستخدام دورك الخاص قبل تنفيذ الإزالة.
تزيل عملية الإزالة جميع الوسوم التي أضافتها هذه الوحدات الجذرية، بما في ذلك الوسم kubernetes.io/role/internal-elb حتى لو كان موجودًا قبل الوحدة الجذرية، لأن aws_ec2_tag يتولى ملكية الوسم الموجود مسبقًا. للإبقاء على هذه الوسوم، اضبط manage_subnet_tags = false (في existing-vpc) أو manage_discovery_tags = false (في existing-eks) وطبّق التغييرات قبل الإزالة، أو نفّذ terraform state rm على موارد aws_ec2_tag.