kubes 0.4.7 → 0.6.2

data/docs/_docs/helpers/google/service-account.md

@@ -41,6 +41,8 @@ metadata:
 
 The role permissions are currently always added to the existing permissions. So removing roles that were previously added does not remove them.
 
+## Variables
+
 ServiceAccount#initialize options:
 
 Variable | Description | Default
@@ -50,3 +52,9 @@ gsa | The Google Service Account name. The conventional name is APP-ENV. IE: dem
 ksa | The Kubernetes Service Account name. The conventional name is APP. IE: demo | APP
 namespace | The Kubernetes namespace. Defaults to the APP-ENV. IE: demo-dev. | APP-ENV
 roles | Google IAM roles to add. This adds permissions to the Google service account. | []
+
+Relevant environment variables:
+
+Name | Description
+---|---
+GOOGLE_PROJECT | Google project id. This is required as it's used to build the full service account name.

data/docs/_docs/intro.md

@@ -6,13 +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 %}).
-* CLI Customizations: You can customize the [cli args]({% link _docs/config/args/kubectl.md %}). You can also run [hooks]({% link _docs/config/hooks/kubectl.md %}) before and after kubectl 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/intro/docker-image.md

@@ -0,0 +1,66 @@
+---
+title: Docker Image
+---
+
+With Kubes, you can use the `docker_image` helper method to select which image to use. It can use images from these sources:
+
+1. CLI Option: The `--image` option specified with the CLI command
+2. Kubes Config: Specified by `config.image` in the `.kubes/config.rb`
+3. Built Docker Image: The image built from Dockerfile
+
+The CLI option has the highest precedence, and the Built Docker image has the lowest precedence.
+
+## 1. CLI Option
+
+Kubes uses the image from the `--image` option if specified. It's a quick way to override the Docker  image used by Kubes.  Example:
+
+    kubes deploy --image repo/image:tag
+
+When the `--image` option is set, Kubes skips the Docker build phase.
+
+## 2. Kubes Config
+
+If you set the `config.image` in the Kubes config, Kubes will use this prebuilt Docker image instead. Example:
+
+.kubes/config.rb:
+
+```ruby
+Kubes.configure do |config|
+  config.image = "nginx"
+end
+```
+
+When `config.image` is set, Kubes skips the Docker build phase.
+
+## 3. Built Docker Image
+
+Kubes can use a Docker image built from your Dockerfile. This is the default behavior of Kubes, as long as the CLI Option and the Kubes Config option is not set.
+
+## Template Example
+
+Here's an example usage of the `docker_image` helper.
+
+.kubes/resources/web/deployment.yaml
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+  labels:
+    role: web
+spec:
+  selector:
+    matchLabels:
+      role: web
+  template:
+    metadata:
+      labels:
+        role: web
+    spec:
+      containers:
+      - name: web
+        image: <%= docker_image %>
+```
+
+When running `kubes deploy`, Kubes will replace `<%= docker_image %>` with the Docker image from one of the sources described above.

data/docs/_docs/intro/how-kubes-works.md

@@ -10,20 +10,16 @@ In fact, you can use Kubes to build the files first, and then run `kubectl` dire
     kubes docker push
     kubes compile  # compiles the .kubes/resources files to .kubes/output
 
-Now, use `kubectl` directly. This will apply all the files:
+Now, use `kubectl` directly and apply them in the proper order:
 
-    kubectl apply --recursive -f .kubes/output
-
-You can also selectively apply specific files:
-
-    kubectl apply -f .kubes/output/web/deployment.yaml
+    kubectl apply -f .kubes/output/shared/namespace.yaml
     kubectl apply -f .kubes/output/web/service.yaml
+    kubectl apply -f .kubes/output/web/deployment.yaml
 
-You can also apply with kubes. This will compile the files automatically also.
-
-    kubes apply
-
-The deploy command, does all 3 steps: builds the docker image, compiles the `.kubes/resources` files, and runs kubectl apply.
+The deploy command simpifily does all 3 steps: build, compile, and apply.
 
     kubes deploy
 
+You can also run the `kubectl apply` only. The `kube apply` command compiles but will skip the docker build stage if it's already been built.
+
+    kubes apply

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/layering/merge.md

@@ -67,7 +67,7 @@ The merging of simple String is a straightforward replacement.
 .kubes/resources/web/deployment.rb
 
 ```ruby
