Skip to content

Commit

Permalink
docs(autok3s): update and refactor all docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@yzeng25 @Jason-ZW
yzeng25 authored and Jason-ZW committed Feb 8, 2021
1 parent a03f4af commit 0ae2a86
Show file tree
Hide file tree
Showing 8 changed files with 610 additions and 347 deletions.
2 changes: 1 addition & 1 deletion docs/i18n/en_us/alibaba/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This article provides users with the instrcutions to create and launch a K3s clu

## Prerequisites

To ensure that ECS instances can be created and accessed successfully, please follow the instrctions below.
To ensure that ECS instances can be created and accessed successfully, please follow the instructions below.

### Setting up Environment

Expand Down
148 changes: 90 additions & 58 deletions docs/i18n/en_us/aws/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
# AWS Provider

It uses the AWS Cloud SDK to create and manage EC2 instances, and then uses SSH to install k3s cluster to the remove host.
You can also use it to join hosts as masters/agents to the k3s cluster.
English / [简体中文](docs/i18n/zh_cn/aws/README.md)

## Pre-Requests
## Introduction

To ensure that EC2 instances can be created and accessed normally, please check and set the following configuration.
This article provides users with the instrcutions to create and launch a K3s cluster on an AWS EC2 instance, and to add nodes for an existing K3s cluster on AWS EC2 instance. In additon, this article provides guidance of advanced usages of running K3s on AWS EC2, such as setting up private registry, enabling AWS CCM, and enabling UI components.

### Setup Environment
## Prerequisites

To ensure that EC2 instances can be created and accessed successfully, please follow the instructions below.

### Setting up Environment

Configure the following environment variables for the host which running `autok3s`.

Expand All @@ -16,50 +19,50 @@ export AWS_ACCESS_KEY_ID='<access-key>'
export AWS_SECRET_ACCESS_KEY='<secret-key>'
```

### Setup IAM
### Setting up IAM

Please refer [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html?icmpid=docs_iam_console) for more IAM settings.

Please make sure your account has permission to manage EC2 instance or other relative resources.

For example:

```
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:AuthorizeSecurityGroupIngress",
"ec2:Describe*",
"ec2:ImportKeyPair",
"ec2:CreateKeyPair",
"ec2:CreateSecurityGroup",
"ec2:CreateTags",
"ec2:DeleteKeyPair",
"ec2:RunInstances",
"ec2:RebootInstances",
"ec2:TerminateInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:CreateInstanceProfile",
"ec2:RevokeSecurityGroupIngress",
"ec2:DeleteTags",
"elasticloadbalancing:Describe*",
"iam:Get*",
"iam:List*",
"iam:PassRole"
],
"Resource": "*"
}
]
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:AuthorizeSecurityGroupIngress",
"ec2:Describe*",
"ec2:ImportKeyPair",
"ec2:CreateKeyPair",
"ec2:CreateSecurityGroup",
"ec2:CreateTags",
"ec2:DeleteKeyPair",
"ec2:RunInstances",
"ec2:RebootInstances",
"ec2:TerminateInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:CreateInstanceProfile",
"ec2:RevokeSecurityGroupIngress",
"ec2:DeleteTags",
"elasticloadbalancing:Describe*",
"iam:Get*",
"iam:List*",
"iam:PassRole"
],
"Resource": "*"
}
]
}
```

### Setup Security Group
### Setting up Security Group

The ECS instances need to apply the following Security Group Rules:
The EC2 instances need to apply the following **minimum** Security Group Rules:

```bash
Rule Protocol Port Source Description
Expand All @@ -72,61 +75,86 @@ InBound TCP 2379,2380 K3s server nodes (Optional) Required only fo
OutBound ALL ALL ALL Allow All
```

## Usage
## Creating a K3s cluster

More usage details please running `autok3s <sub-command> --provider aws --help` commands.
Please use `autok3s create` command to create a cluster in your EC2 instance.

### Quick Start
### Normal Cluster

Create and Start 1 master & 1 worker(agent) k3s cluster.
The following command uses AWS as cloud provider, creates a K3s cluster named "myk3s", and assign it with 1 master node and 1 worker node:

```bash
autok3s -d create -p aws --name myk3s --master 1 --worker 1
```

### Setup K3s HA Cluster
### HA Cluster

Please use one of the following commands to create an HA cluster.

HA(embedded etcd: >= 1.19.1-k3s1) mode. e.g.
#### Embedded etcd

The following command uses AWS as cloud provider, creates an HA K3s cluster named "myk3s", and assigns it with 3 master nodes.

```bash
autok3s -d create -p aws --name myk3s --master 3 --cluster
```

HA(external database) mode need `--master` greater than 1, also need to specify `--datastore`, e.g.
#### External Database

The following requirements must be met before creating an HA K3s cluster with external database:

- The number of master nodes in this cluster must be greater or equal to 1.
- The external database information must be specified within `--datastore "PATH"` parameter.

In the example below, `--master 2` specifies the number of master nodes to be 2, while `--datastore "PATH"` specifies the external database information. As a result, requirements listed above are met.

Run the command below and create an HA K3s cluster with external database:

```bash
autok3s -d create -p aws --name myk3s --master 2 --datastore "mysql://<user>:<password>@tcp(<ip>:<port>)/<db>"
```

### Join K3s Nodes
## Join K3s Nodes

To join master/agent nodes, specify the cluster you want to add, e.g myk3s.
Please use `autok3s join` command to add one or more nodes for an existing K3s cluster.

### Normal Cluster

The command below shows how to add a worker node for an existing K3s cluster named "myk3s".

```bash
autok3s -d join --provider aws --name myk3s --worker 1
```

Join master nodes to (embedded etcd: >= 1.19.1-k3s1) HA cluster. e.g.
### HA Cluster

The commands to add one or more nodes for an existing HA K3s cluster varies based on the types of HA cluster. Please choose one of the following commands to run.

#### Embedded etcd

Run the command below, to add 2 master nodes for an Embedded etcd HA cluster(embedded etcd: >= 1.19.1-k3s1).

```bash
autok3s -d join --provider aws --name myk3s --master 2
```

Join master nodes to (external database) HA cluster, also need to specify `--datastore`, e.g.
#### External Database

Run the command below, to add 2 master nodes for an HA cluster with external database, you will need to fill in `--datastore "PATH"` as well.

```bash
autok3s -d join --provider aws --name myk3s --master 2 --datastore "mysql://<user>:<password>@tcp(<ip>:<port>)/<db>"
```

### Delete K3s Cluster
## Delete K3s Cluster

This command will delete a k3s cluster, e.g myk3s.
This command will delete a k3s cluster named "myk3s".

```bash
autok3s -d delete --provider aws --name myk3s
```

### List K3s Clusters
## List K3s Clusters

This command will list the clusters that you have created on this machine.

Expand All @@ -139,7 +167,7 @@ NAME REGION PROVIDER STATUS MASTERS WORKERS VERSION
myk3s ap-southeast-2 aws Running 1 0 v1.20.2+k3s1
```

