Consul on Minikube guide (#4949)

* Adds images for Minikube guide
* Adds notes about Helm YAML configuration
* Embed Wistia video for Consul Minikube guide
* Cleans up menus, instructions, Helm steps
* Adds captions for all images
* Uses Docker images hosted on hashicorp org for demo
* Adds link to Minikube guide from menu and k8s index page
* Clarify steps in Minikube/Kubernetes guide

website/source/docs/guides/minikube.md

@@ -0,0 +1,261 @@
+---
+layout: "docs"
+page_title: "Minikube"
+sidebar_current: "docs-guides-minikube"
+description: |-
+  Consul can be installed to the Kubernetes minikube tool for local development.
+---
+
+# Consul Installation to Minikube via Helm
+
+<script src="https://fast.wistia.com/embed/medias/qwhi1gvkeq.jsonp" async></script><script src="https://fast.wistia.com/assets/external/E-v1.js" async></script><div class="wistia_responsive_padding" style="padding:56.25% 0 0 0;position:relative;"><div class="wistia_responsive_wrapper" style="height:100%;left:0;position:absolute;top:0;width:100%;"><div class="wistia_embed wistia_async_qwhi1gvkeq videoFoam=true" style="height:100%;position:relative;width:100%"><div class="wistia_swatch" style="height:100%;left:0;opacity:0;overflow:hidden;position:absolute;top:0;transition:opacity 200ms;width:100%;"><img src="https://fast.wistia.com/embed/medias/qwhi1gvkeq/swatch" style="filter:blur(5px);height:100%;object-fit:contain;width:100%;" alt="" onload="this.parentNode.style.opacity=1;" /></div></div></div></div>
+
+In this guide, you'll start a local Kubernetes cluster with minikube. You'll install Consul with only a few commands, then deploy two custom services that use Consul to discover each other over encrypted TLS via Consul Connect. Finally, you'll tighten down Consul Connect so that only the approved applications can communicate with each other.
+
+[Demo code](https://github.com/hashicorp/demo-consul-101) is available.
+
+- [Task 1: Start Minikube and Install Consul with Helm](#task-1-start-minikube-and-install-consul-with-helm)
+- [Task 2: Deploy a Consul Aware Application to the Cluster](#task-2-deploy-a-consul-aware-application-to-the-cluster)
+- [Task 3: Configure Consul Connect](#task-3-use-consul-connect)
+
+## Prerequisites
+
+Let's install Consul on Kubernetes with minikube. This is a relatively quick and easy way to try out Consul on your local machine without the need for any cloud credentials. You'll be able to use most Consul features right away.
+
+First, you'll need to follow the directions for [installing minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/), including VirtualBox or similar.
+
+You'll also need to install `kubectl` and `helm`.
+
+Mac users can install `helm` and `kubectl` with Homebrew.
+
+```sh
+$ brew install kubernetes-cli
+$ brew install kubernetes-helm
+```
+
+Windows users can use Chocolatey with the same package names:
+
+```sh
+$ choco install kubernetes-cli
+$ choco install kubernetes-helm
+```
+
+For more on Helm, see [helm.sh](https://helm.sh/).
+
+## Task 1: Start Minikube and Install Consul with Helm
+
+### Step 1: Start Minikube
+
+Start minikube. You can use the `--memory` option with the equivalent of 4GB to 8GB so there is plenty of memory for all the pods we will run. This may take several minutes. It will download a 100-300MB of dependencies and container images.
+
+```
+$ minikube start --memory 4096
+```
+
+Next, let's view the local Kubernetes dashboard with `minikube dashboard`. Even if the previous step completed successfully, you may have to wait a minute or two for minikube to be available. If you see an error, try again after a few minutes.
+
+Once it spins up, you'll see the dashboard in your web browser. You can view pods, nodes, and other resources.
+
+```
+$ minikube dashboard
+```
+
+![Minikube Dashboard](/assets/images/guides/minikube-dashboard.png "Minikube Dashboard")
+
+### Step 2: Install the Consul Helm Chart to the Cluster
+
+To perform the steps in this lab exercise, clone the [hashicorp/demo-consul-101](https://github.com/hashicorp/demo-consul-101) repository from GitHub. Go into the `demo-consul-101/k8s` directory.
+
+
+```
+$ git clone https://github.com/hashicorp/demo-consul-101.git
+
+$ cd demo-consul-101/k8s
+```
+
+Now we're ready to install Consul to the cluster, using the `helm` tool. Initialize Helm with `helm init`. You'll see a note that Tiller (the server-side component) has been installed. You can ignore the policy warning.
+
+```
+$ helm init
+
+$HELM_HOME has been configured at /Users/geoffrey/.helm.
+```
+
+Now we need to install Consul with Helm. To get the freshest copy of the Helm chart, clone the [hashicorp/consul-helm](https://github.com/hashicorp/consul-helm) repository.
+
+```
+$ git clone https://github.com/hashicorp/consul-helm.git
+```
+
+The chart works on its own, but we'll override a few values to help things go more smoothly with minikube and to enable useful features.
+
+We've created `helm-consul-values.yaml` for you with overrides. See `values.yaml` in the Helm chart repository for other possible values.
+
+We've given a name to the datacenter running this Consul cluster. We've enabled the Consul web UI via a `NodePort`. When deploying to a hosted cloud that implements load balancers, we could use `LoadBalancer` instead. We'll enable secure communication between pods with Connect. We also need to enable `grpc` on the client for Connect to work properly. Finally, specify that this Consul cluster should only run one server (suitable for local development).
+
+```yaml
+# Choose an optional name for the datacenter
+global:
+  datacenter: minidc
+
+# Enable the Consul Web UI via a NodePort
+ui:
+  service:
+    type: "NodePort"
+
+# Enable Connect for secure communication between nodes
+connectInject:
+  enabled: true
+
+client:
+  enabled: true
+  grpc: true
+
+# Use only one Consul server for local development
+server:
+  replicas: 1
+  bootstrapExpect: 1
+  disruptionBudget:
+    enabled: true
+    maxUnavailable: 0
+```
+
+Now, run `helm install` together with our overrides file and the cloned `consul-helm` chart. It will print a list of all the resources that were created.
+
+```
+$ helm install -f helm-consul-values.yaml --name hedgehog ./consul-helm
+```
+
+~> NOTE: If no `--name` is provided, the chart will create a random name for the installation. To reduce confusion, consider specifying a `--name`.
+
+## Task 2: Deploy a Consul-aware Application to the Cluster
+
+### Step 1: View the Consul Web UI
+
+Verify the installation by going back to the Kubernetes dashboard in your web browser. Find the list of services. Several include `consul` in the name and have the `app: consul` label.
+
+![Minikube Dashboard with Consul](/assets/images/guides/minikube-dashboard-consul.png "Minikube Dashboard with Consul")
+
+There are a few differences between running Kubernetes on a hosted cloud vs locally with minikube. You may find that any load balancer resources don't work as expected on a local cluster. But we can still view the Consul UI and other deployed resources.
+
+Run `minikube service list` to see your services. Find the one with `consul-ui` in the name.
+
+```
+$ minikube service list
+```
+
+Run `minikube service` with the `consul-ui` service name as the argument. It will open the service in your web browser.
+
+```
+$ minikube service hedgehog-consul-ui
+```
+
+You can now view the Consul web UI with a list of Consul's services, nodes, and other resources.
+
+![Minikube Consul UI](/assets/images/guides/minikube-consul-ui.png "Minikube Consul UI")
+
+### Step 2: Deploy Custom Applications
+
+Now let's deploy our application. It's two services: a backend data service that returns a number (`counting` service) and a front-end `dashboard` that pulls from the `counting` service over HTTP and displays the number. The kubernetes part is a single line: `kubectl create -f 04-yaml-connect-envoy`. This is a directory with several YAML files, each defining one or more resources (pods, containers, etc).
+
+```
+$ kubectl create -f 04-yaml-connect-envoy
+```
+
+The output shows that they have been created. In reality, they may take a few seconds to spin up. Refresh the Kubernetes dashboard a few times and you'll see that the `counting` and `dashboard` services are running. You can also click a resource to view more data about it.
+
+![Services](/assets/images/guides/minikube-services.png "Services")
+
+### Step 3: View the Web Application
+
+For the last step in this initial task, use the Kubernetes `port-forward` feature for the dashboard service running on port `9002`. We already know that the pod is named `dashboard` thanks to the metadata specified in the YAML we deployed.
+
+```
+$ kubectl port-forward dashboard 9002:9002
+```
+
+Visit http://localhost:9002 in your web browser. You'll see a running `dashboard` container in the kubernetes cluster that displays a number retrieved from the `counting` service using Consul service discovery and secured over the network by TLS via an Envoy proxy.
+
+![Application Dashboard](/assets/images/guides/minikube-app-dashboard.png "Application Dashboard")
+
+### Addendum: Review the Code
+
+Let's take a peek at the code. Relevant to this Kubernetes deployment are two YAML files in the `04` directory. The `counting` service defines an `annotation` in the `metadata` section that instructs Consul to spin up a Consul Connect proxy for this service: `connect-inject`. The relevant port number is found in the `containerPort` section (`9001`). This Pod registers a Consul service that will be available via a secure proxy.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: counting
+  annotations:
+    "consul.hashicorp.com/connect-inject": "true"
+spec:
+  containers:
+  - name: counting
+    image: hashicorp/counting-service:0.0.2
+    ports:
+    - containerPort: 9001
+      name: http
+# ...
+```
+
+The other side is on the `dashboard` service. This declares the same `connect-inject` annotation but also adds another. The `connect-service-upstreams` in the `annotations` section configures Connect such that this Pod will have access to the `counting` service on `localhost` port `9001`. All the rest of the configuration and communication is taken care of by Consul and the Consul Helm chart.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: dashboard
+  labels:
+    app: "dashboard"
+  annotations:
+    "consul.hashicorp.com/connect-inject": "true"
+    "consul.hashicorp.com/connect-service-upstreams": "counting:9001"
+spec:
+  containers:
+  - name: dashboard
+    image: hashicorp/dashboard-service:0.0.3
+    ports:
+    - containerPort: 9002
+      name: http
+    env:
+    - name: COUNTING_SERVICE_URL
+      value: "http://localhost:9001"
+# ...
+```
+
+Within our `dashboard` application, we can access the `counting` service by communicating with `localhost:9001` as seen on the last line of this snippet. Here we are looking at an environment variable that is specific to the Go application running in a container in this Pod. Instead of providing an IP address or even a Consul service URL, we tell the application to talk to `localhost:9001` where our local end of the proxy is ready and listening. Because of the annotation to `counting:9001` earlier, we know that an instance of the `counting` service is on the other end.
+
+This is what is happening in the cluster and over the network when we view the `dashboard` service in the browser.
+
+-> TIP: The full source code for the Go-based web services and all code needed to build the Docker images are available in the [repo](https://github.com/hashicorp/demo-consul-101).
+
+## Task 3: Use Consul Connect
+
+### Step 1: Create an Intention that Denies All Service Communication by Default
+
+For a final task, let's take this a step further by restricting service communication with intentions. We don't want any service to be able to communicate with any other service; only the ones we specify.
+
+Begin by navigating to the _Intentions_ screen in the Consul web UI. Click the "Create" button and define an initial intention that blocks all communication between any services by default. Choose `*` as the source and `*` as the destination. Choose the _Deny_ radio button and add an optional description. Click "Save."
+
+![Connect Deny](/assets/images/guides/minikube-connect-deny.png "Connect Deny")
+
+Verify this by returning to the application dashboard where you will see that the "Counting Service is Unreachable."
+
+![Application is Unreachable](/assets/images/guides/minikube-connect-unreachable.png "Application is Unreachable")
+
+### Step 2: Allow the Application Dashboard to Connect to the Counting Service
+
+Finally, the easy part. Click the "Create" button again and create an intention that allows the `dashboard` source service to talk to the `counting` destination service. Ensure that the "Allow" radio button is selected. Optionally add a description. Click "Save."
+
+![Allow](/assets/images/guides/minikube-connect-allow.png "Allow")
+
+This action does not require a reboot. It takes effect so quickly that by the time you visit the application dashboard, you'll see that it's successfully communicating with the backend `counting` service again.
+
+And there we have Consul running on a Kubernetes cluster, as demonstrated by two services which communicate with each other via Consul Connect and an Envoy proxy.
+
+![Success](/assets/images/guides/minikube-connect-success.png "Success")
+
+## Reference
+
+For more on Consul's integration with Kubernetes (including multi-cloud, service sync, and other features), see the [Consul with Kubernetes](/docs/platform/k8s/index.html) documentation.

website/source/docs/platform/k8s/index.html.md

@@ -13,6 +13,8 @@ to Kubernetes using the Helm chart, sync services between Consul and
 Kubernetes, automatically secure Pod communication with Connect, and more.
 This section documents the official integrations between Consul and Kubernetes.
 
+-> A step-by-step beginner tutorial and accompanying video can be found at the [Minikube with Consul guide](/docs/guides/minikube.html)
+
 ## Use Cases
 
 **Running a Consul server cluster:** The Consul server cluster can run directly

website/source/layouts/docs.erb

@@ -429,6 +429,9 @@
           <li<%= sidebar_current("docs-guides-leader") %>>
             <a href="/docs/guides/leader-election.html">Leader Election</a>
           </li>
+          <li<%= sidebar_current("docs-guides-minikube") %>>
+            <a href="/docs/guides/minikube.html">Minikube with Consul</a>
+          </li>
           <li<%= sidebar_current("docs-guides-monitoring-telegraf") %>>
             <a href="/docs/guides/monitoring-telegraf.html">Monitoring Consul with Telegraf</a>
           </li>