kubes 0.1.0 → 0.2.4

data/docs/_docs/extra-env/yaml.md

@@ -0,0 +1,67 @@
+---
+title: YAML Example
+---
+
+Kubes provides helper methods to make creating extra environments easy: `with_extra`.  We'll create extra environments under different namespaces.
+
+Here's how you achieve extra environments with the YAML form:
+
+.kubes/resources/web/deployment.rb
+
+```ruby
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: demo-web
+  labels:
+    app: demo
+  namespace: <%= with_extra("default") %>
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: demo
+  template:
+    metadata:
+      labels:
+        app: demo
+    spec:
+      containers:
+      - image: <%= built_image %>
+        name: demo-web
+```
+
+.kubes/resources/web/service.rb
+
+```ruby
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: demo-web
+  labels:
+    app: demo
+  namespace: <%= with_extra("default") %>
+spec:
+  ports:
+  - port: 80
+    protocol: TCP
+    targetPort: 8080
+  selector:
+    app: demo
+  type: NodePort
+```
+
+It's important to use the `with_extra` helper to set the namesapce. The helper accounts for `KUBES_EXTRA` and appends the value.
+
+## Deployment
+
+Then to create an additional environment, it's simple:
+
+    kubectl create ns default-2
+    KUBES_EXTRA=2 kubes deploy
+
+To check on the resources:
+
+    kubectl get all -n default-2

data/docs/_docs/helpers.md

@@ -0,0 +1,19 @@
+---
+title: Helpers
+---
+
+Kubes provides some helper methods to help write Kubernetes YAML files.  Here's a list of the helper methods. These are available whether you write your resources in YAML or DSL.
+
+Helper | Description
+--- | ---
+built_image | Method refers to the latest Docker image built by Kubes. This spares you from having to update the image manually in the deployment resource.
+dockerfile_port	| Exposed port extracted from the Dockerfile of the project.
+extra | The `KUBES_EXTRA` value.
+with_extra | Appends the `KUBES_EXTRA` value to a string if it's set. It's covered in the [Extra Env Docs]({% link _docs/extra-env.md %}).
+
+Here's also the source code with the helpers: [helpers.rb](https://github.com/boltops-tools/kubes/blob/master/lib/kubes/compiler/shared/helpers.rb).
+
+
+## DSL Specific Methods
+
+Each DSL resource has it's own specific methods. Refer to the [DSL Docs]({% link _docs/dsl.md %}) for their methods.

data/docs/_docs/intro.md

@@ -0,0 +1,15 @@
+---
+title: What is Kubes?
+---
+
+{% include reference.md %}
+
+## 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 %}).
+* CLI Customizations: You can customize the [cli args]({% link _docs/config/kubectl.md %}). You can also run hooks before and after kubectl 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/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/auto-context.md %}).

data/docs/_docs/intro/concepts.md

@@ -0,0 +1,37 @@
+---
+title: Kubes Concepts
+---
+
+## Resources Files
+
+The `.kubes/resources` where you organized Kubernetes resources. Different subfolders within the resources folder represent your app. Example:
+
+    .kubes
+    └── resources
+        ├── clock
+        │   └── deployment.yaml
+        ├── worker
+        │   └── deployment.yaml
+        └── web
+            ├── deployment.yaml
+            └── service.yaml
+
+Each folder contains your Kubernetes deployment definition, either in [YAML]({% link _docs/yaml.md %}) or [DSL]({% link _docs/dsl.md %}) form. Both can be used together.
+
+## Conventions Over Configuration
+
+Kubes uses Conventions Over Configuration structure to remove boilerplate setup and mental overhead.
+
+You can deploy just the demo-web app
+
+    kubes deploy web
+
+Or you can deploy all 3 with:
+
+    kubes deploy
+
+The deploy command automatically builds the Docker image and replaces the image in the YAML file with the latest built image.
+
+## Layering
+
+Kubes supports layering files together so you can use the same Kubernetes files to build multiple environments like dev and prod. More details in the [Layering Docs]({% link _docs/layering.md %}).

data/docs/_docs/intro/how-kubes-works.md

