Usage docs (#501)

* Add setup and usage docs Signed-off-by: lucperkins <lucperkins@gmail.com> * Finish initial version of setup doc * Add YAML config file for CLI docs * Finish CLI shortcode Signed-off-by: lucperkins <lucperkins@gmail.com> * Fix scrolling on mobile Signed-off-by: lucperkins <lucperkins@gmail.com> * Finish first version of usage doc Signed-off-by: lucperkins <lucperkins@gmail.com> * Remove go install section, modify CSS for CLI docs, and fix typo Signed-off-by: lucperkins <lucperkins@gmail.com>
2019-01-24 11:01:42 -08:00
parent 48127bfcf5
commit 318edee630
13 changed files with 252 additions and 8 deletions
--- a/website/assets/js/app.js
+++ b/website/assets/js/app.js
@@ -4,7 +4,7 @@ function anchorJs() {
      icon: '#'
    }

-    anchors.add('.content h2, .content h3, .content h4');
+    anchors.add('.cli h2, .content h2, .content h3, .content h4');
  }
 }

--- a/website/assets/sass/cli.sass
+++ b/website/assets/sass/cli.sass
@@ -0,0 +1,46 @@
+=border
+  border: 1px solid $grey-light
+  
+.cli
+  +border
+  padding: 1.25rem
+  margin: 2rem 0
+  overflow: scroll
+
+  &-title
+    font-size: 1rem
+    margin-bottom: 3rem
+    font-family: $family-code
+    
+    h2
+      color: $primary
+  
+  &-description
+    font-size: 1.25rem
+  
+  &-example
+    background-color: $black
+    padding: 1.25rem
+    font-family: $family-code
+    color: $white-bis
+    font-size: 1.1rem
+    margin: 1rem 0
+    font-weight: 700
+
+    .dollar
+      color: $primary
+
+    .flags
+      color: $red
+    
+  &-flags
+    +border
+    padding: 1rem
+    overflow: scroll     
+
+    .flag
+      font-family: $family-code
+      color: $primary
+
+      .arg
+        color: $dark
--- a/website/assets/sass/style.sass
+++ b/website/assets/sass/style.sass
@@ -32,7 +32,7 @@ $link-hover: $dark
 $code: $primary

 $family-sans-serif: "{{ $sansSerifFont }}", BlinkMacSystemFont, -apple-system, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", "Helvetica", "Arial", sans-serif
-//$family-code: "{{ $monospaceFont }}", monospace
+$family-code: "{{ $monospaceFont }}", monospace
 $section-padding: 3rem 4rem

 $navbar-height: 5rem
