Skip to content

Commit 4ca4ad7

Browse files
embano1embano1
authored
docs: Add basic SQS tutorial (#1705)
Issue #, if available: #1704 Description of changes: Add basic `SQS` tutorial By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
1 parent a32a2c9 commit 4ca4ad7

File tree

1 file changed

+216
-0
lines changed

1 file changed

+216
-0
lines changed

‎docs/content/docs/tutorials/sqs-example.md

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
title: "Manage SQS queues with the ACK SQS Controller"
3+
description: "Create an SQS queue from an Amazon Elastic Kubernetes Service (EKS) deployment."
4+
lead: "Create and manage an SQS queue directly from Kubernetes"
5+
draft: false
6+
menu:
7+
docs:
8+
parent: "tutorials"
9+
weight: 45
10+
toc: true
11+
---
12+
13+
Amazon Simple Queue Service (SQS) is a fully managed message queuing service for microservices, distributed systems, and
14+
serverless applications. SQS lets you send, store, and receive messages between software components
15+
without losing messages or requiring other services to be available.
16+
17+
In this tutorial you will learn how to create and manage [SQS](https://aws.amazon.com/rds/aurora/serverless/) queues
18+
from an Amazon Elastic Kubernetes (EKS) deployment.
19+
20+
## Setup
21+
22+
Although it is not necessary to use Amazon Elastic Kubernetes Service (Amazon EKS) with ACK, this guide assumes that you
23+
have access to an Amazon EKS cluster. If this is your first time creating an Amazon EKS cluster, see [Amazon EKS
24+
Setup](https://docs.aws.amazon.com/deep-learning-containers/latest/devguide/deep-learning-containers-eks-setup.html).
25+
For automated cluster creation using `eksctl`, see [Getting started with Amazon EKS -
26+
`eksctl`](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) and create your cluster with
27+
Amazon EC2 Linux managed nodes.
28+
29+
### Prerequisites
30+
31+
This guide assumes that you have:
32+
33+
- Created an EKS cluster with Kubernetes version 1.24 or higher.
34+
- AWS IAM permissions to create roles and attach policies to roles.
35+
- AWS IAM permissions to send messages to a queue.
36+
- Installed the following tools on the client machine used to access your Kubernetes cluster:
37+
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html) - A command line tool for interacting
38+
with AWS services.
39+
- [kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) - A command line tool for working
40+
with Kubernetes clusters.
41+
- [eksctl](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html) - A command line tool for working with EKS
42+
clusters.
43+
- [Helm 3.8+](https://helm.sh/docs/intro/install/) - A tool for installing and managing Kubernetes applications.
44+
45+
### Install the ACK service controller for SQS
46+
47+
Log into the Helm registry that stores the ACK charts:
48+
```bash
49+
aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws
50+
```
51+
52+
Deploy the ACK service controller for Amazon SQS using the [sqs-chart Helm chart](https://gallery.ecr.aws/aws-controllers-k8s/sqs-chart). Resources should be created in the `us-east-1` region:
53+
54+
```bash
55+
helm install --create-namespace -n ack-system oci://public.ecr.aws/aws-controllers-k8s/sqs-chart --version=v0.0.3 --generate-name --set=aws.region=us-east-1
56+
```
57+
58+
For a full list of available values to the Helm chart, please [review the values.yaml file](https://github.com/aws-controllers-k8s/sqs-controller/blob/main/helm/values.yaml).
59+
60+
### Configure IAM permissions
61+
62+
Once the service controller is deployed, you will need to [configure the IAM permissions][irsa-permissions] for the
63+
controller to query the SQS API. For full details, please review the AWS Controllers for Kubernetes documentation for
64+
[how to configure the IAM permissions][irsa-permissions]. If you follow the examples in the documentation, use the value
65+
of `sqs` for `SERVICE`.
66+
67+
## Create an SQS Queue
68+
69+
Execute the following command to create a manifest for a basic SQS queue, with an inline policy with `SendMessage`
70+
permissions for the account owner, and submit this manifest to EKS cluster using kubectl.
71+
72+
{{% hint type="info" title="Make sure environment variables are set" %}}
73+
If you followed the steps in the IAM permissions section above, the required environment variables `${AWS_REGION}` and
74+
`${AWS_ACCOUNT_ID}` are already set. Otherwise please set these variables before executing the following steps. The value for `${AWS_REGION}` must also match the `--set=aws.region` value used in the `helm install` command above.
75+
{{% /hint %}}
76+
77+
```bash
78+
QUEUE_NAMESPACE=sqs-example
79+
QUEUE_NAME=basic-sqs
80+
81+
kubectl create ns ${QUEUE_NAMESPACE}
82+
83+
cat <<EOF > basic-sqs-queue.yaml
84+
apiVersion: sqs.services.k8s.aws/v1alpha1
85+
kind: Queue
86+
metadata:
87+
name: ${QUEUE_NAME}
88+
annotations:
89+
services.k8s.aws/region: ${AWS_REGION}
90+
spec:
91+
queueName: ${QUEUE_NAME}
92+
policy: |
93+
{
94+
"Statement": [{
95+
"Sid": "__owner_statement",
96+
"Effect": "Allow",
97+
"Principal": {
98+
"AWS": "${AWS_ACCOUNT_ID}"
99+
},
100+
"Action": "sqs:SendMessage",
101+
"Resource": "arn:aws:sqs:${AWS_REGION}:${AWS_ACCOUNT_ID}:${QUEUE_NAME}"
102+
}]
103+
}
104+
EOF
105+
106+
kubectl -n ${QUEUE_NAMESPACE} create -f basic-sqs-queue.yaml
107+
```
108+
109+
The output of above commands looks like
110+
111+
```
112+
namespace/sqs-example created
113+
queue.sqs.services.k8s.aws/basic-sqs created
114+
```
115+
116+
## Describe SQS Custom Resource
117+
118+
View the SQS custom resource to retrieve the `Queue URL` in the `Status` field
119+
120+
```bash
121+
kubectl -n $QUEUE_NAMESPACE describe queue $QUEUE_NAME
122+
```
123+
124+
The output of above commands looks like
125+
126+
```bash
127+
Name: basic-sqs
128+
Namespace: sqs-example
129+
<snip>
130+
Status:
131+
Ack Resource Metadata:
132+
Arn: arn:aws:sqs:us-east-1:1234567890:basic-sqs
133+
Owner Account ID: 1234567890
134+
Region: us-east-1
135+
Conditions:
136+
Last Transition Time: 2023-02-22T13:31:43Z
137+
Message: Resource synced successfully
138+
Reason:
139+
Status: True
140+
Type: ACK.ResourceSynced
141+
Queue URL: https://sqs.us-east-1.amazonaws.com/1234567890/basic-sqs
142+
Events: <none>
143+
```
144+
145+
Copy and set the Queue URL as an environment variable
146+
147+
```bash
148+
QUEUE_URL=$(kubectl -n $QUEUE_NAMESPACE get queues/basic-sqs -o jsonpath='{.status.queueURL}')
149+
```
150+
151+
## Send a Message
152+
153+
Execute the following command to send a message to the queue
154+
155+
```bash
156+
aws sqs send-message --queue-url ${QUEUE_URL} --message-body "hello from ACK"
157+
```
158+
159+
The output of above commands looks like
160+
161+
```
162+
{
163+
"MD5OfMessageBody": "51e9ec3a483ba8b3159bc5fddcbbf36a",
164+
"MessageId": "281d7695-b066-4a50-853e-1b7c6c65f4a9"
165+
}
166+
```
167+
168+
Verify the message was received with
169+
170+
```bash
171+
aws sqs receive-message --queue-url ${QUEUE_URL}
172+
```
173+
174+
The output of above commands looks like
175+
176+
```
177+
{
178+
"Messages": [
179+
{
180+
"MessageId": "281d7695-b066-4a50-853e-1b7c6c65f4a9",
181+
"ReceiptHandle": "ABCDeFZQxPfbAI201bRkdHZvRWeJUVSFfm2eL/T91L23ltB9nmf0dcx3ALQHz2WsXZhAbThZR+Ns5rX42+OjySNG6pi9Iu/SRZCVuuMzSBXeTrnLo8JjK3h9KE3uUkWirINgXd4fgVR2/C7feI3lCUhMOVhhYhec8ej5EDorL85Ay1IwZ43WYUQ1bIschP6xDvfzHk6vCi3kCXz6ZvPsNH3kTxp1gEvpQsaL/cq+aIZt/d1VVFsHtExbEk32iK1bo39tyA1A3Q7pT2WMowYh6MrfYdHoBw7PxJueGgx9MIQhQge2E+g6rKzGpFN9oPzPx59gu8n8n7Or6oncNM57pESD2LdzWTYjmS5H+Aw74qJ/gAMBIDNVuFt4Wl/5BvJHUTpOSAdi+Jekdbm3+AegzX8qyA==",
182+
"MD5OfBody": "51e9ec3a483ba8b3159bc5fddcbbf36a",
183+
"Body": "hello from ACK"
184+
}
185+
]
186+
```
187+
188+
## Next steps
189+
190+
The ACK service controller for Amazon SQS is based on the [Amazon SQS
191+
API](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Welcome.html).
192+
193+
Refer to [API Reference](https://aws-controllers-k8s.github.io/community/reference/) for *SQS* to find all the supported
194+
Kubernetes custom resources and fields.
195+
196+
### Cleanup
197+
198+
Remove all the resource created in this tutorial using `kubectl delete` command.
199+
200+
```bash
201+
kubectl -n ${QUEUE_NAMESPACE} delete -f basic-sqs-queue.yaml
202+
```
203+
204+
The output of delete command should look like
205+
206+
```bash
207+
queue.sqs.services.k8s.aws "basic-sqs" deleted
208+
```
209+
210+
To remove the SQS ACK service controller, related CRDs, and namespaces, see [ACK Cleanup][cleanup].
211+
212+
To delete your EKS clusters, see [Amazon EKS - Deleting a cluster][cleanup-eks].
213+
214+
[irsa-permissions]: ../../user-docs/irsa/
215+
[cleanup]: ../../user-docs/cleanup/
216+
[cleanup-eks]: https://docs.aws.amazon.com/eks/latest/userguide/delete-cluster.html

0 commit comments

Comments
 (0)