التعرُّف على كيفية استدعاء وظائف Cloud Run التي تمت مصادقتها

1. مقدمة

نظرة عامة

وظائف Cloud Run هي حلّ حوسبة خفيف الوزن يتيح للمطوّرين إنشاء وظائف مستقلة ذات غرض واحد يمكن تشغيلها باستخدام بروتوكول HTTPS أو الاستجابة CloudEvents بدون الحاجة إلى إدارة خادم أو بيئة وقت التشغيل. اطّلِع على مزيد من المعلومات عن دوالّ Cloud Run في مشاركة المدوّنة.

هناك طريقتان رئيسيتان للتحكّم في عمليات استدعاء دوال Cloud Run: تأمين الوصول استنادًا إلى الهوية وتأمين الوصول باستخدام عناصر التحكّم في الوصول المستندة إلى الشبكة. يركز هذا الدرس التطبيقي حول الترميز على المنهج الأول ويرشدك إلى 3 سيناريوهات لتأمين الوصول استنادًا إلى الهوية لتشغيل دالة:

1. استخدام الرمز المميّز لهوية gcloud لاستدعاء دالة لأغراض التطوير والاختبار على الجهاز
2. انتحال هوية حساب خدمة عند التطوير والاختبار على الجهاز فقط لاستخدام بيانات الاعتماد نفسها المستخدَمة في قناة الإصدار العلني
3. استخدام مكتبات عملاء Google لمعالجة المصادقة مع Google Cloud APIs، مثلاً عندما تحتاج الخدمة إلى استدعاء دالة

ما ستتعرّف عليه

• كيفية ضبط المصادقة في إحدى وظائف Cloud Run والتأكّد من ضبط المصادقة بشكلٍ صحيح
• استدعاء دالة تمّت مصادقتها من بيئة تطوير محلية من خلال تقديم الرمز المميّز لهوية gcloud
• كيفية إنشاء حساب خدمة ومنحه الدور المناسب لاستدعاء دالة
• كيفية انتحال هوية خدمة من بيئة تطوير محلية لديها الأدوار المناسبة لاستدعاء وظيفة

2. الإعداد والمتطلبات

المتطلبات الأساسية

• أن تكون مسجِّلاً الدخول إلى Cloud Console
• سبق لك نشر دالة Cloud Run يتم تشغيلها من خلال HTTP. اطّلِع على مثال للبدء السريع.
• (اختياري) في السيناريو الثالث، يستخدم هذا الدرس التطبيقي حول الترميز Node.js وnpm كمثال، ولكن يمكنك استخدام أيّ وقت تشغيل متوافق مع مكتبات Google Auth client.

تفعيل Cloud Shell

1. من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة متوسطة تصف ما هي عليه، وإذا ظهرت لك شاشة متوسطة، انقر على Continue (متابعة).

من المفترض ألا تستغرق عملية توفير Cloud Shell والاتصال بها سوى بضع لحظات.

يتم تحميل هذا الجهاز الافتراضي مع جميع أدوات التطوير اللازمة. ويقدّم هذا الدليل دليلاً منزليًا دائمًا بسعة 5 غيغابايت ويتم تشغيله في Google Cloud، ما يُحسِّن بشكل كبير أداء الشبكة والمصادقة. يمكن تنفيذ الكثير من عملك في هذا الدليل التعليمي للترميز، إن لم يكن كلّه، باستخدام متصفّح.

بعد الربط بخدمة Cloud Shell، من المفترض أن تتأكّد من أنّه تمّت مصادقتك وأنّ المشروع مضبوط على رقم تعريف مشروعك.

2. شغِّل الأمر التالي في Cloud Shell لتأكيد مصادقتك:

gcloud auth list

مخرجات الأمر

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

ملاحظة: أداة سطر أوامر gcloud هي أداة سطر أوامر فعّالة وموحدة في Google Cloud. ويتم تثبيته مسبقًا في Cloud Shell. ستلاحظ دعمه للانتهاء من علامة التبويب. لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على أداة سطر أوامر gcloud.