@@ -0,0 +1,29 @@
+---
+title: How Kubes Works
+---
+
+Kubes is pretty straightforward. Kubes first builds the Docker image. Then it compiles Kubernetes YAML files. Lastly, it merely calls out to `kubectl`.
+
+In fact, you can use Kubes to build the files first, and then run `kubectl` directly. Example:
+
+    kubes docker build
+    kubes docker push
+    kubes compile  # compiles the .kubes/resources files to .kubes/output
+
+Now, use `kubectl` directly. This will apply all the files:
+
+    kubectl apply --recursive -f .kubes/output
+
+You can also selectively apply specific files:
+
+    kubectl apply -f .kubes/output/web/deployment.yaml
+    kubectl apply -f .kubes/output/web/service.yaml
+
+You can also apply with kubes. This will compile the files automatically also.
+
+    kubes apply
+
+The deploy command, does all 3 steps: builds the docker image, compiles the `.kubes/resources` files, and runs kubectl apply.
+
+    kubes deploy
+

data/docs/_docs/intro/install.md

@@ -0,0 +1,6 @@
+---
+title: Installation
+---
+
+{% include intro/install.md %}
+

data/docs/_docs/intro/ordering.md

@@ -0,0 +1,63 @@
+---
+title: Ordering
+---
+
+Generally, Kubes will apply resources in order so dependent resources are created first. If needed, you can completely customize the order: [Custom Ordering]({% link _docs/intro/ordering/custom.md %}).
+
+## Apply
+
+Here's an example that shows it creating the service and deployment first, and then the ingress last.
+
+    $ kubes apply
+    Compiled  .kubes/resources files
+    Deploying kubes files
+    => kubectl apply -f .kubes/output/web/service.yaml
+    service/demo-web created
+    => kubectl apply -f .kubes/output/web/deployment.yaml
+    deployment.apps/demo-web created
+    => kubectl apply -f .kubes/output/web/ingress.yaml
+    ingress.networking.k8s.io/demo-web created
+    $
+
+## Delete
+
+Kubes will delete in the reverse order.
+
+    $ kubes delete -y
+    Compiled  .kubes/resources files
+    => kubectl delete -f .kubes/output/web/ingress.yaml
+    ingress.networking.k8s.io "demo-web" deleted
+    => kubectl delete -f .kubes/output/web/deployment.yaml
+    deployment.apps "demo-web" deleted
+    => kubectl delete -f .kubes/output/web/service.yaml
+    service "demo-web" deleted
+    $
+
+## Shared Resources First
+
+Resources in the `shared` folder will be applied first.  Example:
+
+    .kubes
+    └── resources
+        ├── clock
+        │   └── deployment.yaml
+        ├── web
+        │   ├── deployment.yaml
+        │   └── service.yaml
+        └── shared
+            ├── config_map.yaml
+            └── secret.yaml
+
+Results in:
+
+    $ kubes apply
+    => kubectl apply -f .kubes/output/shared/secret.yaml
+    secret/demo-secret created
+    => kubectl apply -f .kubes/output/clock/deployment.yaml
+    deployment.apps/demo-clock created
+    => kubectl apply -f .kubes/output/web/service.yaml
+    service/demo-web created
+    => kubectl apply -f .kubes/output/web/deployment.yaml
+    deployment.apps/demo-web created
+    $
+

data/docs/_docs/intro/ordering/custom.md

