Add cloud pods collaborative debugging tutorial by tinyg210 · Pull Request #1126 · localstack/docs

tinyg210 · 2024-03-16T14:30:03Z

Add tutorial for using cloud pods for collaborative development and debugging in teams

github-actions · 2024-03-16T14:30:13Z

🎊 PR Preview has been successfully built and deployed to https://localstack-docs-preview-pr-1126.surge.sh 🎊

giograno

Kudos for the tutorial 💯
I have only one question (I don't have a strong opinion about this, but it just came to mind). Since this is a tutorial on collaborative debugging, do you think adding the s3 and ORAS remotes is a bit too much? It's definitively good content, but I am wondering if it makes sense to separate it.

giograno · 2024-03-19T22:22:44Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+  load      Load the state of a Cloud Pod into the application runtime/ Users can import Cloud Pods from...
+  remote    Manage cloud pod remotes
+  save      Create a new Cloud Pod
+  versions  List all available versions for a Cloud Pod


for is colored differently. Any idea why? Maybe we should use console or shell?

whummer

Kudos for this tutorial @tinyg210 - great to see that we're adding some stories and explicit guidance for how users can address collaborative debugging with pods! 🎉

I have some comments and suggestions - high level thoughts/summary:

I generally find the narrative writing style (painting a storyline for the scenario, being a bit witty in a few places, adding a "personal touch" to the text) quite refreshing, but at the same time it can be challenging to stay concise and specific, making it harder to follow. I guess adopting a slightly more neutral and factual writing style could help making the content a bit easier to consume (also, it is hard to make assumptions about the level of maturity/experience of the audience - some readers may understand the context of the more witty parts, others may not)
To focus more on the collaboration part, would it make sense to include a small figure that illustrates the actual personas involved in the scenario? This would allow us to give them explicit names, and consistently refer to the specific person/persona throughout the document. (that could make it easier to follow, rather than referring to different colleagues, team members, etc)
Maybe we could slightly expand the scenario with more usage of pods, for example the team member helping with debugging could create the fix, push the cloud pod with the same name (to create version 2), which the other team member can then check out to reproduce the fix (this could nicely illustrate the concept of versioning). Also, stretch goal - can we think of any third role/persona that could come into play here? (Don't have an explicit example in mind, but 3 is often a good number :) )
Agree with @giograno regarding the sections about alternative cloud pod remotes. Maybe mentioning the S3 remote is helpful, but adding ORAS as well definitely seems like a bit of "overkill". This is generally good content (!) - but could we maybe move this somewhere else in our docs? This would allow us to keep the focus on the collaboration & debugging parts in this tutorial. (We can still mention in a paragraph that alternative storage options are available to enterprise customers, but maybe no need to dedicate entire sections to it in here.)

Hope that helps - please let me know if anything is unclear, also happy to discuss/brainstorm the points directly in more detail..!

whummer · 2024-03-20T15:13:12Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+- Basic understanding of Terraform for provisioning AWS resources
+
+So let’s say a new colleague joins, clones the application repository, and starts working on the Lambda code. They will add the necessary 
+resources in the Terraform configuration file and some IAM policies that the functions need to be allowed to access the database (after all,


after all, they’re following good practices

Not sure what the reference is here - what would be an alternative solution (not following good practice) for the Lambda to access a DynamoDB table? :) (Presumably we're referring to running LS without IAM enforcement (?), but not sure this is becoming clear from the context here..)

My thought was to mention this to highlight the granularity of IAM policy enforcement. This is the opposite of Action = ["dynamodb: *"]. I'm sure there are apps out there that go to production with terrible security policies 😄
I guess it sounded better in my head and it needs some elaborating.

whummer · 2024-03-20T15:22:14Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+}
+```
+
+The new teammate working on this has mistakenly used `dynamodb:Scan` and `dynamodb:Query` as a replacement.


Suggested change

The new teammate working on this has mistakenly used `dynamodb:Scan` and `dynamodb:Query` as a replacement.

The new teammate working on this application has mistakenly used `dynamodb:Scan` and `dynamodb:Query`, but missed adding the `dynamodb:GetItem` action to the policy document above.

whummer · 2024-03-20T15:37:03Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+An `Internal server error⏎`  does not give out too much information. The new colleague doesn’t know for sure what could be 
+causing this. The Lambda code looks fine, the configurations also look ok.
+
+# **Using Cloud Pods for fast collaborative debugging**


nit: maybe we could remove the term "fast" here? (we already have lots of other tutorials that are focusing on the speed/velocity aspect, whereas here the focus is really on debugging&collaboration..)

whummer · 2024-03-20T15:40:40Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+Services: sts,iam,apigateway,dynamodb,lambda,s3,cloudwatch,logs
+```
+
+LocalStack provides a remote storage backend that can be used to store the state of your application and share it with your team members.


Suggested change

LocalStack provides a remote storage backend that can be used to store the state of your application and share it with your team members.

LocalStack provides a managed storage backend that can be used to store the state of your application and share it with your team members.

whummer · 2024-03-20T15:42:14Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+  delete    Delete a Cloud Pod
+  list      List all available Cloud Pods
+  load      Load the state of a Cloud Pod into the application runtime/ Users can import Cloud Pods from...
+  remote    Manage cloud pod remotes


nit: I understand you simply copied the CLI output here, but maybe we can slightly adjust it here, for consistency: 👍

Suggested change

remote Manage cloud pod remotes

remote Manage Cloud Pod remotes

whummer · 2024-03-20T15:43:12Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+Commands:
+  delete    Delete a Cloud Pod
+  list      List all available Cloud Pods
+  load      Load the state of a Cloud Pod into the application runtime/ Users can import Cloud Pods from...


Suggested change

load Load the state of a Cloud Pod into the application runtime/ Users can import Cloud Pods from...

load Load the state of a Cloud Pod into the application runtime

whummer · 2024-03-20T15:45:45Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+Now, in a fresh LocalStack instance, the helper colleague can immediately load the Cloud Pod, because they’re part of the 
+same organization, and their licences permit this:


Not sure if "helper colleague" is a very common term? How about something like:

Suggested change

Now, in a fresh LocalStack instance, the helper colleague can immediately load the Cloud Pod, because they’re part of the

same organization, and their licences permit this:

Now, other team members can load this Cloud Pod into their own LocalStack instances - this sharing

works by default, as they’re part of the same organization:

Overall, I think when we speak about collaboration as a central concept, perhaps it would make sense to include a short diagram at the beginning of the post that illustrates the persons/roles involved, and how they are collaborating as part of this tutorial? 🤔

whummer · 2024-03-20T15:53:56Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+Not only can someone else easily reproduce the bug now, but they also have access to the state and data of the services 
+involved, meaning that the Lambda logs are still in the CloudWatch log groups.


Related to the comment above - I think from the storyline it would make sense to explicitly introduce the persons involved (say, team member A and B, or Alice and Bob, or similar...), and then reference them here directly.

Something like:

After loading the Cloud Pod state, Bob can now easily reproduce the bug on their local machine, and also has access to the state and data of the services involved, meaning that the Lambda logs are available in the CloudWatch log groups.

whummer · 2024-03-20T15:56:24Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+At a first glance, this error points to a permissions issue related to accessing DynamoDB. The action **`dynamodb:GetItem`** is 
+not authorized for the role, preventing the retrieval of a product by its ID. This kind of error was not really foreseen as one 


Suggested change

At a first glance, this error points to a permissions issue related to accessing DynamoDB. The action **`dynamodb:GetItem`** is

not authorized for the role, preventing the retrieval of a product by its ID. This kind of error was not really foreseen as one

At a first glance, this error points to a permissions issue related to accessing DynamoDB. The action **`dynamodb:GetItem`** is

not included in the policy of the Lambda execution role, preventing the retrieval of a product by its ID. This kind of error was not really foreseen as one

tinyg210 · 2024-03-26T17:58:44Z

Hey @whummer and @giograno, thanks for the feedback! This is definitely valuable input, and here's my plan to address your comments:

I will remove the last part related to S3 storage and ORAS and reuse the content for a stack byte; in this article, I will only mention the extra possibilities + link to the docs for more info.
I'll make the writing more clear, with a more neutral tone, to make it easier to read (plus all the other suggestions); I will, however, keep the story, as this is a pretty specific use case.
I'll introduce a diagram to illustrate the flow between Alice and Bob for the collaboration.
After Bob experiences the misconfiguration, Alice can use the AWS CLI to fix the missing action in the policy and save the cloud pod (creating v2). Bob will pull the latest version of the cloud pod, use the AWS CLI to view the updated policy, and then make the fix in the Terraform config file. So Bob will push his own fix.
A third person, Carol, can pull the fixed cloud pod and write integration tests (Bob is only in charge of his own unit tests).

Btw, my initial thought was to have a bug related to bad configuration for the API-Lambda integration (using HTTP GET, instead of POST). At that time, this was not working as expected in LS, but it has since been fixed (localstack/localstack#10473) hehe. I still think the IAM policy enforcement is more important to highlight though.

Please let me know if you'd like to add/remove anything from the new approach (or if I missed anything). Otherwise, I'll be back soon with some fixes.

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

HarshCasper · 2024-04-26T18:01:18Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+### Nice to have
+
+- Basic knowledge of AWS services (API Gateway, Lambda, DynamoDB, IAM)
+- Basic understanding of Terraform for provisioning AWS resources


Can we add this to the previous section itself?

HarshCasper · 2024-04-26T18:01:44Z

content/en/tutorials/cloud-pods-collaborative-debugging/index.md

+
+### Starting LocalStack
+
+In the root directory, there is a `docker-compose.yml` file that will spin up version 3.3.0 of LocalStack, with an 


Any reason for picking a specific version?

it was the latest version at that time. if cloud pods change for future versions i won't go back to change this material

Co-authored-by: Harsh Mishra <erbeusgriffincasper@gmail.com>

…ugging_tutorial' into add_cloud_pods_collaborative_debugging_tutorial

tinyg210 added 2 commits March 15, 2024 15:17

add tutorial for cloud pod collaborative dev & debugging

3bb0ea0

small fixes

1318e34

tinyg210 requested review from HarshCasper, giograno and whummer March 16, 2024 14:30

fix reference errors + tags in new totorial

2c13213

giograno approved these changes Mar 19, 2024

View reviewed changes

whummer reviewed Mar 20, 2024

View reviewed changes

tinyg210 added 3 commits April 17, 2024 12:51

Merge branch 'main' into add_cloud_pods_collaborative_debugging_tutorial

c43b4b4

address PR reviews

d18f951

fix minor aesthetic things

8bd04b8

HarshCasper suggested changes Apr 26, 2024

View reviewed changes

tinyg210 and others added 4 commits April 26, 2024 11:05

Update content/en/tutorials/cloud-pods-collaborative-debugging/index.md

c81e840

Co-authored-by: Harsh Mishra <erbeusgriffincasper@gmail.com>

extra PR fixes

7709e12

Merge remote-tracking branch 'origin/add_cloud_pods_collaborative_deb…

d81196a

…ugging_tutorial' into add_cloud_pods_collaborative_debugging_tutorial

fix disable copy tag

c7416a7

tinyg210 requested a review from HarshCasper April 26, 2024 18:22

remove unused images

def7744

HarshCasper approved these changes Apr 29, 2024

View reviewed changes

tinyg210 merged commit cc78821 into main Apr 30, 2024

tinyg210 deleted the add_cloud_pods_collaborative_debugging_tutorial branch April 30, 2024 03:37

	The new teammate working on this has mistakenly used `dynamodb:Scan` and `dynamodb:Query` as a replacement.
	The new teammate working on this application has mistakenly used `dynamodb:Scan` and `dynamodb:Query`, but missed adding the `dynamodb:GetItem` action to the policy document above.

	LocalStack provides a remote storage backend that can be used to store the state of your application and share it with your team members.
	LocalStack provides a managed storage backend that can be used to store the state of your application and share it with your team members.

	remote Manage cloud pod remotes
	remote Manage Cloud Pod remotes

	load Load the state of a Cloud Pod into the application runtime/ Users can import Cloud Pods from...
	load Load the state of a Cloud Pod into the application runtime

		Now, in a fresh LocalStack instance, the helper colleague can immediately load the Cloud Pod, because they’re part of the
		same organization, and their licences permit this:

		Not only can someone else easily reproduce the bug now, but they also have access to the state and data of the services
		involved, meaning that the Lambda logs are still in the CloudWatch log groups.

		At a first glance, this error points to a permissions issue related to accessing DynamoDB. The action `dynamodb:GetItem` is
		not authorized for the role, preventing the retrieval of a product by its ID. This kind of error was not really foreseen as one


		### Starting LocalStack

		In the root directory, there is a `docker-compose.yml` file that will spin up version 3.3.0 of LocalStack, with an

Conversation

tinyg210 commented Mar 16, 2024

Uh oh!

github-actions bot commented Mar 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giograno left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

whummer left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

whummer Mar 20, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

whummer Mar 20, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tinyg210 commented Mar 26, 2024

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Mar 16, 2024 •

edited

Loading

whummer left a comment •

edited

Loading

whummer Mar 20, 2024 •

edited

Loading

whummer Mar 20, 2024 •

edited

Loading