Skip to content

Commit

Permalink
docs: update k8s.eks (#686)
Browse files Browse the repository at this point in the history 
* provide link to list for EKS regions

* improve description for reference links, fix outdated links

* update k8s.eks guide
  • Loading branch information
@bobheadxi
bobheadxi authored May 13, 2020
1 parent 44c0a36 commit 9e50db9
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 38 deletions.
65 changes: 34 additions & 31 deletions docs/k8s.eks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,33 +16,39 @@ Follow the [EKS Getting Started guide](https://docs.aws.amazon.com/eks/latest/us

## Create the Amazon EKS Cluster VPC

Continuing through the [EKS Getting Started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-prereqs), create the EKS Cluster VPC:

1. Open the [**AWS CloudFormation console**](https://console.aws.amazon.com/cloudformation/).
2. Ensure the region in the top right navigation bar is `us-west-2`, `us-east-1`, or `eu-west-1` (others do not support EKS yet as of September 12, 2018).
3. Click **Create stack**.
4. Select the very last **Specify an Amazon S3 template URL** option. Enter `https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2018-08-30/amazon-eks-vpc-sample.yaml`
2. Ensure the region in the top right navigation bar is an EKS-supported region (see [this list](https://docs.aws.amazon.com/general/latest/gr/eks.html)). <!-- there does not seem to be a nicer list elsewhere -->
3. Click **Create stack**, and select **"with new resources"**.
4. When prompted to specify a template, select "Amazon S3 URL" as your **Template Source** and enter:
```
https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2020-04-21/amazon-eks-vpc-sample.yaml
```
5. Under **Stack name**, enter `eks-vpc-sourcegraph`.
6. Click **Next**, **Next**, **Create**.
6. Click **Next** through the following pages until you get the option to **Create stack**. Review the configuration and click **Create stack**.

## Create the Amazon EKS Cluster
For more details on these steps, refer to [Amazon EKS prerequisites: Create your Amazon EKS cluster VPC](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html#vpc-create).

Follow the [EKS Getting Started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-create-cluster) to create the EKS Cluster:
## Create the Amazon EKS Cluster

1. Open the [**EKS console**](https://console.aws.amazon.com/eks/home#/clusters).
2. Click **Create cluster**.
3. Under **Cluster name**, enter `sourcegraph`.
4. Under **Role ARN**, select `eksServiceRoleSourcegraph`.
4. Under **Cluster Service Role**, select `eksServiceRoleSourcegraph`.
5. Under **VPC**, select `eks-vpc-sourcegraph`.
6. Under **Security groups**, select the one prefixed `eks-vpc-sourcegraph-ControlPlaneSecurityGroup-`. (Do NOT select `NodeSecurityGroup`.)
7. Accept all other values as default and click **Create**.
8. Wait for the cluster to finish **CREATING**. This will take around 10 minutes to complete, so grab some ☕.

For more details on these steps, refer to [Amazon EKS prerequisites: Create your Amazon EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html#eks-create-cluster).

## Create Kubernetes cluster worker nodes

1. Open the [**AWS CloudFormation console**](https://console.aws.amazon.com/cloudformation/).
2. Click **Create stack**
3. Select the very last **Specify an Amazon S3 template URL** option and enter `https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2018-08-30/amazon-eks-nodegroup.yaml`
3. Select the very last **Specify an Amazon S3 template URL** option and enter
```
https://amazon-eks.s3.us-west-2.amazonaws.com/cloudformation/2020-04-21/amazon-eks-nodegroup.yaml
```
4. Under **Stack name**, enter `sourcegraph-worker-nodes`.
5. Under **ClusterName**, enter the exact cluster name you used (`sourcegraph`).
6. Under **ClusterControlPlaneSecurityGroup**, scroll down or begin typing and select the option prefixed `eks-vpc-sourcegraph-ControlPlaneSecurityGroup-` (Do NOT select the `NodeSecurityGroup`.)
Expand All @@ -61,27 +67,26 @@ Follow the [EKS Getting Started guide](https://docs.aws.amazon.com/eks/latest/us

> **Note:** You can always come back here later and modify these values to scale up/down the number of worker nodes. To do so, just visit the console page again, select **Actions**, **Create Change Set For Current Stack**, enter the same template URL mentioned above, modify the values and hit "next" until reviewing final changes, and finally **Execute**.
9. Under **NodeImageId**, choose based on your region:

| Region | Official image ID |
| --------------------------------- | --------------------- |
| US West (Oregon) (us-west-2) | ami-08cab282f9979fc7a |
| US East (N. Virginia) (us-east-1) | ami-0b2ae3c6bda8b5c06 |
| EU (Ireland) (eu-west-1) | ami-066110c1a7466949e |
9. Under **KeyName**, choose a valid key name so that you can SSH into worker nodes if needed in the future.
10. Under **VpcId**, select `eks-vpc-sourcegraph-VPC`.
11. Under **Subnets**, search for and select *all* `eks-vpc-sourcegraph` subnets.
12. Click **Next** through the following pages until you get the option to **Create stack**. Review the configuration and click **Create stack**.

10. Under **KeyName**, choose a valid key name so that you can SSH into worker nodes if needed in the future.
11. Under **VpcId**, select `eks-vpc-sourcegraph-VPC`.
12. Under **Subnets**, search for and select all `eks-vpc-sourcegraph` subnets.
For more details on these steps, refer to [Worker Nodes: Amazon EKS-optimized Linux AMI](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html).

## Install `kubectl` v1.10+ and configure access to the cluster
## Install `kubectl` and configure access to the cluster

On your dev machine:

1. Install the `aws` CLI tool: [bundled installer](https://docs.aws.amazon.com/cli/latest/userguide/awscli-install-bundle.html), [other installation methods](https://docs.aws.amazon.com/cli/latest/userguide/installing.html).
2. Follow [these instructions](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) to create an access key and `aws configure` the CLI to use it.
3. Install `kubectl` and `aws-iam-authenticator` by following [these steps](https://docs.aws.amazon.com/eks/latest/userguide/configure-kubectl.html).
4. [Configure `kubectl` to interact with your cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-configure-kubectl).
- **Important**: If `kubectl` commands prompt you for username/password, be sure that `kubectl version` reports a client version of v1.10+. Older versions of kubectl do not work with the authentication configuration provided by Amazon EKS.
4. [Configure `kubectl` to interact with your cluster](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html):
```
aws eks update-kubeconfig --name ${cluster_name}
```

**Important**: If `kubectl` commands prompt you for username/password, be sure that `kubectl version` reports a client version of v1.10+. Older versions of kubectl do not work with the authentication configuration provided by Amazon EKS.

At this point, `kubectl get svc` should show something like:

Expand All @@ -95,13 +100,11 @@ kubernetes ClusterIP 172.20.0.1 <none> 443/TCP 4m

Now it is time to enable the worker nodes created by CloudFormation to actually join the Kubernetes cluster:

1. Download, edit, and save this configuration map file:

```
curl -O https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2018-08-30/aws-auth-cm.yaml
```

2. Replace `<ARN of instance role (not instance profile)>` in the file (_do not_ modify the file otherwise) with the correct value. To find this value,
1. Download, edit, and save [this configuration map file](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html):
```
curl -O curl -o aws-auth-cm.yaml https://amazon-eks.s3.us-west-2.amazonaws.com/cloudformation/2020-04-21/aws-auth-cm.yaml
```
2. Replace `rolearn` in the file (_do not_ modify the file otherwise) with the correct value. To find this value:
- Open the [**AWS CloudFormation console**](https://console.aws.amazon.com/cloudformation/).
- Locate and select the `sourcegraph-worker-nodes` row.
- Click the **Output** tab, and copy the **NodeInstanceRole** value.
Expand All @@ -116,7 +119,7 @@ Follow [these short steps](https://docs.aws.amazon.com/eks/latest/userguide/stor

## Deploy the Kubernetes Web UI Dashboard (optional)

See https://docs.aws.amazon.com/eks/latest/userguide/dashboard-tutorial.html
See [Tutorial: Deploy the Kubernetes Dashboard](https://docs.aws.amazon.com/eks/latest/userguide/dashboard-tutorial.html).

## Deploy Sourcegraph! 🎉

Expand Down
26 changes: 19 additions & 7 deletions docs/k8s.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,25 @@ table.
<div class="resources">
<table class="table">
<tr>
<th colspan="3">Compute nodes</th>
<th colspan="4">Compute nodes</th>
</tr>
<tr>
<th>Provider</th><th>Node type</th><th>Boot/ephemeral disk size</th><th>Reference</th>
</tr>
<tr>
<td><b>Amazon EKS (better than plain EC2)</b></td> <td>m5.4xlarge</td> <td>N/A</td> <td><a href="/docs/k8s.eks.md">Deploy Sourcegraph on EKS</a> </td>
</tr>
<tr>
<td><b>AWS EC2</b></td> <td>m5.4xlarge</td> <td>N/A</td> <td><a href="https://kubernetes.io/docs/setup/production-environment/turnkey/aws">Run Kubernetes on EC2</a></td>
</tr>
<tr>
<td><b>Google Kubernetes Engine (GKE)</b></td> <td>n1-standard-16</td> <td>100 GB (default)</td> <td><a href="https://cloud.google.com/kubernetes-engine/docs/quickstart">GKE Quickstart</a></td>
</tr>
<tr>
<td><b>Azure</b></td> <td>D16 v3</td><td>100 GB (SSD preferred)</td> <td><a href="/docs/k8s.azure.md">Deploy Sourcegraph on Azure</a> </td>
</tr>
<tr>
<td><b>Other</b></td> <td>16 vCPU, 60 GiB memory per node</td> <td>100 GB (SSD preferred)</td> <td><a href="https://kubernetes.io/partners/#kcsp">Kubernetes Service Providers</a></td>
</tr>
<tr><th>Provider</th><th>Node type</th><th>Boot/ephemeral disk size</th></tr>
<tr><td><a href="/docs/k8s.eks.md">Amazon EKS (better than plain EC2)</a> </td><td>m5.4xlarge</td><td>N/A</td></tr>
<tr><td><a href="https://kubernetes.io/docs/getting-started-guides/aws/">AWS EC2</a></td><td>m5.4xlarge</td><td>N/A</td></tr>
<tr><td><a href="https://cloud.google.com/kubernetes-engine/docs/quickstart">Google Kubernetes Engine (GKE)</a></td><td>n1-standard-16</td><td>100 GB (default)</td></tr>
<tr><td><a href="/docs/k8s.azure.md">Azure</a> </td><td>D16 v3</td><td>100 GB (SSD preferred)</td></tr>
<tr><td><a href="https://kubernetes.io/docs/setup/pick-right-solution/">Other</a></td><td>16 vCPU, 60 GiB memory per node</td><td>100 GB (SSD preferred)</td></tr>
</table>
</div>

0 comments on commit 9e50db9

Please sign in to comment.