Merge pull request #3367 from tigerlinux/route53_based_example

Automatic merge from submit-queue.

Route53 based example

Added in the docs/examples section a new practical example/lab with the use of a route53-based subdomain. All technical details and commands (both for kops and aws) fully included.

docs/examples/README.md

@@ -0,0 +1,11 @@
+# KOPS CASE-USE EXAMPLES AND LABORATORY EXERCISES.
+
+This section of our documentation contains typical use-cases for Kops. We'll cover here from the most basic things to very advanced use cases with a lot of technical detail. You can and will be able to reproduce all exercises (if you first read and understand what we did and why we did it) providing you have access to the proper resources.
+
+All exercises will need you to prepare your base environment (with kops and kubectl). You can see the ["basic requirements"](basic-requirements.md) document that is a common set of procedures for all our exercises. Please note that all the exercises covered here are production-oriented.
+
+Our exercises are divided on "chapters". Each chapter covers a specific use-case for Kops:
+
+- Chapter I: [USING KOPS WITH COREOS - A MULTI-MASTER/MULTI-NODE PRACTICAL EXAMPLE](coreos-kops-tests-multimaster.md).
+- Chapter II: [USING KOPS WITH PRIVATE NETWORKING AND A BASTION HOST IN A HIGLY-AVAILABLE SETUP](kops-tests-private-net-bastion-host.md).
+- Chapter III: [USING KOPS WITH A ROUTE53 BASED SUBDOMAIN AND SCALING UP THE CLUSTER](kops-test-route53-subdomain.md).

docs/examples/basic-requirements.md