@@ -0,0 +1,25 @@
+---
+title: Custom Ordering
+---
+
+You can override the ordering with the `kinds` and `roles` option under the `config.kubectl.order` key. It is fully configurable. Here's an example of overriding the default ordering.
+
+.kubes/config.rb:
+
+```ruby
+Kubes.configure do |config|
+  config.kubectl.order.roles = %w[
+    shared
+    web
+    worker
+    clock
+  ]
+  config.kubectl.order.kinds = [
+    "Namespace",
+    # ...
+    "Deployment",
+  ]
+end
+```
+
+Items not listed in the list are sorted at the end and in alphabetical order. Refer to the source [ordering.rb](https://github.com/boltops-tools/kubes/blob/master/lib/kubes/config.rb#L50) for the default ordering.

data/docs/_docs/intro/structure.md

@@ -0,0 +1,43 @@
+---
+title: Kubes Structure
+---
+
+Here's what a .kubes folder structure can look like this:
+
+    .kubes
+    ├── config
+    │   ├── docker
+    │   │   ├── args.rb
+    │   │   └── hooks.rb
+    │   ├── env
+    │   │   ├── dev.rb
+    │   │   └── prod.rb
+    │   └── kubectl
+    │       ├── args.rb
+    │       └── hooks.rb
+    ├── config.rb
+    ├── output
+    ├── resources
+    │   ├── base
+    │   │   └── all.yaml
+    │   ├── clock
+    │   │   └── deployment.yaml
+    │   ├── shared
+    │   │   ├── config_map.yaml
+    │   │   └── secret.yaml
+    │   ├── web
+    │   │   ├── deployment.yaml
+    │   │   └── service.yaml
+    │   └── worker
+    │       └── deployment.yaml
+    └── state
+
+Name | Description
+--- | ---
+base | The base folder is processed first and can be used to define common fields and resources. Learn more on the [Layering Docs]({% link _docs/layering.md %}).
+config | The config folder can be used to configure behavior of Kubes.  The [docker]({% link _docs/config/docker.md %}) config is used to customize the docker command. The [env]({% link _docs/config/env.md %}) config is used to override `config.rb` settings on a `KUBES_ENV` basis. The [kubectl]({% link _docs/config/kubectl.md %}) config is used to customize the kubectl command.
+config.rb | The main thing to configure here is the repo to push the docker image to.
+output | Where kubes builds and writes the Kubernetes YAML to.
+resources | Where you define your Kubernetes resources.
+shared | The shared folder is where you can put shared resources. This folder gets applied first. More info: [Ordering]({% link _docs/intro/ordering.md %}).
+state | Temporary state info that stores the built Docker image name.

data/docs/_docs/kustomize.md

@@ -0,0 +1,54 @@
+---
+title: Kustomize Support
+---
+
+Kubes supports Kustomize. So if you're a kustomization user, you can use it with Kubes.
+
+## Structure
+
+If there are any kustomization.yaml files in your `.kubes/resources` folder, Kubes kustomize mode is automatically enabled. Example structure:
+
+    .kubes/resources
+    ├── base
+    │   ├── deployment.yaml
+    │   ├── kustomization.yaml
+    │   └── service.yaml
+    └── overlays
+        ├── dev
+        │   └── kustomization.yaml
+        └── prod
+            └── kustomization.yaml
+
+## Deploy
+
+In Kustomize mode, Kubes will call `kubectl apply -k`.  Here's an example:
+
+    kubes deploy overlays/dev
+
+Will call:
+
+    kubectl apply -k .kubes/output/overlays/dev
+
+With Kubes kustomize mode, an argument to the kubes commands are generally required. The argument is the folder within the `.kubes/resources` folder.
+
+## Environments
+
+To deploy different kustomize environments using different overlays:
+
+    kubes deploy overlays/prod
+
+This results in:
+
+    kubectl apply -k .kubes/output/overlays/prod
+
+## Get
+
+To check created resources.
+
+    kubes get overlays/dev
+
+## Compile
+
+With kustomize mode, all files in `.kubes/resources` are compiled and written to `.kubes/output`.
+
+Also, no Kubes layering is performed, as kustomization overlays should be used instead.

data/docs/_docs/layering.md

@@ -0,0 +1,8 @@
+---
+title: Layering
+---
+
+Kubes supports layering files together so you can use the same Kubernetes files to build multiple environments like dev and prod.
+
+* [YAML Layering]({% link _docs/layering/yaml.md %})
+* [DSL Layering]({% link _docs/layering/dsl.md %})

data/docs/_docs/layering/dsl.md

@@ -0,0 +1,5 @@
+---
+title: DSL Layering
+---
+
+{% include layering/layers.md ext="rb" %}

data/docs/_docs/layering/merge.md

@@ -0,0 +1,96 @@
+---
+title: DSL 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.
+
+## Hash Example
+
+.kubes/resources/base/all.rb
+
+```ruby
+labels(app: "demo")
+# ...
+```
+
+.kubes/resources/base/all/env.rb
+
+```ruby
+labels(env: Kubes.env)
+# ...
+```
+
+.kubes/resources/web/deployment.rb
+
+```ruby
+labels(role: "web")
+# ...
+```
+
+Layering results in:
+
+.kubes/output/web/deployment.yaml
+
+```yaml
+metadata:
+  labels:
+    app: demo
+    env: dev
+    role: web
+# ...
+```
+
+## Hash Merge Behavior Override
+
+You can override the merge behavior with the `_mode` key.
+
+.kubes/resources/web/deployment.rb
+
+```ruby
+labels(role: "web", _mode: "reset")
+# ...
+```
+
+This will completely reset the labels and result in:
+
+```yaml
+metadata:
+  labels:
+    role: web
+# ...
+```
+
+## String Example
+
+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
+# ...
+```
+
+.kubes/resources/web/deployment/prod.rb
+
+```ruby
+image "nginx:prod-v1"
+# ...
+```
+
+Results in:
+
+.kubes/output/web/deployment.yaml
+
+```yaml
+spec:
+  # ...
+  template:
+    spec:
+      containers:
+      - image: nginx:prod-v1
+        name: demo-web
+  # ...
+```
+
+{% include dsl/methods.md name="backend_config" %}