-image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+image docker_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
 # ...
 ```
 

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 merged 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/learn/dsl/delete.md

@@ -6,11 +6,19 @@ Let's now delete the app and clean up:
 
     kubes delete
 
-You will be prompted to confirm before deletion. Here's out the output looks like:
+You will be prompted to confirm before deletion.
 
     $ kubes delete
+    Compiled  .kubes/resources files to .kubes/output
+    Will run:
+        kubectl delete -f .kubes/output/web/deployment.yaml
+        kubectl delete -f .kubes/output/web/service.yaml
+        kubectl delete -f .kubes/output/shared/namespace.yaml
+    This will delete resources. Are you sure? (y/N)
+
+Confirm to delete the resources:
+
     This will delete resources. Are you sure? (y/N) y
-    Compiled  .kubes/resources files
     => kubectl delete -f .kubes/output/web/service.yaml
     service "demo-web" deleted
     => kubectl delete -f .kubes/output/web/deployment.yaml

data/docs/_docs/learn/dsl/review-project.md

@@ -29,10 +29,10 @@ labels(role: "web")
 namespace "default"
 
 replicas 1
-image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+image docker_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
 ```
 
-The DSL form is more concise than the YAML form.  Also, notice the use of the `built_image` helper. The `built_image` is a kubes helper method that refers to the latest Docker image built. This spares you from updating the image manually.
+The DSL form is more concise than the YAML form.  Also, notice the use of the `docker_image` helper. The `docker_image` is a kubes helper method that refers to the latest Docker image built. This spares you from updating the image manually.
 
 ## Base Folder
 

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

@@ -6,11 +6,19 @@ Let's now delete the app and clean up:
 
     kubes delete
 
-You will be prompted to confirm before deletion. Here's out the output looks like:
+You will be prompted to confirm before deletion.
 
     $ kubes delete
+    Compiled  .kubes/resources files to .kubes/output
+    Will run:
+        kubectl delete -f .kubes/output/web/deployment.yaml
+        kubectl delete -f .kubes/output/web/service.yaml
+        kubectl delete -f .kubes/output/shared/namespace.yaml
+    This will delete resources. Are you sure? (y/N)
+
+Confirm to delete the resources:
+
     This will delete resources. Are you sure? (y/N) y
-    Compiled  .kubes/resources files
     => kubectl delete -f .kubes/output/web/service.yaml
     service "demo-web" deleted
     => kubectl delete -f .kubes/output/web/deployment.yaml

data/docs/_docs/learn/yaml/review-project.md

@@ -46,10 +46,10 @@ spec:
     spec:
       containers:
       - name: web
-        image: <%= built_image %>
+        image: <%= docker_image %>
 ```
 
-Notice the `<%= built_image %>`.  Kubes processes the YAML files with ERB templating and replaces these tags.  The `built_image` is a kubes helper method that refers to the latest Docker image built by Kubes. This spares you updating the image manually.
+Notice the `<%= docker_image %>`.  Kubes processes the YAML files with ERB templating and replaces these tags.  The `docker_image` is a kubes helper method that refers to the latest Docker image built by Kubes. This spares you updating the image manually.
 
 ## Base Folder
 

data/docs/_docs/patterns/clock-web-worker.md

@@ -31,7 +31,7 @@ namespace "default"
 labels(role: "web")
 
 replicas 1
-image built_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
+image docker_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
 command "bin/clock"
 ```
 
@@ -43,7 +43,7 @@ namespace "default"
 labels(role: "web")
 
 replicas 1
-image built_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
+image docker_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
 ```
 
 .kubes/resources/demo-worker/deployment.rb
@@ -54,7 +54,7 @@ namespace "default"
 labels(role: "web")
 
 replicas 2
-image built_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
+image docker_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
 command "bin/worker"
 ```
 

data/docs/_docs/patterns/migrations.md

@@ -25,7 +25,7 @@ spec:
     spec:
       containers:
       - name: migrate
-        image: <%= built_image %>
+        image: <%= docker_image %>
         command: ["bin/job/migrate.sh"]
       restartPolicy: Never
   backoffLimit: 4

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