設定適用於 AWS AppSync GraphQL API 更新的 CI/光碟 - AWS Prescriptive Guidance

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

設定適用於 AWS AppSync GraphQL API 更新的 CI/光碟

由阿波爾瓦·庫爾卡尼 (AWS) 創建

環境:Element PoC 或試驗

技術:現代化;雲端原生;軟體開發與測試;無伺服器;DevOps

工作負載:開放原始碼

AWS 服務:AWS AppSync;AWS CodeBuild;AWS CodePipeline;AWS CloudFormation

Summary

持續整合和持續交付 (CI/CD) 是認識現代應用程式開發價值的關鍵。Amazon Web Services (AWS) 提供多項服務和開放原始碼架構,可協助開發人員快速設定 CI/CD 管道。透過自動化建置、測試和部署,開發人員可以專注於快速提供新功能,而不是維護和保護 CI 伺服器、手動測試其應用程式,以及執行因錯過步驟而容易出錯的應用程式堆疊部署。

此模式示範如何將 CI/CD 最佳實務套用至 AWS AppSync (GraphQL) 後端 API 的開發、測試和部署。該模式建立在 AWS 部落格文章使用 CDK、TypeScript、AWS 應用程式同步、Amazon DynamoDB DynamoDB 和 AWS 蘭姆達在 AWS 上建置可擴展的 GraphQL SQL API。該模式設置了一個 CI/CD 管道,用於將 GraphQL SQL API 更新部署到 AWS AppSync,這是一個完全受管的 GraphQL SQL API 服務。模式使用 AWS Cloud Development Kit (AWS CDK) 管道模組佈建 CI/CD 管道。AWS CodePipeline 使用 AWS CodeBuild 協調原始程式碼的建置和測試,以及使用 AWS CloudFormation 堆疊的部署 AWS 資源,這些堆疊合成為 AWS CDK 程式碼的建置成品。

先決條件和限制

先決條件

  • 作用中的 AWS 帳戶

套件版本

原始程式碼 (附加) 已在開發環境中使用下列套件版本進行測試:

  • 安裝程式

  • Node.js 15.5.0

  • NPM 6.14.10

  • TypeScript 3.9.7

如需其他使用的相依性和程式庫,請參閱package.json在附加的源代碼中。這些依賴關係和庫被安裝為設置開發環境的一部分,如史詩區段。

Architecture

目標技術堆疊

應用程式資源

  • AWS AppSync GraphQL API、GraphQL 結構描述、解析器、API 金鑰、資料來源

  • AWS CloudFormation 堆疊

  • Amazon DynamoDB 資料表

  • AWS Identity and Access Management (IAM) 角色和政策

  • AWS Lambda 功能

管道資源

  • AWS CloudFormation 堆疊

  • AWS CodeBuild 專案

  • AWS CodePipeline 道,

  • IAM 角色和政策

  • AWS Key Management Service (AWS KMS) 金鑰和別名

  • AWS Secrets Manager

  • Amazon Simple Storage Service (Amazon S3) 儲存貯體

目標架構

下圖顯示堆疊更新架構的詳細資料。

自動化和擴展

若要新增目標環境以部署不同帳戶和區域中的應用程式堆疊,請使用pipeline.addApplicationStage()AWS CDK 的 API管道模組。如需跨帳戶部署的詳細資訊,請參閱文件

Tools

