Skip to content

Commit 5d1da81

Browse files
author
Stephen Gutekanst
authored
docs: add Amazon EKS deployment documentation (sourcegraph#89)
* docs: add Amazon EKS deployment documentation * always suggest just `kubectl get svc` * wording changes * re-emphasize how to use UX
1 parent eba4d88 commit 5d1da81

File tree

3 files changed

+133
-2
lines changed

3 files changed

+133
-2
lines changed

‎docs/configure.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,10 +83,10 @@ Run one of the following commands depending on your desired transport protocol:
8383

8484
Add the command you ran to [create-new-cluster.sh](../create-new-cluster.sh) and commit the change.
8585

86-
Once the load balancer has acquired an external IP address, you should be able to access Sourcegraph using that. You can check the external IP address by running the following command:
86+
Once the load balancer has acquired an external address, you should be able to access Sourcegraph using that. You can check the external address by running the following command and looking for the `LoadBalancer` entry:
8787

8888
```bash
89-
kubectl get service sourcegraph-frontend-loadbalancer -o=custom-columns=EXTERNAL-IP:.status.loadBalancer.ingress[*].ip
89+
kubectl get svc
9090
```
9191

9292
### Network rule

‎docs/k8s.eks.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Kubernetes on Amazon EKS
2+
3+
[Amazon EKS](https://aws.amazon.com/eks/) is Amazon's managed Kubernetes offering, similar to how Google Cloud offers managed Kubernetes clusters (GKE).
4+
5+
If your preferred cloud provider is Amazon, we strongly recommend using EKS instead of plain EC2. By using EKS, you will not need to manage your own Kubernetes control plane (complex). Instead, Amazon will provide it for you and you will only be responsible for managing Sourcegraph, which runs on the Kubernetes cluster.
6+
7+
## Create the Amazon EKS Service Role
8+
9+
Follow the [EKS Getting Started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-prereqs) to create the IAM EKS service role:
10+
11+
1. Open the [**IAM console**](https://console.aws.amazon.com/iam/).
12+
2. Click **Roles** -> **Create role**.
13+
3. Choose **EKS**, accept the defaults and **Next: Permissions**.
14+
4. Click **Next: Review**.
15+
5. Under **Role name**, enter `eksServiceRoleSourcegraph`, then **Create role**.
16+
17+
## Create the Amazon EKS Cluster VPC
18+
19+
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:
20+
21+
1. Open the [**AWS CloudFormation console**](https://console.aws.amazon.com/cloudformation/).
22+
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).
23+
3. Click **Create stack**.
24+
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`
25+
5. Under **Stack name**, enter `eks-vpc-sourcegraph`.
26+
6. Click **Next**, **Next**, **Create**.
27+
28+
## Create the Amazon EKS Cluster
29+
30+
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:
31+
32+
1. Open the [**EKS console**](https://console.aws.amazon.com/eks/home#/clusters).
33+
2. Click **Create cluster**.
34+
3. Under **Cluster name**, enter `sourcegraph`.
35+
4. Under **Role ARN**, select `eksServiceRoleSourcegraph`.
36+
5. Under **VPC**, select `eks-vpc-sourcegraph`.
37+
6. Under **Security groups**, select the one prefixed `eks-vpc-sourcegraph-ControlPlaneSecurityGroup-`. (Do NOT select `NodeSecurityGroup`.)
38+
7. Accept all other values as default and click **Create**.
39+
8. Wait for the cluster to finish **CREATING**. This will take around 10 minutes to complete, so grab some ☕.
40+
41+
## Create Kubernetes cluster worker nodes
42+
43+
1. Open the [**AWS CloudFormation console**](https://console.aws.amazon.com/cloudformation/).
44+
2. Click **Create stack**
45+
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`
46+
4. Under **Stack name**, enter `sourcegraph-worker-nodes`.
47+
5. Under **ClusterName**, enter the exact cluster name you used (`sourcegraph`).
48+
6. Under **ClusterControlPlaneSecurityGroup**, scroll down or begin typing and select the option prefixed `eks-vpc-sourcegraph-ControlPlaneSecurityGroup-` (Do NOT select the `NodeSecurityGroup`.)
49+
7. Under **NodeGroupName**, enter `sourcegraph-node-group`.
50+
8. Choose **NodeAutoScalingGroupMinSize** and **NodeAutoScalingGroupMaxSize** and **NodeInstanceType** based on the following chart:
51+
52+
<div class="table">
53+
54+
| Users | Instance type | Min nodes | Max nodes | Cost est. | Attached Storage | Root Storage |
55+
| ------------ | ------------- | --------- | --------- | ---------- | ---------------- | ------------ |
56+
| 10-25 | t2.xlarge | 4 | 6 | $18-27/day | 500 GB | 50 GB |
57+
| 25-500 | t2.xlarge | 5 | 8 | $22-36/day | 500 GB | 50 GB |
58+
| 500-2,000 | t2.xlarge | 6 | 8 | $27-36/day | 500 GB | 50 GB |
59+
| 2,000-4,000 | t2.xlarge | 8 | 10 | $36-45/day | 900 GB | 50 GB |
60+
| 4,000-10,000 | t2.xlarge | 12 | 14 | $53-62/day | 900 GB | 50 GB |
61+
| 10,000+ | t2.2xlarge | 8 | 10 | $71-89/day | 900 GB | 50 GB |
62+
63+
</div>
64+
65+
> **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**.
66+
67+
9. Under **NodeImageId**, choose based on your region:
68+
69+
| Region | Official image ID |
70+
| --------------------------------- | --------------------- |
71+
| US West (Oregon) (us-west-2) | ami-08cab282f9979fc7a |
72+
| US East (N. Virginia) (us-east-1) | ami-0b2ae3c6bda8b5c06 |
73+
| EU (Ireland) (eu-west-1) | ami-066110c1a7466949e |
74+
75+
10. Under **KeyName**, choose a valid key name so that you can SSH into worker nodes if needed in the future.
76+
11. Under **VpcId**, select `eks-vpc-sourcegraph-VPC`.
77+
12. Under **Subnets**, search for and select all `eks-vpc-sourcegraph` subnets.
78+
79+
## Install `kubectl` v1.10+ and configure access to the cluster
80+
81+
On your dev machine:
82+
83+
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).
84+
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.
85+
3. Install `kubectl` and `aws-iam-authenticator` by following [these steps](https://docs.aws.amazon.com/eks/latest/userguide/configure-kubectl.html).
86+
4. [Configure `kubectl` to interact with your cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-configure-kubectl).
87+
- **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.
88+
89+
At this point, `kubectl get svc` should show something like:
90+
91+
```
92+
$ kubectl get svc
93+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
94+
kubernetes ClusterIP 172.20.0.1 <none> 443/TCP 4m
95+
```
96+
97+
## Enable worker nodes to join the Kubernetes cluster
98+
99+
Now it is time to enable the worker nodes created by CloudFormation to actually join the Kubernetes cluster:
100+
101+
1. Download, edit, and save this configuration map file:
102+
103+
```
104+
curl -O https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2018-08-30/aws-auth-cm.yaml
105+
```
106+
107+
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,
108+
- Open the [**AWS CloudFormation console**](https://console.aws.amazon.com/cloudformation/).
109+
- Locate and select the `sourcegraph-worker-nodes` row.
110+
- Click the **Output** tab, and copy the **NodeInstanceRole** value.
111+
3. Run `kubectl apply -f aws-auth-cm.yaml`
112+
4. Watch `kubectl get nodes --watch` until all nodes appear with status `Ready` (this will take a few minutes).
113+
114+
## Create the default storage class
115+
116+
EKS does not have a default Kubernetes storage class out of the box, but one is needed.
117+
118+
Follow [these short steps](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) to create it. (Simply copy and paste the suggested file and run all suggested `kubectl` commands. You do not need to modify the file.)
119+
120+
## Deploy the Kubernetes Web UI Dashboard (optional)
121+
122+
See https://docs.aws.amazon.com/eks/latest/userguide/dashboard-tutorial.html
123+
124+
## Deploy Sourcegraph! 🎉
125+
126+
Your Kubernetes cluster is now all set up and running!
127+
128+
Luckily, deploying Sourcegraph on your cluster is much easier and quicker than the above steps. :)
129+
130+
Follow our [installation documentation](install.md) to continue.

‎docs/k8s.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ table.
2424
<th colspan="3">Compute nodes</th>
2525
</tr>
2626
<tr><th>Provider</th><th>Node type</th><th>Boot/ephemeral disk size</th></tr>
27+
<tr><td><a href="/docs/k8s.eks.md">AWS EKS (better than plain EC2)</a> </td><td>t2.xlarge</td><td>N/A</td></tr>
2728
<tr><td><a href="https://kubernetes.io/docs/getting-started-guides/aws/">AWS EC2</a></td><td>m4.4xlarge</td><td>N/A</td></tr>
2829
<tr><td><a href="https://cloud.google.com/container-engine/docs/quickstart">Google Compute Engine</a></td><td>n1-standard-16</td><td>100 GB (default)</td></tr>
2930
<tr><td><a href="/docs/k8s.azure.md">Azure</a> </td><td>D16 v3</td><td>100 GB (SSD preferred)</td></tr>

0 commit comments

Comments
 (0)