kubes 0.5.1 → 0.6.4

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,27 @@ 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
+By default, the values are automatically base64 encoded. You can change the default behavior with a config option.
+
+.kubes/config.rb
+
+```ruby
+KubesGoogle.configure do |config|
+  config.base64_secrets = true
+end
+```
+
+Note: The use of `KubesGoogle.configure` instead of `Kubes.configure` here.
+
+You can also set the `base64` option to turn on and off the automated base64 encoding on a per secret basis.
+
+```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/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.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/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/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/plugins.md

@@ -0,0 +1,12 @@
+---
+title: Kubes Plugins
+---
+
+Kubes makes it easier to work with Kubernetes by automating the deployment workflow. Many of the conveniences it adds is done with plugins. For example, `aws_secret`, `aws_ssm`, `google_secret` are implemented with Cloud Provider specific Kubes plugins.
+
+## Baseline Plugins
+
+The baseline plugins that currently ship with Kubes are:
+
+* [kubes_aws]({% link _docs/plugins/aws.md %})
+* [kubes_google]({% link _docs/plugins/google.md %})

data/docs/_docs/plugins/aws.md

@@ -0,0 +1,17 @@
+---
+title: AWS Kubes Plugin
+---
+
+The AWS Kubes Plugin adds support helpers like `aws_secret`. You can configure it's behavior. Example:
+
+.kubes/config.rb
+
+```ruby
+KubesAws.configure do |config|
+  config.base64_secrets = false
+end
+```
+
+Name | Description | Default
+---|---|---
+base64_secrets | Whether or not to automatically base64 encoded values returned by the `aws_secret` helper. | true

data/docs/_docs/plugins/google.md

@@ -0,0 +1,18 @@
+---
+title: Google Kubes Plugin
+---
+
+The Google Kubes Plugin adds support helpers like `google_secret`. You can configure it's behavior. Example:
+
+.kubes/config.rb
+
+```ruby
+KubesGoogle.configure do |config|
+  config.base64_secrets = true
+end
+```
+
+Name | Description | Default
+---|---|---
+base64_secrets | Whether or not to automatically base64 encoded values returned by the `google_secret` helper. | true
+{% include plugins/gke-config.md %}

data/docs/_docs/variables.md

@@ -0,0 +1,12 @@
+---
+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 %}
+
+{% include variables/generator.md %}

data/docs/_docs/variables/advanced.md

@@ -0,0 +1,64 @@
+---
+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
+
+{% include variables/generator.md %}

data/docs/_docs/variables/basic.md

@@ -0,0 +1,139 @@
+---
+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
+```
+
+{% include variables/generator.md %}