[doc] add a deployment guide and update the readme #432

sebsto · 2024-12-19T13:45:03Z

As discussed with @0xTim
This PR

adds a minimal example of deployment using SAM in the README
adds a Deployment.md Swift Docc file to cover deployment with the AWS console, CLI, SAM, and CDK. It mentions and contains a call to contributions to further examples for third-party tools such as the Serverless Framework, Terraform, or Pulumi.

0xTim

Overall it looks good. One typo and a few things to discuss

0xTim · 2024-12-20T14:28:06Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+
+![Console - select zip file](console-40-select-zip-file)
+
+Select the zip file created with the `swift package archive --allow-network-connections docker` command.  This file is located in your project folder at `.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/MyLambda/MyLambda.zip`. The name of the ZIP file depends on the target name you entered in the `Package.swift` file.


Do we have a tutorial on this command we can link to? It came very out of the blue

This doc is about the deployment, so after the package is compiled and zipped.
But you're right, I should add a paragraph on top repeating the requirement : having a Swift lambda function compiled and ZIP. This applies to all deployment techniques presented in this doc.

Yeah I'd add that before going into all the different examples

Done. I added a section in the prerequisites

0xTim · 2024-12-20T14:32:50Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+
+### Invoke the function 
+
+Select the **Test** tab in the console and prepare a payload to send to your Lambda function. In this example, you've deployed the [HelloWorld](Exmaples.HelloWorld/README.md) example function. The function expects a `String` as input parameter and returns a `String`.


This either needs rewording or we need to rework this a bit to talk about the example and explain at the start that this is what we're going to be deploying etc

Done. I added a phrase at the start of the console section to describe the example we're going to deploy and a phrase here in the "Invoke" section to describe the test event

0xTim · 2024-12-20T14:33:58Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+
+The response of the invocation and additional meta data appears in the green section of the page.
+
+I can see the response from the Swift code: `Hello Swift on Lambda`.


We have a mix or first person singular, first person plural and third person in the tutorial. We should align this for consistency

0xTim · 2024-12-20T14:34:41Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+
+The function consumed 109.60ms of execution time, out of this 83.72ms where spent to initialize this new runtime. This initialization time is known as Lambda cold start time.
+
+> Lambda cold start time refers to the initial delay that occurs when a Lambda function is invoked for the first time or after being idle for a while. Cold starts happen because AWS needs to provision and initialize a new container, load your code, and start your runtime environment (in this case, the Swift runtime). This delay is particularly noticeable for the first invocation, but subsequent invocations (known as "warm starts") are typically much faster because the container and runtime are already initialized and ready to process requests. Cold starts are an important consideration when architecting serverless applications, especially for latency-sensitive workloads.


Is it worth adding a note here about how Swift compares to other languages for cold start times?

Usually, compiled languages, such as Swift, Go, and Rust, have shorter cold start times compared to interpreted languages, such as Python, Java, Ruby, and Node.js.

done

0xTim · 2024-12-20T14:37:20Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+
+To create a function, you must first create the function execution role and define the permission. Then, you create the function with the `create-function` command.
+
+The command assumes you've already created the ZIP file with the `swift package archive --allow-network-connections docker` command. The name and the path of the ZIP file depends on the executable target name you entered in the `Package.swift` file.


Or similar

Suggested change

The command assumes you've already created the ZIP file with the `swift package archive --allow-network-connections docker` command. The name and the path of the ZIP file depends on the executable target name you entered in the `Package.swift` file.

The command assumes you've already created the ZIP file with the `swift package archive --allow-network-connections docker` command. The name and the path of the ZIP file depends on the executable target name you entered in the `Package.swift` file. In this example, we're building the HelloWorld example from the examples directory.

In this example, we're building the HelloWorld example from the Examples directory.

done

0xTim · 2024-12-20T14:38:23Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+
+The `--architectures` flag is only required when you build the binary on an Apple Silicon machine (Apple M1 or more recent). It defaults to `x64`.
+
+To update the function, use the `update-function-code` command.


Suggested change

To update the function, use the `update-function-code` command.

To update the function, use the `update-function-code` command, once you've archived the updated code.

To update the function, use the update-function-code command after you've recompiled and archived your code again with the swift package archive command.

done

