kubes 0.1.0 → 0.2.0

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

@@ -0,0 +1,87 @@
+---
+title: Secret
+categories: dsl
+---
+
+## Example
+
+Here's an example of a Secret.
+
+.kubes/resources/shared/secret.rb
+
+```ruby
+name "demo-secret"
+data(
+  username: base64("user"),
+  password: base64("pass"),
+)
+```
+
+Produces:
+
+.kubes/output/shared/service.yaml
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: demo-secret-cfbd534f91
+  labels:
+    app: demo
+  namespace: default
+data:
+  username: dXNlcg==
+  password: cGFzcw==
+```
+
+## Suffix Hash
+
+{% include dsl/rolling_deployment.md kind="Secret" %}
+
+.kubes/output/web/deployment.yaml:
+
+```yaml
+# ..
+spec:
+  template:
+    spec:
+      containers:
+      - name: demo-shared
+        image: nginx
+        envFrom:
+        - secretRef:
+            name: demo-secret-cfbd534f91
+```
+
+{% include dsl/suffix_hash.md %}
+
+## Files Helper
+
+You can use a `files` helper to load secrets values from one or more files.
+
+
+.kubes/resources/shared/secret.rb
+
+```ruby
+name "demo-secret"
+files("files/secrets.txt")
+```
+
+The `files/secrets.txt` should be in the same folder as the `secret.rb` definition.  Example:
+
+.kubes/resources/shared/files/secret.txt
+
+    SECRET1=value1
+    SECRET2=value2
+
+You do not have to worry about base64 encoding the values. Kubes automatically base64 encodes the values.
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+* data
+* stringData
+* type
+
+{% include dsl/methods.md name="secret" %}

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

@@ -0,0 +1,60 @@
+---
+title: Service
+categories: dsl
+---
+
+## Example
+
+Here's an example of a Service.
+
+.kubes/resources/web/service.rb
+
+```ruby
+name "demo-web"
+labels(role: "web")
+namespace "default"
+
+# Optional since these are the defaults
+# port 80
+# targetPort 80
+#
+# type "NodePort"
+```
+
+Produces:
+
+.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
+```
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+* nodePort
+* port
+* portName: Note this field doesn't match the original field name. It's more qualified.
+* ports
+* protocol
+* selector
+* targetPort
+* type
+
+{% include dsl/methods.md name="service" %}

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

@@ -0,0 +1,37 @@
+---
+title: ServiceAccount
+categories: dsl
+---
+
+## Example
+
+Here's an example of a ServiceAccount.
+
+.kubes/resources/shared/service_account.rb
+
+```ruby
+name "demo"
+```
+
+Produces:
+
+.kubes/output/shared/service_account.yaml
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: demo
+```
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+Top-level methods:
+
+* automountServiceAccountToken
+* imagePullSecrets
+* secrets
+
+{% include dsl/methods.md name="service_account" %}

data/docs/_docs/extra-env.md

@@ -0,0 +1,23 @@
+---
+title: Extra Environments
+---
+
+Kubes adds the concept of extra environments.  Let say, you have a demo-web app with a deployment and service.
+
+    .kubes/resources
+    └── web
+        ├── deployment.rb
+        └── service.rb
+
+You can create additional environments using the same resource files with a few minor changes.
+
+* [DSL Example]({% link _docs/extra-env/dsl.md %})
+* [YAML Example]({% link _docs/extra-env/yaml.md %})
+
+## Deploy
+
+Then to create an additional environment, it's simple:
+
+    KUBES_EXTRA=2 kubes deploy
+    KUBES_EXTRA=3 kubes deploy
+    # etc

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

@@ -0,0 +1,86 @@
+---
+title: DSL 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 DSL form:
+
+.kubes/resources/web/deployment.rb
+
+```ruby
+name "demo-web"
+labels(role: "web")
+namespace with_extra("default")
+
+replicas 1
+image built_image # IE: user/demo-web:kubes-2020-06-13T19-55-16-43afc6e
+```
+
+.kubes/resources/web/service.rb
+
+```ruby
+name "demo-web"
+labels(role: "web")
+namespace with_extra("default")
+```
+
+The `name` 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
+
+## Using Different Name Instead
+
+The example on this page uses the `with_extra` helper to create the deployment and service in another namespace. Another approach is to use the same namespace but different names based on `KUBES_EXTRA`. We also used the `extra` helper here, which is the `KUBES_EXTRA` value. Examples:
+
+.kubes/resources/web/deployment.rb
+
+```ruby
+name with_extra("demo-web")
+labels(app: name, extra: extra)
+namespace "default"
+
+replicas 1
+image built_image # IE: user/demo-web:kubes-2020-06-13T19-55-16-43afc6e
+```
+
+.kubes/resources/web/service.rb
+
+```ruby
+name with_extra("demo-web")
+labels(app: name, extra: extra)
+namespace "default"
+```
+
+Adding label with the `extra` key is optional, but helps with filtering the resources.
+
+    kubectl get all -l extra=2
+    kubectl get all -l extra=3
+
+Example:
+
+    $ kubectl get all -l extra=2
+    NAME                              READY   STATUS    RESTARTS   AGE
+    pod/demo-web-2-5f8b8cbcdc-dmbjj   1/1     Running   0          78s
+    pod/demo-web-2-5f8b8cbcdc-kg8hf   1/1     Running   0          78s
+
+    NAME                 TYPE       CLUSTER-IP       EXTERNAL-IP   PORT(S)        AGE
+    service/demo-web-2   NodePort   172.16.158.166   <none>        80:30148/TCP   78s
+
+    NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/demo-web-2   2/2     2            2           78s
+
+    NAME                                    DESIRED   CURRENT   READY   AGE
+    replicaset.apps/demo-web-2-5f8b8cbcdc   2         2         2       79s
+    $
+
+The `extra` and `with_extra` helper methods provide flexibility to create these extra environments with either approach.

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,18 @@
+---
+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.
+with_extra | Appends the `KUBES_ENV` value to a string if it's set. It's covered in the [Extra Env Docs]({% link _docs/extra-env.md %}).
+extra | The `KUBES_ENV` value.
+
+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
+