Merge pull request #3 from aws-ia/html-guide

Generated deployment guide

.gitmodules

@@ -1,3 +1,15 @@
 [submodule "docs/boilerplate"]
 	path = docs/boilerplate
 	url = https://github.com/aws-ia/aws-ia-documentation-base-common.git
+[submodule "submodules/cfn-ps-aws-vpc"]
+	path = submodules/cfn-ps-aws-vpc
+	url = [email protected]:aws-ia/cfn-ps-aws-vpc.git
+	branch = main
+[submodule "submodules/cfn-ps-microsoft-activedirectory"]
+	path = submodules/cfn-ps-microsoft-activedirectory
+	url = [email protected]:aws-ia/cfn-ps-microsoft-activedirectory.git
+	branch = main
+[submodule "submodules/cfn-ps-microsoft-rdgateway"]
+	path = submodules/cfn-ps-microsoft-rdgateway
+	url = [email protected]:aws-ia/cfn-ps-microsoft-rdgateway.git
+	branch = main

.metadata

@@ -0,0 +1 @@
+language_type: cloudformation

.project_automation/functional_tests/entrypoint.sh

@@ -22,15 +22,15 @@ if echo "${DIFF_OUTPUT}" | grep "^diff --git a/docs/"; then
     asciidoctor --base-dir docs/ --backend=html5 -o ../index.html -w --doctype=book -a toc2 -a production_build docs/boilerplate/index_deployment_guide.adoc
     ## Create PR with index.html file
     CURRENT_BRANCH=$(git branch --show-current)
-    git checkout main
+    # git checkout main
     git checkout -b "${DOCS_BRANCH}"
     git add index.html
     git commit -m '(automated) rendered html deployment guide'
     git push --set-upstream origin "${DOCS_BRANCH}"
     gh pr create --title 'Generated deployment guide' --body "_This is an automated PR with rendered html file for the deployment guide. Please review it before merge_"
 else
     printf '\nNo changes detected in the /docs files. \n'
-fi  
+fi
 
 ##----------------------------------------------------
 ## Download taskcat overrides from AWS Secrets Manager

.project_automation/static_tests/Dockerfile

@@ -1,4 +1,4 @@
 FROM public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:4.0
 RUN git clone https://github.com/aws-quickstart/qs-cfn-lint-rules.git /tmp/qs-cfn-lint-rules
-RUN cd /tmp/qs-cfn-lint-rules && pip install .
-RUN cfn-lint -u
+RUN cd /tmp/qs-cfn-lint-rules && git checkout 8268db9df3407ccf5383def635bc22e0f99d6b39 && pip install .
+#RUN cfn-lint -u

.project_automation/static_tests/entrypoint.sh

@@ -6,4 +6,11 @@ PROJECT_PATH=${BASE_PATH}/project
 PROJECT_TYPE_PATH=${BASE_PATH}/projecttype
 
 cd $PROJECT_PATH
-cfn-lint --non-zero-exit-code none -t templates/**/*.yaml -a /tmp/qs-cfn-lint-rules/qs_cfn_lint_rules/
+
+# Ignoring the following for migration
+# All warnings,
+# E1019 - Sub validation - false positive for conditionals,
+# E2521 - required properties, E3002 - resource properties - false positive for newer resources than pinned CloudFormation resource spec
+# E3005 - DependsOn - false positive for conditionals,
+# E9101 - Inclusive language check - false positive for database resources
+cfn-lint --ignore-checks W,E1019,E2521,E3002,E3005,E9101,E3030,E3031 -t templates/**/*.yaml -a /tmp/qs-cfn-lint-rules/qs_cfn_lint_rules/

.taskcat.yml

@@ -1,33 +1,57 @@
 project:
-  name: cfn-sample-template
-  owner: [email protected]
+  name: cfn-ps-microsoft-sql-fci-fsx
+  owner: quickstart-eng@amazon.com
   package_lambda: false
   regions:
   - ap-northeast-1
   - ap-northeast-2
+  - ap-south-1
   - ap-southeast-1
   - ap-southeast-2
+  - ca-central-1
   - eu-central-1
   - eu-west-1
+  - eu-west-2
   - sa-east-1
   - us-east-1
+  - us-east-2
   - us-west-1
   - us-west-2
+  s3_bucket: ''
 tests:
