diff --git a/source/aws-lambda.txt b/source/aws-lambda.txt new file mode 100644 index 00000000..54236adc --- /dev/null +++ b/source/aws-lambda.txt @@ -0,0 +1,173 @@ +.. _php-aws-lambda: + +================================== +Deploy to AWS Lambda by Using Bref +================================== + +.. 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 `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. + +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 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: + +.. 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 + +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`` +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 +-------------------------------- + +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:: /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 +------------------- + +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. +#. 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``. + +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 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. + +In your project's ``serverless.yml`` file, set the +``MONGODB_URI`` environment variable to your connection string: + +.. code-block:: yaml + + provider: + 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 +----------------------- + +Finally, deploy the application: + +.. 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/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 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