إعدادات الجلسة لـ s3_allow_*

إعدادات جلسة ClickHouse ضمن المجموعة المُولَّدة s3_allow_*.

هذه الإعدادات متاحة في system.settings، وهي مُولَّدة تلقائيًا من الشفرة المصدرية.

​

s3_allow_multipart_copy

السماح بالنسخ متعدد الأجزاء في S3.

​

s3_allow_parallel_part_upload

استخدم عدة خيوط تنفيذ لعملية الرفع متعدد الأجزاء إلى S3. قد يؤدي ذلك إلى زيادة طفيفة في استهلاك الذاكرة

​

s3_allow_server_credentials_in_user_queries

اسمح لوصول S3 الصادر من SQL المستخدم باستخدام بيانات اعتماد يديرها الخادم.

عند تعطيل هذا الإعداد (وهو الوضع الافتراضي)، لا يمكن لـ table functions ‏s3/s3Cluster، وengines ‏S3/S3Queue، وnamed collections الخاصة بـ S3، وتعريفات disk(type=s3, ...) الديناميكية، وBACKUP/RESTORE TO S3، وعمليات reads لبيانات جداول DataLake، وقواعد بيانات DataLakeCatalog ‏(Glue وBigLake) استنتاج بيانات الاعتماد من البيئة، أو metadata الخاصة بالـ instance ‏(IMDS)، أو IRSA، أو ECS، أو instance profile، أو SSO، أو ملفات AWS config/credentials، أو خدمة GCP OAuth metadata. ويُرفَض أي request يطلب أحد هذه المصادر التي يديرها الخادم (مثل use_environment_credentials = 1 أو http_client = gcp_oauth) من دون تقديم بيانات اعتماد صريحة قابلة للاستخدام، ويُعاد الخطأ ACCESS_DENIED. أما request الذي لا يطلب أيًا منها، فيُرسَل من دون توقيع (anonymous)، تمامًا كما لو تم تمرير NOSIGN.

يظل STS assume-role المستند إلى role_arn ‏(extra_credentials(role_arn = '...')) مسموحًا حتى عند تعطيل هذا الإعداد: إذ يجب أن يثق الدور المستهدف صراحةً بالهوية التي يعمل الخادم بموجبها، ولا توقّع requests الخاصة بـ S3 في الاستعلام سوى بيانات اعتماد الدور المفترض، لذا لا تُكشَف بيانات اعتماد الخادم نفسه للـ استعلام. وهذه هي الطريقة الموثقة لمنح ClickHouse Cloud وصولًا إلى bucket خاص. ويُفترَض الدور باستخدام المفاتيح الأساسية الخاصة بالـ استعلام عندما توفّر الاستعلام زوجًا كاملًا منها؛ وإلا فتوقّع هوية الخادم المتاحة من البيئة استدعاء STS AssumeRole. ولا تُستخدم مطلقًا المفاتيح الثابتة من config ‏<s3>/endpoint الخاص بالخادم أو من named collection كأساس STS لدور توفّره الاستعلام، كما أن role_arn الذي تمت تهيئته في config ‏<s3> الخاص بالخادم لا يُطبّق على استعلامات المستخدم مطلقًا. وتظل تعريفات disk(type=s3, role_arn=...) الديناميكية مشمولة بالقيد.

ويُحدَّد ما إذا كان request بلا بيانات اعتماد يطلب بيانات اعتماد من البيئة بواسطة use_environment_credentials. وتضبط named collections هذا الخيار افتراضيًا على 0، لذلك فإن collection التي لا تحدد سوى URL تقرأ بشكل anonymous. وتستخدم table functions ‏s3/s3Cluster وengines ‏S3/S3Queue القيمة الافتراضية المضمّنة (1) ما لم يضبط server config ‏<s3> خلاف ذلك؛ اضبط <s3><use_environment_credentials>0</use_environment_credentials></s3> لجعل reads بلا بيانات اعتماد فيها anonymous افتراضيًا أيضًا (وإلا فسيُرفَض مثل هذا request وسيتعيّن عليه استخدام NOSIGN). أما disks المعرّفة في server configuration فلا تتأثر، وتستمر افتراضيًا في استخدام بيانات اعتماد البيئة؛ بينما تخضع تعريفات disk(type = s3, ...) الديناميكية التي ينشئها المستخدم لهذا القيد (انظر أعلاه)، وتُرفَض عندما تعتمد على بيانات الاعتماد الافتراضية/المتاحة من البيئة.

