kubes 0.1.0 → 0.2.0

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/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,
+)
+```

data/docs/_docs/contributing.md

@@ -0,0 +1,98 @@
+---
+title: Contributing
+---
+
+Hi there! Are you interested in contributing to Kubes? We'd love your help. Kubes is an open-source project, built one contribution at a time by users like you.
+
+## Where to get help or report a problem
+
+See [the support guidelines]({% link support.md %})
+
+## Ways to contribute
+
+Whether you're a developer, an infrastructure engineer, or just an enthusiast, there are lots of ways to contribute. Here are a few ideas:
+
+* [Install Kubes on your computer](https://https://kubes.guru.com/docs/install/) and kick the tires. Does it work? Does it do what you'd expect? If not, [open an issue](https://github.com/boltops-tools/kubes/issues/new/choose) and let us know.
+* Comment on some of the project's [open issues](https://github.com/boltops-tools/kubes/issues). Have you experienced the same problem? Know a workaround? Do you have a suggestion for how the feature could be better?
+* Read through [the documentation](https://https://kubes.guru.com/docs/), and click the "improve this page" button, any time you see something confusing or have a suggestion for something that could be improved.
+* Find [an open issue](https://github.com/boltops-tools/kubes/issues) (especially [those labeled `help wanted`](https://github.com/boltops-tools/kubes/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)), and submit a proposed fix. If it's your first pull request, we promise we won't bite and are glad to answer any questions.
+* Help evaluate [open pull requests](https://github.com/boltops-tools/kubes/pulls), by testing the changes locally and reviewing what's proposed.
+
+## Submitting a pull request
+
+### Pull requests generally
+
+* The smaller the proposed change, the better. If you'd like to propose two unrelated changes, submit two pull requests.
+
+* The more information, the better. Make judicious use of the pull request body. Describe what changes were made, why you made them, and what impact they will have for users.
+
+* If this is your first pull request, it may help to [understand GitHub Flow](https://guides.github.com/introduction/flow/).
+
+* If you're submitting a code contribution, be sure to read the [code contributions](#code-contributions) section below.
+
+### Submitting a pull request via github.com
+
+Many small changes can be made entirely through the github.com web interface.
+
+1. Navigate to the file within [boltops-tools/kubes](https://github.com/boltops-tools/kubes) that you'd like to edit.
+2. Click the pencil icon in the top right corner to edit the file.
+3. Make your proposed changes.
+4. Click "Propose file change."
+5. Click "Create pull request."
+6. Add a descriptive title and detailed description for your proposed change. The more information, the better.
+7. Click "Create pull request."
+
+That's it! You'll be automatically subscribed to receive updates as others review your proposed change and provide feedback.
+
+### Submitting a pull request via Git command line
+
+1. Fork the project by clicking "Fork" in the top right corner of [boltops-tools/kubes](https://github.com/boltops-tools/kubes).
+2. Clone the repository locally `git clone https://github.com/<your-username>/kubes`.
+3. Fetch submodules `git submodule init && git submodule update`.
+4. Create a new, descriptively named branch to contain your change ( `git checkout -b my-awesome-feature` ).
+5. Hack away, add tests. Not necessarily in that order.
+6. Make sure everything still passes by running `bundle exec rspec` (see [the tests section](#running-tests-locally) below)
+7. Push the branch up ( `git push origin my-awesome-feature` ).
+8. Create a pull request by visiting `https://github.com/<your-username>/kubes` and following the instructions at the top of the screen.
+
+## Proposing updates to the documentation
+
+We want the Kubes documentation to be the best it can be. We've open-sourced our docs and we welcome any pull requests if you find it lacking.
+
+### How to submit changes
+
+You can find the documentation for [https://kubes.guru](http://https://kubes.guru) in the [docs](https://github.com/boltops-tools/kubes/tree/master/docs) directory. See the section above, [submitting a pull request](#submitting-a-pull-request) for information on how to propose a change.
+
+One gotcha, all pull requests should be directed at the `master` branch (the default branch).
+
+## Code Contributions
+
+Interesting in submitting a pull request? Awesome. Read on. There are a few common gotchas that we'd love to help you avoid.
+
+### Tests and documentation
+
+Any time you propose a code change, you should also include updates to the documentation and tests within the same pull request.
+
+#### Documentation
+
+If your contribution changes any Kubes behavior, make sure to update the documentation. Documentation lives in the `docs` folder.  It's a Jekyll site and can be started with `cd docs && bin/web`. If the docs are missing information, please feel free to add it in. Great docs make a great project. Include changes to the documentation within your pull request, and once merged, `https://kubes.guru.com` will be updated.
+
+#### Tests
+
+* If you're creating a small fix or patch to an existing feature, a simple test is more than enough. You can usually copy/paste from an existing example in the `specs` folder.
+
+### Code contributions generally
+
+* Don't bump the Gem version in your pull request (if you don't know what that means, you probably didn't).
+
+## Running tests
+
+### Test Dependencies
+
+To run the test suite by running the following command:
+
+    bundle exec rspec
+
+## Thank You
+
+Thanks! Hacking on Kubes should be fun. If you find any of this hard to figure out, let us know so we can improve our process or documentation!