kubes 0.1.0 → 0.2.4

data/docs/_docs/learn/yaml/new-project.md

@@ -0,0 +1,37 @@
+---
+title: New Project
+---
+
+If you already a project with an existing Dockerfile, you can use that. If you do not, kubes generates a starter Dockerfile that runs nginx. For this tutorial, we'll start with an empty folder.
+
+    mkdir demo
+    cd demo
+
+For this tutorial, we'll use an ECR repo, though any repo will work.
+
+Let's generate a starter project:
+
+    $ REPO=$(aws ecr describe-repositories --repository-name demo | jq -r '.repositories[].repositoryUri')
+    $ kubes init --app demo --repo $REPO
+          create  Dockerfile
+          create  .kubes/config.rb
+          create  .kubes/config/env/dev.rb
+          create  .kubes/config/env/prod.rb
+          create  .kubes/resources/base/all.yaml
+          create  .kubes/resources/base/deployment.yaml
+          create  .kubes/resources/shared/namespace.yaml
+          create  .kubes/resources/web/deployment.yaml
+          create  .kubes/resources/web/deployment/dev.yaml
+          create  .kubes/resources/web/deployment/prod.yaml
+          create  .kubes/resources/web/service.yaml
+    Initialized .kubes folder
+    Updated .gitignore
+    $
+
+To learn more about the generated structure, here are the [Structure Docs]({% link _docs/intro/structure.md %}).
+
+Let's explore some of the generated files.
+
+{% include learn/review.md %}
+
+Next, we'll review the resources.

data/docs/_docs/learn/yaml/next-steps.md

@@ -0,0 +1,5 @@
+---
+title: Next Steps
+---
+
+{% include learn/next-steps.md %}

data/docs/_docs/learn/yaml/review-project.md