يمنع هذا مستخدمًا authenticated من جعل الخادم يصل إلى S3 باستخدام بيانات اعتماده هو (بيانات الاعتماد المتاحة من البيئة). ولا تتأثر بيانات الاعتماد المقدَّمة صراحةً: فالمفاتيح الممرَّرة في الاستعلام، والمفاتيح الثابتة في named collection (المنشأة عبر SQL أو المعرَّفة في config)، والمفاتيح الموجودة في config ‏<s3> الخاص بالخادم، تظل كلها تعمل.

الطريقة الموصى بها لمنح استعلامات المستخدم وصولًا إلى S3 هي named collection تحتوي على بيانات اعتماد صريحة (أو NOSIGN من أجل public buckets): إذ تبقى المفاتيح خارج نص الاستعلام، ويُتحكَّم في استخدام كل collection عبر RBAC ‏(GRANT NAMED COLLECTION ON <name> TO <user>)، بحيث تمنح مستخدمين محددين buckets محددة بدلًا من كشف هوية الخادم نفسه.

النطاق (خارج النطاق عن قصد): هذا الإعداد يحظر فقط مصادر بيانات الاعتماد المتاحة من البيئة الخاصة بالخادم المذكورة أعلاه. وهو لا يحظر access_key_id/secret_access_key الثابتة التي يوفّرها المشغّل من config ‏<s3> الخاص بالخادم أو من named collection معرّفة في config: فهذه تُعامل على أنها بيانات اعتماد صريحة وتظل تعمل. لكن لاحظ أن مواد request في config مثل access_header أو مفاتيح التشفير server-side لا تُعامَل هنا، بمفردها، على أنها بيانات اعتماد: فالـ request الذي يحمل فقط مثل هذه المواد من دون زوج مفاتيح صريح (ومع القيمة الافتراضية use_environment_credentials = 1) سيظل مرفوضًا، لأنه لولا ذلك لرجع إلى بيانات الاعتماد المتاحة من البيئة الخاصة بالخادم. لذلك يجب أن توفّر مثل هذه endpoint أيضًا مفاتيح صريحة، أو NOSIGN، أو use_environment_credentials = 0، أو مخرج التجاوز المذكور أدناه.

قد يحتاج عميل إداري موثوق إلى بيانات اعتماد يديرها الخادم لإجراء عمليات مشروعة (على سبيل المثال، إرفاق جداول النظام على قرص s3_plain_rewritable عبر SQL). فعّل هذا الإعداد في جلسة أو profile الإعدادات الخاص بهذا العميل للسماح بذلك.

بالنسبة إلى BACKUP/RESTORE ... ON CLUSTER، تُنشر قيمة هذا الإعداد لدى البادئ إلى المضيفات الأخرى وتُستخدم فيها كما هي. تُشغّل تلك المضيفات المتابعة لكل مضيف من العملية عبر قائمة انتظار DDL الموزعة، دون مستخدم البادئ افتراضيًا، ولذلك كانت ستقيّم القيد خلاف ذلك وفقًا لملفها التعريفي الافتراضي؛ لكن تُحفظ قيمة البادئ بدلًا من ذلك، لأنه فتح بالفعل وجهة النسخ الاحتياطي نفسها ضمن إعداداته المقيّدة الخاصة. يظل قيد readonly على البادئ مطبّقًا (فلا يمكن لبادئ غير موثوق تمكين الإعداد لنسخته الاحتياطية الخاصة على العنقود)، لذا لا يضعف هذا القيد.

