kubes 0.1.0 → 0.2.0

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" %}

data/docs/_docs/layering/yaml.md

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

data/docs/_docs/learn/dsl.md

@@ -0,0 +1,5 @@
+---
+title: Getting Started with DSL
+---
+
+{% include learn/start.md type="DSL" %}

data/docs/_docs/learn/dsl/change.md

@@ -0,0 +1,16 @@
+---
+title: Change Project
+---
+
+Let's make a simple change. We'll adjust the number of replicas to 3.  We do this in `deployment/dev.rb`.
+
+.kubes/resources/web/deployment/dev.rb
+
+```ruby
+---
+replicas 3 # <= CHANGED
+```
+
+This demonstrates Kubes [Layering support]({% link _docs/layering.md %}). We can make changes to only the `KUBES_DEV` environment.
+
+Next, we'll deploy this update.

data/docs/_docs/learn/dsl/cluster.md

@@ -0,0 +1,5 @@
+---
+title: Cluster Setup
+---
+
+{% include learn/cluster.md %}

data/docs/_docs/learn/dsl/delete.md

@@ -0,0 +1,30 @@
+---
+title: Delete App
+---
+
+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:
+
+    $ kubes delete
+    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
+    deployment.apps "demo-web" deleted
+    $
+
+Let's double-check that the resources have been deleted:
+
+    $ kubectl get all
+    No resources found.
+    $
+
+Tip: If you want to delete without the prompt, you can use the `-y` option:
+
+    kubes delete -y
+
+Next, we'll look at some next steps.

data/docs/_docs/learn/dsl/deploy.md

@@ -0,0 +1,61 @@
+---
+title: Deploy App
+---
+
+Let's deploy
+
+    kubes deploy
+
+You'll see output like this:
+
+    $ kubes deploy
+    => docker build -t 111111111111.dkr.ecr.us-west-2.amazonaws.com/demo:kubes-2020-06-19T04-19-13 -f Dockerfile .
+    => docker push 111111111111.dkr.ecr.us-west-2.amazonaws.com/demo:kubes-2020-06-19T04-19-13
+    Pushed 111111111111.dkr.ecr.us-west-2.amazonaws.com/demo:kubes-2020-06-19T04-19-13 docker image.
+    Docker push took 15s.
+    Compiled  .kubes/resources 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
+    $
+
+What did Kubes do?
+
+{% include kubes-steps.md %}
+
+## Check Resources
+
+Let's check for the created resource on the Kubernetes cluster:
+
+    kubes get
+
+Example output:
+
+    $ kubes get
+    => kubectl get --recursive -f .kubes/output
+    NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/demo-web   1/1     1            1           10s
+
+    NAME               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+    service/demo-web   ClusterIP   172.16.173.96   <none>        80/TCP    11s
+
+Let's also use the `kubectl get` command:
+
+    $ kubectl get all
+    NAME                            READY   STATUS    RESTARTS   AGE
+    pod/demo-web-6f867f469f-5qhn6   1/1     Running   0          16s
+
+    NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+    service/demo-web     ClusterIP   172.16.173.96   <none>        80/TCP    17s
+
+    NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/demo-web   1/1     1            1           16s
+
+    NAME                                  DESIRED   CURRENT   READY   AGE
+    replicaset.apps/demo-web-6f867f469f   1         1         1       16s
+    $
+
+We can see that the deployment and service got created.
+
+Next, we'll make a change.

data/docs/_docs/learn/dsl/install.md

@@ -0,0 +1,5 @@
+---
+title: Install Kubes
+---
+
+{% include intro/install.md %}