kubes 0.1.0 → 0.2.4

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!

data/docs/_docs/dsl.md

@@ -0,0 +1,66 @@
+---
+title: Kubes DSL
+---
+
+Kubes supports a DSL that builds Kubernetes YAML files. The DSL substantially reduces the amount of code you have to write. Each part of the structure can be customized and overridden.
+
+## DSL Methods
+
+In general, the available DSL methods correspond to resource fields available. To find available methods:
+
+1. Look the at the source for each of the [resources](https://github.com/boltops-tools/kubes/tree/master/lib/kubes/compiler/dsl/syntax).
+2. Refer to each resource's docs, linked at the bottom of this page.
+3. And use the `kubectl explain` command.
+
+Sometimes the methods may not exactly match to avoid field names collisions.  Though this is the exception, not the rule.
+
+## Example
+
+Here's a simple example:
+
+.kubes/resources/web/service.rb
+
+```ruby
+name "demo-web"
+labels(role: "web")
+namespace "demo"
+
+port 80
+targetPort 80
+```
+
+Results in:
+
+.kubes/output/web/service.yaml
+
+```yaml
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: demo-web
+  labels:
+    app: demo
+  namespace: demo
+spec:
+  ports:
+  - port: 80
+    protocol: TCP
+    targetPort: 8080
+  selector:
+    app: demo
+  type: NodePort
+```
+
+Notice how `port` and `targetPort` correspond to `spec.ports.port` and `spec.ports.targetPort` in the YAML.
+
+## Reader and Writer Methods
+
+In general:
+
+* The DSL methods behave as reader methods when no arguments are passed to it. IE: `name "demo-web"` sets the value.
+* The DSL methods behave as writer methods when arguments are passed to it. IE: `name` returns the value.
+
+## Merge Behavior
+
+Generally, the merge should behave as expected. For example, map or Hash fields are merged together from multiple layers. Strings are simply replaced. See more details at [Layering Merge Behavior]({% link _docs/layering/merge.md %})

data/docs/_docs/dsl/multiple-resources.md

@@ -0,0 +1,114 @@
+---
+title: Multiple Resources
+---
+
+Kubes encourages a structure with files that matches the resource kind. Example:
+
+    .kubes
+    └── resources
+        └── web
+            ├── deployment.rb
+            └── service.rb
+
+This structure is nicely organized and covers 80% of use cases. An astute user may point out that this struture assumes one resource of each kind.
+
+Next, we'll cover different ways to create multiple resource of the same kinds.
+
+## Multiple Resources: Multiple Files
+
+You can create multiple resources of same kind by appending a dash followed by anything. Example:
+
+    .kubes
+    └── resources
+        └── web
+            ├── deployment-1.rb
+            ├── deployment-2.rb
+            ├── service-1.rb
+            └── service-2.rb
+
+Only words before the dash are used to infer the resource kind.
+
+Filename | Resource Kind
+--- | ---
+deployment-1.rb | Deployment
+deployment-2.rb | Deployment
+service-1.rb | Service
+service-2.rb | Service
+
+Using multiple files is the general recommended approach.
+
+## Multiple Resources: Block Form
+
+You can also use a block form to create multiple resources.  You name the resource files with plural names. An example helps explain:
+
+    .kubes
+    └── resources
+        └── deployments.rb
+
+.kubes/resources/web/deployments.rb
+
+```ruby
+deployment "demo-web" do
+  labels(role: "web")
+  replicas 1
+  image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+end
+
+deployment "demo-web-2" do
+  labels(role: "web")
+  replicas 1
+  image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+end
+```
+
+You can also mix and matched resources. When you use the block form, the file name is not used to infer the resource type. The resource kind is explicitly declare by the block method name.
+
+
+.kubes/resources/web/resources.rb
+
+```ruby
+deployment "demo-web" do
+  labels(role: "web")
+  replicas 1
+  image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+end
+
+service "demo-web" do
+  labels(role: "web")
+end
+```
+
+You can declare deployment, service, and other resource kinds multiple times.
+
+## Layering
+
+Layering works for both simple and block form. Just create a folder with the corresponding name.
+
+* The layering definitions with the simple form only merge with other simple form layers.
+* The layering definitions for block forms only merge with other block form layers.
+
+Simple form layering:
+
+    .kubes/resources/
+    ├── base
+    │   ├── all.rb
+    │   └── deployment.rb
+    └── web
+        ├── deployment
+        │   ├── dev.rb
+        │   └── prod.rb
+        └── deployment.rb
+
+Block form layering:
+
+    .kubes/resources/
+    ├── base
+    │   ├── alls.rb
+    │   └── deployments.rb
+    └── web
+        ├── deployments
+        │   ├── dev.rb
+        │   └── prod.rb
+        └── deployments.rb
+
+The main difference are pluralized filenames.

data/docs/_docs/dsl/resources.md

@@ -0,0 +1,12 @@
+---
+title: Resources
+---
+
+Here's a list of the resources supported by the Kubes DSL.
+
+{% assign docs = site.docs | where: "categories","dsl" %}
+{% for doc in docs -%}
+* [{{ doc.title }}]({{ doc.url }})
+{% endfor %}
+
+For resources, that are not supported, you can use the [Generic resource]({% link _docs/dsl/resources/generic.md %}) or use [YAML]({% link _docs/yaml.md %}) instead. You can use a mix of DSL and YAML definitions in the `.kubes/resources` folder.

data/docs/_docs/dsl/resources/backend_config.md

@@ -0,0 +1,45 @@
+---
+title: BackendConfig
+categories: dsl
+---
+
+A BackendConfig is [custom resource definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) that allow you to further customize the load balancer.
+
+Here's an example of a BackendConfig.
+
+.kubes/resources/web/backend-config.rb
+
+```ruby
+name "backendconfig"
+spec(
+  timeoutSec: 40,
+  connectionDraining: {
+    drainingTimeoutSec: 60,
+  },
+  sessionAffinity: {
+    affinityType: "CLIENT_IP",
+  }
+)
+```
+
+Produces:
+
+.kubes/output/web/backend-config.yaml
+
+```yaml
+---
+apiVersion: cloud.google.com/v1
+kind: BackendConfig
+metadata:
+  name: my-bsc-backendconfig
+spec:
+  timeoutSec: 40
+  connectionDraining:
+    drainingTimeoutSec: 60
+  sessionAffinity:
+    affinityType: CLIENT_IP
+```
+
+## DSL Methods
+
+{% include dsl/methods.md name="backend_config" %}

data/docs/_docs/dsl/resources/config_map.md

@@ -0,0 +1,84 @@
+---
+title: ConfigMap
+categories: dsl
+---
+
+## Example
+
+Here's an example of a ConfigMap.
+
+.kubes/resources/shared/config_map.rb
+
+```ruby
+name "demo-config-map"
+data(
+  database: "mongodb",
+  database_uri: "mongodb://localhost:27017",
+)
+```
+
+Produces:
+
+.kubes/output/shared/config_map.yaml
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: demo-config-map-cfbd534f91
+  labels:
+    app: demo
+  namespace: default
+data:
+  database: mongodb
+  database_uri: mongodb://localhost:27017
+```
+
+## Suffix Hash
+
+{% include dsl/rolling_deployment.md kind="ConfigMap" %}
+
+.kubes/output/web/deployment.yaml:
+
+```yaml
+# ..
+spec:
+  template:
+    spec:
+      containers:
+      - name: demo-web
+        image: nginx
+        envFrom:
+        - configMapRef:
+            name: demo-config-map-cfbd534f91
+```
+
+{% include dsl/suffix_hash.md %}
+
+## Files Helper
+
+You can use a `files` helper to load ConfigMap values from one or more files.
+
+
+.kubes/resources/shared/config_map.rb
+
+```ruby
+name "demo-secret"
+files("files/configs.txt")
+```
+
+The `files/configs.txt` should be in the same folder as the `config_map.rb` definition.  Example:
+
+.kubes/resources/shared/files/configs.txt
+
+    CONFIG1=value1
+    CONFIG2=value2
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+* data
+* binaryData
+
+{% include dsl/methods.md name="config_map" %}

data/docs/_docs/dsl/resources/daemon_set.md

@@ -0,0 +1,58 @@
+---
+title: DaemonSet
+categories: dsl
+---
+
+## Example
+
+Here's an example of a DaemonSet.
+
+.kubes/resources/shared/daemon_set.rb
+
+```ruby
+name "calico-node"
+namespace "kube-system"
+labels("k8s-app": "calico-node")
+updateStrategy(
+  type: "RollingUpdate",
+  rollingUpdate: {
+    maxUnavailable: 1
+  }
+)
+annotations(
+  "*scheduler**.alpha.kubernetes.io/critical-pod": '*'
+)
+```
+
+Produces:
+
+.kubes/output/shared/daemon_set.yaml
+
+```yaml
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  annotations:
+    "*scheduler**.alpha.kubernetes.io/critical-pod": "*"
+  name: calico-node
+  labels:
+    k8s-app: calico-node
+  namespace: kube-system
+spec:
+  updateStrategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxUnavailable: 1
+```
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+* minReadySeconds
+* revisionHistoryLimit
+* selector
+* template
+* updateStrategy
+
+{% include dsl/methods.md name="daemon_set" %}