3. شغِّل الأمر التالي في Cloud Shell للتأكّد من أنّ الأمر gcloud يعرف مشروعك:

gcloud config list project

مخرجات الأمر

[core]
project = <PROJECT_ID>

إذا لم يكن كذلك، يمكنك تعيينه من خلال هذا الأمر:

gcloud config set project <PROJECT_ID>

ناتج الأمر

Updated property [core/project].

ملاحظة: إذا كنت تُكمل هذا الدليل التعليمي خارج Cloud Shell، اتّبِع إعداد بيانات الاعتماد التلقائية للتطبيق.

3- إنشاء دالة Cloud Run تمّت مصادقتها واختبارها

يعني طلب المصادقة أنّه يجب أن يكون لدى المبدأ الذي يستدعي الدالة دور "مُشغِّل Cloud Run"، وإلا ستعرض الدالة خطأ 403 "محظور". سيوضّح لك هذا الدليل التعليمي حول الرموز البرمجية كيفية منح أدوار Invoker المناسبة لعنصر أساسي.

إعداد متغيّرات البيئة المحلية لأوامر gcloud المبسّطة

أولاً، عليك إنشاء بعض متغيّرات البيئة لتحسين سهولة قراءة أوامر gcloud المستخدَمة في هذا الدرس التطبيقي حول الترميز.

REGION=us-central1
PROJECT_ID=$(gcloud config get-value project)

إنشاء رمز المصدر للدالة

على الرغم من أنّ هذا الدليل التعليمي للترميز يستخدم Node.js، يمكنك استخدام أيّ وقت تشغيل متوافق مع مكتبات عملاء Google Auth.

أولاً، أنشئ دليلاً وانتقل إليه باستخدام الأمر cd.

mkdir auth-function-codelab && cd $_

ثم أنشئ ملف package.json.

touch package.json

echo '{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}
' > package.json

بعد ذلك، أنشئ ملف المصدر index.js.

touch index.js

echo 'const functions = require("@google-cloud/functions-framework");

functions.http("helloWorld", (req, res) => {
 res.send(`Hello ${req.query.name || req.body.name || "World"}!`);
});' > index.js

إنشاء الدالة التي تمّت مصادقتها

في ما يلي خطوات إنشاء دالة تمت مصادقتها لبيئة تشغيلNodejs20. ومع ذلك، يمكنك استخدام أي بيئة تشغيل متوافقة مع مكتبات برامج مصادقة Google.

FUNCTION_NAME=authenticated-function-codelab
ENTRY_POINT=helloWorld

لنشر دالة Cloud Run مباشرةً على Cloud Run، نفِّذ الأمر التالي:

gcloud beta run deploy $FUNCTION_NAME \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated

وبعد ذلك يمكنك حفظ الدالة URL كمتغير بيئي لاستخدامها لاحقًا.

FUNCTION_URL="$(gcloud run services describe $FUNCTION_NAME --region $REGION --format 'value(status.url)')"

إذا كنت تفضّل النشر كخدمة من الجيل الثاني من Cloud Functions، استخدِم الأمر التالي:

gcloud functions deploy nodejs-http-function \
  --gen2 \
  --runtime=nodejs20 \
  --region=$REGION \
  --source=. \
  --entry-point=helloWorld \
  --trigger-http \
  --no-allow-unauthenticated

ويمكنك بعد ذلك حفظ عنوان URL للدالة كمتغيّر بيئة لاستخدامه لاحقًا.

FUNCTION_URL="$(gcloud functions describe $FUNCTION_NAME --gen2 --region us-central1 --format='get(serviceConfig.uri)')"

تأكَّد من أنّ الدالة تتطلّب المصادقة من خلال محاولة استدعائها كمتصل مجهول.

ستستدعي الدالة بدون مصادقة للتأكّد من ظهور خطأ 403 المتوقّع.

من سطر الأوامر، شغِّل أمر curl التالي:

curl -i $FUNCTION_URL

