From b08deba46127cac26a32ad626a00b27fb4c700c5 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 19 Feb 2025 11:04:34 -0500 Subject: [PATCH 1/7] DOCSP-47690: aws lambda tutorial --- .vscode/settings.json | 6 ++ source/aws-lambda.txt | 184 +++++++++++++++++++++++++++++++++ source/index.txt | 9 +- source/tutorial/aws-lambda.txt | 153 --------------------------- 4 files changed, 198 insertions(+), 154 deletions(-) create mode 100644 .vscode/settings.json create mode 100644 source/aws-lambda.txt delete mode 100644 source/tutorial/aws-lambda.txt diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..6d4f70d8 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,6 @@ +{ + "cSpell.words": [ + "Bref", + "guilabel" + ] +} diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt new file mode 100644 index 00000000..73000a1c --- /dev/null +++ b/source/aws-lambda.txt @@ -0,0 +1,184 @@ +.. _php-aws-lambda: + +==================== +Deploy to AWS Lambda +==================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: serverless, deployment, code example, live + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the tool `Bref +`__ to deploy serverless PHP applications on AWS +Lambda. This guide demonstrates how to deploy a PHP application built by +using the {+library-short+} and connect to an Atlas cluster by using AWS +IAM authentication. + +Before You Get Started +---------------------- + +Before you can deploy to AWS Lambda by using Bref, you must set up the +following components: + +- AWS account and access keys +- `Serverless Framework `__ + +The `Setup `__ tutorial in the Bref +documentation describes how to prepare these components. + +Install Dependencies +-------------------- + +Bref uses `Lambda layers +`__ to +provide the PHP runtime. The ``bref`` layer is compiled with PHP and a +few extensions. You can install extensions, such as ``mongodb``, +in other layers. + +The following commands create a new project directory and install the +MongoDB and Bref dependencies: + +.. code-block:: bash + + mkdir bref-mongodb-app && cd bref-mongodb-app + composer init + composer require bref/bref bref/extra-php-extensions mongodb/mongodb + +Then, initialize the serverless configuration by using the ``bref`` +command: + +.. code-block:: bash + + vendor/bin/bref init + +After the commands complete, your project contains the following files: + +- ``composer.json``: Lists PHP dependencies installed in the ``vendor`` directory +- ``index.php``: Defines a sample webpage +- ``serverless.yml``: Configures the deployment + +Deploy the Sample Application +----------------------------- + +To validate your setup, try to deploy the default application. The +following command deploys the application and returns a URL that renders +a webpage that shows the Bref logo: + +.. code-block:: bash + + serverless deploy + +Add the MongoDB Extension to Your Configuration +----------------------------------------------- + +After you initialize the project, you can add the ``mongodb`` extension. +Locate the ``Serverless config`` name in the list of extensions provided +by the `bref/extra-php-extension +`__ package. + +Add it to the ``layers`` of the function in the ``serverless.yaml`` +file, as shown in the following code: + +.. code-block:: yaml + + plugins: + - ./vendor/bref/bref + - ./vendor/bref/extra-php-extensions # Adds the extra Serverless plugin + + functions: + api: + handler: index.php + runtime: php-83-fpm + layers: + - ${bref-extra:mongodb-php-81} # Adds the MongoDB layer + +Customize the Sample Application +-------------------------------- + +This step explains how to create a web page that list planets from the +Atlas :atlas:`sample data `. Replace the contents of +``index.php`` with the following code: + +.. literalinclude:: /examples/aws-lambda/index.php + :language: php + +Redeploy the application with the new ``index.php`` by running the +following command: + +.. code-block:: bash + + serverless deploy + +The application page displays an error message because the ``MONGODB_URI`` +environment variable is not set.The following section explains how to +set your connection string as an environment variable. + +Set AWS Credentials +------------------- + +Atlas supports passwordless authentication when using AWS credentials. +In any Lambda function, AWS sets environment variables that contain the +access token and secret token for the role assigned to deploy the function. + +The following steps demonstrate how to set the role in your Atlas +cluster: + +1. Open the Lambda function in the AWS console. +#. Enter :guilabel:`Configuration > Permission`, then copy the :guilabel:`Role name`. +#. Add this role to your Atlas cluster in the :guilabel:`Database + Access` section. Select the :guilabel:`AWS IAM` authentication method + and set the built-in role ``Read and write any database``. + +To learn how to set up unified AWS access, see :atlas:`Set Up Unified +AWS Access ` in the Atlas documentation. + +After you configure the permissions, the Lambda function is allowed to access +your Atlas cluster. Next, configure your application to use the Atlas endpoint. + +Access to Atlas clusters is also restricted by IP address. Since the +range of IP addresses that comes from AWS is very wide, you can allow +access from everywhere. To learn how to allow universal access, see +:atlas:`Configure IP Access List Entries ` in +the Atlas documentation. + +.. note:: + + Using VPC Peering is recommended in order to isolate your Atlas + cluster from the internet. This requires the Lambda function to be + deployed in this AWS VPC. + +Next, copy your connection string and remove the ``:`` section, as your credentials are read from environment variables. + +Update the ``serverless.yml`` file in your project to set the +environment variable ``MONGODB_URI`` to your connection string: + +.. code-block:: yaml + + provider: + environment: + MONGODB_URI: "" + +Deploy Your Application +----------------------- + +Finally, deploy with the new configuration: + +.. code-block:: bash + + serverless deploy + +After deployment completes, you can access the URL and see the +list of planets from your collection. diff --git a/source/index.txt b/source/index.txt index d1df02fa..3274f5db 100644 --- a/source/index.txt +++ b/source/index.txt @@ -22,6 +22,7 @@ MongoDB PHP Library Monitor Your Application Security Specialized Data Formats + Deploy to AWS Lambda Compatibility What's New Upgrade @@ -111,6 +112,12 @@ Specialized Data Formats Learn how to work with specialized data formats and custom types in the :ref:`php-data-formats` section. +Deploy to AWS Lambda +-------------------- + +Learn how to deploy a PHP application on AWS Lambda by using Bref in the +:ref:`php-aws-lambda` section. + Compatibility ------------- @@ -134,4 +141,4 @@ FAQ --- See answers to commonly asked questions about the {+library-short+} in the -the :ref:`php-faq` section. \ No newline at end of file +the :ref:`php-faq` section. diff --git a/source/tutorial/aws-lambda.txt b/source/tutorial/aws-lambda.txt deleted file mode 100644 index cb27689f..00000000 --- a/source/tutorial/aws-lambda.txt +++ /dev/null @@ -1,153 +0,0 @@ -:orphan: - -============================== -Deploy to AWS Lambda with Bref -============================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -`Bref `__ lets you deploy serverless PHP applications on AWS Lambda. -In this tutorial, you will deploy a simple PHP application with the MongoDB PHP extension, -and connect to an Atlas cluster using AWS IAM authentication. - -Prerequisites --------------- - -To deploy to AWS Lambda by using Bref, you must have the following components set up: - -- AWS account with access keys -- Serverless Framework - -To learn how to set these up, follow the `Setup tutorial `__ -in the Bref official documentation. - -Install the MongoDB extension ------------------------------ - -Bref uses Lambda layers to provide the PHP runtime. The ``bref`` layer is compiled -with PHP and a few extensions. Other extensions, like ``mongodb``, are available -in additional layers. - -Start by creating a new directory for your project and install the required MongoDB -and Bref dependencies. - -.. code-block:: none - - $ mkdir bref-mongodb-app && cd bref-mongodb-app - $ composer init - $ composer require bref/bref bref/extra-php-extensions mongodb/mongodb - -Then initialize the serverless configuration using the ``bref`` command. - -.. code-block:: none - - $ vendor/bin/bref init - - -After this series of commands, you should have this files: - -- ``composer.json`` for PHP dependencies installed in the ``vendor`` directory -- ``index.php`` a sample webpage -- ``serverless.yml`` for the configuration of the deployment - -To validate your setup, try deploying this default application. This outputs -a URL that renders a webpage with the Bref logo: - -.. code-block:: none - - $ serverless deploy - - -Now that you have initialized the project, you will add the ``mongodb`` extension. -Locate the "Serverless config" name in the list of extensions provided by -`bref/extra-php-extension `__. -Add it to the ``layers`` of the function in ``serverless.yaml``, this file -will look like this: - -.. code-block:: yaml - - plugins: - - ./vendor/bref/bref - - ./vendor/bref/extra-php-extensions - - functions: - api: - handler: index.php - runtime: php-83-fpm - layers: - - ${bref-extra:mongodb-php-83} - - - -Let's use the MongoDB driver with a web page that list planets from the Atlas -`sample dataset `__. -Replace the contents of ``index.php`` with the following: - -.. literalinclude:: /examples/aws-lambda/index.php - :language: php - - -Redeploy the application with the new ``index.php``: - -.. code-block:: none - - $ serverless deploy - - -The application will display an error message because the ``MONGODB_URI`` -environment variable has not yet been set. We'll look at how to set this -variable in the next section. - -AWS Credentials ---------------- - -Atlas supports passwordless authentication with AWS credentials. In any Lambda function, -AWS sets environment variables that contains the access token and secret token with -the role assigned to deployed function. - -1. Open the Lambda function in the AWS console -2. In :guilabel:`Configuration > Permission`, copy the :guilabel:`Role name` -3. Add this role to your Atlas cluster with the built-in Role: "Read and write any database" - -To learn how to set up unified AWS access, see `Set Up Unified AWS Access -`__ -in the MongoDB Atlas documentation. - -Now that the permissions have been configured, the Lambda function is allowed to access -your Atlas cluster. You can configure your application with the Atlas endpoint. - -Access to Atlas clusters is also restricted by IP address. Since the range of IP that comes -from AWS is very wide, you can `allow access from everywhere -`__. - -.. note:: - - Using VPC Peering is recommended in order to isolate your Atlas cluster from Internet. - This requires the Lambda function to be deployed in this AWS VPC. - -Find the connection URI in the Atlas UI :guilabel:`Atlas > Deployment > Database > Connect`. -Select :guilabel:`3. AWS IAM`. -Remove the ``:`` part from the URI, the credentials -will be read from environment variables. - -Update the ``serverless.yml`` file to pass the environment variable ``MONGODB_URI``. - -.. code-block:: yaml - - provider: - environment: - MONGODB_URI: "mongodb+srv://cluster0.example.mongodb.net/?authSource=%24external&authMechanism=MONGODB-AWS&retryWrites=true&w=majority" - -Finally, deploy with the new configuration. After deployment completes, you can -access the function URL and see the list of planets from your Atlas cluster. - -.. code-block:: none - - $ serverless deploy From 27cf3041eeaa3eaee98f9d8e8750b79b59b65ef4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 19 Feb 2025 11:20:00 -0500 Subject: [PATCH 2/7] fixes --- source/aws-lambda.txt | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt index 73000a1c..a923fd2a 100644 --- a/source/aws-lambda.txt +++ b/source/aws-lambda.txt @@ -94,15 +94,15 @@ file, as shown in the following code: .. code-block:: yaml plugins: - - ./vendor/bref/bref - - ./vendor/bref/extra-php-extensions # Adds the extra Serverless plugin + - ./vendor/bref/bref + - ./vendor/bref/extra-php-extensions # Adds the extra Serverless plugin functions: - api: - handler: index.php - runtime: php-83-fpm - layers: - - ${bref-extra:mongodb-php-81} # Adds the MongoDB layer + api: + handler: index.php + runtime: php-83-fpm + layers: + - ${bref-extra:mongodb-php-81} # Adds the MongoDB layer Customize the Sample Application -------------------------------- @@ -168,8 +168,12 @@ environment variable ``MONGODB_URI`` to your connection string: .. code-block:: yaml provider: - environment: - MONGODB_URI: "" + environment: + MONGODB_URI: "" + +To learn more about using the ``MONGODB-AWS`` authentication mechanism, +see the :ref:`MONGODB-AWS ` section of the +Authentication Mechanisms guide. Deploy Your Application ----------------------- From e8b11fcf2d1d9eb24c37838ae42e29b258890958 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 19 Feb 2025 11:22:56 -0500 Subject: [PATCH 3/7] fixes --- .vscode/settings.json | 6 ------ source/aws-lambda.txt | 2 +- 2 files changed, 1 insertion(+), 7 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 6d4f70d8..00000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "cSpell.words": [ - "Bref", - "guilabel" - ] -} diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt index a923fd2a..173bb213 100644 --- a/source/aws-lambda.txt +++ b/source/aws-lambda.txt @@ -155,7 +155,7 @@ the Atlas documentation. .. note:: - Using VPC Peering is recommended in order to isolate your Atlas + Using VPC Peering is recommended to isolate your Atlas cluster from the internet. This requires the Lambda function to be deployed in this AWS VPC. From 8ee82a1c1be060923652af65f1168421bc71a7af Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 19 Feb 2025 11:25:37 -0500 Subject: [PATCH 4/7] fixes --- source/aws-lambda.txt | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt index 173bb213..e159abec 100644 --- a/source/aws-lambda.txt +++ b/source/aws-lambda.txt @@ -69,9 +69,6 @@ After the commands complete, your project contains the following files: - ``index.php``: Defines a sample webpage - ``serverless.yml``: Configures the deployment -Deploy the Sample Application ------------------------------ - To validate your setup, try to deploy the default application. The following command deploys the application and returns a URL that renders a webpage that shows the Bref logo: @@ -85,8 +82,8 @@ Add the MongoDB Extension to Your Configuration After you initialize the project, you can add the ``mongodb`` extension. Locate the ``Serverless config`` name in the list of extensions provided -by the `bref/extra-php-extension -`__ package. +by the :github:`bref/extra-php-extension ` +package. Add it to the ``layers`` of the function in the ``serverless.yaml`` file, as shown in the following code: @@ -122,8 +119,8 @@ following command: serverless deploy The application page displays an error message because the ``MONGODB_URI`` -environment variable is not set.The following section explains how to -set your connection string as an environment variable. +environment variable is not set. The following section explains how to +set your connection string in an environment variable. Set AWS Credentials ------------------- @@ -185,4 +182,4 @@ Finally, deploy with the new configuration: serverless deploy After deployment completes, you can access the URL and see the -list of planets from your collection. +list of planets from your collection. From 7ef009a675827eab6586b9359c2589309f91eb17 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 19 Feb 2025 15:18:58 -0500 Subject: [PATCH 5/7] MM PR fixes 1 --- source/aws-lambda.txt | 37 +++++++++++++++---------------------- 1 file changed, 15 insertions(+), 22 deletions(-) diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt index e159abec..dfe5d661 100644 --- a/source/aws-lambda.txt +++ b/source/aws-lambda.txt @@ -20,8 +20,8 @@ Deploy to AWS Lambda Overview -------- -In this guide, you can learn how to use the tool `Bref -`__ to deploy serverless PHP applications on AWS +In this guide, you can learn how to use `Bref +`__ to deploy serverless PHP applications to AWS Lambda. This guide demonstrates how to deploy a PHP application built by using the {+library-short+} and connect to an Atlas cluster by using AWS IAM authentication. @@ -43,9 +43,9 @@ Install Dependencies Bref uses `Lambda layers `__ to -provide the PHP runtime. The ``bref`` layer is compiled with PHP and a -few extensions. You can install extensions, such as ``mongodb``, -in other layers. +provide the PHP runtime. The ``bref`` layer integrates Bref into your +application and is compiled with PHP and a few other extensions. You can +install the other necessary extensions, such as ``mongodb``, in other layers. The following commands create a new project directory and install the MongoDB and Bref dependencies: @@ -69,23 +69,13 @@ After the commands complete, your project contains the following files: - ``index.php``: Defines a sample webpage - ``serverless.yml``: Configures the deployment -To validate your setup, try to deploy the default application. The -following command deploys the application and returns a URL that renders -a webpage that shows the Bref logo: - -.. code-block:: bash - - serverless deploy - Add the MongoDB Extension to Your Configuration ----------------------------------------------- After you initialize the project, you can add the ``mongodb`` extension. Locate the ``Serverless config`` name in the list of extensions provided by the :github:`bref/extra-php-extension ` -package. - -Add it to the ``layers`` of the function in the ``serverless.yaml`` +package. Add it to the ``layers`` of the function in the ``serverless.yaml`` file, as shown in the following code: .. code-block:: yaml @@ -133,7 +123,8 @@ The following steps demonstrate how to set the role in your Atlas cluster: 1. Open the Lambda function in the AWS console. -#. Enter :guilabel:`Configuration > Permission`, then copy the :guilabel:`Role name`. +#. Navigate to :guilabel:`Configuration > Permission`, then copy the + :guilabel:`Role name`. #. Add this role to your Atlas cluster in the :guilabel:`Database Access` section. Select the :guilabel:`AWS IAM` authentication method and set the built-in role ``Read and write any database``. @@ -152,15 +143,17 @@ the Atlas documentation. .. note:: - Using VPC Peering is recommended to isolate your Atlas - cluster from the internet. This requires the Lambda function to be - deployed in this AWS VPC. + Using Virtual Private Cloud (VPC) Peering is recommended to isolate + your Atlas cluster from the internet. This requires the Lambda + function to be deployed in the AWS VPC. To learn more, see + :atlas:`Set Up a Network Peering Connection ` + in the Atlas documentation. Next, copy your connection string and remove the ``:`` section, as your credentials are read from environment variables. -Update the ``serverless.yml`` file in your project to set the -environment variable ``MONGODB_URI`` to your connection string: +In your project's ``serverless.yml`` file, set the +``MONGODB_URI`` environment variable to your connection string: .. code-block:: yaml From a4fdfc3edbaf70561fd71f61632f256f8a717e14 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 19 Feb 2025 15:34:35 -0500 Subject: [PATCH 6/7] remove section --- source/aws-lambda.txt | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt index dfe5d661..c01cc106 100644 --- a/source/aws-lambda.txt +++ b/source/aws-lambda.txt @@ -94,24 +94,13 @@ file, as shown in the following code: Customize the Sample Application -------------------------------- -This step explains how to create a web page that list planets from the -Atlas :atlas:`sample data `. Replace the contents of -``index.php`` with the following code: +Create a web page that list planets from the Atlas :atlas:`sample data +` by replacing the contents of ``index.php`` with the +following code: .. literalinclude:: /examples/aws-lambda/index.php :language: php -Redeploy the application with the new ``index.php`` by running the -following command: - -.. code-block:: bash - - serverless deploy - -The application page displays an error message because the ``MONGODB_URI`` -environment variable is not set. The following section explains how to -set your connection string in an environment variable. - Set AWS Credentials ------------------- From 72ab637020d0d862874565f17a9c0681c79a81ba Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 20 Feb 2025 09:33:30 -0500 Subject: [PATCH 7/7] RB small fix --- source/aws-lambda.txt | 16 +++++++++++----- .../aws-lambda/composer.json | 0 .../{examples => includes}/aws-lambda/index.php | 0 .../aws-lambda/serverless.yml | 0 4 files changed, 11 insertions(+), 5 deletions(-) rename source/{examples => includes}/aws-lambda/composer.json (100%) rename source/{examples => includes}/aws-lambda/index.php (100%) rename source/{examples => includes}/aws-lambda/serverless.yml (100%) diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt index c01cc106..54236adc 100644 --- a/source/aws-lambda.txt +++ b/source/aws-lambda.txt @@ -1,8 +1,8 @@ .. _php-aws-lambda: -==================== -Deploy to AWS Lambda -==================== +================================== +Deploy to AWS Lambda by Using Bref +================================== .. facet:: :name: genre @@ -98,9 +98,15 @@ Create a web page that list planets from the Atlas :atlas:`sample data ` by replacing the contents of ``index.php`` with the following code: -.. literalinclude:: /examples/aws-lambda/index.php +.. literalinclude:: /includes/aws-lambda/index.php :language: php +.. tip:: Find Operations + + The preceding code uses the :phpmethod:`MongoDB\Collection::find()` + method to retrieve documents. To learn more about this method, see the + :ref:`php-retrieve` guide. + Set AWS Credentials ------------------- @@ -157,7 +163,7 @@ Authentication Mechanisms guide. Deploy Your Application ----------------------- -Finally, deploy with the new configuration: +Finally, deploy the application: .. code-block:: bash diff --git a/source/examples/aws-lambda/composer.json b/source/includes/aws-lambda/composer.json similarity index 100% rename from source/examples/aws-lambda/composer.json rename to source/includes/aws-lambda/composer.json diff --git a/source/examples/aws-lambda/index.php b/source/includes/aws-lambda/index.php similarity index 100% rename from source/examples/aws-lambda/index.php rename to source/includes/aws-lambda/index.php diff --git a/source/examples/aws-lambda/serverless.yml b/source/includes/aws-lambda/serverless.yml similarity index 100% rename from source/examples/aws-lambda/serverless.yml rename to source/includes/aws-lambda/serverless.yml