متانة جداول S3 وS3Queue الدائمة: إن تمكين هذا الخيار على مستوى جلسة أو profile فقط لا يظل ساريًا بعد إعادة التشغيل. فعندما يعيد الخادم تحميل جدول من هذا النوع من تعريفه المخزَّن (عند بدء التشغيل أو RESTORE)، فإنه يعيد إنشاء عميل S3 ويعيد تطبيق القيد باستخدام سياق بدء التشغيل. لذلك، فإن الجدول الذي كان يعتمد على بيانات اعتماد يديرها الخادم، وتم إنشاؤه فقط ضمن جلسة/profile مع s3_allow_server_credentials_in_user_queries = 1، يُنشأ بنجاح لكنه يصبح غير قابل للوصول بعد إعادة التشغيل (يبقى الجدول كما هو، لكن تفشل الاستعلامات عليه إلى أن تُحلّ بيانات اعتماده مرة أخرى إلى مصدر مسموح به). ومع ذلك، يواصل الخادم نفسه بدء التشغيل. امنح هذه الجداول بيانات اعتماد صريحة لضمان وصول دائم؛ وبدلًا من ذلك، فإن تمكين هذا الإعداد على مستوى الخادم بأكمله يُبقيها قابلة للتحميل بعد إعادة التشغيل، لكن على حساب تخفيف هذا القيد على جميع عمليات إعادة التحميل.

ولإبقائه معطّلًا للمستخدمين غير الموثوقين، ثبّته في ملفهم التعريفي عبر تعيين القيمة صراحةً إلى 0 ووضع علامة readonly عليه:

<profiles>
    <untrusted>
        <!-- The explicit value is required: a `readonly` constraint alone only blocks direct changes,
             but `compatibility` with a version before this setting was introduced would otherwise
             restore the old (allowing) default. Setting the value explicitly defeats `compatibility`. -->
        <s3_allow_server_credentials_in_user_queries>0</s3_allow_server_credentials_in_user_queries>
        <constraints>
            <s3_allow_server_credentials_in_user_queries>
                <readonly/>
            </s3_allow_server_credentials_in_user_queries>
        </constraints>
    </untrusted>
</profiles>

هذا الإعداد لا يؤثر في clickhouse-local، حيث يكون المستخدم هو المشغّل.

تشمل هذه الحالة أيضًا قواعد بيانات DataLakeCatalog ‏(Glue وBigLake)، مع اختلاف واحد. إذ يُنشأ كائن الكتالوج مرة واحدة ويُشارك بين جميع مستخدمي قاعدة البيانات، لذلك لا يمكن قراءة القيمة لكل استعلام؛ بل تُلتقط من الجلسة التي تُنفّذ CREATE DATABASE (أو من مستخدم يُنفّذ ATTACH DATABASE). قد تستخدم قاعدة بيانات أُنشئت عندما يكون هذا الإعداد مفعّلًا (على سبيل المثال ضمن جلسة أو ملف تعريف موثوقين) بيانات الاعتماد المتاحة من البيئة الخاصة بالخادم لكتالوجها، وعندئذٍ يشترك فيها كل مستخدم يستطيع الاستعلام عن تلك القاعدة؛ أما إذا أُنشئت وفق الإعداد الافتراضي، فسيظل الكتالوج مقيّدًا على الجميع بغض النظر عمّن يُجري الاستعلام عليه. وعندما يحمّل الخادم قاعدة بيانات سبق إنشاؤها من بياناته الوصفية الخاصة به (عند بدء التشغيل أو RESTORE)، يُعاد تطبيق القيد باستخدام سياق بدء التشغيل، تمامًا كما في جداول S3/S3Queue الدائمة: فالكتالوج الذي يحلّ بيانات اعتماد يديرها الخادم يظل غير متاح، وتصبح قاعدة البيانات غير قابلة للوصول بعد إعادة التشغيل (مع ذلك يستمر الخادم في العمل؛ وتُحمَّل قاعدة البيانات مع كتالوج غير متاح وفق s3_load_table_anonymously_if_credentials_restricted، وتُبلغ الاستعلامات عن هذا القيد). أما إذا زُوّد الكتالوج ببيانات اعتماد صريحة (Glue: ‏aws_access_key_id وaws_secret_access_key؛ BigLake: ثلاثية Google ADC كاملة)، فإنه يعمل في جميع الحالات ويظل صالحًا عبر إعادة التشغيل.