<commit_before>= Create A Kubernetes Cluster Using kops
:toc:

This tutorial will walk you through how to install a Kubernetes cluster on AWS using kops.

https://github.com/kubernetes/kops[kops], short for Kubernetes Operations, is a set of tools for installing, operating, and deleting Kubernetes clusters. kops can also perform rolling upgrades from older versions of Kubernetes to newer ones. kops also manages the cluster add-ons. After the cluster is created, the link:../prereqs.adoc[Kubernetes CLI] can be used to manage resources in the cluster. If you have not gone through the link:../prereqs.adoc[Prerequisites] section, please do so now before continuing.

kops is available on Mac OSX, Linux, or the Windows 10 Linux Subsystem. 

== Install kops

There is no need to download a Kubernetes binary distribution for creating a cluster using kops. However, you do need to download the kops CLI. It takes care of downloading the right Kubernetes binary in the cloud, and then provisions and manages the cluster.

==== macOS

At this point brew PR https://github.com/Homebrew/homebrew-core/pull/21305 is not merged, so in order to use kops 1.8 please execute the following command.

    $ curl -LO https://github.com/kubernetes/kops/releases/download/1.8.0/kops-darwin-amd64
    $ chmod +x kops-darwin-amd64
    $ sudo mv kops-darwin-amd64 /usr/local/bin/kops

Once the above PR is merged you will be able to install kops using brew.

    $ brew update && brew install kops

If kops is already installed, then it can be upgraded to the latest version using the following command:

    $ brew upgrade kops

==== Linux / Windows 10 Linux Subsystem

    curl -LO https://github.com/kubernetes/kops/releases/download/$(curl -s https://api.github.com/repos/kubernetes/kops/releases/latest | grep tag_name | cut -d '"' -f 4)/kops-linux-amd64
    chmod +x kops-linux-amd64
    sudo mv kops-linux-amd64 /usr/local/bin/kops

kops is available on Mac OSX, Linux, Container image, or using with the Windows 10 Linux Subsystem. Complete installation instructions are available at https://github.com/kubernetes/kops#installing.

Latest and early versions of kops can be downloaded from https://github.com/kubernetes/kops/releases.

You will also need the Kubernetes CLI (kubectl) to manage the resources on the Kubernetes cluster. If you don't have the Kubernetes CLI installed, please follow the instructions link:../getting-started#download-and-install[here] to do so.

=== Create An SSH Key

kops uses a public SSH key while creating a cluster. The location of this file defaults to `~/.ssh/id_rsa.pub`. Please generate an SSH key using `ssh-keygen` command.

    $ ssh-keygen 
    Generating public/private rsa key pair.
    Enter file in which to save the key (~/.ssh/id_rsa):
    Enter passphrase (empty for no passphrase): 
    Enter same passphrase again: 
    Your identification has been saved in ~/.ssh/id_rsa
    Your public key has been saved in ~/.ssh/id_rsa.pub.
    The key fingerprint is:
    <PASSWORD>256:<PASSWORD>
    The key's randomart image is:
    +---[RSA 2048]----+
    |      ..oo=B**+ +|
    |       . o+=B*=+.|
    |        +..+*O+E=|
    |       . =o=.o=oo|
    |        S.*..  o |
    |         oo      |
    |           .     |
    |                 |
    |                 |
    +----[SHA256]-----+

Alternatively, you can use the `--ssh-public-key` option to specify a custom location. 
More details about kops security can be found in the https://github.com/kubernetes/kops/blob/master/docs/security.md[documentation for kops].

== Install AWS cli

Make sure the latest version of the http://docs.aws.amazon.com/cli/latest/userguide/installing.html[AWS CLI]
is installed. 

   $ pip install --upgrade awscli

== IAM user permissions

The AWS user profile used in this workshop must have these http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html[IAM policies] attached.

    AmazonEC2FullAccess
    AmazonRoute53FullAccess
    AmazonS3FullAccess
    IAMFullAccess
    AmazonVPCFullAccess

If you are using the AWS user and credentials created as part of the link:prereqs.adoc[Prerequisites], then you should already have these permissions.

