kubes 0.1.0 → 0.2.4

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

@@ -0,0 +1,82 @@
+---
+title: Pod
+categories: dsl
+---
+
+## Example
+
+Here's an example of a Pod.
+
+.kubes/resources/shared/pod.rb
+
+```ruby
+name "busybox1"
+hostname "busybox-1"
+subdomain "default-subdomain"
+containers([
+  image: "busybox:1.28",
+  command: ["sleep", "3600"],
+  name: "busybox",
+])
+```
+
+Produces:
+
+.kubes/output/shared/pod.yaml
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: busybox1
+spec:
+  containers:
+  - image: busybox:1.28
+    command:
+    - sleep
+    - '3600'
+    name: busybox
+  hostname: busybox-1
+  subdomain: default-subdomain
+```
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+* activeDeadlineSeconds
+* affinity
+* automountServiceAccountToken
+* containers
+* dnsConfig
+* dnsPolicy
+* enableServiceLinks
+* ephemeralContainers
+* hostAliases
+* hostIPC
+* hostNetwork
+* hostPID
+* hostname
+* imagePullSecrets
+* initContainers
+* nodeName
+* nodeSelector
+* overhead
+* preemptionPolicy
+* priority
+* priorityClassName
+* readinessGates
+* restartPolicy
+* runtimeClassName
+* schedulerName
+* securityContext
+* serviceAccount
+* serviceAccountName
+* shareProcessNamespace
+* subdomain
+* terminationGracePeriodSeconds
+* tolerations
+* topologySpreadConstraints
+* volumes
+
+{% include dsl/methods.md name="pod" %}

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

@@ -0,0 +1,44 @@
+---
+title: Role
+categories: dsl
+---
+
+## Example
+
+Here's an example of a Role.
+
+.kubes/resources/shared/role.rb
+
+```ruby
+name "demo"
+apiGroups([""])
+resources(["pods"])
+verbs(["get", "watch", "list"])
+```
+
+Produces:
+
+.kubes/output/shared/role.yaml
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: demo
+rules:
+- apiGroups:
+  - ''
+  resources:
+  - pods
+  verbs:
+  - get
+  - watch
+  - list
+```
+
+## DSL Methods
+
+Here's the source of the Role resource.
+
+{% include dsl/methods.md name="role" %}
+

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

@@ -0,0 +1,55 @@
+---
+title: RoleBinding
+categories: dsl
+---
+
+## Example
+
+Here's an example of a RoleBinding.
+
+.kubes/resources/shared/role_binding.rb
+
+```ruby
+name "demo"
+
+subjects([
+  {kind: "User", name: "tung@boltops.com"},
+])
+
+roleName "demo"
+```
+
+Produces:
+
+.kubes/output/shared/role_binding.yaml
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: demo
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: demo
+subjects:
+- kind: User
+  name: tung@boltops.com
+```
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+Top-level methods:
+
+* roleRef
+* subjects
+
+roleRef level methods
+
+* apiGroup
+* roleKind
+* roleName
+
+{% include dsl/methods.md name="role_binding" %}

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.