improved limitations docs

vickatte · Apr 27, 2017 · a2c587e · a2c587e
1 parent 643b165
commit a2c587e
Show file tree

Hide file tree

Showing 9 changed files with 55 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -4,6 +4,12 @@ Using our Infrastructure as Code templates will help you to bootstrap common set
 ## Benefits
 * Speed up development and migration: reuse our CloudFormation templates to create complex environments for common use cases with ease.
 * Rely on high quality infrastructure templates: peer-reviewed by an expert (certified AWS solutions architect Professional) and verified with automated tests.
+* All templates are production-ready. If no other limitations are documented, they are:
+** Highly available: no single point of failure
+** Scalable: increase or decrease the number of instances based on load
+** Frictionless deployment: deliver new versions of your application automatically without downtime
+** Secure: using the latest operating systems and software components, follow the least privilege principle in all areas
+** Operations: provide tools like logging, monitoring and alerting to recognize and debug problems
 * Premium Support available: Get help in case of small and big emergencies and submit feature request.
 
 ## Templates
@@ -20,11 +26,18 @@ We are offering the following templates:
 
 We are interested in your requirements. [Please use the following survey to upvote and add templates you are impatiently waiting for](https://docs.google.com/forms/d/e/1FAIpQLSerhIuMuCWrHai639FoUOt8ffmMqWr0PWzLhCn3VN29VUi8TA/viewform?usp=send_form)
 
+## Releases
+We host all versions starting with version 3.1.0 on the `widdix-aws-cf-templates-releases-eu-west-1` S3 bucket.
+The file `vpc/vpc-2azs.yaml` becomes the S3 key `v3.1.0/vpc/vpc-2azs.yaml`.
+The latest version can also be found at `latest/vpc/vpc-2azs.yaml`.
+
+The current master branch (work in progress) is hosted on the `widdix-aws-cf-templates` S3 bucket.
+
 ## License
 All templates are published under Apache License Version 2.0.
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).

diff --git a/ec2/README.md b/ec2/README.md
@@ -22,8 +22,11 @@ This template describes an EC2 instance with auto-recovery. If the instance fail
 * `vpc/vpc-ssh-bastion.yaml` (recommended)
 * `operations/alert.yaml` (recommended)
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+### Limitations
+* The EC2 instance only runs in a single AZ. In case of an AZ outage the instance will be unavailable.
+
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).

diff --git a/ecs/README.md b/ecs/README.md
@@ -80,8 +80,8 @@ This template describes a fault tolerant and scalable ECS service that uses a de
 * `ecs/cluster.yaml` (**required**)
 * `operations/alert.yaml` (recommended)
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).

diff --git a/jenkins/README.md b/jenkins/README.md
@@ -25,6 +25,9 @@ This template describes a Jenkins master in a highly available manner. If the ma
 * `security/auth-proxy-*.yaml`
 * `operations/alert.yaml` (recommended)
 
+## Limitations
+* Jenkins will only run in two Availability Zones, even if your VPC stack has more.
+
 ## Jenkins 2.0: highly available master and dynamic agents
 This template describes a Jenkins master in a highly available manner. If the master instance fails it will be replaced automatically. All data stored on EFS where it is replicated across AZs and the file system can grow without a limit. The Jenkins master sits behind a load balancer to provide a fixed endpoint. A dynamic pool of agents will execute builds. If the build queue grows new agents are provisioned. Of the build queue is empty agents are taken offline (only if they have no build running). System and Jenkins logs are pushed to CloudWatch Logs.
 
@@ -48,8 +51,11 @@ This template describes a Jenkins master in a highly available manner. If the ma
 * `security/auth-proxy-*.yaml`
 * `operations/alert.yaml` (recommended)
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+## Limitations
+* Jenkins will only run in two Availability Zones, even if your VPC stack has more.
+
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).

diff --git a/operations/README.md b/operations/README.md
@@ -18,8 +18,8 @@ This template describes a SNS topic that can be used by many other templates to
 1. Click **Create** to start the creation of the stack.
 1. Wait until the stack reaches the state **CREATE_COMPLETE**
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).

diff --git a/security/README.md b/security/README.md
@@ -61,6 +61,9 @@ This template describes a **highly available** authentication proxy that forward
 * `vpc/vpc-ssh-bastion.yaml` (recommended)
 * `operations/alert.yaml` (recommended)
 
+### Limitations
+* By default, only one EC2 instance is managed by the ASG. In case of an outage the instance will be replaced within 5 minutes. You can change this in the ASG configuration!
+
 ## CloudTrail across all regions
 This template enables CloudTrail to records AWS API calls across all regions in your AWS account. API calls are archived in S3 and also pushed CloudWatch Logs. If new API calls are available in S3 a SNS topic is notified.
 
@@ -170,8 +173,8 @@ If you want to use an external S3 bucket, the bucket needs to have the following
 
 Replace `$ExternalTrailBucket` with the name of your bucket, and add a row for every account you want to write from `$AccountId[*]`.
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).

diff --git a/static-website/README.md b/static-website/README.md
@@ -15,8 +15,8 @@ This template describes the infrastructure for hosting a static website over HTT
 1. Click **Create** to start the creation of the stack.
 1. Wait until the stack reaches the state **CREATE_COMPLETE**
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).