Please review these links for additional info on IAM permissions:
https://github.com/kubernetes/kops/blob/master/docs/aws.md#setup-iam-user. https://github.com/kubernetes/kops/blob/master/docs/iam_roles.md

== S3 Bucket for kops

kops needs a "`state store`" to store configuration information of the cluster.  For example, how many nodes in the cluster, the instance type of each node, and the Kubernetes version. The state is stored during the initial cluster creation. Any subsequent changes to the cluster are also persisted to this store. Amazon S3 is the recommended storage mechanism when running a cluster in AWS Cloud. Create an S3 bucket and pass that to the kops CLI during cluster creation.  A state store can work with multiple kops clusters.

NOTE: The bucket name must be unique otherwise you will encounter an error on deployment. We will use an example bucket name of `example-state-store-` and add a randomly generated string to the end.

    # create variables for bucket, state store, and cluster names
    $ export S3_BUCKET=example-state-store-$(cat /dev/random | LC_ALL=C tr -dc "[:alpha:]" | tr '[:upper:]' '[:lower:]' | head -c 32)
    $ export KOPS_STATE_STORE=s3://${S3_BUCKET}

    # use AWS CLI to create the bucket
    $ aws s3 mb $KOPS_STATE_STORE

    # enable versioning
    $ aws s3api put-bucket-versioning \
      --bucket $S3_BUCKET \
      --versioning-configuration \
      Status=Enabled

== Create A Cluster

The kops CLI can be used to create a highly available cluster, with multiple master nodes spread across multiple Availability Zones. Workers can be spread across multiple zones as well. Some of the tasks that happen behind the scene during cluster creation are:

- Provisioning EC2 instances
- Creating and configuring AWS resources such as a VPC, Auto Scaling Groups, IAM users, and security groups
- Installing Kubernetes
- If required configuring Route53 DNS

When setting up a cluster you have two options on how the nodes in the cluster communicate:

. <<Create a gossip-based Kubernetes cluster, Using the gossip protocol>> - kops has support for a gossip-based cluster. This does not require a domain, subdomain, or Route53 hosted zone to be registered. A gossip-based cluster is therefore easier and quicker to setup, and is the preferred method for creating a cluster for use with this workshop.
. <<Create a DNS-based Kubernetes cluster, Using DNS>> - Creating a Kubernetes cluster that uses DNS for node discovery requires your own domain (or subdomain) and setting up Route 53 hosted zones. This allows the various Kubernetes components to use DNS resolutions find and communicate with each other, and for kubectl to be able to talk directly with the master node(s).

Instructions for creating a gossip-based cluster are provided below, however, the examples in the workshop should work with either option. Instructions for creating a DNS-based cluster are provided as an appendix at the bottom of this page.

=== Create a Gossip Based Kubernetes kops Cluster

kops supports creating a gossip-based cluster, which uses https://github.com/weaveworks/mesh[Weave Mesh] behind the scenes. This makes the process of creating a Kubernetes cluster using kops DNS-free, and therefore much simpler. This also means a top-level domain or a subdomain is no longer required to create the cluster. To create a cluster using the gossip protocol, indicate this to by using a cluster name with a suffix of `.k8s.local`. In the following steps, we will use example.cluster.k8s.local as a sample gossip cluster name. You may choose a different name as long as it ends with `.k8s.local`.

Information on setting up a DNS-based cluster can be found at the bottom of this page in the Appendix. However, setting up a gossip-based cluster allows you to get started quickly.

We show two examples of creating gossip-based clusters below. You can choose whether to create a single-master or multi-master cluster. Workshop exercises will work on both types of cluster.

==== Default Gossip Based Cluster

By default, `create cluster` command creates a single master node and two worker nodes in the specified zones.

Create a Kubernetes cluster using the following command. This will create a cluster with a single master, multi-node and multi-az configuration:

    $ kops create cluster \<commit_msg>[WIP] Fix #288; Update 'Using DNS' link in cluster-install<commit_after>= Create A Kubernetes Cluster Using kops
:toc:

This tutorial will walk you through how to install a Kubernetes cluster on AWS using kops.