工具

  • AWS AppSync— AWS AppSync 提供強大、可擴展的 GraphQL 介面,供應用程式開發人員合併來自多個來源的資料,包括 Amazon DynamoDB 和 AWS Lambda。

  • AWS CLI— AWS Command Line Interface (AWS CLI) 是管理 AWS 服務的統一工具。

  • AWS Cloud Development Kit— AWS Cloud Development Kit (AWS CDK) 是一種軟體開發架構,可在程式碼中定義雲端基礎設施並透過 AWS CloudFormation 進行佈建。

  • AWS CloudFormation— AWS CloudFormation 是一項服務,可協助您建置模型及設定您的 Amazon Web Services 資源。

  • AWS CodeBuild— AWS CodeBuild 是在雲端的全受管組建服務。CodeBuild 可編譯原始碼、執行單元測試,並產生可立即部署的成品。

  • AWS CodePipeline— AWS CodePipeline 是一種持續交付的服務,讓您能夠將發行軟體所需的步驟模型化、視覺化和自動化。

  • Amazon DynamoDB— Amazon DynamoDB 是全受管 NoSQL 資料庫服務,可提供快速且可預期的效能及無縫的可擴展性。

  • AWS Lambda— AWS Lambda 支援執行程式碼,無需佈建或管理伺服器。

  • Node.js 執行時間— Node.js 是一個事件導向的 JavaScript 執行階段環境,專為建置可擴充的網路應用程式而設計。

  • Git 用戶端— Git 用戶端是命令列或桌面工具,用於從 Git 存放庫中檢出必要的成品。

Code

原始碼會以 .zip 檔案格式附加。

Epics

任務描述所需技能
設定工作站。

安裝 Node.js 運行時,AWS CDK,Git 和 TypeScript。

開發人員
安裝 AWS CDK。

若要設定 AWS CDK 的開發環境,請按照AWS CDK 文件

開發人員
為原始程式碼建立 GitHub 儲存庫。

建立名為的新 GitHub 儲存庫cdk-graphql-backend

開發人員
推送密碼

下載附加的 .zip 檔案。在項目目錄中,將 GitHub 存儲庫設置為原點,提交更改並將其推送到原點。 

cd cdk-graphql-backend git init --initial-branch=main git add . git commit -m 'initial commit' git remote add origin https://github.com/<GitHub Org>/cdk-graphql-backend.git git push origin main

開發人員
安裝依存項目。

要安裝引用示例的所有依賴關係,如package.json,請執行npm install命令。

npm install npm run build

開發人員
設定 AWS CLI。

設定 AWS CLI。使用設定檔或環境變數,以便您能夠對 AWS 帳戶發出 AWS CLI 命令。如需詳細資訊,請參閱 AWS 文件

開發人員
建立登入資料。

取得 GitHub 權杖,並建立用於 CodePipeline 整合的 AWS Secrets Manager 密碼。

aws secretsmanager create-secret \ --name GITHUB_TOKEN \ --description "Github Token" \ --secret-string "<Insert Github Oauth Token>"

開發人員
啟動 AWS CDK。

若要啟動 AWS CDK,請使用CDK_NEW_BOOTSTRAP旗標。

env CDK_NEW_BOOTSTRAP=1  cdk bootstrap \  --cloudformation-execution-policies \  arn:aws:iam::aws:policy/AdministratorAccess \  aws://<AWS ACCOUNT ID>/us-west-2

開發人員
任務描述所需技能
建立 GraphQL SQL 架構。

如需建立 GraphQL 結構描述的相關資訊,請參閱AWS 文件

開發人員
建立 AWS AppSync GraphQL API。

使用 AWS CDK 程式碼建立 AWS AppSync API 後端,如原始程式碼所示。

開發人員
建立 Lambda 資料來源。

開發 Lambda 函數,做為查詢和突變的 AWS AppSync 解析器的資料來源。

開發人員
建立 AWS 應用程式同步解析器。

若要將查詢和突變路由到適當的資料來源,請在 AWS AppSync 中建立解析器。

開發人員
建立資料倉庫。

為您的 GraphQL API 建立資料存放區,例如 DynamoDB 表格。

開發人員
任務描述所需技能
建立來源階段。

設置源階段,以便提交可以激活管道。

開發人員
建立建置階段。

設定建置階段以建置 AWS CDK 原始程式碼。此外,建置任何提供做為 AWS AppSync API 資料來源的 Lambda 程式碼。

開發人員
創建單元測試階段。

創建單元測試來測試合成的 CloudFormation 堆棧。包含 Lambda 函數的應用程式單元測試、GraphQL 結構描述驗證等等。

開發人員
建立 Alpha 部署階段。

建立階段,將應用程式堆疊部署至 Alpha 環境,以進一步測試和驗證。

開發人員
建立端對端測試階段。