diff --git a/vpc/README.md b/vpc/README.md
@@ -66,6 +66,9 @@ This template describes a NAT Gateway that forwards HTTP, HTTPS and NTP traffic
 ### Dependencies
 * `vpc/vpc-*azs.yaml` (**required**)
 
+## Limitations
+* The NAT Gateway is a single point of failure because it runs only in one Subnet (and therefore in one Availability Zone): https://github.com/widdix/aws-cf-templates/issues/65
+
 ## NAT instance
 This template describes a **highly available** Network Address Translation (NAT) instance that forwards HTTP, HTTPS and NTP traffic from private subnets to the Internet.
 
@@ -86,6 +89,9 @@ This template describes a **highly available** Network Address Translation (NAT)
 * `vpc/vpc-ssh-bastion.yaml` (recommended)
 * `operations/alert.yaml` (recommended)
 
+### Limitations
+* Only one EC2 instance is managed by the ASG. In case of an outage the instance will be replaced within 5 minutes.
+
 ## SSH bastion host/instance
 This template describes a **highly available** SSH bastion host/instance. SSH Port 22 is open to the world. You can enable the default ec2-user access protected by the referenced EC2 KeyPair. You can also enable personalized SSH access by using the IAM users and their configured public keys. Use `ssh -A user@ip` to enable forwarding of the authentication agent connection when connection to the bastion host.
 **Users are not able to sudo on the bastion host/instance! That's very important for security. Why? SSH places a SSH_AUTH_SOCK file into the /tmp directoy only accessible by the user. If you have root you could use any of those files and jump to other machines as another user!**
@@ -106,6 +112,9 @@ This template describes a **highly available** SSH bastion host/instance. SSH Po
 * `vpc/vpc-*azs.yaml` (**required**)
 * `operations/alert.yaml` (recommended)
 
+### Limitations
+* Only one EC2 instance is managed by the ASG. In case of an outage the instance will be replaced within 5 minutes.
+
 ## VPC Endpoint to S3
 This template describes a VPC endpoint to securely route traffic within a VPC for private instances to access S3 without the need of a NAT Gateway, NAT instance, or public internet. Refer to [AWS VPC endpoint](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/vpc-endpoints.html) documentation if this is necessary for your stack. By default, access to all S3 actions and buckets is allowed, but may be constrained with a policy document.
 
@@ -120,8 +129,8 @@ This template describes a VPC endpoint to securely route traffic within a VPC fo
 1. Wait until the stack reaches the state **CREATE_COMPLETE**
 ![Architecture](./vpc-endpoint-s3.png?raw=true "Architecture")
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).

diff --git a/wordpress/README.md b/wordpress/README.md
@@ -20,7 +20,7 @@ This template combines the following services:
 ![Architecture](./wordpress-ha.png?raw=true "Architecture")
 
 ## Installation Guide
-1. This templates depends on our [`vpc-*azs.yaml`](../vpc/) template. WordPress will use 2 AZs only. <a href="https://console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=vpc-2azs&templateURL=https://s3-eu-west-1.amazonaws.com/widdix-aws-cf-templates/vpc/vpc-2azs.yaml">Launch Stack</a>
+1. This templates depends on our [`vpc-*azs.yaml`](../vpc/) template. <a href="https://console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=vpc-2azs&templateURL=https://s3-eu-west-1.amazonaws.com/widdix-aws-cf-templates/vpc/vpc-2azs.yaml">Launch Stack</a>
 1. Create an ACM certificate for your domain name within the region you want to launch your stack in. Copy the ARN of the certificate. This is for the ELB.
 1. Create another ACM certificate for your domain in region `us-east-1`. Copy the ARN of the certificate. This is for CloudFront (note: [CloudFront only supports ACM certificates in us-east-1](https://docs.aws.amazon.com/acm/latest/userguide/acm-services.html))
 1. <a href="https://console.aws.amazon.com/cloudformation/home#/stacks/new?stackName=wordpress-ha&templateURL=https://s3-eu-west-1.amazonaws.com/widdix-aws-cf-templates/wordpress/wordpress-ha.yaml">Launch Stack</a>
@@ -34,18 +34,19 @@ This template combines the following services:
 1. Grab the `URL` of the WordPress environment from the **Outputs** tab of your stack.
 
 ## Dependencies
-* `vpc/vpc-*azs.yaml` (**required, WordPress will use 2 AZs only**)
+* `vpc/vpc-*azs.yaml` (**required**)
 * `vpc/vpc-ssh-bastion.yaml` (recommended)
 * `security/auth-proxy-*.yaml`
 * `operations/alert.yaml` (recommended)
 
 ## Limitations
+* WordPress will only run in two Availability Zones, even if your VPC stack has more.
 * PHP files are cached for 300 seconds on the web servers.
 * Static files `wp-includes` and `wp-content` are cached for 15 minutes on the CDN.
 * Pre-defined auto-scaling might not be able to cover your requirements and needs load and performance testing.
 
-## Support
-We offer support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
+## Premium Support
+We offer Premium Support for our CloudFormation templates: setting up environments based on our templates, adopting templates to specific use cases, resolving issues in production environments. [Hire us!](https://widdix.net/)
 
 ## Feedback
 We are looking forward to your feedback. Mail to [hello@widdix.de](mailto:hello@widdix.de).