ستظهر لك النتيجة التالية:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>403 Forbidden</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Forbidden</h1>
<h2>Your client does not have permission to get URL <code>/</code> from this server.</h2>
<h2></h2>
</body></html>

أنت الآن جاهز للاطّلاع على 3 سيناريوهات يمكنك من خلالها استدعاء الدالة من خلال تقديم المصادقة.

4. السيناريو 1: استخدام رمز تعريف الهوية gcloud

بصفتك مطوّرًا، ستحتاج إلى طريقة لاختبار الدالة أثناء تطويرها على الجهاز. في هذا القسم، ستُجري اختبارًا سريعًا للتحقّق من مصادقة الدالة بشكل صحيح باستخدام هويتك.

تأكَّد من أنّك تمّت مصادقة حسابك باستخدام gcloud من خلال تنفيذ الأمر التالي:

gcloud auth list

من المفترض أن يظهر لك نجم بجانب هويتك النشطة، على سبيل المثال:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

يمكنك العثور على مزيد من المعلومات حول إعداد gcloud init وgcloud auth login في المستندات.

بعد ذلك، استدعِ الدالة وقم بتمريرها إلى رمز هويتك.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token)"

ستظهر لك الآن النتيجة:

Hello World!

تحديد المشاكل وحلّها

إذا ظهرت لك رسالة الخطأ "403 محظور"، تأكَّد من أنّ هويتك تحمل دور "مرسل تشغيل السحابة الإلكترونية". يمكنك استخدام وحدة تحكّم إدارة الهوية وإمكانية الوصول للتحقّق من الأدوار الممنوحة لمستخدم أساسي.

على الرغم من أنّ استخدام الرمز المميّز للهوية هو طريقة سريعة لاختبار الدالة أثناء التطوير، سيحتاج المُرسِل إلى الدالة التي تمّت مصادقتها إلى الأدوار المناسبة، وإلا سيتلقّى المُرسِل خطأ 403 - "محظور".

يجب اتّباع مبدأ الحد الأدنى من الامتيازات من خلال الحد من عدد الهويات وحسابات الخدمات التي لها أدوار لتشغيل الدالة. في السيناريو التالي، ستتعرّف على كيفية إنشاء حساب خدمة جديد ومنحه الأدوار المناسبة لتشغيل الدالة.

5- السيناريو 2: انتحال هوية حساب خدمة

في هذا السيناريو، عليك انتحال هوية (أي الحصول على أذونات) حساب خدمة لاستدعاء دالة عند التطوير والاختبار على الجهاز. يمكنك اختبار وظائفك باستخدام بيانات الاعتماد نفسها المستخدَمة في قناة الإصدار العلني من خلال انتحال هوية حساب خدمة.

من خلال إجراء ذلك، لن تُثبت صحة الأدوار فحسب، بل ستلتزم أيضًا بمبدأ الحد الأدنى من الامتيازات من خلال عدم الحاجة إلى منح دور "مُشغِّل وظائف السحابة الإلكترونية" لهويات أخرى لأغراض الاختبار المحلي فقط.

لأغراض هذا الدليل التعليمي حول رموز البرامج، ستُنشئ حساب خدمة جديدًا لا يتضمّن سوى أدوار لتشغيل الدالة التي أنشأتها في هذا الدليل التعليمي.

إنشاء حساب خدمة جديد

أولاً، عليك إنشاء متغيّرَين إضافيَين للبيئة لتمثيل حسابات الخدمة المستخدَمة في أوامر gcloud.

SERVICE_ACCOUNT_NAME="invoke-functions-codelab"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

بعد ذلك، عليك إنشاء حساب الخدمة.

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Cloud Run function Authentication codelab"

امنح حساب الخدمة دور "مُشغِّل Cloud Run":

gcloud run services add-iam-policy-binding $FUNCTION_NAME \
  --region=us-central1  \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/run.invoker'

استدعاء الدالة من خلال انتحال هوية حساب الخدمة

