kubes 0.5.1 → 0.6.0

data/docs/_docs/helpers/google/secrets.md

@@ -4,17 +4,9 @@ nav_text: Secrets
 categories: helpers-google
 ---
 
-Set up a [Kubes hook](https://kubes.guru/docs/config/hooks/kubes/).
+The `google_secret` helper fetches secret data from Google Secrets.
 
-.kubes/config/hooks/kubes.rb
-
-```ruby
-before("compile",
-  execute: KubesGoogle::Secrets.new(upcase: true, prefix: 'projects/686010496118/secrets/demo-dev-')
-)
-```
-
-Then set the secrets in the YAML:
+## Example
 
 .kubes/resources/shared/secret.yaml
 
@@ -26,18 +18,17 @@ metadata:
   labels:
     app: demo
 data:
-<% KubesGoogle::Secrets.data.each do |k,v| -%>
-  <%= k %>: <%= base64(v) %>
-<% end -%>
+  PASS: <%= google_secret("demo-#{Kubes.env}-PASS") %>
+  USER: <%= google_secret("demo-#{Kubes.env}-USER") %>
 ```
 
-This results in Google secrets with the prefix the `demo-dev-` being added to the Kubernetes secret data.  The values are automatically base64 encoded.
+The values are automatically base64 encoded.
 
 For example if you have these secret values:
 
-    $ gcloud secrets versions access latest --secret demo-dev-db_user
+    $ gcloud secrets versions access latest --secret demo-dev-USER
     test1
-    $ gcloud secrets versions access latest --secret demo-dev-db_pass
+    $ gcloud secrets versions access latest --secret demo-dev-PASS
     test2
     $
 
@@ -52,8 +43,8 @@ metadata:
 apiVersion: v1
 kind: Secret
 data:
-  db_pass: dGVzdDEK
-  db_user: dGVzdDIK
+  PASS: dGVzdDEK
+  USER: dGVzdDIK
 ```
 
 ## Variables
@@ -62,15 +53,15 @@ These environment variables can be set:
 
 Name | Description
 ---|---
-GCP_SECRET_PREFIX | Prefixed used to list and filter Google secrets. IE: `projects/686010496118/secrets/demo-dev-`.
-GOOGLE_PROJECT | Google project id.
+GOOGLE_PROJECT | Google project id. This is required.
 
-Secrets#initialize options:
+## Base64 Option
 
-Variable | Description | Default
----|---|---
-base64 | Automatically base64 encode the values. | false
-upcase | Automatically upcase the Kubernetes secret data keys. | false
-prefix | Prefixed used to list and filter Google secrets. IE: `projects/686010496118/secrets/demo-dev-`. Can also be set with the `GCP_SECRET_PREFIX` env variable. The env variable takes the highest precedence. | nil
+The value is automatically base64 encoded. You can set the `base64` option to turn on and off the automated base64 encoding.
+
+```ruby
+google_secret("demo-#{Kubes.env}-USER", base64: true)  # default is base64=true
+google_secret("demo-#{Kubes.env}-PASS", base64: false)
+```
 
-{% include helpers/base64.md %}
+{% include helpers/base64.md %}

data/docs/_docs/helpers.md

@@ -6,10 +6,10 @@ Kubes provides some helper methods to help write Kubernetes YAML files.  Here's
 
 Helper | Description
 --- | ---
-decode64 | Basey64 decode a string.
+decode64 | Base64 decode a string.
 docker_image | Method refers to the latest Docker image built by Kubes. This spares you from having to update the image manually in the deployment resource. Note, this can be overridden with the `--image` cli option or the `Kubes.config.image` setting. See: [Docker Image]({% link _docs/intro/docker-image.md %})
 dockerfile_port	| Exposed port extracted from the Dockerfile of the project.
-encode64 | Basey64 encode a string. Also available as `base64` method.
+encode64 | Base64 encode a string. Also available as `base64` method.
 extra | The `KUBES_EXTRA` value.
 with_extra | Appends the `KUBES_EXTRA` value to a string if it's set. It's covered in the [Extra Env Docs]({% link _docs/extra-env.md %}).
 
@@ -25,3 +25,17 @@ There are also provider-specific helpers:
 
 * [AWS Helpers]({% link _docs/helpers/aws.md %})
 * [Google Helpers]({% link _docs/helpers/google.md %})
+
+## Generator
+
+To help you get started quickly, you can generate starter helper code.
+
+    $ kubes new helper custom
+          create  .kubes/helpers/custom_helper.rb
+
+.kubes/helpers/custom_helper.rb
+
+```ruby
+module CustomHelper
+end
+```

data/docs/_docs/intro.md

@@ -6,15 +6,6 @@ title: What is Kubes?
 
 <div class="video-box"><div class="video-container"><iframe src="https://www.youtube.com/embed/M4zHL0mfKNU" frameborder="0" allowfullscreen=""></iframe></div></div>
 
-## Features:
+## Features
 
-* 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 %}).
-* 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 %}).
+{% include intro/features.md %}

