add descriptions for examples docs

related #14
clustergarage · Nov 30, 2018 · cbd16c6 · cbd16c6
1 parent a8951f9
commit cbd16c6
Show file tree

Hide file tree

Showing 12 changed files with 305 additions and 34 deletions.
diff --git a/docs/changelog/index.html b/docs/changelog/index.html
@@ -129,7 +129,7 @@ <h3>v0.2.0 <span class="uk-label">Release</span></h3>
                         <h5>10/10/2018</h5>
                     </div>
                     <div class="tm-timeline-body">
-                        <h3>v0.1.0 <span class="uk-label">Release</span></h3>
+                        <h3>v0.1.0 <span class="uk-label">Pre-Release</span></h3>
                         <ul class="uk-list">
 
                             <li><p>Initial functionality of both argusd and argus-controller.</p>

diff --git a/docs/docs/arguswatcher/index.html b/docs/docs/arguswatcher/index.html
@@ -14,9 +14,9 @@
 <meta property="og:description" content="Once you have Argus installed on your cluster, you are ready to start setting up watchers for your deployments. All possible configurations of the how, and what, of setting up an ArgusWatcher on your deployments are described below." />
 <meta property="og:site_name" content="Argus" />
 <meta property="og:type" content="article" />
-<meta property="article:published_time" content="2018-11-30T15:21:57-05:00" />
+<meta property="article:published_time" content="2018-11-30T16:26:38-05:00" />
 <script type="application/ld+json">
-{"description":"Once you have Argus installed on your cluster, you are ready to start setting up watchers for your deployments. All possible configurations of the how, and what, of setting up an ArgusWatcher on your deployments are described below.","@type":"BlogPosting","url":"/argus/docs/arguswatcher/","headline":"Defining an ArgusWatcher","datePublished":"2018-11-30T15:21:57-05:00","dateModified":"2018-11-30T15:21:57-05:00","mainEntityOfPage":{"@type":"WebPage","@id":"/argus/docs/arguswatcher/"},"@context":"http://schema.org"}</script>
+{"description":"Once you have Argus installed on your cluster, you are ready to start setting up watchers for your deployments. All possible configurations of the how, and what, of setting up an ArgusWatcher on your deployments are described below.","@type":"BlogPosting","url":"/argus/docs/arguswatcher/","headline":"Defining an ArgusWatcher","datePublished":"2018-11-30T16:26:38-05:00","dateModified":"2018-11-30T16:26:38-05:00","mainEntityOfPage":{"@type":"WebPage","@id":"/argus/docs/arguswatcher/"},"@context":"http://schema.org"}</script>
 <!-- End Jekyll SEO tag -->
 
   <meta property="og:image" content=""/>

diff --git a/docs/docs/examples/index.html b/docs/docs/examples/index.html
@@ -14,9 +14,9 @@
 <meta property="og:description" content="Topics" />
 <meta property="og:site_name" content="Argus" />
 <meta property="og:type" content="article" />
-<meta property="article:published_time" content="2018-11-30T15:21:57-05:00" />
+<meta property="article:published_time" content="2018-11-30T16:26:38-05:00" />
 <script type="application/ld+json">
-{"description":"Topics","@type":"BlogPosting","url":"/argus/docs/examples/","headline":"Examples","datePublished":"2018-11-30T15:21:57-05:00","dateModified":"2018-11-30T15:21:57-05:00","mainEntityOfPage":{"@type":"WebPage","@id":"/argus/docs/examples/"},"@context":"http://schema.org"}</script>
+{"description":"Topics","@type":"BlogPosting","url":"/argus/docs/examples/","headline":"Examples","datePublished":"2018-11-30T16:26:38-05:00","dateModified":"2018-11-30T16:26:38-05:00","mainEntityOfPage":{"@type":"WebPage","@id":"/argus/docs/examples/"},"@context":"http://schema.org"}</script>
 <!-- End Jekyll SEO tag -->
 
   <meta property="og:image" content=""/>
@@ -128,19 +128,69 @@ <h1 class="uk-article-title">Examples</h1>
                         <h4 class="no_toc" id="topics">Topics</h4>
 <ul id="markdown-toc">
   <li><a href="#kubernetes" id="markdown-toc-kubernetes">Kubernetes</a>    <ul>
-      <li><a href="#guestbook-example" id="markdown-toc-guestbook-example">Guestbook Example</a></li>
       <li><a href="#nginx-example" id="markdown-toc-nginx-example">NGiNX Example</a></li>