@@ -0,0 +1,108 @@
+---
+title: Review Project
+---
+
+Let's review the resources.
+
+## Namespace
+
+We'll create a namespace for the app resources:
+
+.kubes/resources/shared/namespace.yaml
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: demo
+  labels:
+    app: demo
+```
+
+## Deployment
+
+The `web/deployment.yaml` file is a little more interesting:
+
+.kubes/resources/web/deployment.yaml
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+  labels:
+    role: web
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      role: web
+  template:
+    metadata:
+      labels:
+        role: web
+    spec:
+      containers:
+      - name: web
+        image: <%= built_image %>
+```
+
+Notice the `<%= built_image %>`.  Kubes processes the YAML files with ERB templating and replaces these tags.  The `built_image` is a kubes helper method that refers to the latest Docker image built by Kubes. This spares you updating the image manually.
+
+## Base Folder
+
+Also let's check the files in the base folder.
+
+.kubes/resources/base/all.yaml
+
+```yaml
+metadata:
+  namespace: demo
+```
+
+.kubes/resources/base/deployment.yaml
+
+```yaml
+metadata:
+  labels:
+    app: demo
+spec:
+  selector:
+    matchLabels:
+      app: demo
+  template:
+    metadata:
+      labels:
+        app: demo
+```
+
+The base folder files are processed first as a part of [Kubes Layering]({% link _docs/layering.md %}). This allows you to define common fields and keep your code DRY.
+
+The `all.yaml` means all resources will use the demo namespace.  The `deployment.yaml` adds common labels to all deployment resource kinds.
+
+## Service Resource
+
+Next, let's look at `service.yaml`
+
+.kubes/resources/web/service.yaml
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: web
+  labels:
+    role: web
+spec:
+  ports:
+  - port: 80
+    protocol: TCP
+    targetPort: <%= dockerfile_port %>
+  selector:
+    role: web
+  type: ClusterIP
+```
+
+The `dockerfile_port` helper returns the EXPOSE port in the Dockerfile. This spares you updating this manually, you only have to update the Dockerfile.
+
+Next, we'll deploy the app.

data/docs/_docs/learn/yaml/update.md

@@ -0,0 +1,54 @@
+---
+title: Update App
+---
+
+Let's update the app. In this case, we don't need to update the Docker image, so we'll use the `apply` command, which does not run the Docker build phase.
+
+    kubes apply
+
+Here's what the output looks like. Note, the namespace is not shown for conciseness.
+
+    $ kubes apply
+    Compiled  .kubes/resources files
+    => kubectl apply -f .kubes/output/web/service.yaml
+    service/demo-web unchanged
+    => kubectl apply -f .kubes/output/web/deployment.yaml
+    deployment.apps/demo-web configured
+    $
+
+The change has been deployed. Let's double check it:
+
+    kubes get
+
+Example output:
+
+    $ kubes get
+    => kubectl get --recursive -f .kubes/output
+    NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/demo-web   3/3     3            3           6m5s
+
+    NAME               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+    service/demo-web   ClusterIP   172.16.201.77   <none>        80/TCP    6m5s
+    $
+
+Let's also use the `kubectl get` command:
+
+    $ kubectl get all
+    NAME                            READY   STATUS    RESTARTS   AGE
+    pod/demo-web-5cb4f9fb77-6c7vc   1/1     Running   0          3s
+    pod/demo-web-5cb4f9fb77-lgczj   1/1     Running   0          5m25s
+    pod/demo-web-5cb4f9fb77-ls28f   1/1     Running   0          3s
+
+    NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+    service/demo-web     ClusterIP   172.16.201.77   <none>        80/TCP    5m26s
+
+    NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/demo-web   3/3     3            3           5m26s
+
+    NAME                                  DESIRED   CURRENT   READY   AGE
+    replicaset.apps/demo-web-5cb4f9fb77   3         3         3       5m26s
+    $
+
+We can see that there are now 3 replicas running.
+
+Next, we'll delete the app.

data/docs/_docs/next-steps.md

@@ -0,0 +1,13 @@
+---
+title: Next Steps
+---
+
+Hopefully, you have a good feel for how kubes works now. From here, there are a few resources that can help you continue along:
+
+* Check out the [kubes](https://github.com/boltops-tools/kubes) repo on GitHub
+* ⭐️ the kubes project on GitHub
+* Write a blog post about kubes
+* Post on your favorite discussion about kubes
+* Contribute a pull request
+
+Everyone can contribute to making kubes better, including the documentation. These docs are the kubes repo located the [docs folder](https://github.com/boltops-tools/tree/master/docs). Please fork the project and open a pull request!  We love your pull requests. Contributions are encouraged and welcomed!

data/docs/_docs/patterns.md

@@ -0,0 +1,7 @@
+---
+title: Patterns
+---
+
+We'll cover some common deployment patterns here:
+
+* [Clock Web Worker]({% link _docs/patterns/clock-web-worker.md %})

data/docs/_docs/patterns/clock-web-worker.md

@@ -0,0 +1,71 @@
+---
+title: Clock Web Worker Pattern
+---
+
+A common pattern is to use the same code to run different types of processes like clock, web, worker. Kubes is flexible enough to support this pattern.
+
+Note, often the clock process is also called a scheduler.
+
+## Structure
+
+Here's a structure that achieves this pattern with Kubes:
+
+    .kubes/resources
+    ├── clock
+    │   └── deployment.rb
+    ├── web
+    │   ├── deployment.rb
+    │   └── service.rb
+    └── worker
+        └── deployment.rb
+
+## Source Code
+
+.kubes/resources/demo-clock/deployment.rb
+
+```ruby
+name "demo-clock"
+namespace "default"
+labels(role: "web")
+
+replicas 1
+image built_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
+command "bin/clock"
+```
+
+.kubes/resources/web/deployment.rb
+
+```ruby
+name "demo-web"
+namespace "default"
+labels(role: "web")
+
+replicas 1
+image built_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
+```
+
+.kubes/resources/demo-worker/deployment.rb
+
+```ruby
+name "demo-worker"
+namespace "default"
+labels(role: "web")
+
+replicas 2
+image built_image # IE: user/demo-clock:kubes-2020-06-13T19-55-16-43afc6e
+command "bin/worker"
+```
+
+## Deploy All-At-Once
+
+To deploy all 3 process types:
+
+    kubes deploy
+
+## Deploy Selectively
+
+To deploy selectively:
+
+    kubes deploy clock
+    kubes deploy web
+    kubes deploy worker

data/docs/_docs/resources.md

@@ -0,0 +1,11 @@
+---
+title: Resources
+---
+
+You define your Kubernetes resources in the `.kubes/resources` folder. Kubes categories items within this folder in 3 main buckets:
+
+* [Role-Based Resource]({% link _docs/resources/role.md %}): Role-based resources. This is your main project resources group in roles.
+* [Base Folder]({% link _docs/resources/base.md %}): The base folder contains definitions for common fields that is used for [Layering]({% link _docs/layering.md %}).
+* [Shared Resources]({% link _docs/resources/shared.md %}): Shared resources that are meant to be created first and shared by other resources.
+
+In the next sections, we'll cover how these resources are used.

data/docs/_docs/resources/base.md

@@ -0,0 +1,33 @@
+---
+title: Base
+---
+
+The base folder is used for purely layering.
+
+## Structure
+
+Here's an example structure, so we can understand how layering works with the base folder.
+
+    .kubes/resources/
+    ├── base
+    │   ├── all.rb
+    │   └── deployment.rb
+    └── web
+        ├── deployment.rb
+        └── service.rb
+
+## Layering
+
+Kubes process the files in the `base` folder first, then it process your [role-based resources]({% link _docs/resources/role.md %}) like web. So:
+
+    kubes deploy web deployment
+
+Will layer:
+
+1. .kubes/resources/base/all.rb
+2. .kubes/resources/base/deployment.rb
+3. .kubes/resources/web/deployment.rb
+
+More details on layering can be found in the [Layering Docs]({% link _docs/layering.md %}).
+
+Remember files in the base are used just for layering.

data/docs/_docs/resources/role.md

@@ -0,0 +1,41 @@
+---
+title: Role-Based Resources
+---
+
+Role-based resources are your main project's resources.  Kubes groups resources together under a "role".
+
+## Example Structure
+
+Here's an example structure to help explain how role-based resources work.
+
+    .kubes
+    └── resources
+        ├── clock
+        │   └── deployment.yaml
+        ├── web
+        │   ├── deployment.yaml
+        │   └── service.yaml
+        └── worker
+            └── deployment.yaml
+
+## Resource Roles
+
+Here the resource roles are:
+
+1. clock
+2. web
+3. worker
+
+You can freely add more roles if needed. This structure is flexible enough to account for most use-cases.
+
+## Deploy
+
+You can deploy specific roles like so:
+
+    kubes deploy clock
+    kubes deploy web
+    kubes deploy worker
+
+Or you can deploy all roles at once:
+
+    kubes deploy

data/docs/_docs/resources/shared.md

@@ -0,0 +1,36 @@
+---
+title: Shared
+---
+
+The `shared` folder purpose is to provide a place for Kubernetes resources that are shared between roles.
+
+## Example Structure
+
+Here's an example structure to help explain how shared resources work.
+
+    .kubes/resources
+    ├── clock
+    │   └── deployment.rb
+    ├── shared
+    │   └── secret.rb
+    └── web
+        ├── deployment.rb
+        └── service.rb
+
+## Deploy
+
+When you deploy with Kubes, it will run `kubectl apply` on the shared resources first and then your [role-based resources]({% link _docs/resources/role.md %}) like clock and web.  Example:
+
+    $ kubes apply
+    Deploying kubes resources
+    => 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
+    $
+
+Kubes will order the creation of shared resources first.  You can override the default ordering with an [Order config]({% link _docs/intro/ordering/custom.md %}).

data/docs/_docs/yaml.md

@@ -0,0 +1,41 @@
+---
+title: Kubes YAML
+---
+
+You can write your Kubernetes resources in YAML format.
+
+    .kubes
+    └── resources
+        └── web
+            ├── deployment.yaml
+            └── service.yaml
+
+## YAML and Templating
+
+Kubes provides a little extra power for the YAML format. The YAML files are processed through an ERB templating language.  So you have dynamic control. Here's an example with `Kubes.env` and the `built_image` helper.
+
+.kubes/resources/web/deployment.yaml
+
+```yaml
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: demo-web
+  labels:
+    app: demo
+  namespace: default
+spec:
+  replicas: <%= Kubes.env == "prod" ? 2 : 1 %>
+  selector:
+    matchLabels:
+      app: demo
+  template:
+    metadata:
+      labels:
+        app: demo
+    spec:
+      containers:
+      - name: demo-web
+        image: <%= built_image %>
+```