Merge pull request #63 from rancher/refactor-docs

[Docs] Prepare for proper documentation

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
@@ -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

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 ...

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/`

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`