kubes 0.1.0 → 0.2.0

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

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

@@ -0,0 +1,142 @@
+---
+title: Deployment
+categories: dsl
+---
+
+DSL builds Kubernetes YAML files with a reasonable default structure.  Each part of the structure can be customized and overridden.
+
+## Basics
+
+.kubes/resources/web/deployment.rb:
+
+```ruby
+name "demo-web"
+labels(role: "web")
+namespace "default"
+replicas 2
+image "nginx"
+```
+
+Produces:
+
+.kubes/output/web/deployment.yaml:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: demo-web
+  labels:
+    app: demo
+  namespace: default
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: demo
+  strategy:
+    rollingUpdate:
+      maxSurge: 25
+      maxUnavailable: 25
+    type: RollingUpdate
+  template:
+    metadata:
+      labels:
+        app: demo
+    containers:
+    - name: demo-web
+      image: nginx
+```
+
+## More Customizations
+
+You can override any of the attributes within the deployment structure. You have first-class citizen access to the DSL helpers methods like template and strategy methods that set reasonable defaults.
+
+Examples:
+
+```ruby
+spec(
+  replicas: replicas,
+  selector: {matchLabels: labels},
+  strategy: strategy,
+  template: template,
+)
+```
+
+If you only have a single container:
+
+```ruby
+container(
+  name: name,
+  image: "nginx",
+  ports: [
+    containerPort: 80
+  ]
+)
+```
+
+For multiple containers:
+
+```ruby
+containers([
+  name: name,
+  image: "nginx",
+  ports: [
+    containerPort: 80
+  ]
+])
+```
+
+Refer to the source code [syntax/deployment.rb](https://github.com/boltops-tools/kubes/blob/master/lib/kubes/compiler/dsl/syntax/deployment.rb) for more methods available.
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+Top-level and special fields:
+
+* container
+* containers
+* matchLabels
+* maxSurge
+* maxUnavailable
+* sidecar
+* templateMetadata
+* templateSpec
+
+deployment.spec fields:
+
+* minReadySeconds
+* progressDeadlineSeconds
+* replicas
+* revisionHistoryLimit
+* selector
+* strategy
+* template
+
+deployment.spec.template.spec.containers fields:
+
+* args
+* command
+* env
+* envFrom
+* image
+* imagePullPolicy
+* lifecycle
+* livenessProbe
+* containerName
+* ports
+* readinessProbe
+* volumeDevices
+* volumeMounts
+* workingDir
+
+deployment.spec.template.spec.containers.ports fields:
+
+* containerPort
+* hostIP
+* hostPort
+* portName: Note this field doesn't match the original field name. It's more qualified.
+* protocol
+
+{% include dsl/methods.md name="deployment" %}