kubes 0.1.0 → 0.2.4

data/docs/Procfile

@@ -0,0 +1,2 @@
+web: bin/web
+opal: bin/rerun

data/docs/README.md

@@ -0,0 +1,24 @@
+# kubes Documentation
+
+This project powers the kubes documementation website: [https://kubes.guru](https://kubes.guru).  It is a static website generated by [Jekyll](https://jekyllrb.com/).
+
+## Contributing
+
+For minor changes like typos, you can click **Suggest an edit to this page**, located at the bottom of each article. This will take you to the source file on GitHub, where you can submit a pull request for your change through the UI.
+
+## Local Setup
+
+For larger fixes, you can run the site locally with the following:
+
+    git clone https://github.com/boltops-tools/kubes
+    cd kubes/docs
+    bundle
+    foreman start
+
+You'll be able to view the site on [http://localhost:4000](http://localhost:4000).
+
+## Html Proofer
+
+Run it locally once in a while. Sometimes external sites are intermittently down, even GitHub.
+
+    bundle exec rake html:proof

data/docs/Rakefile

@@ -0,0 +1,38 @@
+# server-side require
+require 'opal'
+require 'opal-jquery'
+require 'opal-browser'
+
+
+# Note the jekyll-opal plugin loads a minimum baseline of opal that doesnt including extra side-side requires
+# So we'll compile our own version instead.
+
+namespace :opal do
+  desc "Build our app to app.js"
+  task :build do
+    puts "build opal files"
+    Opal.append_path "./opal"
+    compiled = Opal::Builder.build("app").to_s
+    IO.write("js/app.js", compiled)
+  end
+end
+
+require 'html-proofer'
+
+namespace :html do
+  desc "proof read the html links"
+  task :proof do
+    system "bundle exec jekyll build"
+    HTMLProofer.check_directory(
+      "./_site",
+      # hacks to get html proof to pass links we wanted ignored
+      check_html: true,
+      # check_favicon: true,
+      only_4xx: true,
+      allow_hash_href: true,
+      empty_alt_ignore: true,
+    ).run
+  end
+end
+
+task :default => ["opal:build", "html:proof"]

data/docs/_config.yml

@@ -0,0 +1,71 @@
+# Site settings
+title: kubes
+email: tung@boltops.com
+url: https://kubes.guru
+description: "Kubernetes Deployment Tool: build docker image, compile Kubernetes YAML files, and apply them"
+keywords: "Kubernetes Deployment"
+skills: ""
+meta_author: Tung Nguyen
+
+# Google webmaster tools
+google_verify:
+google_analytics: "TODO: google_analytics"
+
+# https://ssl.bing.com/webmaster/configure/verify/ownership Option 2 content= goes here
+bing_verify:
+
+# Contact form:
+# - static : pass through formspree.io to validate email sending
+# - disqus : replace contact form by disqus thread
+# - comment the line below if you want to stick with the default PHP contact form
+contact: static
+
+# If you use disqus you need disqus shortname
+# https://help.disqus.com/customer/portal/articles/466208
+disqus_shortname:
+
+# Color settings (hex-codes without the leading hash-tag)
+color:
+  primary: 3972c7
+  primary-rgb: "24,288,156" #"128,179,255"
+  secondary: 2c3e50 #FD6E8A
+  secondary-dark: 233140 #A2122F
+  links: a3c8ff
+
+# Footer settings
+footer:
+  copyright: BoltOps, LLC
+  location: San Francisco, CA
+  social: BoltOps
+  credits:
+  contact: contact@boltops.com
+  phone:
+
+# Social networks usernames (many more available: google-plus, flickr, dribbble, pinterest, instagram, tumblr, linkedin, etc.)
+social:
+  - title: github
+    url: https://github.com/boltops-tools/kubes
+
+# Credits content
+credits:
+
+# Build settings
+markdown: kramdown
+permalink: pretty
+
+gh_url: https://github.com/boltops-tools/kubes
+
+collections:
+  docs:
+    name: "Documentation"
+    output: true
+  reference:
+    name: "Reference"
+    output: true
+
+defaults:
+  - values:
+      layout: default
+
+plugins_dir:
+  # - jekyll-gzip - GitHub pages does not support this plugin.

data/docs/_docs/auto-context.md

@@ -0,0 +1,47 @@
+---
+title: Auto Context
+---
+
+Kubes supports automatically switching the kubectl context based on the `KUBES_ENV`.  Since Kubernetes contexts are composed of three things: cluster, namespace, and user; this feature allows you to target any of them on a per `KUBES_ENV` basis.
+
+## Auto Context
+
+The dev and prod environments can use different kubectl contexts based on what is configured by the Kubes config.rb:
+
+```ruby
+Kubes.configure do |config|
+  config.kubectl.context = "..."
+  # config.kubectl.context_keep = true # keep the context after switching
+end
+```
+
+You can override configs on a per-env basis with `config/env` files. Examples:
+
+.kubes/config/env/dev.rb
+
+```ruby
+Kubes.configure do |config|
+  config.repo = "222222222222.dkr.ecr.us-west-2.amazonaws.com/demo"
+  config.kubectl.context = "dev-services"
+end
+```
+
+.kubes/config/env/prod.rb
+
+```ruby
+Kubes.configure do |config|
+  config.repo = "333333333333.dkr.ecr.us-west-2.amazonaws.com/demo"
+  config.kubectl.context = "prod-services"
+end
+```
+
+## Deploy
+
+With this setup, when you deploy with kubes, it will automatically switch the kubectl context based on `KUBES_ENV`.  Example:
+
+    KUBES_ENV=dev  kubes deploy # to dev-services context
+    KUBES_ENV=prod kubes deploy # to prod-services context
+
+## context_keep Option
+
+Setting `context_keep=true` option means after the context it switched, it stays switched. If `context_keep=false`, then Kubes will switch back to the previous context.

data/docs/_docs/ci/cloudbuild.md

@@ -0,0 +1,69 @@
+---
+title: CloudBuild
+---
+
+To build kubes as a Docker image entrypoint for [Google CloudBuild Custom Builder](https://cloud.google.com/cloud-build/docs/configuring-builds/use-community-and-custom-builders).
+
+    git clone http://github.com/boltops-tools/kubes
+    cd kubes
+    gcloud builds submit --tag gcr.io/$GOOGLE_PROJECT/kubes
+
+Be sure to set GOOGLE_PROJECT to your own project id.
+
+## Example Codebuild YAML
+
+cloudbuild.yaml:
+
+```yaml
+steps:
+# Simply calling kubectl version with the CLOUDSDK_* vars will auth to the GKE cluster. Unsure why.
+- name: gcr.io/cloud-builders/kubectl
+  args: ['version']
+  env:
+  - 'CLOUDSDK_COMPUTE_REGION=$_GCP_REGION'
+  - 'CLOUDSDK_CONTAINER_CLUSTER=$_GKE_CLUSTER'
+- name: 'gcr.io/$PROJECT_ID/kubes'
+  args: ["deploy"]
+  env:
+  - 'GOOGLE_PROJECT=$PROJECT_ID' # .kubes/config.rb: config.repo
+  - 'KUBES_ENV=$_KUBES_ENV'
+  - 'KUBES_EXTRA=$_KUBES_EXTRA'
+
+substitutions:
+  _GCP_REGION: us-central1
+  _GKE_CLUSTER: dev-cluster
+  _KUBES_ENV: dev
+  _KUBES_EXTRA: ''
+options:
+    substitution_option: 'ALLOW_LOOSE'
+```
+
+## Run CloudBuild
+
+Run cloudbuild with:
+
+    gcloud builds submit --config cloudbuild.yaml
+
+Example with output:
+
+    $ gcloud builds submit --config cloudbuild.yaml
+    Starting Step #1
+    Step #1: => docker build -t gcr.io/tung-275700/demo:kubes-2020-07-25T21-13-59 -f Dockerfile .
+    Step #1: Pushed gcr.io/tung-275700/demo:kubes-2020-07-25T21-13-59 docker image.
+    Step #1: Docker push took 2s.
+    Step #1: Compiled  .kubes/resources files to .kubes/output
+    Step #1: Deploying kubes resources
+    Step #1: => kubectl apply -f .kubes/output/shared/namespace.yaml
+    Step #1: namespace/demo unchanged
+    Step #1: => kubectl apply -f .kubes/output/web/service.yaml
+    Step #1: service/web unchanged
+    Step #1: => kubectl apply -f .kubes/output/web/deployment.yaml
+    Step #1: deployment.apps/web configured
+    $
+
+## Create Extra Environments
+
+If you are using the [with_extra helper]({% link _docs/extra-env.md %}), you can create additional environments of the same app like so:
+
+    gcloud builds submit --config cloudbuild.yaml --substitutions=_KUBES_EXTRA=2
+    gcloud builds submit --config cloudbuild.yaml --substitutions=_KUBES_EXTRA=3

data/docs/_docs/config.md

@@ -0,0 +1,9 @@
+---
+title: Config
+---
+
+You can customize the behavior of Kubes with configs. There are different types of configs:
+
+* [Docker]({% link _docs/config/docker.md %}): Used to customize the docker command.
+* [Env]({% link _docs/config/env.md %}): Used to override `config.rb` settings on a `KUBES_ENV` basis.
+* [Kubectl]({% link _docs/config/env.md %}): Used to customize the kubectl command.

data/docs/_docs/config/docker.md

@@ -0,0 +1,70 @@
+---
+title: Docker Config
+---
+
+## General
+
+Kubes builds docker images by calling the docker build commands.  Example:
+
+    kubes docker build
+
+To push:
+
+    kubes docker push
+
+## Deploy
+
+While building the docker image as a separate step can be useful, you can just use the deploy command, and kubes will automatically build the Docker image for you. Example:
+
+    kubes deploy web
+
+If you want to skip the `docker build` phase of the deploy, you can run:
+
+    kubes deploy web --no-build
+
+Also, kubes apply another way to skip the docker build:
+
+    kubes apply web
+
+## Customizing Args
+
+Here are some examples of customizing the docker args.
+
+.kubes/config/docker/args.rb
+
+```ruby
+command("build",
+  args: ["--quiet"],
+)
+
+command("push",
+  args: ["--disable-content-trust"],
+)
+```
+
+## Hooks
+
+Here are some examples of running custom hooks before and after the docker commands.
+
+.kubes/config/docker/hooks.rb
+
+```ruby
+before("build",
+  execute: "echo 'docker build before hook'",
+)
+
+after("push",
+  execute: "echo 'docker push before hook'",
+)
+```
+
+### exit on fail
+
+By default, if the hook commands fail, then terraspace will exit with the original hook error code.  You can change this behavior with the `exit_on_fail` option.
+
+```ruby
+before("build"
+  execute: "/command/will/fail/but/will/continue",
+  exit_on_fail: false,
+)
+```

data/docs/_docs/config/env.md

@@ -0,0 +1,58 @@
+---
+title: Env Config
+---
+
+The `config.rb` is where you can configure Kubes settings:
+
+.kubes/config.rb
+
+```ruby
+Kubes.configure do |config|
+  config.repo = "111111111111.dkr.ecr.us-west-2.amazonaws.com/demo"
+  config.logger.level = "info"
+  # auto-switching
+  # config.kubectl.context = "dev-services"
+  # config.kubectl.context_keep = false
+end
+```
+
+## Layering
+
+You can override configs on a per-env basis with `config/env` files. Examples:
+
+.kubes/config/env/dev.rb
+
+```ruby
+Kubes.configure do |config|
+  config.repo = "222222222222.dkr.ecr.us-west-2.amazonaws.com/demo"
+  config.kubectl.context = "dev-services"
+end
+```
+
+.kubes/config/env/prod.rb
+
+```ruby
+Kubes.configure do |config|
+  config.repo = "333333333333.dkr.ecr.us-west-2.amazonaws.com/demo"
+  config.kubectl.context = "prod-services"
+end
+```
+
+For more details refer to the [Layering Docs]({% link _docs/layering.md %}).
+
+## Auto-Switching Context
+
+Kubes supports automatically switching the kubectl context based on `KUBES_ENV`.  Example:
+
+    KUBES_ENV=dev  kubes deploy
+    KUBES_ENV=prod kubes deploy # can use different kubectl context
+
+So dev and prod can use different kubectl contexts based on what is configured by:
+
+```ruby
+Kubes.configure do |config|
+  config.kubectl.context = "..."
+end
+```
+
+For more details refer to the [Auto Context Docs]({% link _docs/auto-context.md %}).

data/docs/_docs/config/kubectl.md

@@ -0,0 +1,61 @@
+---
+title: Kubectl Config
+---
+
+## General
+
+Kubes calls out the `kubectl` command. You can customize the command.
+
+## Args
+
+Here are some examples of customizing the kubectl args.
+
+.kubes/config/kubectl/args.rb
+
+```ruby
+command("apply",
+  args: ["--validate=true"],
+)
+
+command("delete",
+  args: ["--grace-period=-1"],
+)
+```
+
+## Hooks
+
+Here are some examples of running custom hooks before and after the kubectl commands.
+
+.kubes/config/kubectl/hooks.rb
+
+```ruby
+before("apply",
+  execute: "kubectl apply -f .kubes/shared/namespace.yaml",
+)
+
+after("delete",
+  execute: "echo 'delete hook',
+)
+```
+
+You can use hooks to do things that may not make sense to do in the `.kubes/resources` definition. Here's an example of automatically creating the namespace.
+
+.kubes/shared/namespace.yaml
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: demo
+```
+
+### exit on fail
+
+By default, if the hook commands fail, then terraspace will exit with the original hook error code.  You can change this behavior with the `exit_on_fail` option.
+
+```ruby
+before("apply"
+  execute: "/command/will/fail/but/will/continue",
+  exit_on_fail: false,
+)
+```