ولتنفيذ ذلك، ستُنتحل هوية حساب الخدمة الذي تم إنشاؤه حديثًا من خلال الحصول على الرمز المميّز للمعرِّف.

إضافة الأدوار المطلوبة للتمثيل

للتنكر بصفتك حساب خدمة، يجب أن يكون لحساب المستخدم دور صانع الرموز المميّزة لحساب الخدمة (roles/iam.serviceAccountTokenCreator) لإنشاء رمز تعريف لحساب الخدمة.

يمكنك تشغيل الأوامر التالية لمنح حساب المستخدم النشط هذا الدور:

ACCOUNT_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")

gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT_ADDRESS  \
  --member user:$ACCOUNT_EMAIL \
  --role='roles/iam.serviceAccountTokenCreator'

استخدام الرمز المميّز للمعرّف لحساب الخدمة

انتظِر بضع دقائق حتى يتم نشر الأذونات. يمكنك الآن استدعاء الدالة من خلال تمرير رمز تعريف حساب الخدمة.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token --impersonate-service-account $SERVICE_ACCOUNT_ADDRESS)" 

وسيظهر لك ما يلي:

WARNING: This command is using service account impersonation. All API calls will be executed as [invoke-functions-codelab@<project-id>.iam.gserviceaccount.com].

Hello World!

6- السيناريو 3: استخدام مكتبات عملاء Google

في هذا الجزء الأخير من ورشة رموز البرامج، ستشغّل خدمة صغيرة على الجهاز لإنشاء رمز تعريف لحساب خدمة، ثم ستستدعي الدالة آليًا باستخدام مكتبات برامج Google Auth وبيانات الاعتماد التلقائية للتطبيق (ADC). يمكنك الاطّلاع على المزيد من المعلومات حول مكتبات برامج Google في القسم شرح لمكتبات العملاء في المستندات.

من المهم استخدام أداة ربط البيانات بشكل خاص عندما تريد كتابة وظائفك واختبارها على الجهاز (مثل الكمبيوتر المحمول أو Cloud Shell أو غير ذلك) أثناء التفاعل مع موارد Google Cloud الأخرى (مثل Cloud Storage وVision API وغير ذلك). في هذا المثال، ستتعرّف على كيفية جعل خدمة تستدعي دالة أخرى تتطلّب مصادقة. لمزيد من المعلومات عن ميزة "التطوير على الجهاز فقط" والتطوير على الجهاز، يُرجى الاطّلاع على مشاركة المدونة كيفية تطوير وظائف Cloud واختبارها على الجهاز فقط | مدونة Google Cloud.

تشغيل الأمر gcloud لانتحال هوية حساب خدمة

يعثر "أداة إدارة الاعتمادات" تلقائيًا على بيانات الاعتماد استنادًا إلى بيئة التطبيق، ويستخدم هذه البيانات للمصادقة على Google Cloud APIs. تسمح لك العلامة -impersonate-service-account بانتحال هوية حساب خدمة باستخدام هويته للمصادقة مع واجهات برمجة تطبيقات Google Cloud.

لانتحال هوية حساب خدمة، يمكنك تشغيل الأمر التالي:

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

يتم الآن تنفيذ أوامر gcloud باسم حساب الخدمة هذا بدلاً من هويتك.

إنشاء خدمة وتشغيلها لاستدعاء دالة تمّت مصادقتها

تتضمّن كل بيئة تشغيل مكتبة برامج "مصادقة Google" خاصة بها يمكنك تثبيتها. يرشدك هذا الدرس التطبيقي حول الترميز إلى كيفية إنشاء تطبيق Node.js وتشغيله على جهازك.

في ما يلي خطوات استخدام Node.js:

1. إنشاء دليل جديد

mkdir local-dev && cd $_

2. إنشاء تطبيق Node.js جديد

npm init -y

3. تثبيت مكتبة برامج Google Auth

npm install google-auth-library

4. إنشاء ملف index.js
5. استرجع عنوان URL لدالة Cloud Run التي ستضيفها إلى الرمز البرمجي في الخطوة التالية.

