kubes 0.7.10 → 0.8.3

data/docs/_docs/install/standalone/macosx.md

@@ -0,0 +1,45 @@
+---
+title: "Install: Mac OSX"
+nav_text: MacOSX
+category: standalone
+order: 1
+---
+
+This page shows you how to install kubes on Mac OSX.
+
+Here's a "Mac OSX Homebrew Install" Video:
+
+## Homebrew
+
+You can install kubes via homebrew.
+
+Install
+
+    brew tap boltops-tools/software
+    brew install kubes
+
+Upgrade
+
+    brew update
+    brew install kubes
+
+Uninstall
+
+    brew uninstall kubes
+
+Cleanup
+
+    rm -rf /opt/kubes
+    grep -l /opt/kubes /usr/local/bin/* | xargs rm -f
+
+{% include install/wrapper.md %}
+
+## DMG
+
+You can also download the dmg and install with the Mac OSX GUI installer.
+
+Download link: [kubes DMG](https://tap.boltops.com/packages/kubes/kubes-latest.dmg)
+
+You can check [kubes-latest.dmg.metadata.json](https://tap.boltops.com/packages/kubes/kubes-latest.dmg.metadata.json) to verify the package checksum. Here's the checksum command.
+
+    shasum -a 256 kubes-latest.dmg

data/docs/_docs/install/standalone/ubuntu.md

@@ -0,0 +1,48 @@
+---
+title: "Install: Ubuntu/Debian"
+nav_text: Ubuntu
+category: standalone
+order: 3
+---
+
+This page shows you how to install kubes on Ubuntu and Debian based linux systems that use the apt package manager.
+
+## Ubuntu/Debian: apt-get install
+
+Configure repo
+
+    sudo su
+    echo "deb https://apt.boltops.com stable main" > /etc/apt/sources.list.d/boltops.list
+    curl -s https://apt.boltops.com/boltops-key.public | apt-key add -
+
+Install
+
+    apt-get update
+    apt-get install -y kubes
+
+Upgrade
+
+    apt-get install -y kubes
+
+Remove
+
+    apt-get remove -y kubes
+
+{% include install/wrapper.md %}
+
+## Deb Install
+
+You can also download the deb package and install it directly. Here are the commands:
+
+Install
+
+    wget https://apt.boltops.com/packages/kubes/kubes-latest.deb
+    dpkg -i kubes-latest.deb
+
+You can check [kubes-latest.deb.metadata.json](https://apt.boltops.com/packages/kubes/kubes-latest.deb.metadata.json) to verify the package checksum. Here's the checksum command.
+
+    sha256sum kubes-latest.deb
+
+Uninstall
+
+    dpkg -r kubes-latest.deb

data/docs/_docs/install/standalone.md

@@ -0,0 +1,43 @@
+---
+title: Standalone Package Installation
+---
+
+You can install Kubes as a standalone package.  The nice thing about this approach is that it is easy. You don't have to have Ruby installed. You don’t have to worry about compatible Ruby versions, gems, or conflicting system packages.
+
+Kubes provides the pre-built binaries. Other tools such as [vagrant](https://www.vagrantup.com/), written in ruby, and the [aws cli](https://aws.amazon.com/cli/), written in python, also work the same way.
+
+Important: If you're using rvm or rbenv and already have Ruby installed, you should [install kubes as a gem]({% link _docs/install/gem.md %}). Otherwise, different gem dependencies from the two installations can be used and cause all kinds of trouble.
+
+Below are quickstart instructions for different OSes.
+
+## Mac OSX
+
+    brew tap boltops-tools/software
+    brew install kubes
+
+More info on [Mac OSX Install]({% link _docs/install/standalone/macosx.md %})
+
+## CentOS/RedHat/Fedora
+
+    sudo su
+    curl -so /etc/yum.repos.d/boltops.repo https://yum.boltops.com/boltops.repo
+    rpm --import https://yum.boltops.com/boltops-key.public
+    yum install -y kubes
+
+More info on [CentOS Install]({% link _docs/install/standalone/centos.md %})
+
+## Ubuntu/Debian
+
+    sudo su
+    echo "deb https://apt.boltops.com stable main" > /etc/apt/sources.list.d/boltops.list
+    curl -s https://apt.boltops.com/boltops-key.public | apt-key add -
+    apt-get update
+    apt-get install -y kubes
+
+More info on [Ubuntu Install]({% link _docs/install/standalone/ubuntu.md %})
+
+{% include install/wrapper.md %}
+
+## How It Works
+
+The standalone installer packages are built within a few minutes of the kubes gem release. Here are also details on how the standalone installer works: [Standalone Details]({% link _docs/install/standalone/details.md %}).

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.

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/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/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/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>
@@ -78,10 +104,12 @@
             {% 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 %}
@@ -124,7 +153,11 @@
       </li>
       <li><a href="{% link _docs/helpers.md %}">Helpers</a>
         <ul>
-          <li><a href="{% link _docs/helpers/custom.md %}">Custom</a></li>
+          <li><a href="{% link _docs/helpers/builtin.md %}">Built-In</a>
+            <ul>
+              <li><a href="{% link _docs/helpers/builtin/config-map-files.md %}">Config Map Files</a>
+            </ul>
+          </li>
           <li><a href="{% link _docs/helpers/aws.md %}">AWS</a>
             <ul>
               {% assign docs = site.docs | where: "categories","helpers-aws" %}
@@ -163,6 +196,7 @@
               {% endfor %}
             </ul>
           </li>
+          <li><a href="{% link _docs/helpers/custom.md %}">Custom</a></li>
         </ul>
       </li>
       <li><a href="{% link _docs/patterns.md %}">Patterns</a>
@@ -210,7 +244,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,6 +24,7 @@
   <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>

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

@@ -30,8 +30,8 @@ Gem::Specification.new do |spec|
   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"