Adding deployment guide

aws-ia · Jul 31, 2023 · 81a878b · 81a878b
1 parent 969de5d
commit 81a878b
Show file tree

Hide file tree

Showing 19 changed files with 66 additions and 38 deletions.
diff --git a/docs/deployment_guide/images/S3_new_object.png b/docs/deployment_guide/images/S3_new_object.png
diff --git a/docs/deployment_guide/images/architecture_diagram.png b/docs/deployment_guide/images/architecture_diagram.png
diff --git a/docs/deployment_guide/images/aws-quickstart-graphic.png b/docs/deployment_guide/images/aws-quickstart-graphic.png
diff --git a/docs/deployment_guide/images/cfn_outputs.png b/docs/deployment_guide/images/cfn_outputs.png
diff --git a/docs/deployment_guide/images/commit_push.png b/docs/deployment_guide/images/commit_push.png
diff --git a/docs/deployment_guide/images/image1.png b/docs/deployment_guide/images/image1.png
diff --git a/docs/deployment_guide/images/image3.png b/docs/deployment_guide/images/image3.png
diff --git a/docs/deployment_guide/images/image4.png b/docs/deployment_guide/images/image4.png
diff --git a/docs/deployment_guide/images/outputs_tab.png b/docs/deployment_guide/images/outputs_tab.png
diff --git a/docs/deployment_guide/images/testfile.png b/docs/deployment_guide/images/testfile.png
diff --git a/docs/deployment_guide/images/using_webhooks.png b/docs/deployment_guide/images/using_webhooks.png
diff --git a/docs/deployment_guide/partner_editable/_settings.adoc b/docs/deployment_guide/partner_editable/_settings.adoc
@@ -1,16 +1,16 @@
 :partner-solution-project-name: partner-solution-repo-name
-:partner-solution-github-org: aws-quickstart
-:partner-product-name: Full Product Name
-:partner-product-short-name: Product Name
-:partner-company-name: Example Company Name, Ltd.
+:partner-solution-github-org: aws-ia
+:partner-product-name: Git webhooks
+:partner-product-short-name: Git webhooks
+//:partner-company-name: Example Company Name, Ltd.
 :doc-month: January
-:doc-year: 2023
+:doc-year: 2021
 :partner-contributors: John Smith, {partner-company-name}
 // :other-contributors: Akua Mansa, Trek10
-:aws-contributors: Janine Singh, AWS IoT Partner team
-:aws-ia-contributors: Toni Jones, AWS Integration & Automation team
+//:aws-contributors: Janine Singh, AWS IoT Partner team
+:aws-ia-contributors: Kirankumar Chandrashekar and Jay McConnell, AWS Integration & Automation team
 :deployment_time: 15 minutes
-:default_deployment_region: us-east-1
+:default_deployment_region: us-east-2
 // :private_repo:
 
 

diff --git a/docs/deployment_guide/partner_editable/architecture.adoc b/docs/deployment_guide/partner_editable/architecture.adoc
@@ -1,28 +1,28 @@
 :xrefstyle: short
 
-Deploying this Partner Solution with default parameters builds the following {partner-product-short-name} environment in the
+Deploying this AWS Solution with default parameters builds the following {partner-product-short-name} environment in the
 AWS Cloud.
 
 // Replace this example diagram with your own. Follow our wiki guidelines: https://w.amazon.com/bin/view/AWS_Quick_Starts/Process_for_PSAs/#HPrepareyourarchitecturediagram. Upload your source PowerPoint file to the GitHub {deployment name}/docs/images/ directory in its repository.
 
