Skip to content

Commit 6e5f3ee

Browse files
rustagirrustagir
committed
DOCSP-47690: aws lambda tutorial (#207)
* DOCSP-47690: aws lambda tutorial * fixes * fixes * fixes * MM PR fixes 1 * remove section * RB small fix (cherry picked from commit 8ed8dde)
1 parent 2c4f7d0 commit 6e5f3ee

File tree

6 files changed

+181
-154
lines changed

6 files changed

+181
-154
lines changed

‎source/aws-lambda.txt

+173
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
.. _php-aws-lambda:
2+
3+
==================================
4+
Deploy to AWS Lambda by Using Bref
5+
==================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: serverless, deployment, code example, live
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use `Bref
24+
<https://bref.sh>`__ to deploy serverless PHP applications to AWS
25+
Lambda. This guide demonstrates how to deploy a PHP application built by
26+
using the {+library-short+} and connect to an Atlas cluster by using AWS
27+
IAM authentication.
28+
29+
Before You Get Started
30+
----------------------
31+
32+
Before you can deploy to AWS Lambda by using Bref, you must set up the
33+
following components:
34+
35+
- AWS account and access keys
36+
- `Serverless Framework <https://www.serverless.com/>`__
37+
38+
The `Setup <https://bref.sh/docs/setup>`__ tutorial in the Bref
39+
documentation describes how to prepare these components.
40+
41+
Install Dependencies
42+
--------------------
43+
44+
Bref uses `Lambda layers
45+
<https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html>`__ to
46+
provide the PHP runtime. The ``bref`` layer integrates Bref into your
47+
application and is compiled with PHP and a few other extensions. You can
48+
install the other necessary extensions, such as ``mongodb``, in other layers.
49+
50+
The following commands create a new project directory and install the
51+
MongoDB and Bref dependencies:
52+
53+
.. code-block:: bash
54+
55+
mkdir bref-mongodb-app && cd bref-mongodb-app
56+
composer init
57+
composer require bref/bref bref/extra-php-extensions mongodb/mongodb
58+
59+
Then, initialize the serverless configuration by using the ``bref``
60+
command:
61+
62+
.. code-block:: bash
63+
64+
vendor/bin/bref init
65+
66+
After the commands complete, your project contains the following files:
67+
68+
- ``composer.json``: Lists PHP dependencies installed in the ``vendor`` directory
69+
- ``index.php``: Defines a sample webpage
70+
- ``serverless.yml``: Configures the deployment
71+
72+
Add the MongoDB Extension to Your Configuration
73+
-----------------------------------------------
74+
75+
After you initialize the project, you can add the ``mongodb`` extension.
76+
Locate the ``Serverless config`` name in the list of extensions provided
77+
by the :github:`bref/extra-php-extension <brefphp/extra-php-extensions>`
78+
package. Add it to the ``layers`` of the function in the ``serverless.yaml``
79+
file, as shown in the following code:
80+
81+
.. code-block:: yaml
82+
83+
plugins:
84+
- ./vendor/bref/bref
85+
- ./vendor/bref/extra-php-extensions # Adds the extra Serverless plugin
86+
87+
functions:
88+
api:
89+
handler: index.php
90+
runtime: php-83-fpm
91+
layers:
92+
- ${bref-extra:mongodb-php-81} # Adds the MongoDB layer
93+
94+
Customize the Sample Application
95+
--------------------------------
96+
97+
Create a web page that list planets from the Atlas :atlas:`sample data
98+
</sample-data>` by replacing the contents of ``index.php`` with the
99+
following code:
100+
101+
.. literalinclude:: /includes/aws-lambda/index.php
102+
:language: php
103+
104+
.. tip:: Find Operations
105+
106+
The preceding code uses the :phpmethod:`MongoDB\Collection::find()`
107+
method to retrieve documents. To learn more about this method, see the
108+
:ref:`php-retrieve` guide.
109+
110+
Set AWS Credentials
111+
-------------------
112+
113+
Atlas supports passwordless authentication when using AWS credentials.
114+
In any Lambda function, AWS sets environment variables that contain the
115+
access token and secret token for the role assigned to deploy the function.
116+
117+
The following steps demonstrate how to set the role in your Atlas
118+
cluster:
119+
120+
1. Open the Lambda function in the AWS console.
121+
#. Navigate to :guilabel:`Configuration > Permission`, then copy the
122+
:guilabel:`Role name`.
123+
#. Add this role to your Atlas cluster in the :guilabel:`Database
124+
Access` section. Select the :guilabel:`AWS IAM` authentication method
125+
and set the built-in role ``Read and write any database``.
126+
127+
To learn how to set up unified AWS access, see :atlas:`Set Up Unified
128+
AWS Access </security/set-up-unified-aws-access/>` in the Atlas documentation.
129+
130+
After you configure the permissions, the Lambda function is allowed to access
131+
your Atlas cluster. Next, configure your application to use the Atlas endpoint.
132+
133+
Access to Atlas clusters is also restricted by IP address. Since the
134+
range of IP addresses that comes from AWS is very wide, you can allow
135+
access from everywhere. To learn how to allow universal access, see
136+
:atlas:`Configure IP Access List Entries </security/ip-access-list/>` in
137+
the Atlas documentation.
138+
139+
.. note::
140+
141+
Using Virtual Private Cloud (VPC) Peering is recommended to isolate
142+
your Atlas cluster from the internet. This requires the Lambda
143+
function to be deployed in the AWS VPC. To learn more, see
144+
:atlas:`Set Up a Network Peering Connection </security-vpc-peering>`
145+
in the Atlas documentation.
146+
147+
Next, copy your connection string and remove the ``<AWS access key>:<AWS
148+
secret key>`` section, as your credentials are read from environment variables.
149+
150+
In your project's ``serverless.yml`` file, set the
151+
``MONGODB_URI`` environment variable to your connection string:
152+
153+
.. code-block:: yaml
154+
155+
provider:
156+
environment:
157+
MONGODB_URI: "<connection string without credentials>"
158+
159+
To learn more about using the ``MONGODB-AWS`` authentication mechanism,
160+
see the :ref:`MONGODB-AWS <php-mongodb-aws>` section of the
161+
Authentication Mechanisms guide.
162+
163+
Deploy Your Application
164+
-----------------------
165+
166+
Finally, deploy the application:
167+
168+
.. code-block:: bash
169+
170+
serverless deploy
171+
172+
After deployment completes, you can access the URL and see the
173+
list of planets from your collection.

‎source/examples/aws-lambda/composer.json ‎source/includes/aws-lambda/composer.json

File renamed without changes.

‎source/examples/aws-lambda/index.php ‎source/includes/aws-lambda/index.php

File renamed without changes.

‎source/examples/aws-lambda/serverless.yml ‎source/includes/aws-lambda/serverless.yml

File renamed without changes.

‎source/index.txt

+8-1
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ MongoDB PHP Library
2222
Monitor Your Application </monitoring>
2323
Security </security>
2424
Specialized Data Formats </data-formats>
25+
Deploy to AWS Lambda </aws-lambda>
2526
Compatibility </compatibility>
2627
What's New </whats-new>
2728
Upgrade </upgrade>
@@ -111,6 +112,12 @@ Specialized Data Formats
111112
Learn how to work with specialized data formats and custom types in the
112113
:ref:`php-data-formats` section.
113114

115+
Deploy to AWS Lambda
116+
--------------------
117+
118+
Learn how to deploy a PHP application on AWS Lambda by using Bref in the
119+
:ref:`php-aws-lambda` section.
120+
114121
Compatibility
115122
-------------
116123

@@ -134,4 +141,4 @@ FAQ
134141
---
135142

136143
See answers to commonly asked questions about the {+library-short+} in the
137-
the :ref:`php-faq` section.
144+
the :ref:`php-faq` section.

‎source/tutorial/aws-lambda.txt

-153
This file was deleted.

0 commit comments

Comments
 (0)