DOCSP-47690: aws lambda tutorial

Author: rustagir

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "cSpell.words": [
+        "Bref",
+        "guilabel"
+    ]
+}

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
+<https://bref.sh>`__ 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 <https://www.serverless.com/>`__
+
+The `Setup <https://bref.sh/docs/setup>`__ tutorial in the Bref
+documentation describes how to prepare these components.
+
+Install Dependencies
+--------------------
+
+Bref uses `Lambda layers
+<https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html>`__ 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
+<https://github.com/brefphp/extra-php-extensions>`__ 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 </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 </security/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 </security/ip-access-list/>` 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 ``<AWS access key>:<AWS
+secret key>`` 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: "<connection string without credentials>"
+
+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. 

source/index.txt

@@ -22,6 +22,7 @@ MongoDB PHP Library
    Monitor Your Application </monitoring>
    Security </security>
    Specialized Data Formats </data-formats>
+   Deploy to AWS Lambda </aws-lambda>
    Compatibility </compatibility>
    What's New </whats-new>
    Upgrade </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.
+the :ref:`php-faq` section.