-  sample:
+  mssql-ec2ad:
     parameters:
-      Param1: 'Inputs to Stack'
-      # Examples: of other taskcat dynamic input parameters for more into see http://taskcat.io
-      #
-      #      AvailabilityZones: $[taskcat_genaz_3]
-      #      ByteValue: 1
-      #      PasswordA: $[taskcat_genpass_8A]
-      #      PasswordB: $[taskcat_genpass_32S]
-      #      RandomNumber: $[taskcat_random-numbers]
-      #      RandomString: $[taskcat_random-string]
-      #      StackName: TestStack
-      #      UUID: $[taskcat_genuuid]
-      #
+      ADScenarioType: 'Microsoft AD on Amazon EC2'
+      AvailabilityZones: $[taskcat_getaz_2]
+      DomainAdminPassword: $[taskcat_genpass_16]
+      EnableAppInsights: 'true'
+      KeyPairName: $[taskcat_getkeypair]
+      QSS3BucketName: $[taskcat_autobucket]
+      QSS3BucketRegion: $[taskcat_current_region]
+      NumberOfRDGWHosts: '0'
+      RDGWCIDR: 0.0.0.0/0
+      SQLServiceAccountPassword: $[taskcat_genpass_16]
+      MSSQLMediaBucketName: override
+      MSSQLMediaPathKey: SQLServer2019-x64-ENU.iso
+    regions:
+    - us-east-1
+    s3_bucket: ''
+    template: templates/mssqlfsx-main.template.yaml
+  mssql-mad:
+    parameters:
+      ADScenarioType: 'AWS Directory Service for Microsoft AD (Enterprise Edition)'
+      AvailabilityZones: $[taskcat_getaz_2]
+      DomainAdminPassword: $[taskcat_genpass_16]
+      EnableAppInsights: 'true'
+      KeyPairName: $[taskcat_getkeypair]
+      QSS3BucketName: $[taskcat_autobucket]
+      QSS3BucketRegion: $[taskcat_current_region]
+      NumberOfRDGWHosts: '0'
+      RDGWCIDR: 0.0.0.0/0
+      SQLServiceAccountPassword: $[taskcat_genpass_16]
+      MSSQLMediaBucketName: override
+      MSSQLMediaPathKey: SQLServer2019-x64-ENU.iso
     regions:
     - us-east-2
-    template: templates/another-workload.template.yaml
+    s3_bucket: ''
+    template: templates/mssqlfsx-main.template.yaml

README.md

