gregandev
/
k3d
mirror of https://github.com/k3d-io/k3d
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #63 from rancher/refactor-docs

Browse Source 
[Docs] Prepare for proper documentation
pull/48/head v1.2.2-beta.0
Andy Zhou 5 years ago committed by GitHub
parent ea96d375af a3bb1b03f3
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 all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 91
      README.md
  2. 25
      docs/documentation.md
  3. 81
      docs/examples.md
  4. 4
      docs/faq.md

91
README.md
Unescape 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
Unescape 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
Unescape 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
Unescape 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`
Write Preview
Loading…
Cancel
Save