From 6e42d079f753202475374b10e1aa017f6bd20528 Mon Sep 17 00:00:00 2001 From: iwilltry42 Date: Tue, 21 May 2019 16:16:33 +0200 Subject: [PATCH 1/3] refactor documentation --- README.md | 87 +++---------------------------------------- docs/documentation.md | 25 +++++++++++++ docs/examples.md | 81 ++++++++++++++++++++++++++++++++++++++++ docs/faq.md | 4 ++ 4 files changed, 115 insertions(+), 82 deletions(-) create mode 100644 docs/documentation.md create mode 100644 docs/examples.md create mode 100644 docs/faq.md diff --git a/README.md b/README.md index 2251cf013..bc65a8fdd 100644 --- a/README.md +++ b/README.md @@ -46,87 +46,10 @@ 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... -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/` - -## 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` \ No newline at end of file +- [... further documentation here](docs/documentation.md) +- [... usage examples here](docs/examples.md) +- [... frequently asked questions and nice-to-know facts here](docs/faq.md) \ No newline at end of file diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 000000000..13e6f28ba --- /dev/null +++ b/docs/documentation.md @@ -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 ... \ No newline at end of file diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 000000000..584e56c94 --- /dev/null +++ b/docs/examples.md @@ -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/` \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..2ff264abc --- /dev/null +++ b/docs/faq.md @@ -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` \ No newline at end of file From 41ccf89fdcbfdfcf18190c8747e1f90e89b46a50 Mon Sep 17 00:00:00 2001 From: iwilltry42 Date: Wed, 22 May 2019 00:27:45 +0200 Subject: [PATCH 2/3] improve section --- README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index bc65a8fdd..98b31c848 100644 --- a/README.md +++ b/README.md @@ -48,8 +48,14 @@ Example Workflow: Create a new cluster and use it with `kubectl` ## What now? -Find... +Find more details under the following Links: -- [... further documentation here](docs/documentation.md) -- [... usage examples here](docs/examples.md) -- [... frequently asked questions and nice-to-know facts here](docs/faq.md) \ No newline at end of file +- [Further documentation](docs/documentation.md) +- [Usage examples](docs/examples.md) +- [Frequently asked questions and nice-to-know facts](docs/faq.md) + +### Connect + +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 \ No newline at end of file From a3bb1b03f3dd7606c82915412229e42df70d5332 Mon Sep 17 00:00:00 2001 From: iwilltry42 Date: Wed, 22 May 2019 00:28:23 +0200 Subject: [PATCH 3/3] clarification --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 98b31c848..2bbedcfcd 100644 --- a/README.md +++ b/README.md @@ -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