@@ -0,0 +1,59 @@
+# COMMON BASIC REQUIREMENTS FOR KOPS-RELATED LABS. PRE-FLIGHT CHECK:
+
+Before rushing in to replicate any of the exercises, please ensure your basic environment is correctly setup. See the [KOPS AWS tutorial for more information](../docs/aws.md). 
+
+Ensure that the following points are covered and working in your environment:
+
+- AWS cli fully configured (aws account already with proper permissions/roles needed for kops). Depending on your distro, you can setup directly from packages, or if you want the most updated version, use "pip" and install awscli by issuing a "pip install awscli" command. Your choice!
+- Local ssh key ready on ~/.ssh/id_rsa / id_rsa.pub. You can generate it using "ssh-keygen" command if you dont' have one already: `ssh-keygen -t rsa -f ~/.ssh/id_rsa -P ""`.
+- Region set to us-east-1 (az's: us-east-1a, us-east-1b, us-east-1c, us-east-1d and us-east-1e). For most of our exercises we'll deploy our clusters in "us-east-1". For real HA at kubernetes master level, you need 3 masters. If you want to ensure that each master is deployed on a different availability zone, then a region with "at least" 3 availabity zones is required here. You can still deploy a multi-master kubernetes setup on regions with just 2 az's or even 1 az but this mean that two or all your masters will be deployed on a single az and if this az goes offline then you'll lose two or all your masters. If possible, always pick a region with at least 3 different availability zones for real H.A. You always can check amazon regions and az's on the link: [AWS Global Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/). Remember: The masters are Kubernetes control plane. If your masters die, you loose control of your Kubernetes cluster.
+- kubectl and kops installed. For this last part, you can do this with using following commnads. Next commands asume you are running a amd64/x86_64 linux distro:
+
+As root (either ssh directly to root, local root console, or by using "sudo su -" previouslly):
+
+```bash
+cd ~
+curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
+curl -LO https://github.com/kubernetes/kops/releases/download/1.7.0/kops-linux-amd64
+chmod 755 kubectl kops-linux-amd64
+mv kops-linux-amd64 kops
+mv kubectl kops  /usr/local/bin
+```
+
+If you are not root and/or do you want to keep the kops/kubectl utilities in your own account:
+
+```bash
+cd ~
+curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
+curl -LO https://github.com/kubernetes/kops/releases/download/1.7.0/kops-linux-amd64
+chmod 755 kubectl kops-linux-amd64
+mv kops-linux-amd64 kops
+mkdir ~/bin
+export PATH=$PATH:~/bin
+mv kubectl kops  ~/bin
+```
+
+Finally, some of our exercises use the "jq" utility that is available on modern linux distributions. Please ensure to install it too. Some examples of how to do it:
+
+**Centos 7:**
+
+```bash
+yum -y install epel-release
+yum -y install jq
+```
+
+**Debian7/Debian8/Debian9/Ubuntu1404lts/Ubuntu1604lts:**
+
+```bash
+apt-get -y update
+apt-get -y install jq
+```
+
+Also, if you are using **OS X** you can install jq using ["Homebrew"](https://brew.sh):
+
+```bash
+brew install jq
+```
+
+More information about "jq" on the following site: [https://stedolan.github.io/jq/download/](https://stedolan.github.io/jq/download/)
+

docs/examples/coreos-kops-tests-multimaster.md

@@ -1,8 +1,8 @@
 # USING KOPS WITH COREOS - A MULTI-MASTER/MULTI-NODE PRACTICAL EXAMPLE
 
-## WHAT WE WANT TO ACOMPLISH HERE ?.
+## WHAT WE WANT TO ACOMPLISH HERE?
 
-The exercise described on this document will focus on the following goals:
+The exercise described in this document will focus on the following goals:
 
 - Demonstrate how to use a production-setup with 3 masters and multiple working nodes (two).
 - Change our default base-distro (Debian 8) for CoreOS stable, available too as an AMI on AWS.
@@ -12,28 +12,12 @@ The exercise described on this document will focus on the following goals:
 
 ## PRE-FLIGHT CHECK:
 
-Before rushing in to replicate this exercise, please ensure your basic environment is correctly setup. See the [KOPS AWS tutorial for more information](https://github.com/kubernetes/kops/blob/master/docs/aws.md).
-
-Ensure that the following points are covered and working in your environment:
-
-- AWS cli fully configured (aws account already with proper permissions/roles needed for kops). Depending on your distro, you can setup directly from packages, or if you want the most updated version, use "pip" and install awscli by issuing a "pip install awscli" command. Your choice !.
-- Local ssh key ready on ~/.ssh/id_rsa / id_rsa.pub. You can generate it using "ssh-keygen" command: `ssh-keygen -t rsa -f ~/.ssh/id_rsa -P ""`
-- Region set to us-east-1 (az's: us-east-1a, us-east-1b, us-east-1c, us-east-1d and us-east-1e). For this exercise we'll deploy our cluster on US-EAST-1. For real HA at kubernetes master level, you need 3 masters. If you want to ensure that each master is deployed on a different availability zone, then a region with "at least" 3 availabity zones is required here. You can still deploy a multi-master kubenetes setup on regions with just 2 az's, but this mean that two masters will be deployed on a single az, and of this az goes offline then you'll lose two master !. If possible, always pick a region with at least 3 different availability zones for real H.A. You always can check amazon regions and az's on the link: [AWS Global Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/)
-- kubectl and kops installed. For this last part, you can do this with using following commnads (do this as root please). Next commands asume you are running a amd64/x86_64 linux distro:
-
-```bash
-cd ~
-curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
-wget https://github.com/kubernetes/kops/releases/download/1.7.0/kops-linux-amd64
-chmod 755 kubectl kops-linux-amd64
-mv kops-linux-amd64 kops
-mv kubectl kops  /usr/local/bin
-```
+Please follow our [basic-requirements document](basic-requirements.md) that is common for all our exercises. Ensure the basic requirements are covered before continuing.
 
 
 ## AWS/KOPS ENVIRONMENT INFORMATION SETUP:
 
-First, using some scripting and asuming you already configured your "aws" environment on your linux system, use the following commands in order to export your AWS access/secret (this will work if you are using the default profile):
+First, using some scripting and assuming you already configured your "aws" environment on your linux system, use the following commands in order to export your AWS access/secret (this will work if you are using the default profile):
 
 ```bash
 export AWS_ACCESS_KEY_ID=`grep aws_access_key_id ~/.aws/credentials|awk '{print $3}'`
@@ -50,7 +34,7 @@ export AWS_PROFILE=name_of_your_profile
 Create a bucket (if you don't already have one) for your cluster state:
 
 ```bash
-aws s3 mb s3://my-kops-s3-bucket-for-cluster-state --region us-east-1
+aws s3api create-bucket --bucket my-kops-s3-bucket-for-cluster-state --region us-east-1
 ```
 
 Then export the name of your cluster along with the "S3" URL of your bucket:
@@ -70,7 +54,7 @@ Some things to note from here:
 
 CoreOS webpage includes a "json" with the updated list of lattest images: [https://coreos.com/dist/aws/aws-stable.json](https://coreos.com/dist/aws/aws-stable.json)
 
-If you install the "jq" utility (available on most distros) you can obtain the "ami" for a specific region (change the region "-" for "_" in the following command):
+By using "jq" you can obtain the "ami" for a specific region (change the region "-" for "_" in the following command):
 
 
 ```bash
@@ -135,17 +119,17 @@ aws ec2 describe-images --region=us-east-1 --owner=595879546273 \
     --query 'sort_by(Images,&CreationDate)[-1].{id:ImageLocation}' \
 	--output table
 
-
+	
 ---------------------------------------------------
 |                 DescribeImages                  |
 +----+--------------------------------------------+
 |  id|  595879546273/CoreOS-stable-1409.8.0-hvm   |
 +----+--------------------------------------------+
 ```
 
-Then, our image for CoreOS, in "AMI" format is "ami-32705b49", or in owner/name format "595879546273/CoreOS-stable-1409.8.0-hvm". Note that KOPS default image is a debian-jessie based one (more specifically: "kope.io/k8s-1.6-debian-jessie-amd64-hvm-ebs-2017-07-28" at the moment we are writing this document).
+Then, our image for CoreOS, in "AMI" format is "ami-32705b49", or in owner/name format "595879546273/CoreOS-stable-1409.8.0-hvm". Note that KOPS default image is a debian-jessie based one (more specifically: "kope.io/k8s-1.6-debian-jessie-amd64-hvm-ebs-2017-05-02" at the moment we are writing this document).
 
-**NOTE:** Always obtain the latest image before deploying KOPS. CoreOS updates it's AWS image very often. Don't rely on the versions included on this document. Always check first !
+**NOTE:** Always obtain the latest image before deploying KOPS. CoreOS updates it's AWS image very often. Don't rely on the versions included on this document. Always check first.
 
 
 ## KOPS CLUSTER CREATION AND MODIFICATION:
@@ -289,7 +273,7 @@ curl http://54.210.119.98
 curl http://34.200.247.63
 <html><body><h1>It works!</h1></body></html>
 
-```
+``` 
 
 **NOTE:** If you are replicating this exercise in a production environment, use a "real" load balancer in order to expose your replicated services. We are here just testing things so we really don't care right now about that, but, if you are doing this for a "real" production environment, either use an AWS ELB service, or an nginx ingress controller as described in our documentation: [NGINX Based ingress controller](https://github.com/kubernetes/kops/tree/master/addons/ingress-nginx).