0xTim · 2024-12-20T14:41:16Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+
+In this example, the Lambda function must accept an APIGateway v2 JSON payload as input parameter and return a valid APIGAteway v2 JSON response.  See the example code in the [APIGateway example README file](https://github.com/swift-server/swift-aws-lambda-runtime/blob/main/Examples/APIGateway/README.md).
+
+To deploy the function with SAM, use the `sam deploy` command. The very first time you deploy a function, you must use the `--guided` flag to configure the deployment. The command will ask you a series of questions to configure the deployment.


You don't need to do it if you provide all the flags right?

Suggested change

To deploy the function with SAM, use the `sam deploy` command. The very first time you deploy a function, you must use the `--guided` flag to configure the deployment. The command will ask you a series of questions to configure the deployment.

To deploy the function with SAM, use the `sam deploy` command. The very first time you deploy a function, you should use the `--guided` flag to configure the deployment. The command will ask you a series of questions to configure the deployment.

0xTim · 2024-12-20T14:41:50Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+Outputs                                                                                                                                         
+--------------------------------------------------------------------------------
+Key                 APIGatewayEndpoint                                                                                                          
+Description         API Gateway endpoint UR"                                                                                                    


Suggested change

Description API Gateway endpoint UR"

Description API Gateway endpoint URL

0xTim · 2024-12-20T14:53:47Z

Sources/AWSLambdaRuntimeCore/Documentation.docc/Deployment.md

+ }
+}    
+```
+The code assumes you already built the Swift Lambda function with the `swift package archive --allow-network-connections docker` command. The ZIP file is located in the `.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/MyLambda/MyLambda.zip` folder.


Again we should be clear about what app we're deploying here so there's no confusion when invoking the lambda etc

done, I added a phrase at the start of the section and clarified this one.

sebsto · 2024-12-24T11:39:07Z

Thank you @0xTim for having taken the time to review this, I included all modifications you suggested.
You can see the list of changes in this commit 17f6b46

Note that integration tests will fail until #441 will be merged

0xTim

LGTM!

sebsto added 7 commits November 27, 2024 11:12

add deploy with console and CLI

9a54935

WIP : SAM deployment

383bb35

move deployment doc to Swift docc and finish SAM deployment section

b03312a

[doc] deployment : add section for third-party

e85638a

Merge branch 'main' into sebsto/readme

0043d9f

add CDK deployment

9a41ec3

update TOC

e077554

sebsto requested a review from 0xTim December 19, 2024 13:47

sebsto added the semver/none No version bump required. label Dec 19, 2024

sebsto added 13 commits December 19, 2024 18:07

fix typo

9c929bb

Merge branch 'main' into sebsto/readme

fa9993c

Merge branch 'main' into sebsto/readme

dac4131

Merge branch 'main' into sebsto/readme

4be3d96

add the shell script referenced in the redame file

362a18d

create a separate script for role creation

e1a9503

add a note in the readme to explain the IAM role must be present

adad938

clarify

78f4438

fix shelcheck errors

474f9cf

fix shellcheck

63e48c5

fix spellcheck

1b16e5e

fix shellcheck

1cca175

update ref to script

a301109

0xTim approved these changes Dec 20, 2024

View reviewed changes

sebsto added 2 commits December 24, 2024 12:36

added all changes suggested by Tim

17f6b46

Merge branch 'main' into sebsto/readme

5447fbf

sebsto force-pushed the sebsto/readme branch from e1630cd to 5447fbf Compare December 24, 2024 11:36

0xTim approved these changes Dec 25, 2024

View reviewed changes

sebsto merged commit f65ec32 into swift-server:main Dec 25, 2024
17 of 24 checks passed

sebsto deleted the sebsto/readme branch December 25, 2024 06:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[doc] add a deployment guide and update the readme #432

[doc] add a deployment guide and update the readme #432

sebsto commented Dec 19, 2024

0xTim left a comment

0xTim Dec 20, 2024

sebsto Dec 20, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

0xTim Dec 20, 2024

sebsto Dec 24, 2024

sebsto commented Dec 24, 2024 •

edited

Loading

0xTim left a comment


		![Console - select zip file](console-40-select-zip-file)

		Select the zip file created with the `swift package archive --allow-network-connections docker` command. This file is located in your project folder at `.build/plugins/AWSLambdaPackager/outputs/AWSLambdaPackager/MyLambda/MyLambda.zip`. The name of the ZIP file depends on the target name you entered in the `Package.swift` file.


		### Invoke the function

		Select the Test tab in the console and prepare a payload to send to your Lambda function. In this example, you've deployed the [HelloWorld](Exmaples.HelloWorld/README.md) example function. The function expects a `String` as input parameter and returns a `String`.


		The response of the invocation and additional meta data appears in the green section of the page.

		I can see the response from the Swift code: `Hello Swift on Lambda`.


		The function consumed 109.60ms of execution time, out of this 83.72ms where spent to initialize this new runtime. This initialization time is known as Lambda cold start time.

		> Lambda cold start time refers to the initial delay that occurs when a Lambda function is invoked for the first time or after being idle for a while. Cold starts happen because AWS needs to provision and initialize a new container, load your code, and start your runtime environment (in this case, the Swift runtime). This delay is particularly noticeable for the first invocation, but subsequent invocations (known as "warm starts") are typically much faster because the container and runtime are already initialized and ready to process requests. Cold starts are an important consideration when architecting serverless applications, especially for latency-sensitive workloads.


		To create a function, you must first create the function execution role and define the permission. Then, you create the function with the `create-function` command.

		The command assumes you've already created the ZIP file with the `swift package archive --allow-network-connections docker` command. The name and the path of the ZIP file depends on the executable target name you entered in the `Package.swift` file.


		The `--architectures` flag is only required when you build the binary on an Apple Silicon machine (Apple M1 or more recent). It defaults to `x64`.

		To update the function, use the `update-function-code` command.


		In this example, the Lambda function must accept an APIGateway v2 JSON payload as input parameter and return a valid APIGAteway v2 JSON response. See the example code in the [APIGateway example README file](https://github.com/swift-server/swift-aws-lambda-runtime/blob/main/Examples/APIGateway/README.md).

		To deploy the function with SAM, use the `sam deploy` command. The very first time you deploy a function, you must use the `--guided` flag to configure the deployment. The command will ask you a series of questions to configure the deployment.

	Description API Gateway endpoint UR"
	Description API Gateway endpoint URL

[doc] add a deployment guide and update the readme #432

[doc] add a deployment guide and update the readme #432

Conversation

sebsto commented Dec 19, 2024

0xTim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sebsto commented Dec 24, 2024 • edited Loading

0xTim left a comment

Choose a reason for hiding this comment

sebsto commented Dec 24, 2024 •

edited

Loading