kubes 0.4.3 → 0.5.0

data/docs/_docs/helpers/aws/ssm.md

@@ -0,0 +1,76 @@
+---
+title: AWS SSM Parameters
+nav_text: SSM
+categories: helpers-aws
+---
+
+For example if you have these secret values:
+
+    $ aws ssm get-parameter --name /demo/development/db_user --with-decryption | jq '.Parameter.Value'
+    user
+    $ aws ssm get-parameter --name /demo/development/db_pass --with-decryption | jq '.Parameter.Value'
+    pass
+
+Set up a [Kubes hook](https://kubes.guru/docs/config/hooks/kubes/).
+
+.kubes/config/hooks/kubes.rb
+
+```ruby
+ssm = KubesAws::SSM.new(upcase: true, prefix: "/demo/development/")
+before("compile",
+  label: "Get secrets from AWS SSM Manager",
+  execute: ssm,
+)
+```
+
+Then set the secrets in the YAML:
+
+.kubes/resources/shared/secret.yaml
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: demo
+  labels:
+    app: demo
+data:
+<% KubesAws::SSM.data.each do |k,v| -%>
+  <%= k %>: <%= base64(v) %>
+<% end -%>
+```
+
+This results in AWS secrets with the prefix the `demo/dev/` being added to the Kubernetes secret data.  The values are automatically base64 encoded. Produces:
+
+.kubes/output/shared/secret.yaml
+
+```yaml
+metadata:
+  namespace: demo
+  name: demo-2a78a13682
+  labels:
+    app: demo
+apiVersion: v1
+kind: Secret
+data:
+  db_pass: dGVzdDEK
+  db_user: dGVzdDIK
+```
+
+## Variables
+
+These environment variables can be set:
+
+Name | Description
+---|---
+AWS_SSM_PREFIX | Prefixed used to list and filter AWS SSM Parameters. IE: `demo/dev/`.
+
+Secrets#initialize options:
+
+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 AWS secrets. IE: `demo/dev/`. Can also be set with the `AWS_SECRET_PREFIX` env variable. The env variable takes the highest precedence. | nil
+
+{% include helpers/base64.md %}

data/docs/_docs/helpers/custom.md

@@ -0,0 +1,40 @@
+---
+title: Custom Helpers
+---
+
+Kubes ships with several built-in helpers. On top of this, you can define your own custom helpers.  This allows you to define new methods and customize Kubes further.
+
+## Example
+
+You define custom helpers in the `.kubes/helpers` folder.
+
+.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 `database_endpoint` will be available to use in the `.kubes/resources` YAML files. IE:
+
+.kubes/helpers/resources/shared/config_map.yaml
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: demo
+  labels:
+    app: demo
+data:
+  DATABASE_ENDPOINT: <%= database_endpoint %>
+```
+

data/docs/_docs/helpers/google.md

@@ -0,0 +1,17 @@
+---
+title: Google Helpers
+---
+
+List of Google helpers:
+
+{% assign docs = site.docs | where: "categories","helpers-aws" %}
+{% for doc in docs -%}
+  * [{{ doc.nav_text }}]({{ doc.url }})
+{% endfor %}
+
+## Notes
+
+* By default, `KubeGoogle.logger = Kubes.logger`. This means, you can set `logger.level = "debug"` in `.kubes/config.rb` to see more details.
+* The `gcloud` cli is used to create IAM roles. So `gcloud` is required.
+* Note: Would like to use the google sdk, but it wasn't obvious how to do so. PRs are welcomed.
+* The Google helpers are provided by the [boltops-tools/kubes_google](https://github.com/boltops-tools/kubes_google) library.

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

@@ -0,0 +1,76 @@
+---
+title: Google Secrets
+nav_text: Secrets
+categories: helpers-google
+---
+
+Set up a [Kubes hook](https://kubes.guru/docs/config/hooks/kubes/).
+
+.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:
+
+.kubes/resources/shared/secret.yaml
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: demo
+  labels:
+    app: demo
+data:
+<% KubesGoogle::Secrets.data.each do |k,v| -%>
+  <%= k %>: <%= base64(v) %>
+<% end -%>
+```
+
+This results in Google secrets with the prefix the `demo-dev-` being added to the Kubernetes secret data.  The values are automatically base64 encoded.
+
+For example if you have these secret values:
+
+    $ gcloud secrets versions access latest --secret demo-dev-db_user
+    test1
+    $ gcloud secrets versions access latest --secret demo-dev-db_pass
+    test2
+    $
+
+.kubes/output/shared/secret.yaml
+
+```yaml
+metadata:
+  namespace: demo
+  name: demo-2a78a13682
+  labels:
+    app: demo
+apiVersion: v1
+kind: Secret
+data:
+  db_pass: dGVzdDEK
+  db_user: dGVzdDIK
+```
+
+## Variables
+
+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.
+
+Secrets#initialize options:
+
+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
+
+{% include helpers/base64.md %}

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

@@ -0,0 +1,60 @@
+---
+title: Google Service Account
+nav_text: Service Account
+categories: helpers-google
+---
+
+## Service Accounts
+
+You can automatically create the Google Service Account associated with the [GKE Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity).
+
+Here's a Kubes hook that creates a service account:
+
+.kubes/config/hooks/kubes.rb
+
+```ruby
+service_account = KubesGoogle::ServiceAccount.new(
+  app: "demo",
+  namespace: "demo-#{Kubes.env}", # defaults to APP-ENV when not set. IE: demo-dev
+  roles: ["cloudsql.client", "secretmanager.viewer"], # defaults to empty when not set
+)
+before("apply",
+  label: "create service account",
+  execute: service_account,
+)
+```
+
+The corresponding Kubernetes Service account looks like this:
+
+.kubes/resources/shared/service_account.yaml
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  annotations:
+    iam.gke.io/gcp-service-account: demo-<%= Kubes.env %>@<%= ENV['GOOGLE_PROJECT'] %>.iam.gserviceaccount.com
+  name: demo
+  labels:
+    app: demo
+```
+
+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
+---|---|---
+app | The app name. It's used to set other variables conventionally. This is required. | nil
+gsa | The Google Service Account name. The conventional name is APP-ENV. IE: demo-dev. | APP-ENV
+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

@@ -11,7 +11,9 @@ title: What is Kubes?
 * 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.
+* 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 %}).

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/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/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"
 ```