+      <li><a href="#guestbook-example" id="markdown-toc-guestbook-example">Guestbook Example</a></li>
     </ul>
   </li>
   <li><a href="#openshift" id="markdown-toc-openshift">OpenShift</a>    <ul>
       <li><a href="#django-example" id="markdown-toc-django-example">Django Example</a></li>
-      <li><a href="#jenkins-sidecar-example" id="markdown-toc-jenkins-sidecar-example">Jenkins Sidecar Example</a></li>
+      <li><a href="#jenkins-sidecar-example-advanced" id="markdown-toc-jenkins-sidecar-example-advanced">Jenkins Sidecar Example (Advanced)</a></li>
     </ul>
   </li>
 </ul>
 
 <h2 id="kubernetes">Kubernetes</h2>
 
+<p>Whether you’re running a vanilla Kubernetes cluster with minikube, or in a
+cloud-provided one such as GKE, we provide a set of examples to test out
+Argus located in the <a href="https://github.com/clustergarage/argus/tree/master/examples">examples/
+folder</a> of the
+GitHub repo.</p>
+
+<h3 id="nginx-example">NGiNX Example</h3>
+
+<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>kubectl run nginx <span class="nt">--image</span><span class="o">=</span>nginx
+kubectl apply <span class="nt">-f</span> <span class="se">\</span>
+  https://raw.githubusercontent.com/clustergarage/argus/master/examples/nginx-argus-watch.yaml
+</code></pre></div></div>
+
+<p>This is a basic example of monitoring two different paths for a single event.
+The watcher spec has a single subject that watches:</p>
+
+<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">paths</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">/etc/nginx</span>
+<span class="pi">-</span> <span class="s">/etc/init.d/nginx</span>
+<span class="na">events</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">modify</span>
+</code></pre></div></div>
+
+<p>If you were to change any of the files under <code class="highlighter-rouge">/etc/nginx</code> it would notify on
+that <code class="highlighter-rouge">modify</code> message.</p>
+
+<p>You could also edit this watcher and update the <code class="highlighter-rouge">paths</code> to include
+<code class="highlighter-rouge">/var/log/nginx</code>. This should update the watcher, that you can then exec into
+the container to generate some messages:</p>
+
+<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>kubectl <span class="nb">exec</span> <span class="nt">-it</span> &lt;nginx-pod-name&gt; <span class="nt">--</span> /bin/bash
+
+root@&lt;nginx-pod-name&gt;:/# <span class="nb">echo</span> <span class="s2">"test"</span> <span class="o">&gt;&gt;</span> /var/log/nginx/foo.log
+</code></pre></div></div>
+
+<p>This will create a new log file and generate a <code class="highlighter-rouge">MODIFY</code> event that will show up
+in the <code class="highlighter-rouge">argusd</code> logs:</p>
+
+<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>kubectl logs &lt;argusd-pod-name&gt;
+
+MODIFY file <span class="s1">'/var/log/nginx/foo.log'</span> <span class="o">(</span>&lt;nginx-pod-name&gt;:&lt;node-name&gt;<span class="o">)</span>
+</code></pre></div></div>
+
+<p>Another interesting test to try is to edit the <a href="/argus/docs/arguswatcher/#recursively-watching-a-directory">ArgusWatcher
+definition</a>
+with <code class="highlighter-rouge">recursive: true</code> on the subject to receive all events that happen under
+subdirectories of the specified paths as well. For example, editing the
+<code class="highlighter-rouge">/etc/nginx/conf.d/default.conf</code> once it is watching recursively would report
+messages when it previously would have not.</p>
+
 <h3 id="guestbook-example">Guestbook Example</h3>
 
 <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>kubectl apply <span class="nt">-f</span> <span class="se">\</span>
@@ -149,30 +199,110 @@ <h3 id="guestbook-example">Guestbook Example</h3>
   https://raw.githubusercontent.com/clustergarage/argus/master/examples/guestbook-argus-watch.yaml
 </code></pre></div></div>
 
-<h3 id="nginx-example">NGiNX Example</h3>
+<p>The “Hello World” of Kubernetes deployments can be monitored fairly easily.
+Since this creates both a backend and frontend deployment with differing
+labels, we’ll need to create two watchers as well.</p>
 
-<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>kubectl run nginx <span class="nt">--image</span><span class="o">=</span>nginx
-kubectl apply <span class="nt">-f</span> <span class="se">\</span>
-  https://raw.githubusercontent.com/clustergarage/argus/master/examples/nginx-argus-watch.yaml
+<p>The frontend matches on labels: <code class="highlighter-rouge">app=guestbook,tier=frontend</code> with a subject:</p>
+
+<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">paths</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">/var/www/html</span>
+<span class="na">events</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">modify</span>
 </code></pre></div></div>
 
