mirrors/k3d
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #63 from rancher/refactor-docs

Browse Source 
[Docs] Prepare for proper documentation
This commit is contained in:
Andy Zhou 2019-05-21 16:00:13 -07:00 committed by GitHub
commit 3947baf3bb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 120 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
README.md
View File

@ -30,7 +30,7 @@ or...
1. Clone this repo, e.g. via `go get -u github.com/rancher/k3d`
2. Inside the repo run
- 'make install-tools' to make sure required go packages are installed
3. Inside the repo run
3. Inside the repo run one of the following commands
- `make build` to build for your current system
- `go install` to install it to your `GOPATH` (**Note**: this will give you unreleased/bleeding-edge changes)
- `make build-cross` to build for all systems
@ -46,87 +46,16 @@ Example Workflow: Create a new cluster and use it with `kubectl`
3. execute some commands like `kubectl get pods --all-namespaces`
4. `k3d delete` to delete the default cluster
### Expose services
## What now?
#### 1. via Ingress
Find more details under the following Links:
1. Create a cluster, mapping the ingress port 80 to localhost:8081
- [Further documentation](docs/documentation.md)
- [Usage examples](docs/examples.md)
- [Frequently asked questions and nice-to-know facts](docs/faq.md)
`k3d create --api-port 6550 --publish 8081:80 --workers 2`
### Connect
- Note: `--api-port 6550` is not required for the example to work. It's used to have `k3s`'s ApiServer listening on port 6550 with that port mapped to the host system.
2. Get the kubeconfig file
`export KUBECONFIG="$(k3d get-kubeconfig --name='k3s-default')"`
3. Create a nginx deployment
`kubectl create deployment nginx --image=nginx`
4. Create a ClusterIP service for it
`kubectl create service clusterip nginx --tcp=80:80`
5. Create an ingress object for it with `kubectl apply -f`
```YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: nginx
annotations:
ingress.kubernetes.io/ssl-redirect: "false"
spec:
rules:
- http:
paths:
- path: /
backend:
serviceName: nginx
servicePort: 80
```
6. Curl it via localhost
`curl localhost:8081/`
#### 2. via NodePort
1. Create a cluster, mapping the port 30080 from worker-0 to localhost:8082
`k3d create --publish 8082:30080@k3d-k3s-default-worker-0 --workers 2`
- Note: Kubernetes' default NodePort range is [`30000-32767`](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport)
... (Steps 2 and 3 like above) ...
1. Create a NodePort service for it with `kubectl apply -f`
```YAML
apiVersion: v1
kind: Service
metadata:
labels:
app: nginx
name: nginx
spec:
ports:
- name: 80-80
nodePort: 30080
port: 80
protocol: TCP
targetPort: 80
selector:
app: nginx
type: NodePort
```
2. Curl it via localhost
`curl localhost:8082/`
## FAQ / Nice to know
- As [@jaredallard](https://github.com/jaredallard) [pointed out](https://github.com/rancher/k3d/pull/48), people running `k3d` on Linux with **LUKS/LVM**, may need to mount `/dev/mapper` into the nodes for the setup to work.
- This will do: `k3d create -v /dev/mapper:/dev/mapper`
1. Join the Rancher community on slack via [slack.rancher.io](https://slack.rancher.io/)
2. Go to [rancher-users.slack.com](https://rancher-users.slack.com) and join our channel #k3d
3. Start chatting

25
docs/documentation.md Normal file
View File

@ -0,0 +1,25 @@
# Documentation
## Functionality
```shell
COMMANDS:
check-tools, ct Check if docker is running
create, c Create a single- or multi-node k3s cluster in docker containers
delete, d, del Delete cluster
stop Stop cluster
start Start a stopped cluster
list, ls, l List all clusters
get-kubeconfig Get kubeconfig location for cluster
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--verbose Enable verbose output
--help, -h show help
--version, -v print the version
```
## Compatibility with `k3s` functionality/options
... under construction ...

81
docs/examples.md Normal file
View File

@ -0,0 +1,81 @@
# Examples
## Expose services
### 1. via Ingress
1. Create a cluster, mapping the ingress port 80 to localhost:8081
`k3d create --api-port 6550 --publish 8081:80 --workers 2`
- Note: `--api-port 6550` is not required for the example to work. It's used to have `k3s`'s ApiServer listening on port 6550 with that port mapped to the host system.
2. Get the kubeconfig file
`export KUBECONFIG="$(k3d get-kubeconfig --name='k3s-default')"`
3. Create a nginx deployment
`kubectl create deployment nginx --image=nginx`
4. Create a ClusterIP service for it
`kubectl create service clusterip nginx --tcp=80:80`
5. Create an ingress object for it with `kubectl apply -f`
```YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: nginx
annotations:
ingress.kubernetes.io/ssl-redirect: "false"
spec:
rules:
- http:
paths:
- path: /
backend:
serviceName: nginx
servicePort: 80
```
6. Curl it via localhost
`curl localhost:8081/`
### 2. via NodePort
1. Create a cluster, mapping the port 30080 from worker-0 to localhost:8082
`k3d create --publish 8082:30080@k3d-k3s-default-worker-0 --workers 2`
- Note: Kubernetes' default NodePort range is [`30000-32767`](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport)
... (Steps 2 and 3 like above) ...
1. Create a NodePort service for it with `kubectl apply -f`
```YAML
apiVersion: v1
kind: Service
metadata:
labels:
app: nginx
name: nginx
spec:
ports:
- name: 80-80
nodePort: 30080
port: 80
protocol: TCP
targetPort: 80
selector:
app: nginx
type: NodePort
```
2. Curl it via localhost
`curl localhost:8082/`

4
docs/faq.md Normal file
View File

@ -0,0 +1,4 @@
# FAQ / Nice to know
- As [@jaredallard](https://github.com/jaredallard) [pointed out](https://github.com/rancher/k3d/pull/48), people running `k3d` on a system with **btrfs**, may need to mount `/dev/mapper` into the nodes for the setup to work.
- This will do: `k3d create -v /dev/mapper:/dev/mapper`