Merge commit 'stash' into feature/update-doc-tfvars

Author: andersla

.travis.yml

@@ -10,4 +10,19 @@ install:
 
 script:
   - sphinx-build -W -b html -d _build/doctrees   . _build/html
-  
+
+notifications:
+  email: false
+  slack:
+    secure: >
+      Q1Ln2QTsVCzvxQUUZUHEgY1s48mk6qv0bfCH4k4szzQk3rYRoM0oKz+CxqlDHaaeav
+      J7tbYtiYh+rBnTTUKM7EIduoYnwJ98qsCMPoRlJl/5hknW9wF4bhjX9QouFSrdqrqh
+      8mK/be/QU95D+f82Z2yuJTtBMakmmYhhbWkuecTr6g+uukLRDIzSZKJnyXKxh3xiKz
+      kT1RMqn3dg6QFNYWGMsI9aZBYaDpMYHbnW1BPQClRvoTxtojQqQsAhhnOIJI3Z4xkz
+      IxNzzkcj3xFU3e6bUEVO6A9/GzRgddrUBzyTQEwj/JuhPgxlQe0Effniyp29Y31C2i
+      AMnCCXH+lGCJe18q254Q7xzg5jRJiEKUgPKui3Ku2tK9GLlDdXngUcMTlmwcZI227V
+      79oryqW7mk1Bl5+RqzEHqcTJhS8+iSLZdwXaH8n7Ne1UJABaDRS9/X2SsXP6h5gO9R
+      UTvj1+zypdLnvhEyUhM9KywB/31/KsIM9bUC023zS2vVtiOD/TVY3ZVmVdDx8UXsfc
+      3s3InRGJ0OVu3eO5ILHyoZnYDYXFS/3YoXJaFsEbyMxIDEKRMvhMleTxZHXUu7Win+
+      EKEFi3Yv6IfZbbj4DTO7RdlUWHMTUMkFRYMV6I/ftuZNAb+6+RtlKGL5wwANclkbE7
+      6JqZ67WSQPtl6VklfYHLYRY=

CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing Guidelines
+
+**First off, thanks for taking the time to contribute!**
+
+Information about contributing to all the various [KubeNow's repositories](https://github.com/kubenow) lives in the [KubeNow's main repo](https://github.com/kubenow/KubeNow).
+
+We'd love to get your questions and accept your patches! Thus before we can take them, please make sure to read our contributing guidelines [here](https://github.com/kubenow/KubeNow/blob/master/CONTRIBUTING.md).

PULL_REQUEST_TEMPLATE.md

@@ -1,39 +1,15 @@
-<!-- 
-Thanks for sending a Pull Request (PR)! Please use this template to facilitate the review/merge process. 
-
-WARNING!!! Make sure that the PR fullfills the review criteria before submitting:
-
-POSITIVES
-- Change has already been discussed and is known to committers (open an issue first otherwise)
-- Has a nice, self-explanatory title
-- Fixes the root cause of a bug in existing functionality
-- Adds functionality or fixes a problem needed by a large number of users
-- Simple, targeted
-- Easily tested; has tests
-- Reduces complexity and lines of code
-
-NEGATIVES
-- Makes lots of modifications in one "big bang" change
-- Band-aids a symptom of a bug only
-- Introduces complex new functionality
-- Adds complexity that only helps a niche use case
-- Adds user-space functionality that does not need to be maintained in KubeNow, but could be hosted externally 
-- Adds large dependencies
-- Changes versions of existing dependencies
-- Adds a large amount of code
--->
-
 ## Change content and motivation
 <!-- please describe briefly the content of this PR, and motivate why this changes are needed -->
 
-## GitHub cross-links 
+<!-- Please uncomment if applicable -->
+<!-- ## GitHub cross-links -->
 <!-- 
 please list the issues that are going to be fixed by this PR (if applicable). 
 Use the suggested format to facilitate issue closing. 
 -->
-**Fixes:** <!-- fixes #X, fixes #Y, ... fixes #Z -->
+<!-- Fixes #X, fixes #Y, ... fixes #Z -->
 <!-- 
 please add documentation for your feature (if applicable), and link the documentation changes. 
 Documentation PRs are to be sent to https://github.com/kubenow/docs.
 -->
-**Docs**: <!-- #X, #Y, ... #Z -->
+<!-- Docs: kubenow/docs#X, kubenow/docs#Y, ... kubenow/docs#Z -->

advanced_topics/cloudflare-dns.rst

@@ -0,0 +1,12 @@
+Cloudflare DNS Records
+======================
+`Cloudflare <https://www.cloudflare.com>`_ runs one of the largest authoritative DNS networks in the world. In order to resolve domain names for exposed services, KubeNow can optionally configure the Cloudflare dynamic DNS service, so that a base domain name will resolve to the edge nodes (or the master node if no edge node is deployed).
+
+To configure the Cloudflare dynamic DNS service, it is sufficient to uncomment the following lines in the ``config.tfvars`` file, specifying credentials, domain and subdomain::
+
+  # Cloudflare configuration (optional)
+  use_cloudflare = "true"
+  cloudflare_email = "your-cloudflare-email"
+  cloudflare_token = "your-cloudflare-token"
+  cloudflare_domain = "your-domain-name"
+  cloudflare_subdomain = "your-subdomain-name"

advanced_topics/cloudflare-proxied.rst

@@ -0,0 +1,9 @@
+Cloudflare: Proxied Traffic
+===========================
+Incoming container traffic can be optionally proxied through the `Cloudflare <https://www.cloudflare.com>`_ servers. When operating in this mode Cloudflare provides HTTPS for container services, and it protects against distributed denial of service, customer data breach and malicious bot abuse.
+
+To enable Cloudflare proxied traffic, it is sufficient to uncomment the following lines in the ``config.tfvars`` file, specifying DNS records to be proxied::
+
+  # Cloudflare proxy (optional)
+  cloudflare_proxied = "true"
+  cloudflare_record_texts = ["record1","record2",...] # Warn: wildcards are not supported when using proxied records

advanced_topics/edge-nodes.rst

@@ -0,0 +1,15 @@
+Edge Nodes
+==========
+Edge nodes are specialized service nodes with an associated public IP address, and they run `Traefik <https://traefik.io>`_ acting as reverse proxies, and load balancers, for the services that are exposed to the Internet. In the default settings, we don't deploy any edge node enabling the reverse proxy logic in the master node instead. However, in production settings we recommend to deploy one or more edge nodes to reduce the load in the master.
+
+To deploy edge nodes, it is sufficient to uncomment the following lines in the ``config.tfvars`` file, and to set the desired number of edge nodes, along with an available instance flavor::
+
+  # Master configuration (mandatory in general, above all for single-server setup)
+  master_flavor = "your-master-flavor"
+  master_as_edge = "false"
+
+  # Edge configuration
+  edge_count = "2"
+  edge_flavor = "your-edge-flavor"
+
+Please notice that we set ``master_as_edge = "false"`` to disable Traefik in the master node.

advanced_topics/glusterfs-nodes.rst

@@ -0,0 +1,10 @@
+GlusterFS Nodes
+===============
+GlusterFS nodes are specialized service nodes. They run only `GlusterFS <https://www.gluster.org>`_ and they are attached to a block storage volume to provide additional capacity. In the default settings, we don't deploy GlusterFS nodes, as it is not required in many use cases. However, GlusterFS can be particularly convenient when a distributed file system is needed for container synchronization.
+
+To deploy GlusterFS nodes, it is sufficient to uncomment the following lines in the ``config.tfvars`` file, and to set the desired number of edge nodes, along with an available instance flavor and block storage disk size::
+
+ # Gluster configuration
+ glusternode_count = "1"
+ glusternode_flavor = "your-glusternode-flavor"
+ glusternode_extra_disk_size = "200" # Size in GB

advanced_topics/single-node-deployments.rst

@@ -0,0 +1,22 @@
+Single-Node Deployments
+=======================
+When resources are scarce, or for testing purpose, KubeNow enables single-node deployments. In fact, it is possible to deploy the master node only, which will automatically enabled for service scheduling.
+
+You can achieve this by commenting all of the lines for the other instance types (i.e. edge node, gluster node and worker node) in the ``config.tfvars`` file, leaving the master node only as it is shown below::
+
+    # Master configuration (mandatory in general, above all for single-server setup)
+    master_flavor = "your-master-flavor"
+    master_as_edge = "true"
+
+    # Node configuration
+    # node_count = "3"
+    # node_flavor = "your-node-flavor"
+
+    # Edge configuration
+    # edge_count = "2"
+    # edge_flavor = "your-edge-flavor"
+
+    # Gluster configuration
+    # glusternode_count = "1"
+    # glusternode_flavor = "your-glusternode-flavor"
+    # glusternode_extra_disk_size = "200" # Size in GB

conf.py

@@ -33,6 +33,7 @@
 # ones.
 extensions = [
     'sphinx.ext.todo',
+    'sphinx.ext.ifconfig',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

getting_started/bootstrap.rst

@@ -157,7 +157,7 @@ Deploy KubeNow
 ~~~~~~~~~~~~~~
 Once you are done with your settings you are ready deploy your cluster running::
 
-  kn apply gce
+  kn apply
 
 The first time you are going to deploy it will take longer, since the KubeNow image needs to be imported. Future deployments will be considerably faster, since the image will be already present in your user space.
 
@@ -222,7 +222,7 @@ Deploy KubeNow
 ~~~~~~~~~~~~~~
 Once you are done with your settings you are ready deploy your cluster running::
 
-  kn apply aws
+  kn apply
 
 To check that your cluster is up and running you can run::
 
@@ -283,7 +283,7 @@ Deploy KubeNow
 ~~~~~~~~~~~~~~
 Once you are done with your settings you are ready deploy your cluster running::
 
-  kn apply azure
+  kn apply
 
 The first time you are going to deploy it will take longer, since the KubeNow image needs to be imported. Future deployments will be considerably faster, since the image will be already present in your user space.
 

getting_started/first-app.rst

@@ -31,9 +31,9 @@ Accessing the Traefik UI
 
 One simple and quick way to access the Traefik UI is to tunnel via SSH to one of the edge nodes with the following command::
 
-    ssh -N -f -L localhost:8080:localhost:8080 ubuntu@<your-domain>
+    ssh -N -f -L localhost:8081:localhost:8081 ubuntu@<your-domain>
 
-Using SSH tunnelling, the Traefik UI should be reachable at http://localhost:8080, and it should look something like this:
+Using SSH tunnelling, the Traefik UI should be reachable at http://localhost:8081, and it should look something like this:
 
 .. image:: ../img/traefik_UI_example.png
 

getting_started/prerequisites.rst

@@ -17,13 +17,14 @@ In order to get the provisioning tools please run:
 
 We wrote up a handy CLI that wraps around the Docker container above, you can install it with a one-liner:
 
-.. parsed-literal::
+.. ifconfig:: release == "master"
 
-  curl -Lo kn \https://raw.githubusercontent.com/kubenow/KubeNow/|release|/bin/kn && chmod +x kn && sudo mv kn /usr/local/bin/
- 
-By default ``kn`` uses the ``latest`` provisioner release, if you are planning to use another you need to set the ``KUBENOW_VERSION`` environment variable. For instance if you are planning to use the `master` version, you need to run:
+  .. parsed-literal::
 
-.. parsed-literal::
+    curl -Lo kn \https://raw.githubusercontent.com/kubenow/KubeNow/|release|/bin/kn && chmod +x kn && sudo mv kn /usr/local/bin/
+
+.. ifconfig:: release != "master"
+
+  .. parsed-literal::
 
-  export KUBENOW_VERSION="master"
- 
+    curl -Lo kn \https://github.com/kubenow/KubeNow/releases/download/|release|/kn && chmod +x kn && sudo mv kn /usr/local/bin/

index.rst

@@ -12,7 +12,7 @@ Welcome to KubeNow's documentation! This is a place where we aim to help you to
    getting_started/clean-up
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
   :caption: Troubleshooting
 
   troubleshoot/trouble-terraform
@@ -21,7 +21,17 @@ Welcome to KubeNow's documentation! This is a place where we aim to help you to
   troubleshoot/trouble-misc
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
+  :caption: Advanced Topics
+
+  advanced_topics/edge-nodes
+  advanced_topics/glusterfs-nodes
+  advanced_topics/single-node-deployments
+  advanced_topics/cloudflare-dns
+  advanced_topics/cloudflare-proxied
+
+.. toctree::
+  :maxdepth: 2
   :caption: Developers guide
 
   developers/build-img

troubleshoot/trouble-kubernetes.rst

@@ -13,7 +13,7 @@ List kubernetes pods
   kubectl get pods --all-namespaces
 
   # With Ansible from your local computer:
-  ansible master -a "kubectl get pods --all-namespaces"
+  kn ansible master -a "kubectl get pods --all-namespaces"
 
 Describe status of a specific pod
 ---------------------------------
@@ -24,7 +24,7 @@ Describe status of a specific pod
   kubectl describe pod <pod id> --all-namespaces
 
   # With Ansible from your local computer:
-  ansible master -a "kubectl describe pod <pod id> --all-namespaces"
+  kn ansible master -a "kubectl describe pod <pod id> --all-namespaces"
 
 Get the kubelet service log
 ---------------------------
@@ -35,4 +35,4 @@ Get the kubelet service log
   sudo journalctl -r -u kubelet
 
   #  With Ansible from your local computer:
-  ansible master -a "journalctl -r -u kubelet"
+  kn ansible master -a "journalctl -r -u kubelet"