@@ -53,6 +53,8 @@ $colors: mergeColorMaps(("twitter-blue": ($twitter-blue, $white), "slack-green":
@import "bulma-dashboard/bulma-dashboard.sass"
@import "bulma-toc/bulma-toc.sass"

+@import "cli"
+
 // Ensure sticky footer at the bottom of the page
 .page
  display: flex
--- a/website/content/docs/providers.md
+++ b/website/content/docs/providers.md
@@ -1,7 +1,7 @@
 ---
 title: Providers
 description: Extend the Virtual Kubelet interface
-weight: 2
+weight: 4
 ---

 The Virtual Kubelet provides a pluggable **provider interface** that developers can implement to define the actions of a typical kubelet.
--- a/website/content/docs/setup.md
+++ b/website/content/docs/setup.md
@@ -0,0 +1,24 @@
+---
+title: Setup
+description: Install Virtual Kubelet using one of several methods
+weight: 1
+---
+
+You can install Virtual Kubelet by building it [from source](#source). First, make sure that you have a [`GOPATH`](https://github.com/golang/go/wiki/GOPATH) set. Then clone the Virtual Kubelet repository and run `make build`:
+
+```bash
+mkdir -p ${GOPATH}/src/github.com/virtual-kubelet
+cd ${GOPATH}/src/github.com/virtual-kubelet
+git clone https://github.com/virtual-kubelet/virtual-kubelet
+make build
+```
+
+This method adds a `virtual-kubelet` executable to the `bin` folder. To run it:
+
+```bash
+bin/virtual-kubelet
+```
+
+## Using Virtual Kubelet
+
+Once you have Virtual Kubelet installed, you can move on to the [Usage](../usage) documentation.
--- a/website/content/docs/usage.md
+++ b/website/content/docs/usage.md
@@ -0,0 +1,55 @@
+---
+title: Usage
+description: Run a Virtual Kubelet inside or outside of your Kubernetes cluster
+weight: 2
+---
+
+Virtual Kubelet is run via the `virtual-kubelet` command-line tool (documented [below](#virtual-kubelet-cli)). You can run Virtual Kubelet either [outside](#outside-k8s) or [inside](#inside-k8s) of a Kubernetes cluster.
+
+## Outside of a Kubernetes cluster {#outside-k8s}
+
+> Before you go through this section, make sure to [install Virtual Kubelet](../setup) first.
+
+To run Virtual Kubelet outside of a Kubernetes cluster, run the [`virtual-kubelet`](#virtual-kubelet-cli) binary with your chosen [provider](../providers). Here's an example:
+
+```bash
+virtual-kubelet --provider aws
+```
+
+Once the Virtual Kubelet is deployed, run `kubectl get nodes` and you should see a `virtual-kubelet` node (unless you've named it something else using the [`--nodename`](#virtual-kubelet-cli) flag).
+
+<!-- The CLI docs are generated using the shortcode in layouts/shortcodes/cli.html
+and the YAML config in data/cli.yaml
+-->
+{{< cli >}}
+
+## Inside a Kubernetes cluster {#inside-k8s}
+
+It's possible to run the Virtual Kubelet as a Kubernetes Pod inside a [Minikube](https://kubernetes.io/docs/setup/minikube/) or [Docker for Desktop](https://docs.docker.com/docker-for-windows/kubernetes/) Kubernetes cluster.
+
+> At this time, automation of this deployment is supported only for the [`mock`](https://github.com/virtual-kubelet/virtual-kubelet/tree/master/providers/mock) provider.
+
+In order to deploy the Virtual Kubelet, you need to install [Skaffold](https://skaffold.dev/), a Kubernetes development tool. You also need to make sure that your current [kubectl context](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) is either `minikube` or `docker-for-desktop` (depending on which Kubernetes platform you're using).
+
+First, clone the Virtual Kubelet repository:
+
+```bash
+git clone https://github.com/virtual-kubelet/virtual-kubelet
+cd virtual-kubelet
+```
+
+Then:
+
+```bash
+make skaffold
+```
+
+By default, this will run Skaffold in [development mode](https://github.com/GoogleContainerTools/skaffold#skaffold-dev), which will make Skaffold watch [`hack/skaffold/virtual-kubelet/Dockerfile`](https://github.com/virtual-kubelet/virtual-kubelet/blob/master/hack/skaffold/virtual-kubelet/Dockerfile) and its dependencies for changes and re-deploy the Virtual Kubelet when changes happen. It will also make Skaffold stream logs from the Virtual Kubelet Pod.
+
+Alternative, you can run Skaffold outside of development mode—if you aren't concerned about continuous deployment and log streaming—by running:
+
+```bash
+make skaffold MODE=run
+```
+
+This will build and deploy the Virtual Kubelet and return.
--- a/website/data/cli.yaml
+++ b/website/data/cli.yaml
@@ -0,0 +1,60 @@
+description: The command-line tool for running Virtual Kubelets
+flags:
+- name: --disable-taint
+  description: Disable the Virtual Kubelet [Node taint](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
+  default: "false"
+- name: --full-resync-period
+  arg: duration
+  description: How often to perform a full resync of Pods between Kubernetes and the provider
+  default: 1m0s
+- name: --kubeconfig
+  arg: string
+  description: kubectl config file
+  default: $HOME/.kube/config
+- name: --log-level
+  arg: string
+  description: The log level, e.g. `trace` `debug`, `info`, `warn`, or `error`
+  default: info
+- name: --metrics-addr
+  arg: string
+  description: The address to listen on for metrics and stats
+  default: ":10255"
+- name: --namespace
+  arg: string
+  description: The Kubernetes namespace
+  default: all
+- name: --nodename
+  arg: string
+  description: The Kubernetes Node name
+  default: virtual-kubelet
+- name: --os
+  arg: string
+  description: The operating system (must be `Linux` or `Windows`)
+  default: Linux
+- name: --pod-sync-workers
+  arg: int
+  description: The number of Pod synchronization workers
+  default: 10
+- name: --provider
+  arg: string
+  description: The Virtual Kubelet [provider](/docs/providers)
+- name: --provider-config
+  arg: string
+  description: The Virtual Kubelet [provider](/docs/providers) configuration file
+- name: --trace-exporter
+  arg: strings
+  description: The tracing exporter to use. Available exporters are `jaeger` and `ocagent`.
+- name: --trace-sample-rate
+  arg: string
+  description: The probability of tracing samples
+- name: --trace-service-name
+  arg: string
+  description: The name of the services used to register with the trace exporter
+  default: virtual-kubelet
+- name: --trace-tag
+  arg: map
+  description: Tags to include with traces, in `key=value` form
+- name: --version
+  description: The Virtual Kubelet version
+- name: --help
+  description: Command help information
--- a/website/layouts/partials/docs/main.html
+++ b/website/layouts/partials/docs/main.html
@@ -2,7 +2,7 @@
  {{ partial "docs/header.html" . }}

  <section class="section">
-    <div class="content is-medium">
+    <div class="content">
      {{ .Content }}
    </div>
  </section>
--- a/website/layouts/shortcodes/cli.html
+++ b/website/layouts/shortcodes/cli.html
@@ -0,0 +1,57 @@
+{{ $cli         := .Site.Data.cli }}
+{{ $description := $cli.description | markdownify }}
+{{ $flags       := $cli.flags }}
+<div class="cli">
+  <span class="cli-title" id="virtual-kubelet-cli">
+    <h2>
+      virtual-kubelet
+    </h2>
+  </span>
+
+  <p class="cli-description">
+    {{ $description }}
+  </p>
+
+  <div class="cli-example">
+    <span class="dollar">$</span> virtual-kubelet <span class="flags">flags</span>
+  </div>
+
+  <div class="cli-flags">
+    <h3>
+      Flags
+    </h3>
+
+    <table>
+      <thead>
+        <tr>
+          <th>
+            Flag
+          </th>
+          <th>
+            Description
+          </th>
+          <th>
+            Default
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        {{ range $flags }}
+        <tr>
+          <td class="flag">
+            {{ .name }}{{ with .arg }} <span class="arg">{{ . }}</span>{{ end }}
+          </td>
+          <td>
+            {{ .description | markdownify }}
+          </td>
+          <td>
+            {{ with .default }}
+            <code>{{ . }}</code>
+            {{ end }}
+          </td>
+        </tr>
+        {{ end }}
+      </tbody>
+    </table>
+  </div>
+</div>
--- a/website/resources/_gen/assets/js/js/app.js_d11fe7b62c27961c87ecd0f2490357b9.content
+++ b/website/resources/_gen/assets/js/js/app.js_d11fe7b62c27961c87ecd0f2490357b9.content
@@ -1,5 +1,5 @@
 function anchorJs(){if($('.is-docs-page').length>0){anchors.options={icon:'#'}
-anchors.add('.content h2, .content h3, .content h4');}}
+anchors.add('.cli h2, .content h2, .content h3, .content h4');}}
 function scrollFadeInOut(threshold,element){$(window).scroll(function(){if($(this).scrollTop()>threshold){element.fadeIn();}else{element.fadeOut();}});}
 function navbarScrollToggle(){const navbar=$('.is-home-page .navbar');const heroHeight=$('.hero').height();scrollFadeInOut(heroHeight,navbar);}
 $(function(){anchorJs();navbarScrollToggle();});
--- a/website/resources/_gen/assets/js/js/app.js_d11fe7b62c27961c87ecd0f2490357b9.json
+++ b/website/resources/_gen/assets/js/js/app.js_d11fe7b62c27961c87ecd0f2490357b9.json
@@ -1 +1 @@
-{"Target":"js/app.min.f21b34fa42a57f2e8dd0f59faffe4a19d8eb880de4359555cb257d027a2c1481.js","MediaType":"application/javascript","Data":{"Integrity":"sha256-8hs0+kKlfy6N0PWfr/5KGdjriA3kNZVVyyV9AnosFIE="}}
+{"Target":"js/app.min.9e071501d6584bd61565975c3dfba5db8331dfc23dec319aa0e13bd88638bb49.js","MediaType":"application/javascript","Data":{"Integrity":"sha256-ngcVAdZYS9YVZZdcPful24Mx38I97DGaoOE72IY4u0k="}}
--- a/website/resources/_gen/assets/sass/sass/style.sass_6af550c30182af2cbd2f775fdbb9d3bc.content
+++ b/website/resources/_gen/assets/sass/sass/style.sass_6af550c30182af2cbd2f775fdbb9d3bc.content
--- a/website/resources/_gen/assets/sass/sass/style.sass_6af550c30182af2cbd2f775fdbb9d3bc.json
+++ b/website/resources/_gen/assets/sass/sass/style.sass_6af550c30182af2cbd2f775fdbb9d3bc.json
@@ -1 +1 @@
-{"Target":"css/style.7557002ca2e3a2c3558d1dd6957c18a5a518c37b0da952b617441ae9ed7ffc04.css","MediaType":"text/css","Data":{"Integrity":"sha256-dVcALKLjosNVjR3WlXwYpaUYw3sNqVK2F0Qa6e1//AQ="}}
+{"Target":"css/style.35ad12b92255aeb32325f4f75c3b731908876cea6d08e142530f92e44ea8d018.css","MediaType":"text/css","Data":{"Integrity":"sha256-Na0SuSJVrrMjJfT3XDtzGQiHbOptCOFCUw+S5E6o0Bg="}}