+<p>The backend matches on labels: <code class="highlighter-rouge">app=redis,tier=backend</code> with a subject:</p>
+
+<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">paths</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">/data</span>
+<span class="na">events</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">create</span>
+<span class="pi">-</span> <span class="s">modify</span>
+</code></pre></div></div>
+
+<p>The Redis app that runs in this backend container will create and modify
+various data objects as it goes. We can see these being monitored as they
+happen as a simple test.</p>
+
 <h2 id="openshift">OpenShift</h2>
 
+<p>With an OpenShift cluster, we provide some slightly different examples, though
+the watcher definition is completely environment-agnostic. These are also
+located under the <a href="https://github.com/clustergarage/argus/tree/master/examples">examples/
+folder</a> of the
+GitHub repo.</p>
+
 <h3 id="django-example">Django Example</h3>
 
 <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>oc new-app python:3.5~https://github.com/openshift/django-ex
 oc apply <span class="nt">-f</span> <span class="se">\</span>
   https://raw.githubusercontent.com/clustergarage/argus/master/examples/djangoex-argus-watch.yaml
 </code></pre></div></div>
 
-<h3 id="jenkins-sidecar-example">Jenkins Sidecar Example</h3>
+<p>Another basic example, for OpenShift specifically, to test the same kind of
+watchers you would be doing above in regular Kubernetes environments, simply
+watching a path for multiple events:</p>
+
+<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">paths</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">/opt/app-root</span>
+<span class="na">events</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">create</span>
+<span class="pi">-</span> <span class="s">modify</span>
+</code></pre></div></div>
+
+<h3 id="jenkins-sidecar-example-advanced">Jenkins Sidecar Example (Advanced)</h3>
 
 <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>oc apply <span class="nt">-f</span> <span class="se">\</span>
   https://raw.githubusercontent.com/clustergarage/argus/master/examples/sidecar/jenkins-sidecar.yaml
 oc apply <span class="nt">-f</span> <span class="se">\</span>
   https://raw.githubusercontent.com/clustergarage/argus/master/examples/sidecar/sidecar-argus-watch.yaml
 </code></pre></div></div>
 
+<p>This advanced example combines a Jenkins deployment with an NGiNX sidecar, so
+multiple containers are running in a single pod. This will allow us to still
+define our watchers the same way, which will attempt to monitor specified paths
+in each of the containers. If that container does not have that path, e.g.
+Jenkins’ container will not have an <code class="highlighter-rouge">/etc/nginx</code> path to watch, so it will
+ignore it.</p>
+
+<p>In addition to multiple containers running in this pod, we set up multiple
+subjects, one dealing with <code class="highlighter-rouge">modify</code> events on files/folders we would not want
+to see any changes happen to (such as password and secrets files):</p>
+
+<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">paths</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">/var/lib/jenkins/password</span>
+<span class="pi">-</span> <span class="s">/var/lib/jenkins/secret.key</span>
+<span class="pi">-</span> <span class="s">/var/lib/jenkins/secrets</span>
+<span class="pi">-</span> <span class="s">/etc/nginx</span>
+<span class="na">events</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">modify</span>
+</code></pre></div></div>
+
+<p>The other subject will recursively watch a well-known Jenkins directory for
+<code class="highlighter-rouge">open</code> events, ignoring a set of paths we wouldn’t care to monitor, and tacking
+on a custom tag on each message (<code class="highlighter-rouge">foo=bar</code>).</p>
+
+<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">paths</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">/var/lib/jenkins</span>
+<span class="na">ignore</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">.groovy</span>
+<span class="pi">-</span> <span class="s">.java</span>
+<span class="pi">-</span> <span class="s">.pki</span>
+<span class="pi">-</span> <span class="s">plugins</span>
+<span class="pi">-</span> <span class="s">war</span>
+<span class="na">events</span><span class="pi">:</span>
+<span class="pi">-</span> <span class="s">open</span>
+<span class="na">recursive</span><span class="pi">:</span> <span class="no">true</span>
+<span class="na">tags</span><span class="pi">:</span>
+  <span class="na">foo</span><span class="pi">:</span> <span class="s">bar</span>
+</code></pre></div></div>
+
+<p>Messages generated with this custom tag will look similar to this:</p>
+
+<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>oc logs &lt;argusd-pod-name&gt;
+
+OPEN file <span class="s1">'/var/lib/jenkins/&lt;subdir&gt;/&lt;file&gt;'</span> <span class="o">(</span>&lt;jenkins-pod-name&gt;:&lt;node-name&gt;<span class="o">)</span> <span class="nv">foo</span><span class="o">=</span>bar
+</code></pre></div></div>
 
                     </div>
 