-[#architecture1]
-.Partner Solution architecture for {partner-product-short-name} on AWS
-image::../docs/deployment_guide/images/architecture_diagram.png[Architecture]
+[#architecture_diagram]
+.Solution architecture for {partner-product-short-name} on AWS
+[link=images/architecture_diagram.png]
+image::../docs/deployment_guide/images/architecture_diagram.png[architecture_diagram,width=100%,height=100%]
 
-As shown in <<architecture1>>, this Partner Solution sets up the following:
+As shown in <<architecture_diagram>>, this solution sets up the following:
 
-* A highly available architecture that spans two Availability Zones.*
-* A virtual private cloud (VPC) configured with public and private subnets, according to AWS
-best practices, to provide you with your own virtual network on AWS.*
-* In the public subnets:
-** Managed network address translation (NAT) gateways to allow outbound
-internet access for resources in the private subnets.*
-** A Linux bastion host in an Auto Scaling group to allow inbound Secure
-Shell (SSH) access to Amazon Elastic Compute Cloud (Amazon EC2) instances in public and private subnets.*
-* In the private subnets:
-** <item>.
-** <item>.
-// Add bullet points for any additional components that are included in the deployment. Ensure that the additional components are shown in the architecture diagram. End each bullet with a period.
-* <describe any additional components>.
+* Amazon API Gateway to receive Git webhook requests and forward them to AWS Lambda.
+* An AWS Lambda function to process Git webhook requests from API Gateway and invoke an AWS CodeBuild project.
+* An AWS CodeBuild project to connect to your Git service, then retrieve, zip, and upload the latest version of your Git repository to Amazon S3.
+* An AWS Key Management Service (AWS KMS) key to encrypt/decrypt the SSH (Secure Shell) keys used by AWS CodeBuild to connect to your Git repository using SSH. The SSH key pair is generated by a Lambda-backed AWS CloudFormation custom resource when the stack is deployed.
+* Two Amazon S3 buckets: one for Git repository contents, and another for encrypted SSH keys. A Lambda-backed AWS CloudFormation custom resource deletes the contents of the S3 buckets when you delete the CloudFormation stack. If you need backups, copy the S3 buckets before deleting the stack.
 
 [.small]#* The template that deploys this Partner Solution into an existing VPC skips the components marked by asterisks and prompts you for your existing VPC configuration.#
+
+[NOTE]
+========
+* The solution deploys AWS Identity and Access Management (IAM) roles required by Lambda and API Gateway. The inline permissions attached to the roles are scoped using the least-privilege model. For more information, refer to http://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege[Apply least-privilege permissions^].
+* The AWS CodeBuild project must be able to communicate with your Git repository. For example, you can employ a SaaS-based Git service like GitHub to which CodeBuild can connect over the internet.
+* The Git repository S3 bucket this solution deploys has versioning enabled, and all previous versions are retained indefinitely. To modify the retention period, see http://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-lifecycle.html[How do I create a lifecycle rule for an S3 bucket?^]
+========
diff --git a/docs/deployment_guide/partner_editable/deployment_options.adoc b/docs/deployment_guide/partner_editable/deployment_options.adoc
@@ -1,8 +1,5 @@
 // Edit this placeholder text as necessary to describe the deployment options.
 
-This Partner Solution provides the following deployment options:
+This solution provides a single deployment option:
 
-* https://qs_launch_permalink[Deploy {partner-product-short-name} into a new VPC^]. This option builds a new AWS environment that consists of the VPC, subnets, NAT gateways, security groups, bastion hosts, and other infrastructure components. It then deploys {partner-product-short-name} into this new VPC.
-* https://qs_launch_permalink[Deploy {partner-product-short-name} into an existing VPC^]. This option provisions {partner-product-short-name} in your existing AWS infrastructure.
-
-This Partner Solution provides separate templates for these options. It also lets you configure Classless Inter-Domain Routing (CIDR) blocks, instance types, and {partner-product-short-name} settings.
+* https://fwd.aws/mDMrd[Launch the AWS CloudFormation template^] into your AWS account.
diff --git a/docs/deployment_guide/partner_editable/licenses.adoc b/docs/deployment_guide/partner_editable/licenses.adoc
@@ -1,3 +1,9 @@
 // Include details about any licenses and how to sign up. Provide links as appropriate.
 
-There is no cost to use this Partner Solution, but you will be billed for any AWS services or resources that this Partner Solution deploys. For more information, refer to the https://fwd.aws/rA69w?[AWS Partner Solution General Information Guide^].
+There is no cost to use this AWS Solution, but you will be billed for any AWS services or resources that this AWS Solution deploys. For more information, refer to the https://fwd.aws/rA69w?[AWS Partner Solution General Information Guide^].
+
+The solution provides an Amazon API Gateway endpoint, Lambda functions, and an AWS CodeBuild project to access, compress, and upload code to Amazon S3. AWS CodePipeline carries a cost for each active pipeline. For more information, refer to https://aws.amazon.com/codepipeline/pricing/[AWS CodePipeline pricing^].
+
+Depending on your configuration, the solution may deploy an AWS Key Management Service (AWS KMS) key which incurs a monthly cost for key storage and usage. For more information, refer to https://aws.amazon.com/kms/pricing/[AWS Key Management Service pricing^].
+
+API Gateway, Amazon S3, Lambda, and AWS CodeBuild costs vary depending on how often you commit code to the connected Git repository. For more information, refer to https://aws.amazon.com/api-gateway/pricing/[Amazon API Gateway pricing^], https://aws.amazon.com/s3/pricing/[Amazon S3 pricing^], https://aws.amazon.com/lambda/pricing/[AWS Lambda pricing^] and https://aws.amazon.com/codebuild/pricing/[AWS CodeBuild pricing^].
diff --git a/docs/deployment_guide/partner_editable/overview.adoc b/docs/deployment_guide/partner_editable/overview.adoc
@@ -1,7 +1,4 @@
-This guide covers the information you need to deploy the {partner-product-name} Partner Solution in the AWS Cloud.
-
-// Fill in the info in <angle brackets> for use on the landing page only: 
-This Amazon Web Services (AWS) Partner Solution deploys [<product name>](<partner's marketing product page>) in the AWS Cloud so that <purpose>. This solution is for <target users> who want to <do what> so that <why>. For more information, refer to the [<product name> documentation](<URL>).
+This guide covers the information you need to deploy the {partner-product-name} solution in the AWS Cloud.
 
 // Deploying this solution does not guarantee an organization’s compliance with any laws, certifications, policies, or other regulations. [Uncomment this statement only for solutions that relate to compliance. We'll add the corresponding reference part to the landing page and get legal approval before publishing.]
 

diff --git a/docs/deployment_guide/partner_editable/post_deployment.adoc b/docs/deployment_guide/partner_editable/post_deployment.adoc
@@ -1,3 +1,2 @@
 // Include any postdeployment steps here, such as steps necessary to test that the deployment was successful. If there are no postdeployment steps, leave this file empty.
 
-== Postdeployment steps
diff --git a/docs/deployment_guide/partner_editable/pre_deployment.adoc b/docs/deployment_guide/partner_editable/pre_deployment.adoc
@@ -1,3 +1,2 @@
 //Include any predeployment steps here, such as signing up for a Marketplace AMI or making any changes to a partner account. If there are no predeployment steps, leave this file empty.
 
-== Predeployment steps
diff --git a/docs/deployment_guide/partner_editable/troubleshooting.adoc b/docs/deployment_guide/partner_editable/troubleshooting.adoc
@@ -2,5 +2,35 @@
 
 For troubleshooting common Partner Solution issues, refer to the https://fwd.aws/rA69w?[AWS Partner Solution General Information Guide^] and https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html[Troubleshooting CloudFormation^].
 
+If commits to your repository do not show up in Amazon S3, do the following:
+
+* Check the security parameters and endpoint in your Git webhook configuration. See link:#_configuring_git_services[Configuring Git services] earlier in this guide and consult your Git service documentation for help with configuring webhooks.
+* Check the AWS Lambda logs for errors. These are stored in Amazon CloudWatch Logs. For help with accessing them, see https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html[Accessing Amazon CloudWatch logs for AWS Lambda^].
+* Check the AWS CodeBuild project logs for errors. To access them, do the following:
+. Open the AWS CodeBuild console.
+. On the *Build history* page, choose the *Build run* link for the project.
+. On the *Build status* page, see the *Build logs* tab.
+
+== Additional resources
+
+=== AWS services
+
+* https://aws.amazon.com/documentation/cloudformation/[AWS CloudFormation^]
+* https://aws.amazon.com/documentation/lambda/[AWS Lambda^]
+** https://docs.aws.amazon.com/lambda/latest/dg/lambda-troubleshooting.html[Troubleshooting issues in AWS Lambda^]
+* https://aws.amazon.com/documentation/apigateway/[Amazon API Gateway^]
+* https://aws.amazon.com/documentation/s3/[Amazon S3^]
+* https://aws.amazon.com/documentation/codepipeline/[AWS CodePipeline^]
+** http://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-simple-s3.html[Tutorial: Create a simple pipeline (S3 bucket)^]
+* https://aws.amazon.com/documentation/codebuild/[AWS CodeBuild^]
+** https://docs.aws.amazon.com/codebuild/latest/userguide/troubleshooting.html[Troubleshooting AWS CodeBuild^]
+** http://docs.aws.amazon.com/codebuild/latest/userguide/getting-started.html[Getting started with AWS CodeBuild using the console]
+
+=== Webhooks
+
+* https://developer.github.com/v3/repos/hooks/[GitHub Docs: Webhooks^]
+* https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html[BitBucket Support: Manage webhooks^]
+* https://docs.gitlab.com/ce/user/project/integrations/webhooks.html[GitLab Docs: Webhooks^]
+
 // == Resources
 // Uncomment section and add links to any external resources that are specified by the partner.