### Describe k3s cluster
## Describe k3s cluster

This command will show detail information of specified cluster, such as instance status, node IP, kubelet version, etc.

Expand Down Expand Up @@ -170,7 +198,7 @@ Nodes:
version: v1.20.2+k3s1
```

### Access K3s Cluster
## Access K3s Cluster

After the cluster created, `autok3s` will automatically merge the `kubeconfig` which necessary for us to access the cluster.

Expand All @@ -186,19 +214,23 @@ autok3s kubectl config get-contexts
autok3s kubectl config use-context <context>
```

### SSH K3s Cluster's Node
## SSH K3s Cluster's Node

Login to specified k3s cluster node via ssh, e.g myk3s.

```bash
autok3s ssh --provider aws --name myk3s
```

## Advanced Usage
## Other Usages

More usage details please running `autok3s <sub-command> --provider aws --help` commands.

## Advanced Usages

We integrate some advanced components related to the current provider, e.g. ccm/ui.
We integrate some advanced components such as private registries, AWS Cloud Controller Manager(CCM) and UI, related to the current provider.

### Setup Private Registry
### Setting up Private Registry

Below are examples showing how you may configure `/etc/autok3s/registries.yaml` on your current node when using TLS, and make it take effect on k3s cluster by `autok3s`.

Expand Down Expand Up @@ -229,7 +261,7 @@ autok3s -d create \
--registry /etc/autok3s/registries.yaml
```

### Enable AWS Cloud Controller Manager
### Enabling AWS Cloud Controller Manager(CCM)

Please check [this](https://kubernetes.github.io/cloud-provider-aws/prerequisites.html) to prepare IAM policies as prerequisites.

Expand Down
Loading

0 comments on commit 0ae2a86

Please sign in to comment.