kubes 0.4.6 → 0.6.1

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 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/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/patterns/secrets.md

@@ -78,5 +78,3 @@ 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
 
 Note, Kubernetes secrets are only base64 encoded. So users who have access to read Kubernetes secrets will be able to decode and get the value trivially. Depending on your security posture requirements, this may or may not suffice.
-
-The Google helpers are provided by the [boltops-tools/kubes_google](https://github.com/boltops-tools/kubes_google) library. For more details, check out its README.

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