https://github.com/kubernetes/kops[kops], short for Kubernetes Operations, is a set of tools for installing, operating, and deleting Kubernetes clusters. kops can also perform rolling upgrades from older versions of Kubernetes to newer ones. kops also manages the cluster add-ons. After the cluster is created, the link:../prereqs.adoc[Kubernetes CLI] can be used to manage resources in the cluster. If you have not gone through the link:../prereqs.adoc[Prerequisites] section, please do so now before continuing.

kops is available on Mac OSX, Linux, or the Windows 10 Linux Subsystem. 

== Install kops

There is no need to download a Kubernetes binary distribution for creating a cluster using kops. However, you do need to download the kops CLI. It takes care of downloading the right Kubernetes binary in the cloud, and then provisions and manages the cluster.

==== macOS

At this point brew PR https://github.com/Homebrew/homebrew-core/pull/21305 is not merged, so in order to use kops 1.8 please execute the following command.

    $ curl -LO https://github.com/kubernetes/kops/releases/download/1.8.0/kops-darwin-amd64
    $ chmod +x kops-darwin-amd64
    $ sudo mv kops-darwin-amd64 /usr/local/bin/kops

Once the above PR is merged you will be able to install kops using brew.

    $ brew update && brew install kops

If kops is already installed, then it can be upgraded to the latest version using the following command:

    $ brew upgrade kops

==== Linux / Windows 10 Linux Subsystem

    curl -LO https://github.com/kubernetes/kops/releases/download/$(curl -s https://api.github.com/repos/kubernetes/kops/releases/latest | grep tag_name | cut -d '"' -f 4)/kops-linux-amd64
    chmod +x kops-linux-amd64
    sudo mv kops-linux-amd64 /usr/local/bin/kops

kops is available on Mac OSX, Linux, Container image, or using with the Windows 10 Linux Subsystem. Complete installation instructions are available at https://github.com/kubernetes/kops#installing.

Latest and early versions of kops can be downloaded from https://github.com/kubernetes/kops/releases.

You will also need the Kubernetes CLI (kubectl) to manage the resources on the Kubernetes cluster. If you don't have the Kubernetes CLI installed, please follow the instructions link:../getting-started#download-and-install[here] to do so.

=== Create An SSH Key

kops uses a public SSH key while creating a cluster. The location of this file defaults to `~/.ssh/id_rsa.pub`. Please generate an SSH key using `ssh-keygen` command.

    $ ssh-keygen 
    Generating public/private rsa key pair.
    Enter file in which to save the key (~/.ssh/id_rsa):
    Enter passphrase (empty for no passphrase): 
    Enter same passphrase again: 
    Your identification has been saved in ~/.ssh/id_rsa
    Your public key has been saved in ~/.ssh/id_rsa.pub.
    The key fingerprint is:
    SHA256:bQXH2zAAcFVtpEwcOL5D1QZnXp3zkiC123456789
    The key's randomart image is:
    +---[RSA 2048]----+
    |      ..oo=B**+ +|
    |       . o+=B*=+.|
    |        +..+*O+E=|
    |       . =o=.o=oo|
    |        S.*..  o |
    |         oo      |
    |           .     |
    |                 |
    |                 |
    +----[SHA256]-----+

Alternatively, you can use the `--ssh-public-key` option to specify a custom location. 
More details about kops security can be found in the https://github.com/kubernetes/kops/blob/master/docs/security.md[documentation for kops].

== Install AWS cli

Make sure the latest version of the http://docs.aws.amazon.com/cli/latest/userguide/installing.html[AWS CLI]
is installed. 

   $ pip install --upgrade awscli

== IAM user permissions

The AWS user profile used in this workshop must have these http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html[IAM policies] attached.

    AmazonEC2FullAccess
    AmazonRoute53FullAccess
    AmazonS3FullAccess
    IAMFullAccess
    AmazonVPCFullAccess

If you are using the AWS user and credentials created as part of the link:prereqs.adoc[Prerequisites], then you should already have these permissions.

