Skip to content

Commit b802a7f

Browse files
knottntknottnt
authored
Add documentation for using Lambda with Secrets Manager (#2544)
Issue #, if available: Description of changes: - Add tutorial for creating a secret in AWS Secrets Manager with a reference to a Kubernetes Secret - Add tutorial for retrieving a secret from AWS Secrets Manager from a Lambda function created by ACK By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
1 parent 88a9ce8 commit b802a7f

File tree

2 files changed

+396
-0
lines changed

2 files changed

+396
-0
lines changed

‎docs/content/docs/tutorials/lambda-with-secrets-manager.md

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
---
2+
title: "Pass secrets to Lambda Function with AWS Secrets Manager"
3+
description: "Retrieve sensitive information in a Lambda Function from AWS Secrets Manager."
4+
lead: "Retrieve sensitive information in a Lambda Function from AWS Secrets Manager."
5+
draft: false
6+
menu:
7+
docs:
8+
parent: "tutorials"
9+
weight: 43
10+
toc: true
11+
---
12+
13+
The ACK service controller for Amazon Lambda lets you manage Lambda functions directly from Kubernetes.
14+
This guide shows you how to create a Lambda function that can retrieve sensitive data from AWS Secrets Manager.
15+
16+
## Setup
17+
18+
Although it is not necessary to use Amazon Elastic Kubernetes Service (Amazon EKS) or Amazon Elastic Container Registry (Amazon ECR) with ACK, this guide assumes that you
19+
have access to an Amazon EKS cluster. If this is your first time creating an Amazon EKS cluster, see [Amazon EKS Setup][eks-setup]. For automated cluster creation using `eksctl`, see [Getting started with Amazon EKS - `eksctl`](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) and create your cluster with Amazon EC2 Linux managed nodes.
20+
21+
## Prerequisites
22+
23+
This guide assumes that you have:
24+
25+
- Created an EKS cluster with Kubernetes version 1.16 or higher.
26+
- AWS IAM permissions to create roles and attach policies to roles.
27+
- Installed the following tools on the client machine used to access your Kubernetes cluster:
28+
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html) - A command line tool for interacting with AWS services.
29+
- [kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) - A command line tool for working with Kubernetes clusters.
30+
- [eksctl](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html) - A command line tool for working with EKS clusters.
31+
- [Helm 3.8+](https://helm.sh/docs/intro/install/) - A tool for installing and managing Kubernetes applications.
32+
- [jq](https://github.com/stedolan/jq/wiki/Installation)
33+
34+
### Install the Lambda ACK service controller
35+
36+
Log into the Helm registry that stores the ACK charts:
37+
38+
```bash
39+
aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws
40+
```
41+
42+
Deploy the ACK service controller for Amazon Lambda using the [lambda-chart Helm chart](https://gallery.ecr.aws/aws-controllers-k8s/lambda-chart). This example creates resources in the `us-west-2` region, but you can use any other region supported in AWS.
43+
44+
```bash
45+
SERVICE=lambda
46+
RELEASE_VERSION=$(curl -sL https://api.github.com/repos/aws-controllers-k8s/${SERVICE}-controller/releases/latest | jq -r '.tag_name | ltrimstr("v")')
47+
helm install --create-namespace -n ack-system oci://public.ecr.aws/aws-controllers-k8s/lambda-chart "--version=${RELEASE_VERSION}" --generate-name --set=aws.region=us-west-2
48+
```
49+
50+
For a full list of available values to the Helm chart, please [review the values.yaml file](https://github.com/aws-controllers-k8s/lambda-controller/blob/main/helm/values.yaml).
51+
52+
### Configure IAM permissions
53+
54+
Once the service controller is deployed [configure the IAM permissions](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/) for the
55+
controller to invoke the Lambda API. For full details, please review the AWS Controllers for Kubernetes documentation
56+
for [how to configure the IAM permissions](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/). If you follow the examples in the documentation, use the
57+
value of `lambda` for `SERVICE`.
58+
59+
### Create Secret in Secrets Manger
60+
To test our Lambda function's integration with AWS Secrets Manager we'll need to create a sample secret value. We can create a new secret with the aws cli.
61+
62+
```bash
63+
aws secretsmanager create-secret --name test-secret --secret-string "secret value"
64+
```
65+
66+
The ACK Secrets Manager service controller can also be used to create and manage secrets directly from Kubernetes. See, [Create a Secret with AWS Secrets Manager](https://aws-controllers-k8s.github.io/community/docs/tutorials/secrets-manager-example/)
67+
68+
### Create Lambda function handler
69+
The Lambda function handler is the method in your function code that processes events. When your function is invoked, Lambda runs the handler method.
70+
71+
```bash
72+
cat > index.mjs << 'EOF'
73+
import http from 'http';
74+
75+
export const handler = async (event) => {
76+
try {
77+
const secretName = process.env.TEST_SECRET_ARN;
78+
const options = {
79+
hostname: 'localhost',
80+
port: 2773,
81+
path: `/secretsmanager/get?secretId=${secretName}`,
82+
headers: {
83+
'X-Aws-Parameters-Secrets-Token': process.env.AWS_SESSION_TOKEN
84+
}
85+
};
86+
87+
const response = await new Promise((resolve, reject) => {
88+
http.get(options, (res) => {
89+
let data = '';
90+
res.on('data', (chunk) => { data += chunk; });
91+
res.on('end', () => {
92+
resolve({
93+
statusCode: res.statusCode,
94+
body: data
95+
});
96+
});
97+
}).on('error', reject);
98+
});
99+
100+
const secret = JSON.parse(response.body).SecretString;
101+
console.log('Retrieved secret:', secret);
102+
103+
return {
104+
statusCode: response.statusCode,
105+
body: JSON.stringify({
106+
message: 'Successfully retrieved secret',
107+
secretRetrieved: true
108+
})
109+
};
110+
} catch (error) {
111+
console.error('Error:', error);
112+
return {
113+
statusCode: 500,
114+
body: JSON.stringify({
115+
message: 'Error retrieving secret',
116+
error: error.message
117+
})
118+
};
119+
}
120+
};
121+
EOF
122+
```
123+
124+
To package the function handler we then need to add it to a zip file.
125+
126+
```bash
127+
zip -r function.zip index.mjs
128+
```
129+
130+
### Create an IAM Execution Role for the Lambda function
131+
Our Lambda function will need use an execution role that can access the secret in AWS Secrets Manager.
132+
133+
Create the IAM role:
134+
135+
```bash
136+
read -r -d '' TRUST_RELATIONSHIP <<EOF
137+
{
138+
"Version": "2012-10-17",
139+
"Statement": [
140+
{
141+
"Effect": "Allow",
142+
"Principal": {
143+
"Service": "lambda.amazonaws.com"
144+
},
145+
"Action": "sts:AssumeRole"
146+
}
147+
]
148+
}
149+
EOF
150+
echo "${TRUST_RELATIONSHIP}" > trust.json
151+
152+
ACK_LAMBDA_IAM_ROLE="ack-lambda-function"
153+
ACK_LAMBDA_IAM_ROLE_DESCRIPTION="Role for ACK managed Lamdba function"
154+
aws iam create-role --role-name "${ACK_LAMBDA_IAM_ROLE}" --assume-role-policy-document file://trust.json --description "${ACK_LAMBDA_IAM_ROLE_DESCRIPTION}"
155+
ACK_LAMBDA_IAM_ROLE_ARN=$(aws iam get-role --role-name=$ACK_LAMBDA_IAM_ROLE --query Role.Arn --output text)
156+
```
157+
158+
And then attach an IAM Policy that grants read access to our secret.
159+
160+
```bash
161+
SECRET_ARN=$(aws secretsmanager describe-secret --secret-id test-secret | jq ".ARN")
162+
POLICY_NAME=ack-lambda-policy
163+
read -r -d '' POLICY <<EOF
164+
{
165+
"Version": "2012-10-17",
166+
"Statement": [
167+
{
168+
"Effect": "Allow",
169+
"Action": "secretsmanager:GetSecretValue",
170+
"Resource": $SECRET_ARN
171+
}
172+
]
173+
}
174+
EOF
175+
echo "${POLICY}" > policy.json
176+
177+
POLICY_ARN=$(aws iam create-policy --policy-name $POLICY_NAME --policy-document file://policy.json | jq ".Policy.Arn" | tr -d '"')
178+
179+
180+
181+
aws iam attach-role-policy \
182+
--role-name $ACK_LAMBDA_IAM_ROLE \
183+
--policy-arn $POLICY_ARN
184+
```
185+
186+
### Deploy the Lambda Function using the ACK Lambda Controller
187+
The following example creates a manifest that contains the Lambda function with the necessary environment variable and
188+
IAM role to read the secret from AWS Secrets Manager. In order to limit the number of calls made to AWS Secrets Manager the [AWS Parameter and Secrets Lambda extension](https://aws.amazon.com/blogs/compute/using-the-aws-parameter-and-secrets-lambda-extension-to-cache-parameters-and-secrets/) layer is applied.
189+
190+
```bash
191+
BASE64_ZIP=$(cat function.zip | base64)
192+
TEST_SECRET_ARN=$(aws secretsmanager describe-secret --secret-id test-secret | jq ".ARN")
193+
194+
read -r -d '' LAMBDA_MANIFEST <<EOF
195+
apiVersion: lambda.services.k8s.aws/v1alpha1
196+
kind: Function
197+
metadata:
198+
name: sample-lambda
199+
annotations:
200+
services.k8s.aws/region: us-west-2
201+
spec:
202+
name: sample-lambda
203+
environment:
204+
variables:
205+
TEST_SECRET_ARN: $TEST_SECRET_ARN
206+
packageType: Zip
207+
runtime: nodejs18.x
208+
handler: index.handler
209+
code:
210+
zipFile: $BASE64_ZIP
211+
212+
role: $ACK_LAMBDA_IAM_ROLE_ARN
213+
description: Sample function for retrieving secrets from AWS Secrets Manager
214+
layers:
215+
- "arn:aws:lambda:us-west-2:345057560386:layer:AWS-Parameters-and-Secrets-Lambda-Extension:17"
216+
EOF
217+
218+
echo "${LAMBDA_MANIFEST}" > function.yaml
219+
```
220+
221+
```bash
222+
kubectl create -f function.yaml
223+
```
224+
225+
### Invoke the Lambda Function
226+
227+
After the Lambda function has finished deploying, you can invoke the function through the AWS CLI.
228+
229+
```bash
230+
aws lambda invoke --function-name sample-lambda --region us-west-2 /dev/stdout | jq
231+
```
232+
233+
You will get the output as below:
234+
235+
```bash
236+
{"statusCode":200,"body":"\"Successfully retrieved secret!\""}
237+
```
238+
239+
### Cleanup
240+
241+
You can delete you Lambda function using the `kubectl delete` command:
242+
243+
```bash
244+
kubectl delete -f function.yaml
245+
```
246+
247+
The IAM role and policy can removed with the AWS CLI
248+
249+
```bash
250+
aws iam detach-role-policy --role-name $ACK_LAMBDA_IAM_ROLE --policy-arn $POLICY_ARN
251+
aws iam delete-role --role-name $ACK_LAMBDA_IAM_ROLE
252+
aws iam delete-policy --policy-arn $POLICY_ARN
253+
```
254+
255+
We can also delete our secret from AWS Secrets Manager with the AWS CLI
256+
257+
```bash
258+
aws secretsmanager delete-secret --secret-id test-secret
259+
```
260+
261+
To remove the Lambda ACK service controller, related CRDs, and namespaces, see [ACK Cleanup][cleanup].
262+
263+
To delete your EKS clusters, see [Amazon EKS - Deleting a cluster][cleanup-eks].
264+
265+
[eks-setup]: https://docs.aws.amazon.com/deep-learning-containers/latest/devguide/deep-learning-containers-eks-setup.html
266+
[cleanup]: ../../user-docs/cleanup/
267+
[cleanup-eks]: https://docs.aws.amazon.com/eks/latest/userguide/delete-cluster.html
268+

‎docs/content/docs/tutorials/secrets-manager-example.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: "Create a Secret with AWS Secrets Manager"
3+
description: "Use ACK secretsmanger-controller to create and manage secrets directly from Kubernetes. "
4+
lead: "Use ACK secretsmanger-controller to create and manage secrets directly from Kubernetes."
5+
draft: false
6+
menu:
7+
docs:
8+
parent: "tutorials"
9+
weight: 43
10+
toc: true
11+
---
12+
13+
The ACK service controller for AWS Secrets Manager lets you create secrets directly from Kubernetes.
14+
This guide shows you how to create a new secret in AWS Secrets Manager using a reference to a Kubernetes Secret.
15+
16+
## Setup
17+
18+
Although it is not necessary to use Amazon Elastic Kubernetes Service (Amazon EKS) or Amazon Elastic Container Registry (Amazon ECR) with ACK, this guide assumes that you
19+
have access to an Amazon EKS cluster. If this is your first time creating an Amazon EKS cluster, see
20+
[Amazon EKS Setup][eks-setup]. For automated cluster creation using `eksctl`, see [Getting started with Amazon EKS - `eksctl`](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) and create your cluster with Amazon EC2 Linux managed nodes.
21+
22+
## Prerequisites
23+
24+
This guide assumes that you have:
25+
26+
- Created an EKS cluster with Kubernetes version 1.16 or higher.
27+
- AWS IAM permissions to create roles and attach policies to roles.
28+
- Installed the following tools on the client machine used to access your Kubernetes cluster:
29+
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html) - A command line tool for interacting with AWS services.
30+
- [kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) - A command line tool for working with Kubernetes clusters.
31+
- [eksctl](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html) - A command line tool for working with EKS clusters.
32+
- [Helm 3.8+](https://helm.sh/docs/intro/install/) - A tool for installing and managing Kubernetes applications.
33+
34+
### Install the Secrets Manager ACK service controller
35+
36+
Log into the Helm registry that stores the ACK charts:
37+
38+
```bash
39+
aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws
40+
```
41+
42+
Deploy the ACK service controller for AWS Secrets Manager using the [secretsmanager-chart Helm chart](https://gallery.ecr.aws/aws-controllers-k8s/secretsmanager-chart). This example creates resources in the `us-west-2` region, but you can use any other region supported in AWS.
43+
44+
```bash
45+
SERVICE=secretsmanager
46+
RELEASE_VERSION=$(curl -sL https://api.github.com/repos/aws-controllers-k8s/${SERVICE}-controller/releases/latest | jq -r '.tag_name | ltrimstr("v")')
47+
helm install --create-namespace -n ack-system oci://public.ecr.aws/aws-controllers-k8s/secretsmanager-chart "--version=${RELEASE_VERSION}" --generate-name --set=aws.region=us-west-2
48+
```
49+
50+
For a full list of available values to the Helm chart, please [review the values.yaml file](https://github.com/aws-controllers-k8s/secretsmanager-controller/blob/main/helm/values.yaml).
51+
52+
### Configure IAM permissions
53+
54+
Once the service controller is deployed [configure the IAM permissions](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/) for the
55+
controller to invoke the Secrets Manager API. For full details, please review the AWS Controllers for Kubernetes documentation
56+
for [how to configure the IAM permissions](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/). If you follow the examples in the documentation, use the
57+
value of `secretsmanager` for `SERVICE`.
58+
59+
### Create Kubernetes Secret
60+
61+
Now that the ACK secretsmanager-controller is setup we'll need to create a Kubernetes Secret.
62+
63+
```bash
64+
cat <<EOF > secret.yaml
65+
apiVersion: v1
66+
kind: Secret
67+
metadata:
68+
name: my-k8s-secret
69+
namespace: default
70+
type: Opaque
71+
data:
72+
secret: UzNjcjN0UGFzc3cwcmQ= # Base64 encoded "S3cr3tPassw0rd"
73+
EOF
74+
```
75+
76+
```bash
77+
kubectl apply -f secret.yaml
78+
```
79+
80+
### Create ACK Secret
81+
Finally, we'll create an ACK Secret referencing the Kubernetes Secret we just created.
82+
83+
```bash
84+
cat <<EOF > aws-secret.yaml
85+
apiVersion: secretsmanager.services.k8s.aws/v1alpha1
86+
kind: Secret
87+
metadata:
88+
name: my-aws-secret
89+
spec:
90+
name: sample-aws-secret
91+
description: "A sample secret created for demonstration"
92+
secretString:
93+
name: my-k8s-secret
94+
namespace: default
95+
key: secret
96+
EOF
97+
```
98+
99+
```bash
100+
kubectl apply -f aws-secret.yaml
101+
```
102+
103+
You can verify that the secret was created with the AWS CLI.
104+
105+
```bash
106+
aws secretsmanager describe-secret sample-aws-secret
107+
```
108+
109+
### Cleanup
110+
You can delete your ACK and Kubernetes Secrets using the `kubectl delete` command:
111+
112+
```bash
113+
kubectl delete -f secret.yaml && kubectl delete -f aws-secret.yaml
114+
```
115+
116+
To remove the Secrets Manager ACK service controller, related CRDs, and namespaces, see [ACK Cleanup][cleanup].
117+
118+
To delete your EKS clusters, see [Amazon EKS - Deleting a cluster][cleanup-eks].
119+
120+
[eks-setup]: https://docs.aws.amazon.com/deep-learning-containers/latest/devguide/deep-learning-containers-eks-setup.html
121+
[cleanup]: ../../user-docs/cleanup/
122+
[cleanup-eks]: https://docs.aws.amazon.com/eks/latest/userguide/delete-cluster.html
123+
124+
125+
126+
127+
128+

0 commit comments

Comments
 (0)