kubes 0.5.1 → 0.6.4

data/docs/_docs/vs.md

@@ -0,0 +1,10 @@
+---
+title: Kubes vs. Other Tools
+---
+
+Here are some useful comparisons to help you compare Kubes vs other tools in the ecosystem:
+
+{% assign docs = site.docs | where: "categories","vs" %}
+{% for doc in docs -%}
+* [{{ doc.nav_text }}]({{ doc.url }})
+{% endfor %}

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.

data/docs/_docs/vs/helm.md

@@ -0,0 +1,243 @@
+---
+title: Kubes vs Helm
+nav_text: Helm
+categories: vs
+---
+
+Though both Kubes and Helm can be used to deploy applications to Kubernetes, they work quite differently.  Kubernetes is more focused on deploying your application. Helm is more like a package manager.
+
+{% include vs/article.md %}
+
+## Project Structures
+
+### Helm Project Structure
+
+Here's an example of Helm project structure:
+
+    ├── Chart.yaml
+    ├── templates
+    │   ├── _helpers.tpl
+    │   ├── deployment.yaml
+    │   └── service.yaml
+    └── values.yaml
+
+The Kubernetes YAML files reside in the templates folder.  The `values.yaml` contains the default configuration values for the YAML files.
+
+{% include vs/kubes/structure.md %}
+
+## Multiple Environments: Variables vs Layering
+
+Both Helm and Kubes allow you to use the same code to create multiple environments. They take different approaches, though.
+
+### Helm Variables
+
+Helm supports creating multiple environments like dev and prod by using different variables files.  Here are example commands:
+
+    helm install chart-dev . --namespace chart-dev --create-namespace -f values/dev.yaml
+    helm install chart-prod . --namespace chart-prod --create-namespace -f values/prod.yaml
+
+To create different environments in different namespaces with helm, you use the namespace CLI options. Helm creates the namespace outside of YAML, so it's lifecycle is not managed. The `--create-namespace` option is only necessary once.  To use different variable values, you use the `-f` option. You can specify as many variables files as you wish.
+
+The commands can become verbose, as you have to remember to type the CLI options.
+
+{% include vs/kubes/layering.md %}
+
+## Templating Support
+
+Both Helm and Kubes support templating logic.
+
+### Helm Templating
+
+The templating language is a mixture of the [Go template language](https://godoc.org/text/template) and the [Sprig template library](https://masterminds.github.io/sprig/). Here's an example of Helm templating.
+
+templates/deployment.yaml
+
+```yaml
+{% raw %}apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "mychart.fullname" . }}
+  labels:
+    {{- include "mychart.labels" . | nindent 4 }}
+spec:
+{{- if not .Values.autoscaling.enabled }}
+  replicas: {{ .Values.replicaCount }}
+{{- end }}
+  selector:
+    matchLabels:
+      {{- include "mychart.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+    {{- with .Values.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+    {{- end }}
+      labels:
+        {{- include "mychart.selectorLabels" . | nindent 8 }}
+    spec:
+      containers:
+        - name: {{ .Chart.Name }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: 80
+              protocol: TCP{% endraw %}
+```
+
+### Kubes Templating
+
+Kubes uses ERB Ruby for templating.  Here's an example.
+
+.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 %>
+```
+
+The `docker_image` method is a built-in helper. It returns the Docker image built from your Dockerfile or a configured pre-built image. See: [Docker Image Docs]({% link _docs/intro/docker-image.md %}).
+
+One of the reasons why the Kubes YAML template is more straightforward is because Kubes also supports layering. So logic can be moved to different layered YAML files that get merged.
+
+## Define Custom Helpers
+
+Both Helm and Kubes support custom user-defined helpers. We'll take a look at examples from each tool.
+
+### Helm Helpers
+
+With Helm, you can define custom helpers in `templates/_helpers.tpl`. Example:
+
+templates/_helpers.tpl
+
+```go{% raw %}
+{{- define "demo.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "demo.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}{% endraw %}
+```
+
+The helper methods need to be defined in the go-lang templating language, hence the need for curly brackets.
+
+### Kubes Helpers
+
+With Kubes, to define template helper methods, it's just Ruby code. Example:
+
+.kubes/helpers/my_helpers.rb
+
+```ruby
+module MyHelpers
+  def database_endpoint
+    case Kubes.env
+    when "dev"
+      "dev-db.cbuqdmc3nqvb.us-west-2.rds.amazonaws.com"
+    when "prod"
+      "prod-db.cbuqdmc3nqvb.us-west-2.rds.amazonaws.com"
+    end
+  end
+end
+```
+
+The custom helper definitions are a lot more natural.
+
+## Custom Hooks
+
+Both Helm and Kubes support hooks. This allows you to hook into the deploy lifecycle and add your own custom business logic.
+
+Helm supports a wide variety of hooks for the install, delete, upgrade, and rollback.  The hooks run at the helm-level.
+
+Kubes also supports hook as the kubes-level; this is similar to the helm-level. Kubes also provide finer-grain control hooks at the kubectl-level.
+
+Overally, Helm and Kubes hooks work quite differently. We'll take a look at **some** examples:
+
+### Helm Hook Example
+
+Helm hooks are Kubernetes Job resources with a special `helm.sh/hook` annotation. Example:
+
+templates/job.yaml
+
+```yaml
+{% raw %}apiVersion: batch/v1
+kind: Job
+metadata:
+  name: "{{ .Release.Name }}"
+  annotations:
+    "helm.sh/hook": post-install # This is what defines this resource as a hook.
+spec:
+  template:
+    metadata:
+      name: "{{ .Release.Name }}"
+    spec:
+      restartPolicy: Never
+      containers:
+      - name: post-install-job
+        image: "alpine:3.3"
+        command: ["/bin/sleep","{{ default "10" .Values.sleepyTime }}"]{% endraw %}
+```
+
+So Helm hooks are just Kubernetes jobs and run on the cluster.
+
+### Kubes Hook Example
+
+Kube hooks are scripts that run on the same machine that kubes is running on. Here's an example:
+
+.kubes/config/hooks/kubectl.rb
+
+```ruby
+before("apply",
+  on: "web/deployment",
+  execute: "echo 'before apply hook test'",
+)
+```
+
+The hook will simply run the `echo` command on the same machine as what kubes is running on.  The scope is much more fine-grain.  We can target any role and resource kind. For example:
+
+    # hook can run here
+    kubectl apply -f .kubes/output/shared/namespace.yaml
+    # hook can run here
+    kubectl apply -f .kubes/output/web/service.yaml
+    # hook can run here
+    kubectl apply -f .kubes/output/web/deployment.yaml
+    # hook can run here
+
+### Hook Differences
+
+We showed examples of hooks with both Helm and Kubes. We already covered one of the differences:
+
+* Code: Helm hooks are written as Kubernetes resources. Kubes hooks are written as Ruby code that can shell out to scripts or call an inline [Ruby code]({% link _docs/config/hooks/ruby.md %}).
+* Context: Helm runs as a Kubernetes job. Kubes hooks run on the same machine as kubes itself.
+* Fine-Grain Control: With Kubes we can target the hook at each kubectl resource. Kubes also supports the coarser-grain hooks at the kubes-level. These are like helm hooks.
+
+For more info on hooks, check out the [Kubes Hooks Docs](https://kubes.guru/docs/config/hooks/).
+
+## Additional Features
+
+Helm and Kubes are quite different tools. Helm is more like a package manager. Kubes is more focused on deploying your specific application and adds additional convenient tooling.
+
+Helm can package up your applications and then helps distribute them via a helm server. It's a full-fledge package management system.
+
+Kubes supports the deployment workflow. It can build the docker image from your Dockerfile use it to deploy to Kubernetes. Kubes also has additional convenience CLI commands like [exec]({% link _reference/kubes-exec.md %}) and [logs]({% link _reference/kubes-logs.md %}) to work with Kubernetes containers.
+
+## Summary
+
+Helm and Kubes are quite different. Helm is a full-fledge package management. Kubes is a more focused on deployment. Both tools support templating logic to help keep your code DRY. Additionally, Kubes supports layering to merge YAML files together for DRYness. Kubes also helps you build your Docker images.

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.