Please review these links for additional info on IAM permissions:
https://github.com/kubernetes/kops/blob/master/docs/aws.md#setup-iam-user. https://github.com/kubernetes/kops/blob/master/docs/iam_roles.md

== S3 Bucket for kops

kops needs a "`state store`" to store configuration information of the cluster.  For example, how many nodes in the cluster, the instance type of each node, and the Kubernetes version. The state is stored during the initial cluster creation. Any subsequent changes to the cluster are also persisted to this store. Amazon S3 is the recommended storage mechanism when running a cluster in AWS Cloud. Create an S3 bucket and pass that to the kops CLI during cluster creation.  A state store can work with multiple kops clusters.

NOTE: The bucket name must be unique otherwise you will encounter an error on deployment. We will use an example bucket name of `example-state-store-` and add a randomly generated string to the end.

    # create variables for bucket, state store, and cluster names
    $ export S3_BUCKET=example-state-store-$(cat /dev/random | LC_ALL=C tr -dc "[:alpha:]" | tr '[:upper:]' '[:lower:]' | head -c 32)
    $ export KOPS_STATE_STORE=s3://${S3_BUCKET}

    # use AWS CLI to create the bucket
    $ aws s3 mb $KOPS_STATE_STORE

    # enable versioning
    $ aws s3api put-bucket-versioning \
      --bucket $S3_BUCKET \
      --versioning-configuration \
      Status=Enabled

== Create A Cluster

The kops CLI can be used to create a highly available cluster, with multiple master nodes spread across multiple Availability Zones. Workers can be spread across multiple zones as well. Some of the tasks that happen behind the scene during cluster creation are:

- Provisioning EC2 instances
- Creating and configuring AWS resources such as a VPC, Auto Scaling Groups, IAM users, and security groups
- Installing Kubernetes
- If required configuring Route53 DNS

When setting up a cluster you have two options on how the nodes in the cluster communicate:

. <<Create a gossip-based Kubernetes cluster, Using the gossip protocol>> - kops has support for a gossip-based cluster. This does not require a domain, subdomain, or Route53 hosted zone to be registered. A gossip-based cluster is therefore easier and quicker to setup, and is the preferred method for creating a cluster for use with this workshop.
. <<Appendix-create-a-dns-based-kubernetes-cluster, Using DNS>> - Creating a Kubernetes cluster that uses DNS for node discovery requires your own domain (or subdomain) and setting up Route 53 hosted zones. This allows the various Kubernetes components to use DNS resolutions find and communicate with each other, and for kubectl to be able to talk directly with the master node(s).

Instructions for creating a gossip-based cluster are provided below, however, the examples in the workshop should work with either option. Instructions for creating a DNS-based cluster are provided as an appendix at the bottom of this page.

=== Create a Gossip Based Kubernetes kops Cluster

kops supports creating a gossip-based cluster, which uses https://github.com/weaveworks/mesh[Weave Mesh] behind the scenes. This makes the process of creating a Kubernetes cluster using kops DNS-free, and therefore much simpler. This also means a top-level domain or a subdomain is no longer required to create the cluster. To create a cluster using the gossip protocol, indicate this to by using a cluster name with a suffix of `.k8s.local`. In the following steps, we will use example.cluster.k8s.local as a sample gossip cluster name. You may choose a different name as long as it ends with `.k8s.local`.

Information on setting up a DNS-based cluster can be found at the bottom of this page in the Appendix. However, setting up a gossip-based cluster allows you to get started quickly.

We show two examples of creating gossip-based clusters below. You can choose whether to create a single-master or multi-master cluster. Workshop exercises will work on both types of cluster.

==== Default Gossip Based Cluster

By default, `create cluster` command creates a single master node and two worker nodes in the specified zones.

Create a Kubernetes cluster using the following command. This will create a cluster with a single master, multi-node and multi-az configuration:

    $ kops create cluster \
{'fraction_non_alphanumeric': 0.06991537788152903, 'fraction_numerical': 0.008403851765392472, 'mean_word_length': 3.6527287537333697, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 22, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 14, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7559397', 'n_tokens_mistral': 4826, 'n_tokens_neox': 4473, 'n_words': 2244}