data/docs/_docs/layering/mix.md

@@ -0,0 +1,99 @@
+---
+title: Mixed Layering
+---
+
+You can mix and match the YAML and DSL forms together and layering still works.
+
+## Project Structure
+
+Here's an example structure, so we can understand how layering works.
+
+    .kubes/resources/
+    ├── base
+    │   ├── all.yaml
+    │   └── deployment.yaml
+    └── web
+        ├── deployment
+        │   ├── dev.yaml
+        │   └── prod.yaml
+        ├── deployment.rb
+        └── service.yaml
+
+Notice, how deployment.rb is defined as a DSL. The layers will still be merged like so:
+
+    .kubes/resources/base/all.yaml
+    .kubes/resources/base/deployment.yaml
+    .kubes/resources/web/deployment.rb
+    .kubes/resources/web/deployment/dev.rb
+
+## Resources Files
+
+.kubes/resources/base/all.yaml
+
+```yaml
+metadata:
+  namespace: demo-<%= Kubes.env %>
+  labels:
+    app: demo
+```
+
+.kubes/resources/base/deployment.yaml
+
+```yaml
+metadata:
+  labels:
+    app: demo
+spec:
+  selector:
+    matchLabels:
+      app: demo
+  template:
+    metadata:
+      labels:
+        app: demo
+```
+
+.kubes/resources/web/deployment.rb
+
+```ruby
+name "web"
+labels(role: "web")
+image "nginx"
+```
+
+.kubes/resources/web/deployment/dev.yaml
+
+```yaml
+spec:
+  replicas: 2
+```
+
+## Output
+
+The result is the merge layered files.
+
+```yaml
+metadata:
+  namespace: demo-dev
+  labels:
+    app: demo
+    role: web
+  name: web
+spec:
+  selector:
+    matchLabels:
+      app: demo
+      role: web
+  template:
+    metadata:
+      labels:
+        app: demo
+        role: web
+    spec:
+      containers:
+      - image: nginx
+        name: web
+  replicas: 2
+apiVersion: apps/v1
+kind: Deployment
+```

data/docs/_docs/layering.md

@@ -6,3 +6,5 @@ Kubes supports layering files together so you can use the same Kubernetes files
 
 * [YAML Layering]({% link _docs/layering/yaml.md %})
 * [DSL Layering]({% link _docs/layering/dsl.md %})
+* [Mix Layering]({% link _docs/layering/mix.md %})
+* [Merge Behavior]({% link _docs/layering/merge.md %})

data/docs/_docs/patterns/multiple-envs.md

