kubes 0.4.7 → 0.6.2

data/docs/_docs/vs/kustomize.md

@@ -0,0 +1,167 @@
+---
+title: Kubes vs Kustomize
+nav_text: Kustomize
+categories: vs
+---
+
+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.
+
+Kubes lets you create Kubernetes files more directly. It handles layering and merging YAML files via a conventional structure. It also supports additional conveniences like building Docker images, CLI Customizations, Hooks, etc.
+
+{% include vs/article.md %}
+
+## Project Structures
+
+### Kustomize Project Structure
+
+Kustomize doesn't define a strict a project folder structure. You define any project structure you wish and use `kustomization.yaml` files to connect things together. Here's a possible Kustomize example project structure:
+
+    ├── base
+    │   ├── deployment.yaml
+    │   ├── kustomization.yaml
+    │   └── service.yaml
+    └── overlays
+        ├── dev
+        │   ├── deployment.yaml
+        │   ├── kustomization.yaml
+        │   └── namespace.yaml
+        └── prod
+            ├── deployment.yaml
+            ├── kustomization.yaml
+            └── namespace.yaml
+
+The provided structure allows you to use the same code to create different environments with overlays. The `overlays/dev/kustomization.yaml` file stitches the structure together.
+
+overlays/dev/kustomization.yaml:
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+bases:
+  - ../../base
+patchesStrategicMerge:
+  - deployment.yaml
+namespace: demo-dev
+resources:
+- ./namespace.yaml
+```
+
+{% include vs/kubes/structure.md %}
+
+## Multiple Environments: Overlays vs Layering
+
+Both Kustomize and Kubes allow you to use the same code to create multiple environments. They take different approaches, though.
+
+### Kustomize Overlays
+
+Kustomize achieves multiple environments via `kustomization.yaml` and manually specifying and wiring how the files should merge. To create different dev and prod environments, we use overlays:
+
+    kubectl apply -k overlays/dev
+    kubectl apply -k overlays/prod
+
+{% include vs/kubes/layering.md %}
+
+## DRY Differences
+
+## DRY with Kustomize
+
+Both Kubes and Kustomize try to achieve DRY YAML code. It tries to avoid YAML duplication.
+
+Kustomize takes a purist viewpoint. You use `kustomization.yaml` to decorate original YAML.  The original files are untouched and left as-is.  Here are example overlays files.
+
+overlays/dev/kustomization.yaml:
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+bases:
+  - ../../base
+patchesStrategicMerge:
+  - deployment.yaml
+namespace: demo-dev
+resources:
+- ./namespace.yaml
+```
+
+overlays/prod/kustomization.yaml:
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+bases:
+  - ../../base
+patchesStrategicMerge:
+  - deployment.yaml
+namespace: demo-prod
+resources:
+- ./namespace.yaml
+```
+
+While duplication is reduced since the original `base/deployment.yaml` is left untouched, there is duplication in the `kustomization.yaml` files.
+
+## DRY with Kubes
+
+With Kubes, DRY has handled by layering and templating support. Let's first take a look at how layering removes duplication.
+
+Let's focus on `deployment.yaml` to explain and understand layering. Here are the files that get layered.
+
+    .kubes/resources/base/all.yaml            # common YAML for all files
+    .kubes/resources/base/deployment.yaml     # common YAML for deployment kind
+    .kubes/resources/web/deployment.yaml
+    .kubes/resources/web/deployment/dev.yaml  # env-specific that overrides YAML
+
+Each file is merged together and produces a resulting YAML file:
+
+    .kubes/output/web/deployment.yaml
+
+Additionally, you can use ERB templating to keep things DRY.  Here's an example:
+
+.kubes/resources/shared/namespace.yaml
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: demo-<%= Kubes.env %>
+  labels:
+    app: demo
+```
+
+Notice the `<%= Kubes.env %>` templating logic. When is `KUBES_ENV=dev`, then `name: demo-dev`. When is `KUBES_ENV=prod`, then `name: demo-prod`.
+
+You can even define your own custom helpers for even more control. See: [Helpers Docs](https://kubes.guru/docs/helpers/custom/)
+
+## Kubes Features
+
+Kubes does a lot more than build YAML files. Here's a list of features:
+
+{% include intro/features.md %}
+
+## Kubes Kustomize Support
+
+All of that being said, Kubes also supports Kustomize.  So if you’re a Kustomize user, you can use it with Kubes. Here's an example Kustomize structure with Kubes.
+
+    .kubes/resources
+    ├── base
+    │   ├── deployment.yaml
+    │   ├── kustomization.yaml
+    │   └── service.yaml
+    └── overlays
+        ├── dev
+        │   └── kustomization.yaml
+        └── prod
+            └── kustomization.yaml
+
+In Kustomize mode, Kubes will call `kubectl apply -k`.  Here's an example:
+
+    kubes deploy overlays/dev
+
+This calls:
+
+    kubectl apply -k .kubes/output/overlays/dev
+
+## Summary
+
+Kustomize and Kubes are quite different. Kustomize is more of a feature to kubectl and takes on a purist view on changing YAML files for deployment. Kubes has similar merging concepts as Kustomize in the form of layering. Kustomize is more about control things with additional `kustomization.yaml` configurations. Whereas, Kubes takes more of a convention-over-configuration approach, so it just works without having to do extra prewiring work.  Kubes additionally helps you build your Docker images.

data/docs/_docs/yaml.md

@@ -12,7 +12,7 @@ You can write your Kubernetes resources in YAML format.
 
 ## YAML and Templating
 
-Kubes provides a little extra power for the YAML format. The YAML files are processed through an ERB templating language.  So you have dynamic control. Here's an example with `Kubes.env` and the `built_image` helper.
+Kubes provides a little extra power for the YAML format. The YAML files are processed through an ERB templating language.  So you have dynamic control. Here's an example with `Kubes.env` and the `docker_image` helper.
 
 .kubes/resources/web/deployment.yaml
 
@@ -37,5 +37,5 @@ spec:
     spec:
       containers:
       - name: demo-web
-        image: <%= built_image %>
+        image: <%= docker_image %>
 ```

data/docs/_includes/commands.html

@@ -108,7 +108,7 @@ spec:
     spec:
       containers:
       - name: demo-web
-        image: <%= built_image %>
+        image: <%= docker_image %>
 {% endhighlight %}
               </div>
             </div>
@@ -121,7 +121,7 @@ namespace "default"
 labels(role: "web")
 
 replicas 2
-image built_image # IE: user/demo-web:kubes-2020-06-13T19-55-16-43afc6e
+image docker_image # IE: user/demo-web:kubes-2020-06-13T19-55-16-43afc6e
 {% endhighlight %}
               </div>
             </div>

data/docs/_includes/intro/features.md

@@ -0,0 +1,11 @@
+* Automation: [Builds the Docker image]({% link _docs/config/docker.md %}) and updates the compiled YAML files
+* Syntactic Sugar: Use an [ERB/YAML]({% link _docs/yaml.md %}) or a [DSL]({% link _docs/dsl.md %}) to write your Kubernetes YAML files. You can use a mix of DSL and YAML definitions in the `.kubes/resources` folder.
+* Layering: Use the same Kubernetes YAML to build multiple environments like dev and prod with [layering]({% link _docs/layering.md %}).
+* Secrets: Use helpers like [aws_secret]({% link _docs/helpers/aws/secrets.md %}), [aws_ssm]({% link _docs/helpers/aws/ssm.md %}), and [google_secret]({% link _docs/helpers/google/secrets.md %}) to build Kubernetes secrets.yaml from secret providers designed for it.
+* Generators: Kubes ships with a few generators to help you get building with Kubernetes quickly. See: [Generator Docs]({% link _docs/generators.md %}).
+* CLI Customizations: You can customize the [cli args]({% link _docs/config/args/kubectl.md %}).
+* Hooks: You can also run [hooks]({% link _docs/config/hooks.md %}) before and after [kubes]({% link _docs/config/hooks/kubes.md %}) and [kubectl]({% link _docs/config/hooks/kubectl.md %}) commands.
+* Automated Suffix Hashes: Automatically appends a suffix hash to ConfigMap and Secret resources. More details in [ConfigMap]({% link _docs/dsl/resources/config_map.md %}) and [Secret]({% link _docs/dsl/resources/secret.md %}) docs.
+* Kustomize Support: If you're a kustomization user, you can use it with Kubes. More details in [Kustomize Support Docs]({% link _docs/misc/kustomize.md %}).
+* Auto Context Switching: Map dev to a specific kubectl context and prod to another kubectl context and Kubes can switch them automatically so you won't have to remember. More details in [Auto Context Docs]({% link _docs/misc/auto-context.md %}).
+* Ordering: Kubes run kubectl apply to create resources in the [correct order]({% link _docs/intro/ordering.md %}). For deleting, it kubes will run `kubectl delete` in the correct reverse order. The order is also [customizable]({% link _docs/intro/ordering/custom.md %}).

data/docs/_includes/layering/layers.md

@@ -1,6 +1,6 @@
 Kubes Layering in it's full form allows you to keep your resource definitions DRY and create different environments with the same code.
 
-## Structure
+## Project Structure
 
 Here's an example structure, so we can understand how layering works.
 
@@ -25,9 +25,7 @@ To explain the layering, here's the general processing order that Kubes takes.
 2. Then Kubes will process your `.kubes/resources/ROLE` definitions.
 3. Lastly, Kubes processes any post-layers in the `.kubes/resources/ROLE/KIND` folders.
 
-Note, both YAML and DSL forms support layering.
-
-Layering only combines resources definitions with the same form. For example, the DSL form `base/all.rb` will not be combined with YAML form `web/deployment.yaml`.
+Note, both YAML and DSL forms support layering. They can be mixed together.
 
 ## Full Layering
 

data/docs/_includes/sidebar.html

@@ -28,6 +28,14 @@
           <li><a href="{% link _docs/learn/dsl/next-steps.md %}">Next Steps</a></li>
         </ul>
       </li>
+      <li><a href="{% link _docs/vs.md %}">Kubes vs Others</a>
+        <ul>
+        {% assign docs = site.docs | where: "categories","vs" %}
+        {% for doc in docs -%}
+          <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
+        {% endfor %}
+        </ul>
+      </li>
     </ul>
     <h2><a href="{% link docs.md %}">Docs</a></h2>
     <ul id="docs">
@@ -42,6 +50,7 @@
             </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/resources.md %}">Resources</a>
@@ -76,11 +85,13 @@
           <li><a href="{% link _docs/config/reference.md %}">Reference</a></li>
         </ul>
       </li>
+      <li><a href="{% link _docs/generators.md %}">Generators</a></li>
       <li><a href="{% link _docs/yaml.md %}">YAML</a></li>
       <li><a href="{% link _docs/layering.md %}">Layering</a>
         <ul>
           <li><a href="{% link _docs/layering/yaml.md %}">YAML</a></li>
           <li><a href="{% link _docs/layering/dsl.md %}">DSL</a></li>
+          <li><a href="{% link _docs/layering/mix.md %}">Mix</a></li>
           <li><a href="{% link _docs/layering/merge.md %}">Merge Behavior</a></li>
         </ul>
       </li>
@@ -97,6 +108,14 @@
           <li><a href="{% link _docs/dsl/multiple-resources.md %}">Multiple Resources</a>
         </ul>
       </li>
+      <li><a href="{% link _docs/variables.md %}">Variables</a>
+        <ul>
+          {% assign docs = site.docs | where: "categories","variables" %}
+          {% for doc in docs -%}
+            <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
+          {% endfor %}
+        </ul>
+      </li>
       <li><a href="{% link _docs/helpers.md %}">Helpers</a>
         <ul>
           <li><a href="{% link _docs/helpers/custom.md %}">Custom</a></li>
@@ -104,7 +123,18 @@
             <ul>
               {% assign docs = site.docs | where: "categories","helpers-aws" %}
               {% for doc in docs -%}
+                {% if doc.nav_text == "Advanced" %}
+                <li><a href='{{ doc.url }}'>{{ doc.nav_text }}</a>
+                  <ul>
+                    {% assign docs = site.docs | where: "categories","advanced-helpers-aws" %}
+                    {% for doc in docs -%}
+                    <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
+                    {% endfor %}
+                  </ul>
+                </li>
+                {% else %}
                 <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
+                {% endif %}
               {% endfor %}
             </ul>
           </li>
@@ -112,7 +142,18 @@
             <ul>
               {% assign docs = site.docs | where: "categories","helpers-google" %}
               {% for doc in docs -%}
+                {% if doc.nav_text == "Advanced" %}
+                <li><a href='{{ doc.url }}'>{{ doc.nav_text }}</a>
+                  <ul>
+                    {% assign docs = site.docs | where: "categories","advanced-helpers-google" %}
+                    {% for doc in docs -%}
+                    <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
+                    {% endfor %}
+                  </ul>
+                </li>
+                {% else %}
                 <li><a href="{{ doc.url }}">{{ doc.nav_text }}</a></li>
+                {% endif %}
               {% endfor %}
             </ul>
           </li>

data/docs/_includes/vs/article.md

@@ -0,0 +1 @@
+This article also covers more differences in detail: [Kustomize vs Helm vs Kubes: Kubernetes Deploy Tools](https://blog.boltops.com/2020/11/05/kustomize-vs-helm-vs-kubes-kubernetes-deploy-tools)

data/docs/_includes/vs/kubes/layering.md

@@ -0,0 +1,10 @@
+### Kubes Layering
+
+To deploy and create multiple environments like dev and prod with the same YAML, we use a different KUBES_ENV setting:
+
+    KUBES_ENV=dev  kubes deploy
+    KUBES_ENV=prod kubes deploy
+
+The layering is achieved thanks to the conventional project structure. You don't have to do any extra work, you just create pre-process base layer files or post-process environment specific layer files.
+
+* [Kubes Layering Docs]({% link _docs/layering.md %})

data/docs/_includes/vs/kubes/structure.md

@@ -0,0 +1,24 @@
+### Kubes Project Structure
+
+On the other hand, Kubes defines a conventional project structure. Here's a project directory example:
+
+    .kubes
+    └── resources
+        ├── base
+        │   ├── all.yaml
+        │   └── deployment.yaml
+        ├── shared
+        │   └── namespace.yaml
+        └── web
+            ├── deployment
+            │   ├── dev.yaml
+            │   └── prod.yaml
+            ├── deployment.yaml
+            └── service.yaml
+
+A Kubes project structure also supports introduces a role concept or folder. The folder structure only shows a web role for simplicity. You can always add more roles.  For example:
+
+    .kubes/resources/ROLE/deployment.yaml
+    .kubes/resources/clock/deployment.yaml
+    .kubes/resources/web/deployment.yaml
+    .kubes/resources/worker/deployment.yaml

data/docs/_reference/kubes-delete.md

@@ -9,7 +9,7 @@ reference: true
 
 ## Description
 
-Delete Kubernetes resources within the app folder
+Delete Kubernetes resources in defined .kubes/resources
 
 
 ## Options

data/docs/_reference/kubes-exec.md

@@ -36,13 +36,29 @@ If you have have multiple containers in your pod. You can specify the specfic co
 
     kubes exec --name web
 
+## Default Exec Command
+
+The default exec command is `sh`.  Example:
+
+    $ kubes exec
+    => kubectl exec -n demo-dev -ti web-568645f665-62j8f -- sh
+    /app #
+
+You can override the default with `KUBES_DEFAULT_EXEC`.  Example:
+
+    $ export KUBES_DEFAULT_EXEC=bash
+    $ kubes exec
+    => kubectl exec -n demo-dev -ti web-568645f665-62j8f -- bash
+    /app #
+
 
 ## Options
 
 ```
     [--compile], [--no-compile]  # whether or not to compile the .kube/resources
                                  # Default: true
-n, [--name=NAME]                 # deployment name to use. IE: demo-web
+p, [--pod=POD]                   # pod to use. IE: web
+d, [--deployment=DEPLOYMENT]     # deployment name to use. IE: demo-web
 c, [--container=CONTAINER]       # Container name. If omitted, the first container in the pod will be chosen
     [--verbose], [--no-verbose]  
     [--noop], [--no-noop]        

data/docs/_reference/kubes-init.md

@@ -16,11 +16,11 @@ Init project
 
 ```
 a, --app=APP                     # Docker repo name. Example: web. Generates .kubes/APP/resources folder
-    [--force]                    # Bypass overwrite are you sure prompt for existing files
+y, [--force]                     # Bypass overwrite are you sure prompt for existing files
 t, [--type=TYPE]                 # Type: dsl or yaml
                                  # Default: yaml
     --repo=REPO                  # Docker repo name. Example: user/repo. Configures .kubes/config.rb
-n, [--namespace=NAMESPACE]       # Namespace to use, defaults to the app option
+n, [--namespace=NAMESPACE]       # Namespace to use, defaults to APP-ENV. IE: demo-dev
     [--verbose], [--no-verbose]  
     [--noop], [--no-noop]        
 ```

data/docs/_reference/kubes-logs.md

@@ -17,7 +17,8 @@ logs from all deployment pods
 ```
     [--compile], [--no-compile]  # whether or not to compile the .kube/resources
                                  # Default: true
-n, [--name=NAME]                 # deployment name to use. IE: demo-web
+p, [--pod=POD]                   # pod to use. IE: web
+d, [--deployment=DEPLOYMENT]     # deployment name to use. IE: demo-web
 c, [--container=CONTAINER]       # Container name. If omitted, the first container in the pod will be chosen
 f, [--follow], [--no-follow]     # Follow logs
                                  # Default: true

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

@@ -0,0 +1,15 @@
+---
+title: kubes new help
+reference: true
+---
+
+## Usage
+
+    kubes new help [COMMAND]
+
+## Description
+
+Describe subcommands or one specific subcommand
+
+
+

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

@@ -0,0 +1,25 @@
+---
+title: kubes new helper
+reference: true
+---
+
+## Usage
+
+    kubes new helper
+
+## Description
+
+Generates kubes helper file.
+
+## Examples
+
+    $ kubes new helper custom
+          create  .kubes/helpers/custom_helper.rb
+
+
+## Options
+
+```
+y, [--force]  # Bypass overwrite are you sure prompt for existing files
+```
+