Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

'Building your function' README updates #543

Merged
merged 4 commits into from Jan 6, 2024
Merged

'Building your function' README updates #543

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
56ed6ec
README updates
bmoffatt Jan 3, 2024
cd952a2
Update README.md
bmoffatt Jan 4, 2024
f9a40af
Merge branch 'main' into build-docs-refresh
bmoffatt Jan 5, 2024
b968a06
Merge branch 'main' into build-docs-refresh
bmoffatt Jan 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
32 changes: 28 additions & 4 deletions README.md
View file
Open in desktop
Expand Up @@ -43,16 +43,26 @@ func main() {

# Building your function

Preparing a binary to deploy to AWS Lambda requires that it is compiled for Linux and placed into a .zip file.
Preparing a binary to deploy to AWS Lambda requires that it is compiled for Linux and placed into a .zip file. When using the `provided`, `provided.al2`, or `provided.al2023` runtime, the executable within the .zip file should be named `bootstrap`. Lambda's default architecture is `x86_64`, so when cross compiling from a non-x86 environment, the executable should be built with `GOARCH=amd64`. Likewise, if the Lambda function will be [configured to use ARM](https://docs.aws.amazon.com/lambda/latest/dg/foundation-arch.html), the executable should built with `GOARCH=arm64`.

## For developers on Linux and macOS
``` shell
# Remember to build your handler executable for Linux!
# When using the `provided.al2` runtime, the handler executable should be named `bootstrap`
GOOS=linux GOARCH=amd64 go build -o bootstrap main.go
zip lambda-handler.zip bootstrap
```

## For developers on Linux

On Linux, the Go compiler's default behavior is to link the output executable to the system libc for some standard library functionality (for example, DNS lookups). If the build environment is using a Linux distribution with a GNU libc version newer than the deployment environment, the application when deployed to Lambda may fail with an error like ``/lib64/libc.so.6: version `GLIBC_X.YZ' not found``.

Most Go applications do not require linking to the system libc. This behavior can be disabled by using the `CGO_ENABLED` environment variable.

```
CGO_ENABLED=0 go build -o bootstrap main.go
zip lambda-handler.zip bootstrap
```

See [Using CGO](#using-cgo)

## For developers on Windows

Windows developers may have trouble producing a zip file that marks the binary as executable on Linux. To create a .zip that will work on AWS Lambda, the `build-lambda-zip` tool may be helpful.
Expand Down Expand Up @@ -81,6 +91,20 @@ $env:CGO_ENABLED = "0"
go build -o bootstrap main.go
~\Go\Bin\build-lambda-zip.exe -o lambda-handler.zip bootstrap
```

## Using CGO

For applications that require CGO, the build environment must be using a GNU libc version installed compatible with the target Lambda runtime. Otherwise, execution may fail with errors like ``/lib64/libc.so.6: version `GLIBC_X.YZ' not found``.

| Lambda runtime | GLIBC version
| ----- | ---
| `provided.al2023` | 2.34
| `provided.al2` | 2.26
| `provided` and `go1.x` | 2.17


Alternatively, Lambda supports container images as a deployment package alternative to .zip files. For more information, refer to the official documentation for [working with with container images](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html).

# Deploying your functions

To deploy your function, refer to the official documentation for [deploying using the AWS CLI, AWS Cloudformation, and AWS SAM](https://docs.aws.amazon.com/lambda/latest/dg/deploying-lambda-apps.html).
Expand Down