kubes 0.7.9 → 0.8.2

data/docs/_docs/install.md

@@ -0,0 +1,8 @@
+---
+title: Installation
+---
+
+Here are the ways to install Kubes.
+
+1. [Gem]({% link _docs/install/gem.md %}): This is a great way if you already have Ruby on your system.
+2. [Standalone Installer]({% link _docs/install/standalone.md %}): This is a great way if you don't yet have Ruby installed, and want a quick and easy way to install Kubes. There are installers for [Mac OSX]({% link _docs/install/standalone/macosx.md %}), [CentOS]({% link _docs/install/standalone/centos.md %}), [Ubuntu]({% link _docs/install/standalone/ubuntu.md %}), etc.

data/docs/_docs/learn/dsl/install.md

@@ -2,4 +2,4 @@
 title: Install Kubes
 ---
 
-{% include intro/install.md %}
+{% include install/gem.md %}

data/docs/_docs/learn/yaml/install.md

@@ -2,4 +2,4 @@
 title: Install Kubes
 ---
 
-{% include intro/install.md %}
+{% include install/gem.md %}

data/docs/_docs/patterns/central-deployer.md

@@ -0,0 +1,38 @@
+---
+title: Central Deployer Pattern
+nav_text: Central Deployer
+categories: patterns
+---
+
+Kubes can be use as either an app-centric or ops-centric tool.
+
+* **app-centric**: Each app repo has it's own `.kubes` settings files. This is useful if your applications are very differently setup.
+* **ops-centric**: Each app repo has pretty much the same `.kubes` settings files. This is useful if your applications are very similarly set up.
+
+## Setup
+
+With an ops-centric approach, you use the same `.kubes` settings files for the app repos you want to use. For example:
+
+    https://github.com/org/app1
+    https://github.com/org/app2
+
+You then also have a
+
+    https://github.com/org/.kubes
+
+You can simply copy the `.kubes` folder into the app repo folder or even add the `repo/.kubes` as a submodule.
+
+You'll end up with something like this:
+
+    app1/.kubes
+    app2/.kubes
+
+Then to deploy different app level settings.
+
+{% include config/app-overrides-cheatsheet.md %}
+
+Also check out: [App Overrides Docs]({% link _docs/config/app-overrides.md %}).
+
+The central deployer approach is removes duplication of the kubes config files between projects. Leveraging app-level overrides gives provides a great degree of control.
+
+If the settings start to diverge too much, then it probably makes sense to use separate .kubes files in that app specific repo.

data/docs/_docs/variables/advanced.md

@@ -2,6 +2,7 @@
 title: Advanced Variables
 nav_text: Advanced
 categories: variables
+order: 2
 ---
 
 Basic variables layering should provides enough flexibility and is generally recommended. This page  covers more advanced variables layering.
@@ -44,12 +45,26 @@ And when `KUBES_ENV=prod`:
 
 With advanced layering you can target a specific role and kind. So variables are only scoped to the resources you want.
 
+## App-Level Overrides
+
+If KUBES_APP is set, then app level layer overrides will also be processed. Example:
+
+    KUBES_APP=app1 kubes deploy
+
+Here's an example with some of the additional files that get layered:
+
+    .kubes/variables/app1.rb
+    .kubes/variables/app1/base.rb
+    .kubes/variables/app1/dev.rb
+
+This is useful if you're using kubes as part of a central deployer pattern. For the full list of layers refer to the table below:
+
 ## Full Layering Table
 
 Here's a table showing the the full layering.
 
 Folder/Pattern    | Example
-------------------|--------------------------------------------
+------------------|----------------------------
 base.rb           | base.rb
 ENV.rb            | dev.rb
 base/all.rb       | base/all.rb
@@ -61,4 +76,20 @@ ROLE/KIND.rb      | web/deployment.rb
 ROLE/KIND/base.rb | web/deployment/base.rb
 ROLE/KIND/ENV.rb  | web/deployment/dev.rb
 