@@ -0,0 +1,7 @@
+## SQL Server Failover Cluster Instance on AWS—Quick Start
+
+For architectural details, step-by-step instructions, and customization options, see the [deployment guide](https://fwd.aws/5XG6A?).
+
+To post feedback, submit feature ideas, or report bugs, use the **Issues** section of this GitHub repo. 
+
+To submit code for this Quick Start, see the [AWS Quick Start Contributor's Kit](https://aws-quickstart.github.io/).

docs/deployment_guide/partner_editable/_settings.adoc

@@ -1,15 +1,15 @@
-: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.
-:doc-month: January
+:partner-solution-project-name: cfn-ps-microsoft-sql-fci-fsx
+:partner-solution-github-org: aws-ia
+:partner-product-name: SQL Server Failover Cluster Instance
+:partner-product-short-name: SQL Server FCI
+//:partner-company-name: Example Company Name, Ltd.
+:doc-month: August
 :doc-year: 2023
-:partner-contributors: John Smith, {partner-company-name}
+//: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
-:deployment_time: 15 minutes
+:aws-contributors: Sepehr Samiei and Garry Singh, AWS Microsoft Tech Specialist Solutions Architect team
+:aws-ia-contributors: Dave May, AWS Integration & Automation team
+:deployment_time: 2.25 hours
 :default_deployment_region: us-east-1
 // :private_repo:
 

docs/deployment_guide/partner_editable/architecture.adoc

@@ -7,22 +7,46 @@ AWS Cloud.
 
 [#architecture1]
 .Partner Solution architecture for {partner-product-short-name} on AWS
-image::../docs/deployment_guide/images/architecture_diagram.png[Architecture]
+image::../docs/deployment_guide/images/ms-sql-fci-fsx-architecture_diagram.png[architecture1,90%]
 
 As shown in <<architecture1>>, this Partner 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.*
+* A 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.*
+** Managed network address translation (NAT) gateways to allow outbound internet access for resources in the private subnets.*
+** A Remote Desktop Gateway (RD Gateway) host in an Auto Scaling group to allow inbound Remote Desktop Protocol (RDP) access to 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>.
+** Two EC2 instances running Microsoft Windows with SQL Server. These instances are installed as nodes in a WSFC cluster in an Always On FCI configuration across the Availability Zones. Each node contains an Amazon Elastic Block Store (Amazon EBS) root volume.
+* An Amazon FSx file system, which the FCI nodes share. SQL Server is installed in this file system. This file system also stores all SQL database and log files, and it acts as the WSFC cluster's file-share witness.*
+* AWS Directory Service with a managed directory. The Amazon FSx file system and the EC2 Windows instances that host this architecture's nodes are joined to the same Active Directory domain.
+* AWS Secrets Manager keys to store credentials.
+* An AWS Systems Manager automation document to automate the deployment.
 
-[.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.#
+[.small]#*The template that deploys the Partner Solution into an existing VPC skips the components marked by asterisks and prompts you for your existing VPC configuration.#
+
+=== Comparison with SQL Server with Always On Replication ===
+
+To better understand the architecture of the {partner-product-short-name} Partner Solution, it's helpful to compare with the https://fwd.aws/KEvrk?/[Partner Solution for SQL Server with Always On Replication^]. Both Partner Solutions are architected to ensure high availability. Both have EC2 instances clustered using WSFC. Both have database files stored in multiple Availability Zones. What's different is the way each Partner Solution accomplishes database high availability.
+
+The replication-based architecture requires a full installation of SQL Server (Standard or Enterprise edition) on each EC2 instance. Therefore, each EC2 instance requires a SQL Server license.
+
+*What makes the FCI-based architecture unique is that it requires only one SQL Server license.* With FCI, database-related files aren't replicated across the WSFC cluster, and SQL Server is not installed in the local file systems. Instead, this Partner Solution creates an Amazon FSx file system and installs SQL Server there. The EC2 instances (FCI nodes) share this file system, which also stores all the SQL database files and log files. In addition, this shared file system acts as the cluster's file-share witness. 
+
+=== Advantages and disadvantages ===
+The architecture of each SQL Server Partner Solution has advantages and disadvantages.
+
+*SQL Server with Always On Replication Partner Solution:*
+
+* Advantages: 
+** The EBS volume type, capacity, and IOPS can be configured, allowing flexibility.
+** It supports both AWS-provided licensing and Bring Your Own License models for Microsoft SQL.
+* Disadvantage: 
+** Each WSFC node with SQL Server installed requires a SQL Server license, increasing cost.
+
+*{partner-product-short-name} Partner Solution:*
+
+* Advantage: It requires only one SQL Server license.
+* Disadvantages:
+** It relies on an Amazon FSx Multi-AZ file system, which is not supported in all AWS Regions.
+** It requires the customer to provide a SQL Server .iso file and license since AWS-provided SQL licensing is not supported.

docs/deployment_guide/partner_editable/deployment_options.adoc

@@ -2,7 +2,8 @@
 
 This Partner Solution provides the following deployment options:
 
-* 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.
+* https://fwd.aws/KmBKD?[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://fwd.aws/6JaVw?[Deploy into an existing VPC with AWS Managed Microsoft AD^]. This option provisions {partner-product-short-name} in your existing AWS infrastructure.
+* https://fwd.aws/x5n57?[Deploy into an existing VPC with self-managed Active Directory^]. 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.

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 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^].
+
+This Quick Start requires a license for Microsoft SQL Server 2019. You can obtain a trial license from the https://www.microsoft.com/en-us/evalcenter/evaluate-sql-server-2019[Microsoft Evaluation Center^]. 
+
+Alternatively, if you're not using the software for a production environment, you can use the MSSQL Developer Edition. This edition provides the full capabilities of Enterprise Edition without requiring license costs. 
+
+This Quick Start deploys MSSQL in Bring-Your-Own-License mode. It does not support deployment of MSSQL license-included Amazon Machine Images (AMIs).

docs/deployment_guide/partner_editable/overview.adoc

@@ -1,10 +1,33 @@
-This guide covers the information you need to deploy the {partner-product-name} Partner Solution in the AWS Cloud.
+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 Partner Solution is for IT infrastructure architects, database administrators, and DevOps professionals who plan to implement or extend Microsoft SQL Server (MSSQL) using SQL Server on AWS with Windows Server Failover Clustering (WSFC). Unlike the Partner Solution for https://aws.amazon.com/quickstart/architecture/sql/[SQL Server with Always On Replication^], this one deploys an https://docs.microsoft.com/en-us/sql/sql-server/failover-clusters/windows/always-on-failover-cluster-instances-sql-server?view=sql-server-ver15[Always On Failover Cluster Instance^] (FCI). It also deploys https://aws.amazon.com/fsx/windows/[Amazon FSx for Windows File Server^] as a network share to store the database files.
 
-// 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.]
+This guide does not provide general configuration and usage information for WSFC and MSSQL. For general guidance and best practices, consult the Microsoft product documentation and the https://d1.awsstatic.com/whitepapers/best-practices-for-deploying-microsoft-sql-server-on-aws.pdf[Best Practices for Deploying Microsoft SQL Server on AWS^] whitepaper.
 
-// For advanced information about the product, troubleshooting, or additional functionality, refer to the https://{partner-solution-github-org}.github.io/{partner-solution-project-name}/operational/index.html[Operational Guide^].
+:xrefstyle: short
 
-// For information about using this Partner Solution for migrations, refer to the https://{partner-solution-github-org}.github.io/{partner-solution-project-name}/migration/index.html[Migration Guide^].
+The {partner-product-short-name} Partner Solution deploys a highly available environment that includes Windows Server and SQL Server running on Amazon Elastic Compute Cloud (EC2). It requires shared storage that is accessible by all nodes within the WSFC cluster. It supports SQL Server 2019 running on Windows Server 2019.
+
+This architecture uses a highly available Multi-AZ Amazon FSx file system as the network share used to store MSSQL database files. The Amazon FSx file system and EC2 Windows instances that host this architecture's nodes are joined to the same Active Directory domain.
+
+NOTE: The "instance" in "failover cluster instance" means something different from the "instance" in "EC2 instance." In this Partner Solution, a failover cluster instance, or FCI, has the appearance of an instance of SQL Server running on a single computer. A failover cluster instance provides failover from one EC2 instance (WSFC node) to another if the current EC2 instance goes down. For an illustration, see <<architecture1>>.
+
+Traditionally, FCIs have been difficult to deploy and manage. With its Multi-AZ file system option, Amazon FSx provides fully managed file storage. This storage enables the high availability and durability that's required to run business-critical Microsoft SQL Server database workloads without requiring licenses for each server. Amazon FSx automatically handles failover, simplifying shared storage to host your database deployments while reducing cost.
+
+The automation in this deployment uses AWS Systems Manager Automation, AWS CloudFormation, and   Windows PowerShell Desired State Configuration (DSC) to deploy a multi-node SQL Always On FCI. Windows Server Failover Clustering is a prerequisite for deploying an Always On FCI. MSSQL uses WSFC to increase application availability. WSFC provides infrastructure features that complement the high availability and disaster recovery scenarios supported in the AWS Cloud.
+
+FCI, which was introduced with SQL Server 2008 as a high availability feature, continues to be available in all newer versions of MSSQL. When used on premises, SQL Server FCI is often used purely for high availability within a single data center. On AWS, you can use the {partner-product-short-name} Partner Solution to cover both high availability and disaster recovery requirements.
+
+Since FCIs require shared storage, traditionally they had to be deployed within a single data center. On AWS, the shared storage can span multiple Availability Zones, enabling WSFC clusters to span multiple Availability Zones.
+
+Implementing WSFC on AWS is similar to deploying it on premises as long as you meet these two requirements:
+
+* The cluster nodes are deployed inside a virtual private cloud (VPC).
+* The cluster nodes are deployed in separate subnets to provide high availability across multiple Availability Zones.
+
+This Partner Solution meets these requirements.
+
+For more information:
+
+* https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html[What Is Amazon FSx for Windows File Server?^]
+* https://docs.aws.amazon.com/fsx/latest/WindowsGuide/sql-server.html[Using Amazon FSx for Windows File Server with Microsoft SQL Server^]