echo $FUNCTION_URL

6. أضِف الرمز التالي إلى index.js. احرص على تغيير متغيّر targetAudience إلى عنوان URL لوظيفة Cloud Run.

index.js

// Cloud Functions uses your function's url as the `targetAudience` value

const targetAudience = '<YOUR-CLOUD-RUN-FUNCTION-URL>';

// For Cloud Functions, endpoint(`url`) and `targetAudience` should be equal

const url = targetAudience;

const { GoogleAuth } = require('google-auth-library');
const auth = new GoogleAuth();

async function request() {
    console.info(`request ${url} with target audience ${targetAudience}`);

    // this call retrieves the ID token for the impersonated service account
    const client = await auth.getIdTokenClient(targetAudience);

    const res = await client.request({ url });
    console.info(res.data);
}

request().catch(err => {
    console.error(err.message);
    process.exitCode = 1;
});

7. تشغيل التطبيق

node index.js

وينبغي أن ترى "مرحبًا أيها العالم!"

تحديد المشاكل وحلّها

إذا ظهرت لك رسالة خطأ تفيد برفض الإذن "iam.serviceAccounts.getOpenIdToken" على المورد (أو قد لا يكون متوفّرًا)، يُرجى الانتظار بضع دقائق حتى يتم نشر دور "منشئ الرمز المميّز لحساب الخدمة".

إذا ظهر لك الخطأ "تعذّر جلب رمز التعريف في هذه البيئة، استخدِم GCE أو اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على ملف JSON لبيانات اعتماد حساب الخدمة"، قد يكون السبب أنّك نسيت تنفيذ الأمر

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

7- تهانينا!

تهانينا على إكمال دورة codelab.

ننصحك بمراجعة المستندات حول كيفية تأمين وظائف Cloud Run.

ننصحك أيضًا بقراءة مشاركة المدونة هذه حول التطوير على الجهاز المحلي باستخدام دوال Cloud Run للتعرّف على كيفية تطوير واختبار وظيفة Cloud Run في بيئة المطوّر المحلية.

المواضيع التي تناولناها

• كيفية ضبط المصادقة في إحدى وظائف Cloud Run والتأكّد من ضبط المصادقة بشكلٍ صحيح
• استدعاء دالة تمّت مصادقتها من بيئة تطوير محلية من خلال تقديم الرمز المميّز لهوية gcloud
• كيفية إنشاء حساب خدمة ومنحه الدور المناسب لاستدعاء دالة
• كيفية انتحال هوية خدمة من بيئة تطوير محلية تتضمّن الأدوار المناسبة لتشغيل دالة

8. تَنظيم

لتجنُّب الرسوم غير المقصودة (على سبيل المثال، إذا تمّ استدعاء دالة Cloud هذه بدون قصد أكثر من المساحة المخصّصة لك شهريًا لاستدعاء دالة Cloud Run في الفئة المجانية)، يمكنك إما حذف دالة Cloud أو حذف المشروع الذي أنشأته في الخطوة 2.

لإيقاف انتحال هوية حساب الخدمة، يمكنك إعادة تسجيل الدخول باستخدام هويتك:

gcloud auth application-default login

لحذف وظيفة Cloud Run، انتقِل إلى Cloud Console من خلال وظيفة Cloud Run على الرابط https://console.cloud.google.com/functions/ وتأكَّد من أنّ المشروع الذي أنشأته في الخطوة 2 هو المشروع المحدّد حاليًا.

اختَر my-authenticated-function التي تم نشرها سابقًا. بعد ذلك، انقر على حذف.

إذا اخترت حذف المشروع بأكمله، يمكنك الانتقال إلى https://console.cloud.google.com/cloud-resource-manager واختيار المشروع الذي أنشأته في الخطوة 2 ثم اختيار "حذف". في حال حذف المشروع، عليك تغيير المشاريع في حزمة تطوير البرامج (SDK) من Cloud. يمكنك عرض قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.