{"id":26009952,"url":"https://github.com/byu-oit/hw-lambda-api","last_synced_at":"2025-07-25T02:35:30.506Z","repository":{"id":36983895,"uuid":"266179305","full_name":"byu-oit/hw-lambda-api","owner":"byu-oit","description":"Create and deploy an API with Lambda and Terraform on AWS","archived":false,"fork":false,"pushed_at":"2025-07-20T22:22:22.000Z","size":12122,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":22,"default_branch":"prd","last_synced_at":"2025-07-21T00:19:02.584Z","etag":null,"topics":["devops","template"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/byu-oit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-22T18:21:18.000Z","updated_at":"2025-07-20T22:22:23.000Z","dependencies_parsed_at":"2023-02-15T12:16:19.480Z","dependency_job_id":"41083a7d-f635-4346-8f9b-dffac5cee959","html_url":"https://github.com/byu-oit/hw-lambda-api","commit_stats":null,"previous_names":[],"tags_count":3,"template":true,"template_full_name":"byu-oit/hw-fargate-api","purl":"pkg:github/byu-oit/hw-lambda-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fhw-lambda-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fhw-lambda-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fhw-lambda-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fhw-lambda-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byu-oit","download_url":"https://codeload.github.com/byu-oit/hw-lambda-api/tar.gz/refs/heads/prd","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byu-oit%2Fhw-lambda-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266944731,"owners_count":24010488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devops","template"],"created_at":"2025-03-05T22:26:37.408Z","updated_at":"2025-07-25T02:35:30.494Z","avatar_url":"https://github.com/byu-oit.png","language":"HCL","readme":"# hw-lambda-api\nExample of creating and deploying a Lambda API with OpenTofu on AWS\n\n## Prerequisites\n\n* Install [OpenTofu](https://opentofu.org/docs/intro/install/)\n* Install the [AWS CLI](https://aws.amazon.com/cli/)\n* Log into your `dev` account (with [`aws sso login`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sso/login.html))\n* Ensure your account has a [Terraform/OpenTofu State S3 Backend](https://github.com/byu-oit/terraform-aws-backend-s3) deployed\n* If you're outside the [`byu-oit` GitHub organization](https://github.com/byu-oit):\n  * Obtain a DivvyCloud username and password from the Cloud Office at cloudoffice@byu.edu\n\n## Setup\n* Create a new repo [using this template](https://github.com/byu-oit/hw-lambda-api/generate).\n\n  You need your own repo so that you can push changes and have GitHub Actions deploy them.\n  \n  Keep your repo name relatively short. Since we're creating AWS resources based off the name, we've seen [issues with repo names longer than about 24 characters](https://github.com/byu-oit/hw-fargate-api/issues/22).\n\n* Clone your new repo\n```sh\ngit clone https://github.com/byu-oit/my-new-repo\n```\n* Check out the `dev` branch \n```sh\ncd my-new-repo\ngit checkout -b dev\n```\n* Find and replace across the repo:\n  * replace `977306314792` with your `dev` AWS account number\n  * replace `539738229445` with your `prd` AWS account number\n  * replace `hw-lambda-api` with the name of your repo\n  * replace `byu-oit-terraform-dev` with the name of your `dev` AWS account\n  * replace `byu-oit-terraform-prd` with the name of your `prd` AWS account\n  * replace `Codepipeline-Standard-Change` with your [Standard Change Template ID](https://it.byu.edu/nav_to.do?uri=%2Fu_standard_change_template_list.do) - If you need to create a new template, ask in [#servicenow](https://byu-oit.slack.com/archives/C18T2SYTT) for help getting it into the [sandbox ServiceNow environment](https://support-test.byu.edu/)\n* _Rename_ [`.postman/hw-lambda-api.postman_collection.json`](.postman/hw-lambda-api.postman_collection.json) with the name of your repo replacing `hw-lambda-api` in the filename\n* Add yourself (or your team) as a [Dependabot reviewer](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#reviewers) in [`dependabot.yml`](.github/dependabot.yml)\n* Enable [Dependabot Security updates](https://github.com/byu-oit/hw-fargate-api/settings/security_analysis) if you're outside the [`byu-oit` GitHub organization](https://github.com/byu-oit)\n* Commit your changes\n```sh\ngit commit -am \"Update template with repo specific details\" \n```\n\n## Deployment\n\n### Deploy the \"one time setup\" resources\n\n```sh\ncd iac/dev/setup/\ntofu init\ntofu apply\n```\n\nIn the AWS Console, see if you can find the resources from `setup.tf` (SSM Param).\n\n### Push your changes\n\n```sh\ngit push -u origin dev\n```\n\nIf you look at [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml), you'll see that it is set up to run on pushes to the `dev` branch. Because you have already pushed to the `dev` branch, this workflow should be running now.\n\n* In GitHub, click on the workflow run (it has the same name as the last commit message you pushed)\n* Click on the `Build and Deploy` job\n* Expand any of the steps to see what they are doing\n\n### View the deployed application\n\nAnytime after the `Tofu Apply` step succeeds:\n```sh\ncd ../app/\ntofu init\ntofu output\n```\n\nThis will output a DNS Name. Enter this in a browser. You should get a JSON response. Between `index.js` and `main.tf`, can you find what pieces are necessary to make this data available to the app?\n\nIn the AWS Console, see if you can find the other resources from `main.tf`.\n\n### Push a change to your application\n\nMake a small change to `index.js` (try adding a `console.log`, a simple key/value pair to the JSON response, or a new path). Commit and push this change to the `dev` branch.\n\n```sh\ngit commit -am \"try deploying a change\"\ngit push\n```\n\nIn GitHub Actions, watch the deploy steps run (you have a new push, so you'll have to go back and select the new workflow run instance and the job again). Once it gets to the CodeDeploy step, you can watch the deploy happen in the CodeDeploy console in AWS. Once CodeDeploy says that production traffic has been switched over, hit your application in the browser and see if your change worked. If the service is broken, look at you Lambda logs in CloudWatch to see if you can figure out why.\n\n\u003e Note: \n\u003e\n\u003e It's always best to test your changes locally before pushing to GitHub and AWS. Testing locally will significantly increase your productivity as you won't be constantly waiting for GitHub Actions and CodeDeploy to deploy, just to discover bugs.\n\u003e\n\u003e You can either test locally inside Docker, or with Node directly on your computer. Whichever method you choose, you'll have to setup any environment variables that your code is expecting when it runs in AWS. You can find these environment variables in `index.js` and `main.tf`. You'll also have to provide an alternate way of serving your API. Fronting the API code with an express app is a common pattern for local development. Then switching to using the Lambda Handler when deployed in AWS.\n\n## Learn what was built\n\nBy digging through the `.tf` files, you'll see what resources are being created. You should spend some time searching through the AWS Console for each of these resources. The goal is to start making connections between the OpenTofu syntax and the actual AWS resources that are created.\n\nSeveral OIT created Terraform/OpenTofu modules are used. You can look these modules up in our GitHub Organization. There you can see what resources each of these modules creates. You can look those up in the AWS Console too.\n\n\u003c!--TODO add some architecture docs and diagrams --\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyu-oit%2Fhw-lambda-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyu-oit%2Fhw-lambda-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyu-oit%2Fhw-lambda-api/lists"}