Doc edits

.gitmodules

@@ -1,4 +1,3 @@
-[submodule "submodules/quickstart-aws-vpc"]
-	path = submodules/quickstart-aws-vpc
-	url = ../../aws-quickstart/quickstart-aws-vpc.git 
-	branch = master
+[submodule "docs/boilerplate"]
+	path = docs/boilerplate
+	url = https://github.com/aws-ia/aws-ia-documentation-base-common.git

README.md

@@ -1,37 +1,37 @@
-# Splunk Enterprise on AWS - Quick Start
-
-Source code associated with [Splunk Enterprise AWS Quick Start](https://fwd.aws/r7QNJ)
-
-## Usage
-
-Use these templates to deploy a highly available Splunk Enterprise environment across multiple AZs (2 or 3) in a given AWS region.
-AZ-aware indexer clustering is enabled for horizontal scaling and to guarantee data is replicated in every AZ.
-AZ-aware Search head clustering (3 nodes by default) can also be enabled for horizontal scaling and to guarantee data is available for search in every AZ.
-
-View the accompanying [deployment guide](https://fwd.aws/bGBmy) for everything you need to get started. Refer to 'Deployment Steps' section for a step-by-step walkthrough on how to use these templates in AWS console.
-
-### Prerequisites
-
-Before getting started with the template configuration, you will need to make your Splunk Enterprise license privately accessible for CloudFormation template deployment via S3 download.  The following steps will guide you through that process.   *(Note:  This step is not required, and you can upload your license from the Splunk web interface.  It is, however, required that you have a non-trial Splunk Enterprise license to fully utilize the deployment our template creates.  If you don't already have a Splunk Enterprise license, you can obtain one by contacting sales@splunk.com.)*
-
- 1. From the AWS Console, select "S3" under the "Storage" heading, or by simply typing "S3" into the search bar.
- 2. You can either select an existing private bucket to upload to, or create a new one. If you select an existing bucket, make sure its access policy does not grant public access. By default, all the S3 resources are private, so only the AWS account that created the resources can access them. For this exercise, I'm outlining how to create a new bucket.
- 3. Click "create bucket"
- 4. Name your bucket, and select your region.  In this example, I will use "bbartlett-splunk-config".  Your bucket name must be unique, and you should select the same region where you plan on deploying Splunk. <br><br> ![new bucket example](https://s3-us-west-2.amazonaws.com/splk-bbartlett/splunk_newbucket.png) <br><br>
- 5. Once you've created your bucket, select your new bucket from the list of buckets.
- 6. Click "Upload" on the upper left of the page
- 7. Click "Add Files"
- 8. Select your license file.
- 9. Click "Start Upload" on the lower right of the page.
- 10. Once the license has finished uploading, you'll need the bucket name and the filename to use with the CloudFormation template.
-
-## License
-
-This project is licensed under Apache License 2.0 - see [LICENSE.txt](./LICENSE.txt) file for details
-
-## Help
-
-If you have any problems or general questions, please file an issue in the parent repository:
-https://github.com/aws-quickstart/quickstart-splunk-enterprise/issues
-
-
+# Splunk Enterprise on AWS - Quick Start
+
+Source code associated with [Splunk Enterprise AWS Quick Start](https://fwd.aws/r7QNJ)
+
+## Usage
+
+Use these templates to deploy a highly available Splunk Enterprise environment across multiple AZs (2 or 3) in a given AWS region.
+AZ-aware indexer clustering is enabled for horizontal scaling and to guarantee data is replicated in every AZ.
+AZ-aware Search head clustering (3 nodes by default) can also be enabled for horizontal scaling and to guarantee data is available for search in every AZ.
+
+View the accompanying [deployment guide](https://fwd.aws/bGBmy) for everything you need to get started. Refer to 'Deployment Steps' section for a step-by-step walkthrough on how to use these templates in AWS console.
+
+### Prerequisites
+
+Before getting started with the template configuration, you will need to make your Splunk Enterprise license privately accessible for CloudFormation template deployment via S3 download.  The following steps will guide you through that process.   *(Note:  This step is required.  A non-trial Splunk Enterprise license is required to allow our template to configure the Splunk deployment.  If you don't already have a Splunk Enterprise license, you can obtain one by contacting sales@splunk.com.)*
+
+ 1. From the AWS Console, select "S3" under the "Storage" heading, or by simply typing "S3" into the search bar.
+ 2. You can either select an existing private bucket to upload to, or create a new one. If you select an existing bucket, make sure its access policy does not grant public access. By default, all the S3 resources are private, so only the AWS account that created the resources can access them. For this exercise, I'm outlining how to create a new bucket.
+ 3. Click "create bucket"
+ 4. Name your bucket, and select your region.  In this example, I will use "bbartlett-splunk-config".  Your bucket name must be unique, and you should select the same region where you plan on deploying Splunk. <br><br> ![new bucket example](https://s3-us-west-2.amazonaws.com/splk-bbartlett/splunk_newbucket.png) <br><br>
+ 5. Once you've created your bucket, select your new bucket from the list of buckets.
+ 6. Click "Upload" on the upper left of the page
+ 7. Click "Add Files"
+ 8. Select your license file.
+ 9. Click "Start Upload" on the lower right of the page.
+ 10. Once the license has finished uploading, you'll need the bucket name and the filename to use with the CloudFormation template.
+
+## License
+
+This project is licensed under Apache License 2.0 - see [LICENSE.txt](./LICENSE.txt) file for details
+
+## Help
+
+If you have any problems or general questions, please file an issue in the parent repository:
+https://github.com/aws-quickstart/quickstart-splunk-enterprise/issues
+
+

docs/_deployment_guide.adoc

@@ -0,0 +1 @@
+:type: cfn

docs/deployment_guide/partner_editable/_settings.adoc

@@ -0,0 +1,10 @@
+:quickstart-project-name: quickstart-splunk-enterprise
+:quickstart-github-org: aws-quickstart
+:partner-product-short-name: Splunk Enterprise
+:partner-company-name: Splunk Inc.
+:doc-month: May
+:doc-year: 2021
+:partner-contributors: Bill Bartlett, {partner-company-name}
+:aws-contributors: Shivansh Singh, Amazon Web Services
+:deployment_time: 25 minutes
+:default_deployment_region: us-east-1

docs/deployment_guide/partner_editable/additional_info.adoc

@@ -0,0 +1,35 @@
+// Add steps as necessary for accessing the software, post-configuration, and testing. Don’t include full usage instructions for your software, but add links to your product documentation for that information.
+//Should any sections not be applicable, remove them
+
+== Post deployment steps
+// If steps are required to test the deployment, add them here. If not, remove the heading
+
+After the Quick Start has successfully completed, you can log into your {partner-product-name} deployment from a web browser and verify configuration.
+
+==== Verify Distributed Search
+. Begin by logging into {partner-product-name} search head to verify all of the indexers are available for search. To log into the {partner-product-name} search head, navigate your browser to the URL shown in the CloudFormation Outputs labeled "SearchHeadURL" with the credentials of "admin" and the password configured with the "SplunkAdminPassword" parameter when launching the Quick Start.
+. Navigate to Settings -> 'Distributed search' menu item as shown below
+
+image:../images/search-head-distributed-search-menu.png[distributed_search_menu,width=850,height=294,link="../docs/images/search-head-distributed-search-menu.png"]
+[start=3]
+. Click on "Search peers"
+
+. A screen similar to the screenshot below indicates that distributed search in good standing. (This example was created with a 4 node indexer cluster.)
+
+image:../images/search-head-distributed-search-success.png[distributed_search_success,width=850,height=202,link="../docs/images/search-head-distributed-search-success.png"]
+
+==== Verify Indexer Replication Status
+. Begin by logging into {partner-product-name} cluster master to verify all of the indexers are successfully replicating buckets across the cluster. To log into the {partner-product-name} cluster master, navigate your browser to the URL shown in the CloudFormation Outputs labeled "ClusterMasterURL" with the credentials of "admin" and the password configured with the "SplunkAdminPassword" parameter when launching the Quick Start.
+. Navigate to Settings -> 'Indexer clustering' menu item as shown below
+
+image:../images/indexer-clustering-menu.png[indexer_clustering_menu,width=850,height=294,link="../docs/images/indexer-clustering-menu.png"]
+[start=3]
+. A screen similar to the screenshot below indicates that both the search factor and replication factor are in good standing. (This example was created with a 4 node indexer cluster across 2 AZ)
+.. _Please note that it will likely take a few minutes after the Quick Start has successfully launched before the buckets are replicated and this status window shows both search factor and replication factor being met. If there are errors for replication and/or search factor after 10 minutes, please see the link:#_faq[FAQ section] below._
+
+image:../images/cluster-master-sfrf-met.png[indexer_clustering_success,width=850,height=202,link="../docs/images/cluster-master-sfrf-met.png"]
+
+== Security
+// Provide post-deployment best practices for using the technology on AWS, including considerations such as migrating data, backups, ensuring high performance, high availability, etc. Link to software documentation for detailed information.
+
+The {partner-product-name} Quick Start exposes three user-configurable security group access parameters: 'WebClientLocation', 'HECClientLocation', and 'SSHClientLocation'. Be sure that the 'SSHClientLocation' parameter is accessible only on tightly controlled authorized network ranges as this allows direct access to the instances.  The parameter 'WebClientLocation' allows connections to the {partner-product-name} web interfaces, while 'HECClientLocation' controls access to the load balancer in front of the {partner-product-name} HTTP Event Collector listener.

docs/deployment_guide/partner_editable/architecture.adoc

@@ -0,0 +1,25 @@
+:xrefstyle: short
+
+Deploying this Quick Start for a new VPC with default parameters builds the following {partner-product-name} environment in the AWS Cloud.
+[#architecture1]
+.Quick Start architecture for {partner-product-name} on AWS
+[link=images/splunk-enterprise-architecture-on-aws.png]
+image::../images/splunk-enterprise-architecture-on-aws.png[Architecture,width=648,height=439]
+
+As shown in <<architecture1>>, the Quick Start sets up the following:
+
+* A VPC configured across two or three Availability Zones, depending on your selection. The Quick Start provisions one public subnet in each Availability Zone.
+* Two Elastic Load Balancing (ELB) load balancers: one to load-balance HTTP web traffic to the search head instances, and the other to load-balance HTTP event traffic destined for the Splunk HTTP Event Collector (HEC) across all indexer instances.
+* An IAM user with fine-grained permissions for access to AWS services necessary for the initial deployment process.
+* Appropriate security groups for each instance or function to restrict access to only necessary protocols and ports.
+* Amazon Simple Storage Service (Amazon S3) bucket for Splunk SmartStore usage.
+* In the public subnets, EC2 instances for {partner-product-name}, including the following:
+** {partner-product-name} indexer cluster with the number of indexers you specify (3-10), distributed across the number of Availability Zones you specify (2 or 3). The Splunk receiver (splunktcp) and Splunk HEC are enabled across all indexers.
+** Splunk search head(s), either stand-alone or in a 3-node cluster, based on your input during deployment. In the latter case, the search heads are distributed across the number of Availability Zones you specify.
+** Splunk license server and indexer cluster master, co-located.
+** Splunk search head deployer, where applicable.
+
+
+If you decide to deploy Splunk Enterprise into your existing VPC, please see link:#_deployment_options[deployment options] later in this guide.  The Quick Start assumes that the infrastructure components already exist, and deploys Splunk Enterprise into the environment you specify.
+
+

docs/deployment_guide/partner_editable/deployment_options.adoc

@@ -0,0 +1,11 @@
+// There are generally two deployment options. If additional are required, add them here
+
+This Quick Start provides two deployment options:
+
+* *Deploy {partner-product-name} into a new VPC (end-to-end deployment)*. This option builds a new AWS environment consisting of the VPC, subnets, security groups, load balancers, and other infrastructure components. It then deploys {partner-product-name} into this new VPC.
+
+* *Deploy {partner-product-name} into an existing VPC*. This option provisions {partner-product-name} in your existing AWS infrastructure.
+
+The Quick Start provides separate templates for these options. It also lets you configure Classless Inter-Domain Routing (CIDR) blocks, instance types, and {partner-product-name} settings, as discussed later in this guide.
+
+For further information about the dimensions of a Splunk Enterprise deployment, see the {partner-product-name} https://docs.splunk.com/Documentation/Splunk/latest/Capacity/DimensionsofaSplunkEnterprisedeployment[capacity planning manual^].  Finally, for additional information specific to an AWS deployment, see {partner-product-name} https://www.splunk.com/pdfs/technical-briefs/deploying-splunk-enterprise-on-amazon-web-services-technical-brief.pdf[AWS tech brief^] for instance sizing considerations.

docs/deployment_guide/partner_editable/licenses.adoc

@@ -0,0 +1 @@
+This Quick Start requires a subscription to the Amazon Machine Image (AMI) for {partner-product-name}, which is available from AWS Marketplace. For subscription instructions, see step 2 under "Subscribe to the {partner-product-name} AMI" in the link:#_deployment_steps[deployment steps]. In addition, to fully utilize the Quick Start environment, a {partner-product-name} license is required.  If you do not have one, please contact sales@splunk.com

docs/deployment_guide/partner_editable/overview.adoc

@@ -0,0 +1,3 @@
+This Quick Start provides architectural guidance and step-by-step instructions for a high availability deployment of {partner-product-name} on AWS.  The guide addresses common scalability, high-availability, and security considerations for your deployment.
+
+This guide is intended for a variety of audiences, including IT infrastructure architects, administrators, and DevOps professionals who are planning to implement or extend their Splunk Enterprise deployments on the AWS Cloud.  It also provides direct links for viewing and launching AWS CloudFormation templates that assist with automating the deployment

docs/deployment_guide/partner_editable/pre-reqs.adoc

@@ -0,0 +1,9 @@
+// If no preperation is required, remove all content from here.
+There are two important steps to verify prior to launching this Quick start:
+
+* Ensure that the SmartStore bucket that is defined in the "SmartStoreBucketName" parameter *does not exist*.  This Quick Start will attempt to create that bucket with an appropriate bucket policy. If that bucket already exists, the Quick Start will fail.
+* Upload a valid Splunk license to an S3 bucket owned by the user launching the Quick Start.  Take note of the bucket name as well as the path to the license file.  An example may look something like this:
+** Splunk license file is named "splunk.license" and uploaded to an S3 bucket called "my-s3-bucket" under the 'directory' called "license"
+*** Parameter "SplunkLicenseBucket" should be configured to: my-s3-bucket
+*** Parameter "SplunkLicensePath" should be configured to: license/splunk.license (note the lack of a leading "/" on the license path)
+