建立端對端測試以驗證 AWS AppSync GraphQL API 端點會傳回查詢和突變的適當結果。

開發人員
建立生產部署階段。

建立階段,將應用程式堆疊部署至生產環境,供使用者使用。

若要部署管道堆疊,請執行下列命令。

cdk deploy --parameters GitHubOrg=<GitHub Org>

開發人員

其他資訊

測試

單元測試

此範例會示範如何使用 Jest 程式庫的快照測試功能。快照測試案例會呈現堆疊、擷取快照,然後將其與儲存在測試旁的參考快照檔案進行比較。如果兩個快照不相符,測試將會失敗。發生快照不相符的情況,可能是因為變更是未預期的,或因為參考快照必須更新為新版本的堆疊。

test('Snapshot test - AppsyncCdkApp', () => { const stack = new Stack(); // WHEN new AppSyncCdkApp.AppsyncCdkAppStack(stack, 'MyTestConstruct'); // THEN expect(SynthUtils.toCloudFormation(stack)).toMatchSnapshot(); });

更新測試

若要在新增測試案例或變更應用程式堆疊的 AWS CDK 程式碼時更新單元測試,請先更新快照檔案。若要更新快照檔案,請執行下列命令。

$ npm test -- -u --group=unit 

端對端測試

透過其 API 介面測試 AWS AppSync GraphQL API 後端,可讓您最有信心地判斷您的 API 是否如預期般運作給客戶。下列範例示範如何使用Amplify JavaScript 程式庫結合了 Jest 快照測試單元測試區段。您可以使用此方法來執行端對端測試,以模擬 API 用戶端對 Alpha 環境執行作業。

import Amplify, { API } from 'aws-amplify'; Amplify.configure({ aws_appsync_region: process.env.AWS_DEFAULT_REGION, // Stack region aws_appsync_graphqlEndpoint: process.env.API_URL, // AWS AppSync endpoint aws_appsync_authenticationType: "API_KEY", //Primary AWS AppSync authentication type aws_appsync_apiKey: process.env.API_KEY // AppSync API Key }); describe('List Empty Notes', () => { it('List Notes, should be empty', async () => { const query = ` query listNotes { listNotes { id name completed } } ` const response = await API.graphql({ query }); expect(response).toMatchSnapshot(); }); });

更新測試

若要更新端對端測試,在更新graphql結構描述或進行其他變更,請執行下列命令。

$ npm test -- -u --group=e2e

管道階段

成功部署管道之後,可以通過將提交推送到 GitHub 來部署應用程序代碼或管道的進一步更改。以下章節說明管道中不同階段的作用。

Source (來源)

創建與 GitHub 集成一個 webhook,以便任何提交到主分支啟動管道進程。

BUILD

創建一個代 CodeBuild 項目來構建源代碼。AWS CDK 管道模組使用這個階段來合成 CloudFormation 堆疊。此外,在這種模式中,TypeScript Lambda 函數,這是包含在應用程序源代碼中,也被編譯。

UpdatePipeline (自我變異)

透過使用 CloudFormation 變更集的自我變異,將任何變更套用至管線本身。如需詳細資訊,請參閱 AWS CDK管道模組文件

資產

建立 CodeBuild 專案以準備和發佈 AWS CDK 資產。如需詳細資訊,請參閱 AWS CDK管道模組文件

單元測試

創建一個 CodeBuild 項目來運行存在於源代碼中的任何單元測試。此外,您可以使用此階段驗證graphql架構使用graphql-schema-utilities,一個用於驗證和合併的開源軟件包graphql結構描述。

部署 Alpha

使用 CloudFormation 變更集,將佈建應用程式資源 (例如 AWS AppSync、DynamoDB 表格和 Lambda 函數) 的應用程式堆疊部署到 Alpha 環境,您可以在此環境中執行整合測試、端對端測試等。

電子測試

建立 CodeBuild 專案,針對 Alpha 環境執行端對端測試。

部署工程

使用 CloudFormation 變更集,將應用程式資源佈建至生產環境的應用程式堆疊部署。

Attachments

attachment.zip