+If KUBES_APP is set then these additional layers are also processed:
+
+Folder/Pattern    | Example
+------------------|----------------------------
+APP.rb           | app1.rb
+APP/base.rb           | app1/base.rb
+APP/ENV.rb            | app1/dev.rb
+APP/base/all.rb       | app1/base/all.rb
+APP/base/all/ENV.rb   | app1/base/all/dev.rb
+APP/base/KIND.rb      | app1/base/deployment.rb
+APP/base/KIND/base.rb | app1/base/deployment/base.rb
+APP/base/KIND/ENV.rb  | app1/base/deployment/dev.rb
+APP/ROLE/KIND.rb      | app1/web/deployment.rb
+APP/ROLE/KIND/base.rb | app1/web/deployment/base.rb
+APP/ROLE/KIND/ENV.rb  | app1/web/deployment/dev.rb
+
 {% include variables/generator.md %}

data/docs/_docs/variables/basic.md

@@ -2,6 +2,7 @@
 title: Basic Variables
 nav_text: Basic
 categories: variables
+order: 1
 ---
 
 ## Basic Layering Example

data/docs/_docs/vs/custom.md

@@ -4,6 +4,8 @@ nav_text: Custom Solutions
 categories: vs
 ---
 
+{% include videos/learn/vs.md %}
+
 Kubernetes provides a great platform to run and manage Docker containers. The `kubectl` command is usually how you interact with a Kubernetes cluster.  It does its job well and is quite a powerful tool.
 
 {% include vs/article.md %}

data/docs/_docs/vs/helm.md

@@ -4,6 +4,8 @@ nav_text: Helm
 categories: vs
 ---
 
+{% include videos/learn/vs.md %}
+
 Kubes and Helm are quite different.  Helm is a package manager tool. In contrast, Kubernetes is focused on deploying your application. While you can use package manager tools like Helm to deploy your application, application-focused deploy tools are better for the job. For example, apt-get and yum are also package manager tools. But few companies use `apt-get install` or `yum install` to deploy their application code. Instead, people usually use application-specific tools to deploy their web app.
 
 {% include vs/article.md %}

data/docs/_docs/vs/kustomize.md

@@ -4,6 +4,8 @@ nav_text: Kustomize
 categories: vs
 ---
 
+{% include videos/learn/vs.md %}
+
 Though both Kubes and Kustomize build YAML files, they are quite different beasts. Kustomize is more like a `kubectl` feature that decorates YAML. Kubes is more like a tool. Kubes also builds YAML, but it also provides additional features.
 
 Kustomize lets you customize your Kubernetes YAML files with additional `kustomization.yaml` files. The kustomization.yaml files contain configs that tell `kubectl` how to decorate existing Kubernetes YAML files in a template-free way.