@@ -0,0 +1,55 @@
+---
+title: Multiple Enviroments with Layering
+nav_text: Multiple Enviroments
+categories: patterns
+---
+
+You can use Kubes to easily create multiple enviroments with the same YAML configs.  This is thanks to [Kubes Layering]({% link _docs/layering.md %}). We'll walk through an example to help understand how it works.
+
+## Creating Multiple Enviroments
+
+To create multiple enviroments like dev and prod just change KUBES_ENV. Example:
+
+    KUBES_ENV=dev  kubes deploy
+    KUBES_ENV=prod kubes deploy
+
+Different env files will be layered and merged to produce YAML files specific to each environment.
+
+## Project Structure
+
+Here's an example structure, so we can understand how layering works to create multiple enviroments.
+
+    .kubes/resources/
+    ├── base
+    │   ├── all.yaml
+    │   └── deployment.yaml
+    └── web
+        ├── deployment
+        │   ├── dev.yaml
+        │   └── prod.yaml
+        ├── deployment.yaml
+        └── service.yaml
+
+## Concrete Example
+
+Let's look at a concrete web/deployment.yaml.
+
+Here are the files that get layered when `KUBES_ENV=dev`:
+
+    .kubes/resources/base/all.yaml
+    .kubes/resources/base/deployment.yaml
+    .kubes/resources/web/deployment.yaml
+    .kubes/resources/web/deployment/dev.yaml
+
+And when `KUBES_ENV=prod`:
+
+    .kubes/resources/base/all.yaml
+    .kubes/resources/base/deployment.yaml
+    .kubes/resources/web/deployment.yaml
+    .kubes/resources/web/deployment/prod.yaml
+
+Layering allows us to have common settings that are processed before your main `.kubes/resources/web/deployment.yaml` YAML manifest. And then add **environment** specific YAML files that get merged.
+
+## Variables and Helpers
+
+Additional, you can use variables and helpers to provide environment specific values.

data/docs/_docs/variables/advanced.md

@@ -0,0 +1,62 @@
+---
+title: Advanced Variables
+nav_text: Advanced
+categories: variables
+---
+
+Basic variables layering should provides enough flexibility and is generally recommended. This page  covers more advanced variables layering.
+
+## Advanced Layering Example
+
+Here's a more complex structure to demonstrate advanced layering.
+
+    .kubes/variables
+    ├── base
+    │   └── deployment.rb
+    ├── base.rb
+    ├── dev.rb
+    ├── prod.rb
+    └── web
+        ├── deployment
+        │   ├── dev.rb
+        │   └── prod.rb
+        └── deployment.rb
+
+## Concrete Example
+
+Let's look at a concrete web/deployment.yaml.
+
+Here are the files that get layered when `KUBES_ENV=dev`:
+
+    .kubes/variables/base.rb
+    .kubes/variables/dev.rb
+    .kubes/variables/base/deployment.rb
+    .kubes/variables/web/deployment.rb
+    .kubes/variables/web/deployment/dev.rb
+
+And when `KUBES_ENV=prod`:
+
+    .kubes/variables/base.rb
+    .kubes/variables/prod.rb
+    .kubes/variables/base/deployment.rb
+    .kubes/variables/web/deployment.rb
+    .kubes/variables/web/deployment/prod.rb
+
+With advanced layering you can target a specific role and kind. So variables are only scoped to the resources you want.
+
+## 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
+base/all/ENV.rb   | base/all/dev.rb
+base/KIND.rb      | base/deployment.rb
+base/KIND/base.rb | base/deployment/base.rb
+base/KIND/ENV.rb  | base/deployment/dev.rb
+ROLE/KIND.rb      | web/deployment.rb
+ROLE/KIND/base.rb | web/deployment/base.rb
+ROLE/KIND/ENV.rb  | web/deployment/dev.rb

data/docs/_docs/variables/basic.md

