kubes 0.1.0 → 0.2.0

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

@@ -0,0 +1,33 @@
+---
+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 --type dsl
+          create  .kubes/config.rb
+          create  .kubes/config/env/dev.rb
+          create  .kubes/config/env/prod.rb
+          create  .kubes/resources/base/all.rb
+          create  .kubes/resources/web/deployment.rb
+          create  .kubes/resources/web/deployment/dev.rb
+          create  .kubes/resources/web/deployment/prod.rb
+          create  .kubes/resources/web/service.rb
+    Initialized .kubes folder
+    $
+
+The `--type=dsl` option tells Kubes to generate DSL format files. 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/dsl/next-steps.md

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

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

@@ -0,0 +1,52 @@
+---
+title: Review Project
+---
+
+Let's review the resources.
+
+## Deployment Resource
+
+The `web/deployment.rb` file is a little more interesting:
+
+.kubes/resources/web/deployment.rb
+
+```ruby
+name "demo-web"
+labels(role: "web")
+namespace "default"
+
+replicas 1
+image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+```
+
+The DSL form is more concise than the YAML form.  Also, notice the use of the `built_image` helper. The `built_image` is a kubes helper method that refers to the latest Docker image built. This spares you from updating the image manually.
+
+## Base Resource
+
+Also let's check the files in the base folder.
+
+.kubes/resources/base/all.rb
+
+```ruby
+namespace "default"
+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.
+
+Next, let's look at `service.rb`
+
+.kubes/resources/web/service.rb
+
+```ruby
+name "demo-web"
+labels(role: "web")
+
+# Optional since default port is 80
+# port 80
+# targetPort 80
+```
+
+Service is also pretty simple.  Though the DSL may seem simple, it allows you to fully control the generated YAML. You can learn more about the DSL form at: [Deployment DSL Docs]({% link _docs/dsl/resources/deployment.md %})
+
+Next, we'll deploy the app.

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

@@ -0,0 +1,53 @@
+---
+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:
+
+    $ 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           3m34s
+
+    NAME               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+    service/demo-web   ClusterIP   172.16.173.96   <none>        80/TCP    3m35s
+
+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          3m37s
+    pod/demo-web-6f867f469f-cqmpd   1/1     Running   0          7s
+    pod/demo-web-6f867f469f-slnsw   1/1     Running   0          108s
+
+    NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+    service/demo-web     ClusterIP   172.16.173.96   <none>        80/TCP    3m38s
+
+    NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/demo-web   3/3     3            3           3m37s
+
+    NAME                                  DESIRED   CURRENT   READY   AGE
+    replicaset.apps/demo-web-6f867f469f   3         3         3       3m37s
+    $
+
+We can see that there are now 3 replicas running.
+
+Next, we'll delete the app.

data/docs/_docs/learn/yaml.md

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

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

@@ -0,0 +1,17 @@
+---
+title: Change Project
+---
+
+Let's make a simple change. We'll adjust the number of replicas to 3.  We do this in `deployment/dev.yaml`.
+
+.kubes/resources/web/deployment/dev.yaml
+
+```yaml
+---
+spec:
+  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/yaml/cluster.md

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

data/docs/_docs/learn/yaml/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/yaml/deploy.md

@@ -0,0 +1,62 @@
+---
+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           7s
+
+    NAME               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+    service/demo-web   ClusterIP   172.16.201.77   <none>        80/TCP    7s
+    $
+
+Let's also use the `kubectl get` command:
+
+    $ kubectl get all
+    NAME                            READY   STATUS    RESTARTS   AGE
+    pod/demo-web-5cb4f9fb77-lgczj   1/1     Running   0          3m48s
+
+    NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+    service/demo-web     ClusterIP   172.16.201.77   <none>        80/TCP    3m49s
+
+    NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
+    deployment.apps/demo-web   1/1     1            1           3m49s
+
+    NAME                                  DESIRED   CURRENT   READY   AGE
+    replicaset.apps/demo-web-5cb4f9fb77   1         1         1       3m49s
+    $
+
+We can see that the deployment and service got created.
+
+Next, we'll make a change.

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

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

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

@@ -0,0 +1,36 @@
+---
+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/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,97 @@
+---
+title: Review Project
+---
+
+Let's review the resources.
+
+## Deployment Resource
+
+The `web/deployment.yaml` file is a little more interesting:
+
+.kubes/resources/web/deployment.yaml
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: demo-web
+  labels:
+    role: web
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      role: web
+  strategy:
+    rollingUpdate:
+      maxSurge: 25
+      maxUnavailable: 25
+    type: RollingUpdate
+  template:
+    metadata:
+      labels:
+        role: web
+    spec:
+      containers:
+      - name: demo
+        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 Resource
+
+Also let's check the files in the base folder.
+
+.kubes/resources/base/all.yaml
+
+```yaml
+metadata:
+  namespace: default
+```
+
+.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.
+
+## Service Resource
+
+Next, let's look at `service.yaml`
+
+.kubes/resources/web/service.yaml
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: demo-web
+  labels:
+    app: demo
+  namespace: default
+spec:
+  ports:
+  - port: 80
+    protocol: TCP
+    targetPort: 8080
+  selector:
+    app: demo
+  type: ClusterIP
+```
+
+There's no use of ERB templating here.
+
+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:
+
+    $ 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.