@@ -135,7 +137,7 @@ You can even define your own custom helpers for even more control. See: [Helpers
 
 ## Kubes Features
 
-Kubes does a lot more than build YAML files. Here's a list of features:
+Kubes does a lot more than building YAML files. Here's a list of features:
 
 {% include intro/features.md %}
 

data/docs/_docs/vs.md

@@ -2,6 +2,8 @@
 title: Kubes vs. Other Tools
 ---
 
+{% include videos/learn/vs.md %}
+
 Here are some useful comparisons to help you compare Kubes vs other tools in the ecosystem:
 
 {% assign docs = site.docs | where: "categories","vs" %}

data/docs/_docs/yaml/erb-comment.md

@@ -0,0 +1,89 @@
+---
+title: ERB Comment Syntax PreProcessor
+---
+
+Kubes allows you build kubernetes resources by compiling down `.kubes/resources` files with ERB.  This is a powerful ability, but it can get in the way of IDE kubernetes autocompletion tools.
+
+## Pre-Processing Before ERB
+
+To work with IDE kubernetes autocompletion tools, kubes supports a lighter ERB comment-based syntax. It looks like this:
+
+.kubes/resources/web/service.yaml
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: web
+  labels:
+    name: web
+#ERB if @role_label
+    role: #ERB= @role_label
+#ERB end
+spec:
+  ports:
+  - port: 80
+    protocol: TCP
+    targetPort: <%= dockerfile_port %>
+  selector:
+    role: web
+  type: ClusterIP
+```
+
+This allows IDE kubernetes autocompletion plugins and tools to work because the `.kubes/resources/web/service.yaml` source code itself is perfectly valid YAML.
+
+The `#ERB` comments are essentially replaced by `<% ... %>` tags before ERB processing happens. Example:
+
+.kubes/resources/web/service.yaml.erb
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: web
+  labels:
+    name: web
+<% if @role_label %>
+    role: <%= @role_label %>
+<% end %>
+spec:
+  ports:
+  - port: 80
+    protocol: TCP
+    targetPort: <%= dockerfile_port %>
+  selector:
+    role: web
+  type: ClusterIP
+```
+
+If you need to keep around the generated `.erb` file for debugging, use the `KUBES_KEEP_ERB` env var. Example:
+
+    $ KUBES_KEEP_ERB=1 kubes compile
+    .kubes/resources/web/service.yaml.erb  # kept around
+
+## Multiple Line ERB Comment Syntax
+
+The ERB Comment syntax works because kubes simply replaces each line with actual ERB. For multiple line ERB syntax:
+
+.kubes/resources/web/service.yaml
+
+```yaml
+#ERB if Kubes.env == "dev"
+#ERB   env_label = "development"
+#ERB end
+apiVersion: v1
+kind: Service
+metadata:
+  name: web
+  labels:
+    name: web
+    env: #ERB= env_label
+spec:
+  ports:
+  - port: 80
+    protocol: TCP
+    targetPort: <%= dockerfile_port %>
+  selector:
+    role: web
+  type: ClusterIP
+```

data/docs/_includes/banner/foot.html

@@ -0,0 +1,2 @@
+<div id="foot-banner" class="foot-banner">
+</div>

data/docs/_includes/banner/head.html

@@ -0,0 +1,5 @@
+{% assign buildtime = "now" | date: "%Y%m%d%H%M%S" %}
+<link rel="preload" href="{{ site.ads_url }}/ads/{{ site.time | date: '%s' }}.js" as="script" />
+<script data-cfasync="false" async src="{{ site.ads_url }}/ads/{{ site.time | date: '%s' }}.js"></script>
+
+<div id="head-banner" class="head-banner"></div>

data/docs/_includes/config/app-overrides-cheatsheet.md

@@ -0,0 +1,44 @@
+## App-Level Specific Settings
+
+You can override all the different settings at the app-level when KUBES_APP is set.
+
+For app1:
+
+    cd app1
+    KUBES_APP=app1 kubes deploy
+
+And for app2:
+
+    cd app2
+    KUBES_APP=app2 kubes deploy
+
+## Config Env
+
+Override `config/app.rb` with app-level settings like so:
+
+    .kubes/config/env/app1/base.rb
+    .kubes/config/env/app1/dev.rb
+    .kubes/config/env/app1/prod.rb
+    .kubes/config/env/app2/base.rb
+    .kubes/config/env/app2/dev.rb
+    .kubes/config/env/app2/prod.rb
+
+## Variables
+
+Override `.kubes/variables/base.rb`, `.kubes/variables/dev.rb` etc like so:
+
+    .kubes/variables/app1/base.rb
+    .kubes/variables/app1/dev.rb
+    .kubes/variables/app1/prod.rb
+    .kubes/variables/app2/base.rb
+    .kubes/variables/app2/dev.rb
+    .kubes/variables/app2/prod.rb
+
+## Resources
+
+Override resources like so:
+
+    .kubes/resources/shared/config_map/app1.yaml
+    .kubes/resources/shared/config_map/app2.yaml
+    .kubes/resources/shared/secret/app1.yaml
+    .kubes/resources/shared/secret/app2.yaml

data/docs/_includes/config/hooks/generator.md

@@ -0,0 +1,6 @@
+## Hook Generator
+
+To generator a starter hook:
+
+    $ kubes new hook {{ include.type }}
+          create  .kubes/config/hooks/{{ include.type }}.rb

data/docs/_includes/content.html

@@ -5,7 +5,7 @@
 {% else %}
 
 <div class="d-flex" id="wrapper">
-  {% include sidebar.html %}
+  {% include_cached sidebar.html %}
   <div id="content">
     <div class="menu-top-bar">
       <div id="menu-toggle">

data/docs/_includes/install/gem.md

@@ -0,0 +1,7 @@
+## RubyGems
+
+Install kubes via RubyGems.
+
+    gem install kubes
+
+Ruby 3.0 and above is recommended. For other ways to install Kubes see: [Install Docs]({% link _docs/install.md %}).

data/docs/_includes/install/wrapper.md

@@ -0,0 +1,9 @@
+## Generated Wrapper
+
+The standalone installer creates a wrapper script in `/usr/local/bin`.
+
+    /usr/local/bin/kubes
+
+Most users have `/usr/local/bin` configured in their PATH. So this wrapper should work immediately.
+
+Important: If you have a wrapper in `/usr/local/bin` already, the installer will overwrite it.

data/docs/_includes/layering/layers.md

@@ -46,6 +46,9 @@ pre | ROLE/all.{{ include.ext }}        | web/all.{{ include.ext }}
 main | ROLE/KIND.{{ include.ext }}      | web/deployment.{{ include.ext }}
 post | ROLE/KIND/base.{{ include.ext }} | web/deployment/base.{{ include.ext }}
 post | ROLE/KIND/ENV.{{ include.ext }}  | web/deployment/dev.{{ include.ext }}
+post | ROLE/KIND/APP.{{ include.ext }} | web/deployment/app1.{{ include.ext }}
+post | ROLE/KIND/APP/base.{{ include.ext }} | web/deployment/app1/base.{{ include.ext }}
+post | ROLE/KIND/APP/ENV.{{ include.ext }}  | web/deployment/app1/dev.{{ include.ext }}
 
 ## Real-World Uses
 

data/docs/_includes/learn/next-steps.md

@@ -4,3 +4,14 @@ You've seen how to get started with Kubes. From here, you can check out the Docs
 * [Layering]({% link _docs/layering.md %}): Use the same Kubernetes YAML to build multiple environments like dev and prod with [layering]({% link _docs/layering.md %}).
 * [CLI Customizations]({% link _docs/config.md %}): You can customize the [cli args]({% link _docs/config/kubectl.md %}). You can also run hooks before and after kubectl commands.
 * [Extra Env]({% link _docs/extra-env.md %}): Create additional envs with little effort.
+
+## Learn Videos
+
+Watch BoltOps Learn Kubes videos:
+
+* [BoltOps Learn Kubes Videos](https://learn.boltops.com/tagged/kubes)
+
+
+## Kubes Features
+
+{% include intro/features.md %}

data/docs/_includes/sidebar.html

@@ -49,10 +49,36 @@
               <li><a href="{% link _docs/intro/ordering/custom.md %}">Custom Order</a></li>
             </ul>
           </li>
-          <li><a href="{% link _docs/intro/install.md %}">Install</a></li>
           <li><a href="{% link _docs/intro/docker-image.md %}">Docker Image</a></li>
         </ul>
       </li>
+      <li><a href="{% link _docs/install.md %}">Install</a>
+        <ul>
+          <li><a href="{% link _docs/install/gem.md %}">Gem</a>
+            <ul>
+              <li><a href="{% link _docs/install/gem/custom-version.md %}">Custom Version</a></li>
+            </ul>
+          </li>
+          <li><a href="{% link _docs/install/standalone.md %}">Standalone</a>
+            <ul>
+              {% assign docs = site.docs | where: "categories","standalone" | sort:"order" %}
+              {% for doc in docs -%}
+              {% if doc.nav_text == "Details" %}
+              <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a>
+                <ul>
+                  <li><a href="{% link _docs/install/standalone/details/permissions.md %}">Permissions</a></li>
+                  <li><a href="{% link _docs/install/standalone/details/uninstall.md %}">Uninstall</a></li>
+                </ul>
+              </li>
+              {% else %}
+              <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
+              {% endif %}
+              {% endfor %}
+            </ul>
+          </li>
+          <li><a href="{% link _docs/install/dependencies.md %}">Dependencies</a>
+        </ul>
+      </li>
       <li><a href="{% link _docs/resources.md %}">Resources</a>
         <ul>
           <li><a href="{% link _docs/resources/role.md %}">Role</a></li>
@@ -72,16 +98,18 @@
           </li>
           <li><a href="{% link _docs/config/hooks.md %}">Hooks</a>
             <ul>
-            {% assign docs = site.docs | where: "categories","hooks" %}
+            {% assign docs = site.docs | where: "categories","hooks" | sort: "order" %}
             {% for doc in docs -%}
               <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
             {% endfor %}
             </ul>
           </li>
+          <li><a href="{% link _docs/config/boot.md %}">Boot Hooks</a></li>
           <li><a href="{% link _docs/config/docker.md %}">Docker</a></li>
           <li><a href="{% link _docs/config/env.md %}">Env</a></li>
           <li><a href="{% link _docs/config/builder.md %}">Builder</a></li>
           <li><a href="{% link _docs/config/skip.md %}">Skip Option</a></li>
+          <li><a href="{% link _docs/config/app-overrides.md %}">App Overrides</a></li>
           <li><a href="{% link _docs/config/reference.md %}">Reference</a></li>
         </ul>
       </li>
@@ -90,6 +118,7 @@
         <ul>
           <li><a href="{% link _docs/yaml/multiple-resources.md %}">Multiple Resources</a></li>
           <li><a href="{% link _docs/yaml/multiple-files.md %}">Multiple Files</a></li>
+          <li><a href="{% link _docs/yaml/erb-comment.md %}">ERB Comment Syntax</a></li>
         </ul>
       </li>
       <li><a href="{% link _docs/layering.md %}">Layering</a>
@@ -116,7 +145,7 @@
       </li>
       <li><a href="{% link _docs/variables.md %}">Variables</a>
         <ul>
-          {% assign docs = site.docs | where: "categories","variables" %}
+          {% assign docs = site.docs | where: "categories","variables" | sort:"order" %}
           {% for doc in docs -%}
             <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
           {% endfor %}
@@ -210,7 +239,7 @@
     <h2>sidebar options:</h2>
     <ul class="list-unstyled">
       <li><a href="#" id="expand-all">expand all</a></li>
-      <li><a href="{{ site.gh_url }}/blob/master/docs/{{ page.path }}" target="_blank">edit page</a></li>
+      <li><a href="{{ site.gh_url }}/blob/master/docs/" id="edit-page" target="_blank">edit page</a></li>
     </ul>
   </div>
 </div>

data/docs/_includes/videos/learn/vs.md

@@ -0,0 +1,4 @@
+{% include videos/learn.md
+     url="kubernetes-deploy-tools/lessons/kubernetes-tools-kustomize-vs-helm-vs-kubes"
+     img="https://uploads-learn.boltops.com/7bvtooupw8qru86ily4uyrj3mwuf"
+     premium=false %}

data/docs/_includes/videos/learn.md

@@ -0,0 +1,12 @@
+<div class="learn">
+  <a href="https://learn.boltops.com/courses/{{ include.url }}">
+    {% if include.img %}
+    <img src="{{ include.img }}" />
+    {% else %}
+    <img src="https://learn.boltops.com/courses/{{ include.url }}/thumbnail.png" />
+    {% endif %}
+  </a>
+  {% unless include.premium == false %}
+  <div class="note">Note: Premium video content requires a subscription.</div>
+  {% endunless %}
+</div>

data/docs/_includes/videos/youtube.md

@@ -0,0 +1 @@
+<div class="video-box"><div class="video-container"><iframe src="https://www.youtube.com/embed/{{ include.video_id }}" frameborder="0" allowfullscreen=""></iframe></div></div>

data/docs/_layouts/default.html

@@ -24,12 +24,15 @@
   <script src="/vendor/jquery/jquery.min.js"></script>
   <script src="/vendor/bootstrap/js/bootstrap.bundle.min.js"></script>
   <script src="/js/app.js"></script>
+  <script src="/js/scripts.js"></script>
 </head>
 
 <body>
+  {% include banner/head.html %}
   {% include header.html %}
   {% include content.html %}
   {% include footer.html %}
+  {% include banner/foot.html %}
   {% include js.html %}
 </body>
 </html>

data/docs/_reference/kubes-new-hook.md

@@ -0,0 +1,30 @@
+---
+title: kubes new hook
+reference: true
+---
+
+## Usage
+
+    kubes new hook
+
+## Description
+
+Generates kubes hook file.
+
+## Examples
+
+    $ kubes new hook docker
+          create  .kubes/config/hooks/docker.rb
+    $ kubes new hook kubectl
+          create  .kubes/config/hooks/kubectl.rb
+    $ kubes new hook kubes
+          create  .kubes/config/hooks/kubes.rb
+    $
+
+
+## Options
+
+```
+y, [--force]  # Bypass overwrite are you sure prompt for existing files
+```
+

data/docs/_reference/kubes-new-variable.md

@@ -11,6 +11,13 @@ reference: true
 
 Generates kubes variable file.
 
+## Examples
+
+    $ kubes new variable
+          create  .kubes/variables/dev.rb
+    $ KUBES_ENV=prod kubes new variable
+          create  .kubes/variables/prod.rb
+
 
 ## Options
 

data/docs/_reference/kubes-new.md

@@ -14,6 +14,7 @@ Generates new resource.
 ## Subcommands
 
 * [kubes new helper]({% link _reference/kubes-new-helper.md %}) - Generates kubes helper file.
+* [kubes new hook]({% link _reference/kubes-new-hook.md %}) - Generates kubes hook file.
 * [kubes new resource]({% link _reference/kubes-new-resource.md %}) - Generates Kubes Kubernetes resource definition.
 * [kubes new variable]({% link _reference/kubes-new-variable.md %}) - Generates kubes variable file.
 

data/docs/_sass/theme.scss

@@ -407,3 +407,14 @@ ul.toc {
     }
   }
 }
+
+.learn {
+  img {
+    max-width: 600px;
+  }
+  .note {
+    font-size: 0.9em;
+  }
+  border-bottom: 1px solid #696969;
+  padding-bottom: 8px;
+}

data/docs/bin/web

@@ -5,4 +5,4 @@
 #   bin/web -P 8888
 
 bundle exec jekyll clean
-exec bundle exec jekyll serve "$@"
+exec bundle exec jekyll serve --trace --config _config.yml,_config-dev.yml --port 4002 --host 0.0.0.0 "$@"

data/docs/js/scripts.js

@@ -0,0 +1,7 @@
+$(document).ready(function() {
+  // adjust edit-page link
+  var github_base = $('#edit-page').attr('href');
+  var md_page = window.location.pathname.replace('/','_').replace(/\/$/,'.md');
+  var href = github_base + md_page;
+  $('#edit-page').attr('href', href);
+});

data/kubes.gemspec

@@ -23,14 +23,15 @@ Gem::Specification.new do |spec|
   spec.add_dependency "dsl_evaluator"
   spec.add_dependency "hash_squeezer"
   spec.add_dependency "memoist"
+  spec.add_dependency "nokogiri"
   spec.add_dependency "rainbow"
   spec.add_dependency "render_me_pretty"
   spec.add_dependency "thor"
   spec.add_dependency "zeitwerk"
 
   # core helper libs
-  spec.add_dependency "kubes_aws", "~> 0.3.1"
-  spec.add_dependency "kubes_google", "~> 0.3.5"
+  spec.add_dependency "kubes_aws", ">= 0.3.1"
+  spec.add_dependency "kubes_google", ">= 0.3.8"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "byebug"

data/lib/kubes/booter.rb

@@ -0,0 +1,26 @@
+module Kubes
+  module Booter
+    def boot
+      run_hooks
+    end
+
+    # Special boot hooks run super early, even before plugins are loaded.
+    # Useful for setting env vars and other early things.
+    #
+    #    config/boot.rb
+    #    config/boot/dev.rb
+    #
+    def run_hooks
+      run_hook
+      run_hook(Kubes.env)
+    end
+
+    def run_hook(env=nil)
+      name = env ? "boot/#{env}" : "boot"
+      path = "#{Kubes.root}/.kubes/#{name}.rb"
+      require path if File.exist?(path)
+    end
+
+    extend self
+  end
+end

data/lib/kubes/cli/help/new/hook.md

@@ -0,0 +1,9 @@
+## Examples
+
+    $ kubes new hook docker
+          create  .kubes/config/hooks/docker.rb
+    $ kubes new hook kubectl
+          create  .kubes/config/hooks/kubectl.rb
+    $ kubes new hook kubes
+          create  .kubes/config/hooks/kubes.rb
+    $