You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+22-22Lines changed: 22 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Firetail Lambda Extension
1
+
# FireTail Lambda Extension
2
2
3
3
[](https://www.gnu.org/licenses/lgpl-3.0)[](https://github.com/FireTail-io/firetail-lambda-extension/actions/workflows/codecov.yml)[](https://codecov.io/gh/FireTail-io/firetail-lambda-extension)
4
4
@@ -14,13 +14,13 @@ Includes a wrapper script, [firetail-wrapper.sh](./firetail-wrapper.sh), that yo
14
14
15
15
## Tests
16
16
17
-
Automated testing is setup with the `testing` package, using [github.com/stretchr/testify](https://pkg.go.dev/github.com/stretchr/testify) for shorthand assertions. You can run them with `go test`, or use the provided [Makefile](./Makefile)'s `test` target, which is as simple as:
17
+
Automated testing is set up with the `testing` package, using [github.com/stretchr/testify](https://pkg.go.dev/github.com/stretchr/testify) for shorthand assertions. You can run them with `go test`, or use the provided [Makefile](./Makefile)'s `test` target, which is:
18
18
19
19
```bash
20
20
make test
21
21
```
22
22
23
-
This will output a coverage report (`coverage.out`) which you may view in your browser by using the [go tool cover](https://pkg.go.dev/cmd/cover) command:
23
+
This will output a coverage report (`coverage.out`) which you can view in your browser by using the [go tool cover](https://pkg.go.dev/cmd/cover) command:
24
24
25
25
```bash
26
26
go tool cover -html coverage.out
@@ -30,29 +30,29 @@ go tool cover -html coverage.out
30
30
31
31
## Deployment
32
32
33
-
The Firetail Logging Extension is an external Lambda extension, published as a Lambda Layer. Deploying it is a fivestep process. If you wish to use the publicly accessible Lambda Layer published by Firetail, you can skip to the final step. The full list of steps to build, package, publish and use the Firetail Lambda Extension are as follows:
33
+
The FireTail Logging Extension is an external Lambda extension, published as a Lambda Layer. Deploying it is a five-step process. If you want to use the publicly accessible Lambda Layer published by FireTail, you can skip to the final step. The full list of steps to build, package, publish and use the FireTail Lambda Extension are as follows:
34
34
35
-
- The first step is to [build the extension binary](#building-the-extension-binary).
36
-
- The second step is to [package the extension binary](#packaging-the-extension-binary).
37
-
- The third step is to [publish the package as a Lambda Layer](#publishing-the-package).
38
-
- An optional fourth step is to [make the layer public](#making-the-layer-public).
39
-
- The final step is to [add the layer to a Lambda Function](#adding-the-layer-to-a-lambda-function).
35
+
1.[Build the extension binary](#building-the-extension-binary).
36
+
2.[Package the extension binary](#packaging-the-extension-binary).
37
+
3.[Publish the package as a Lambda Layer](#publishing-the-package).
38
+
4. (Optional) [Make the layer public](#making-the-layer-public).
39
+
5.[Add the layer to a Lambda Function](#adding-the-layer-to-a-lambda-function).
40
40
41
-
This process has been partially automated in the provided [Makefile](./Makefile). In order to use this makefile you will need to install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), [Golang](https://go.dev/doc/install) and [JQ](https://stedolan.github.io/jq/). You may observe how this Makefile is used by us in the Github action named "[build & publish](./.github/workflows/release.yaml)".
41
+
This process has been partially automated in the provided [Makefile](./Makefile). To use this makefile you need to install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), [Golang](https://go.dev/doc/install) and [JQ](https://stedolan.github.io/jq/). You can observe how this Makefile is used by us in the Github action named "[build & publish](./.github/workflows/release.yaml)".
42
42
43
43
44
44
45
45
### Building The Extension Binary
46
46
47
-
The logging extension is a standard Go project and can be built by [installing Go](https://go.dev/doc/install) and using the [go build](https://pkg.go.dev/cmd/go#hdr-Compile_packages_and_dependencies) command from the root directory of this repository. You will need to set the `GOOS` and `GOARCH` environment variables appropriately for your target Lambda runtime's operating system and architecture. See the [Environment variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables) section of the [go command docs](https://pkg.go.dev/cmd/go) for more information. An example may look like this:
47
+
The logging extension is a standard Go project and can be built by [installing Go](https://go.dev/doc/install) and using the [go build](https://pkg.go.dev/cmd/go#hdr-Compile_packages_and_dependencies) command from the root directory of this repository. You will need to set the `GOOS` and `GOARCH` environment variables appropriately for your target Lambda runtime's operating system and architecture. See the [Environment variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables) section of the [go command docs](https://pkg.go.dev/cmd/go) for more information. An example is:
48
48
49
49
```bash
50
50
GOOS=linux GOARCH=amd64 go build
51
51
```
52
52
53
53
This will yield a binary with the same name as the root directory, which if you have just cloned this repository will be `firetail-lambda-extension`.
54
54
55
-
The target in the provided makefile that corresponds to this step is `build`. It requires a target architecture (`ARCH`) which defaults to `amd64`. For example, you may wish to do:
55
+
The target in the provided makefile that corresponds to this step is `build`. It requires a target architecture (`ARCH`) that defaults to `amd64`. For example, you can:
56
56
57
57
```bash
58
58
make build ARCH=arm64
@@ -70,7 +70,7 @@ To package the extension binary, it must be placed into a directory named `exten
The target in the provided makefile that corresponds to this step is `package`, and it depends upon the `build` step. It requries a target architecture (`ARCH`), and extension version (`VERSION`) which defaults to `latest`. For example, you may wish to do:
73
+
The target in the provided makefile that corresponds to this step is `package`, and it depends upon the `build` step. It requires a target architecture (`ARCH`), and extension version (`VERSION`) which defaults to `latest`. For example, you can do:
74
74
75
75
```bash
76
76
make package ARCH=arm64 VERSION=v1.0.0
@@ -82,11 +82,11 @@ This will yield a `.zip` file in the `build` directory named `firetail-extension
82
82
83
83
### Publishing The Package
84
84
85
-
To publish the package, you may use the AWS CLI's [publish-layer-version](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/publish-layer-version.html) command. You will need to repeat this process for every region in which you wish to use the layer. You will also need to specify the compatible architectures, and give the layer a name. The output of the command will provide you with the layer's ARN and layer version, which you may use to add it to your Lambdas.
85
+
To publish the package, you can use the AWS CLI's [publish-layer-version](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/publish-layer-version.html) command. You will need to repeat this process for every region in which you wish to use the layer. You will also need to specify the compatible architectures, and give the layer a name. The output of the command will provide you with the layer's ARN and layer version, which you may use to add it to your Lambdas.
86
86
87
87
If you reuse the same layer name multiple times, the layer version will be incremented. The approach taken in the provided makefile is to publish each extension version with a new layer name, so the layer version will almost always be `1`.
88
88
89
-
The target in the provided makefile that corresponds to this step is `publish`. You must make the `build` target before the `publish` target. The `publish` target requires a target architecture (`ARCH`) and extension version (`VERSION`), which match that used when you made the `package` target; and a region in which to publish the layer (`AWS_REGION`). For example, you may wish to do:
89
+
The target in the provided makefile that corresponds to this step is `publish`. You must make the `build` target before the `publish` target. The `publish` target requires a target architecture (`ARCH`) and extension version (`VERSION`), which match that used when you made the `package` target; and a region in which to publish the layer (`AWS_REGION`). For example, you can:
90
90
91
91
```bash
92
92
make publish ARCH=arm64 VERSION=v1.0.0 AWS_REGION=eu-west-1
@@ -101,7 +101,7 @@ make publish ARCH=arm64 VERSION=v1.0.0 AWS_REGION=eu-west-1
101
101
102
102
To make the layer public, you may use the AWS CLI's [add-layer-version-permission](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/add-layer-version-permission.html) command. You will need to repeat this process for every layer you publish in every region. You will need to provide the layer name & layer version, a statement ID and region; and to make the layer public an action of `lambda:GetLayerVersion` and principal of `*`.
103
103
104
-
The target in the provided makefile corresponding to this step is `public`. You must make the `publish` target before the `public` target. The `public` target requires a target architecture (`ARCH`), extension version (`VERSION`) and AWS region (`AWS_REGION`) which match that used when you made the `publish` target, as well as the layer version created when you made the `publish` target (`AWS_LAYER_VERSION`). For example, you may wish to do:
104
+
The target in the provided makefile corresponding to this step is `public`. You must make the `publish` target before the `public` target. The `public` target requires a target architecture (`ARCH`), extension version (`VERSION`) and AWS region (`AWS_REGION`) which match that used when you made the `publish` target, as well as the layer version created when you made the `publish` target (`AWS_LAYER_VERSION`). For example, you can:
105
105
106
106
```bash
107
107
make public ARCH=arm64 VERSION=v1.0.0 AWS_REGION=eu-west-1 AWS_LAYER_VERSION=1
@@ -111,15 +111,15 @@ make public ARCH=arm64 VERSION=v1.0.0 AWS_REGION=eu-west-1 AWS_LAYER_VERSION=1
111
111
112
112
### Adding The Layer To A Lambda Function
113
113
114
-
There are a number of ways to add the published layer to your Lambda Function:
114
+
There are several ways to add the published layer to your Lambda Function:
115
115
116
116
1.[Using the AWS CLI](#using-the-aws-cli).
117
117
2.[Using An AWS Lambda Docker Build](#using-an-aws-lambda-docker-build).
118
118
3.[Using Terraform](#using-terraform).
119
119
120
-
You will need to ascertain the layer ARN of the Lambda Layer containing the Firetail Lambda Extension that you wish to use. If you are not publishing your own Firetail Extension Lambda Layer, you may use the Lambda Layer published publicly by Firetail.
120
+
You will need to ascertain the layer ARN of the Lambda Layer containing the FireTail Lambda Extension that you wish to use. If you are not publishing your own FireTail Extension Lambda Layer, you may use the Lambda Layer published publicly by FireTail.
121
121
122
-
The latest extension version of the publically accessible Lambda Layer published by Firetail can be derived by taking the latest version tag in the [Github Releases](https://github.com/FireTail-io/firetail-lambda-extension/releases) of this repository, and replacing the `.` characters with `-` characters. For example, `v1.2.3` would become `v1-2-3`. You will also need to determine the architecture you need for your Lambda Runtime, which may be either `arm64` or `x86_64`. Once you have these two values, you may substitute them into `${VERSION}` and `${ARCH}` respectively in the following string:
122
+
The latest extension version of the publically accessible Lambda Layer published by FireTail can be derived by taking the latest version tag in the [Github Releases](https://github.com/FireTail-io/firetail-lambda-extension/releases) of this repository, and replacing the `.` characters with `-` characters. For example, `v1.2.3` would become `v1-2-3`. You will also need to determine the architecture you need for your Lambda Runtime, which may be either `arm64` or `x86_64`. Once you have these two values, you may substitute them into `${VERSION}` and `${ARCH}` respectively in the following string:
@@ -152,7 +152,7 @@ Find below a full list of the environment variables used by the FireTail Lambda
152
152
153
153
To add the Lambda Layer to a Function, you may use the AWS CLI's [update-function-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-configuration.html) command. You will need to provide a region, the layer ARN and the name of the Function to which the layer is to be added.
154
154
155
-
The target in the provided makefile corresponding to this step is `add`. The `add` target requires the layer ARN (`LAYER_ARN`), the name of the Function to add the layer to (`FUNCTION_NAME`), and the AWS region in which both the layer and the Function must be found (`AWS_REGION`). For example, you may wish to do:
155
+
The target in the provided makefile corresponding to this step is `add`. The `add` target requires the layer ARN (`LAYER_ARN`), the name of the Function to add the layer to (`FUNCTION_NAME`), and the AWS region in which both the layer and the Function must be found (`AWS_REGION`). For example, you can do:
156
156
157
157
```bash
158
158
make add AWS_REGION=eu-west-1 LAYER_ARN=your-layer-arn FUNCTION_NAME=your-function-name
@@ -190,7 +190,7 @@ You will then need to add the following step into the final stage in your Docker
190
190
COPY --from=firetail-layer-copy /opt /opt
191
191
```
192
192
193
-
Once these steps are complete you should be able to run your build process as before, except with the addition of the `AWS_DEFAULT_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_LAYER_ARN` build arguments.
193
+
When these steps are complete you should be able to run your build process as before, except with the addition of the `AWS_DEFAULT_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_LAYER_ARN` build arguments.
194
194
195
195
⚠️ Ensure you securely use, and store these minimal access credentials ⚠️
0 commit comments