diff --git a/docs/docs/getting-started/index.html b/docs/docs/getting-started/index.html
@@ -14,9 +14,9 @@
 <meta property="og:description" content="Argus works by configuring a custom Kubernetes resource that defines paths and events that you want to be notified about for your current deployments. This custom resource, in conjunction with a cluster controller running and listening for lifecycle events, is responsible for maintaining a source of truth between the state of the cluster and the daemons listening for filesystem events on each node." />
 <meta property="og:site_name" content="Argus" />
 <meta property="og:type" content="article" />
-<meta property="article:published_time" content="2018-11-30T15:21:57-05:00" />
+<meta property="article:published_time" content="2018-11-30T16:26:38-05:00" />
 <script type="application/ld+json">
-{"description":"Argus works by configuring a custom Kubernetes resource that defines paths and events that you want to be notified about for your current deployments. This custom resource, in conjunction with a cluster controller running and listening for lifecycle events, is responsible for maintaining a source of truth between the state of the cluster and the daemons listening for filesystem events on each node.","@type":"BlogPosting","url":"/argus/docs/getting-started/","headline":"Getting Started","datePublished":"2018-11-30T15:21:57-05:00","dateModified":"2018-11-30T15:21:57-05:00","mainEntityOfPage":{"@type":"WebPage","@id":"/argus/docs/getting-started/"},"@context":"http://schema.org"}</script>
+{"description":"Argus works by configuring a custom Kubernetes resource that defines paths and events that you want to be notified about for your current deployments. This custom resource, in conjunction with a cluster controller running and listening for lifecycle events, is responsible for maintaining a source of truth between the state of the cluster and the daemons listening for filesystem events on each node.","@type":"BlogPosting","url":"/argus/docs/getting-started/","headline":"Getting Started","datePublished":"2018-11-30T16:26:38-05:00","dateModified":"2018-11-30T16:26:38-05:00","mainEntityOfPage":{"@type":"WebPage","@id":"/argus/docs/getting-started/"},"@context":"http://schema.org"}</script>
 <!-- End Jekyll SEO tag -->
 
   <meta property="og:image" content=""/>

diff --git a/docs/docs/monitoring/index.html b/docs/docs/monitoring/index.html
@@ -14,9 +14,9 @@
 <meta property="og:description" content="Once you have ArgusWatchers defined, you’re ready to start monitoring for notify events; perhaps you’ll even want to set up alerts on high priority events. There are generic logfiles included in both apps, and we provide out-of-the-box metrics handling with Prometheus so you’ll be able to receive time-series data that you can immediately monitor. Ultimately, it will be up to you to use your logging framework of choice to monitor the way you’re used to doing." />
 <meta property="og:site_name" content="Argus" />
 <meta property="og:type" content="article" />
-<meta property="article:published_time" content="2018-11-30T15:21:57-05:00" />
+<meta property="article:published_time" content="2018-11-30T16:26:38-05:00" />
 <script type="application/ld+json">
-{"description":"Once you have ArgusWatchers defined, you’re ready to start monitoring for notify events; perhaps you’ll even want to set up alerts on high priority events. There are generic logfiles included in both apps, and we provide out-of-the-box metrics handling with Prometheus so you’ll be able to receive time-series data that you can immediately monitor. Ultimately, it will be up to you to use your logging framework of choice to monitor the way you’re used to doing.","@type":"BlogPosting","url":"/argus/docs/monitoring/","headline":"Monitoring Watches","datePublished":"2018-11-30T15:21:57-05:00","dateModified":"2018-11-30T15:21:57-05:00","mainEntityOfPage":{"@type":"WebPage","@id":"/argus/docs/monitoring/"},"@context":"http://schema.org"}</script>
+{"description":"Once you have ArgusWatchers defined, you’re ready to start monitoring for notify events; perhaps you’ll even want to set up alerts on high priority events. There are generic logfiles included in both apps, and we provide out-of-the-box metrics handling with Prometheus so you’ll be able to receive time-series data that you can immediately monitor. Ultimately, it will be up to you to use your logging framework of choice to monitor the way you’re used to doing.","@type":"BlogPosting","url":"/argus/docs/monitoring/","headline":"Monitoring Watches","datePublished":"2018-11-30T16:26:38-05:00","dateModified":"2018-11-30T16:26:38-05:00","mainEntityOfPage":{"@type":"WebPage","@id":"/argus/docs/monitoring/"},"@context":"http://schema.org"}</script>
 <!-- End Jekyll SEO tag -->
 
   <meta property="og:image" content=""/>