@@ -0,0 +1,137 @@
+---
+title: Basic Variables
+nav_text: Basic
+categories: variables
+---
+
+## Basic Layering Example
+
+Here's an example variables directory structure:
+
+    .kubes/variables
+    ├── base.rb
+    ├── dev.rb
+    └── prod.rb
+
+base.rb
+
+```ruby
+@endpoint = "base-endpoint" # overriden by ENV specific variable files.
+```
+
+dev.rb
+
+```ruby
+@endpoint = "dev-endpoint"
+```
+
+prod.rb
+
+```ruby
+@endpoint = "prod-endpoint"
+```
+
+The `@endpoint` value will be overriden by the ENV specific variable files.
+
+## Deployment YAML
+
+Here's an example deployment.yaml
+
+.kubes/resources/web/deployment.yaml
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+  labels:
+    role: web
+spec:
+  replicas: 1  # overridden on a env basis
+  selector:
+    matchLabels:
+      role: web
+  template:
+    metadata:
+      labels:
+        role: web
+    spec:
+      containers:
+      - name: web
+        image: <%= docker_image %>
+        env:
+        - name: endpoint
+          value: <%= @endpoint %>
+```
+
+## Deploy
+
+When you deploy you can use `KUBES_ENV` to and the ENV specific variables will be used:
+
+    KUBES_ENV=dev  kubes deploy
+
+Results in:
+
+```yaml
+metadata:
+  namespace: demo-dev
+  labels:
+    app: demo
+    role: web
+  name: web
+spec:
+  selector:
+    matchLabels:
+      app: demo
+      role: web
+  template:
+    metadata:
+      labels:
+        app: demo
+        role: web
+    spec:
+      containers:
+      - name: web
+        image: gcr.io/GOOGLE_PROJECT/demo:kubes-2020-11-07T22-29-02
+        env:
+        - name: endpoint
+          value: dev-endpoint
+  replicas: 1
+apiVersion: apps/v1
+kind: Deployment
+```
+
+When using `KUBES_ENV=prod` the endpoint will use the `variables/prod.rb` values.
+
+    KUBES_ENV=prod kubes deploy
+
+Results in:
+
+```yaml
+metadata:
+  namespace: demo-prod
+  labels:
+    app: demo
+    role: web
+  name: web
+spec:
+  selector:
+    matchLabels:
+      app: demo
+      role: web
+  template:
+    metadata:
+      labels:
+        app: demo
+        role: web
+    spec:
+      containers:
+      - name: web
+        image: gcr.io/GOOGLE_PROJECT/demo:kubes-2020-11-07T22-29-02
+        env:
+        - name: endpoint
+          value: prod-endpoint
+  replicas: 1
+apiVersion: apps/v1
+kind: Deployment
+```

data/docs/_docs/variables.md

@@ -0,0 +1,23 @@
+---
+title: Variables
+---
+
+You can set variables to be made available to the templates. Generally, it is recommended to use Basic layering.
+
+{% assign docs = site.docs | where: "categories","variables" %}
+{% for doc in docs -%}
+* [{{ doc.title }}]({{ doc.url }})
+{% endfor %}
+
+## Generator
+
+To help you get started quickly, you can generate starter variable code.
+
+    $ kubes new variable
+          create  .kubes/variables/dev.rb
+
+.kubes/variables/dev.rb
+
+```ruby
+@example = "dev-value"
+```

data/docs/_docs/vs/custom.md

@@ -0,0 +1,109 @@
+---
+title: Kubes vs Custom Solutions
+nav_text: Custom Solutions
+categories: vs
+---
+
+Kubernetes provide a great platform to run and manage Docker containers. The `kubectl` command how you usually interact with a Kubernetes cluster.  It does its job well and is quite a powerful tool.
+
+{% include vs/article.md %}
+
+## Kubernetes Questions
+
+With Kubernetes, you usually use `kubectl` commands to deploy Docker images and run them on a Kubernetes cluster. As you get your Kubernetes applications production-ready, you'll have to answer many questions:
+
+* How do you create multiple environments like dev and prod with the same code and not duplicate the YAML?
+* How you handle creating service accounts and managing cloud permissions like AWS IAM, Google Service Accounts, etc?
+* How will we build the Docker image and update Docker image?
+* How do you deploy updated Kubernetes YAML settings in a controlled manner?
+
+## Kubectl with Simple Wrappers
+
+Most folks start off with `kubectl` commands to create their Kubernetes resources. It's simple. It's also important to learn how to use `kubectl` commands to establish fundamentals. Eventually, you grow tired of typing the same commands repeatedly, though. So you write a wrapper bash script. Example:
+
+kubectl-wrapper.sh
+
+    kubectl apply -f service.yaml
+    kubectl apply -f deployment.yaml
+
+Bash shines for simple scripts and light glue, but it can quickly get messy as the script takes on more things to do.
+
+## Multiple Envs Duplication
+
+One way to create different env like dev and prod is to copy their YAML files. Here's a naive example structure:
+
+    ├── dev
+    │   ├── deployment.yaml
+    │   └── service.yaml
+    └── prod
+        ├── deployment.yaml
+        └── service.yaml
+
+We then write a wrapper script that selects the folder:
+
+kubectl-wrapper.sh
+
+    KUBE_ENV=${1:-dev}
+    kubectl apply -f $KUBE_ENV/service.yaml
+    kubectl apply -f $KUBE_ENV/deployment.yaml
+
+We've duplicated `service.yaml` and `deployment.yaml`, though. Instead, it'll be nice if we use the same YAML and create a different env like dev and prod with it. Things like `envsubst` to replace variables from the same "template" YAML files can help. As requirements increases, the simple bash glue scripts end up getting messy.
+
+## PreBuilt Docker Image
+
+Additionally, the Docker image is expected to be prebuilt. Because you must first build the Docker image, folks will usually write bash script that perform these additional steps and then glue things together.
+
+## Kubernetes Resources Galore
+
+Kubernetes has a large service area, and there are so many resource Kinds that we can create that it's difficult for a simple wrapper script to handle enough control for your needs.
+
+## Kubes Makes It Easier
+
+Kubes is a Kubernetes Deployment Tool that automates the following:
+
+1. It builds the docker image
+2. Creates the Kubernetes YAML
+3. Runs kubectl apply
+
+Kubes works transparently and straightforwardly. The deploy command simply do all 3 steps: build, compile, and apply.
+
+    kubes deploy
+
+### Layering: Multiple Environments like dev and prod
+
+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 same code is used to create different environments. Kubes achieves this with a feature called Layering. The concept is similar to Kustomize overlays. Here's the general layering processing order that Kubes takes.
+
+* [Layering Docs]({% link _docs/layering.md %})
+
+## Hooks
+
+Kubes support a variety of hooks run scripts at any part of the `kubectl` commands. This allows you customize and add app-specific logic needed. Example:
+
+.kubes/config/hooks/kubectl.rb
+
+```ruby
+before("apply",
+  on: "web/deployment",
+  execute: "echo 'before apply hook test'",
+)
+
+after("delete",
+  on: "web/deployment",
+  execute: "echo 'after delete hook test'",
+)
+```
+
+There are also [cloud helpers]({% link _docs/helpers.md %}) that will handle things like Secrets and IAM Account creation.
+
+* [Kubes Kubectl Hooks Docs]({% link _docs/config/hooks/kubectl.md %})
+
+## Summary
+
+Many companies roll their own custom solutions. Chances are that the `kubectl` wrapper scripts eventually grow into messy glue. Every time you go to another company, you must relearn and figure out the home-grown solution's particularities. Even within companies, going from team to team, there may be different scripts that are their own unique beasts. It's a science project.
+
+Kubes provides a tool that streamlines the `kubectl` deployment already. Kubes also works in a transparent and straightforward manner. You know what's going on. It's also extendable and customizable. You can add business logic that you wish.  Kubes provides convenient tooling and helps you get things done quickly.