github.com/projectcontour/contour@v1.28.2/site/content/posts/2019-07-11-kindly-running-contour.md (about)

     1  ---
     2  title: Kind-ly running Contour
     3  image: /img/posts/kind-contour.png
     4  excerpt: This blog post demonstrates how to install kind, create a cluster, deploy Contour, and then deploy a sample application, all locally on your machine.
     5  author_name: Steve Sloka
     6  author_avatar: /img/contributors/steve-sloka.png
     7  categories: [kubernetes]
     8  # Tag should match author to drive author pages
     9  tags: ['Contour Team', 'Steve Sloka', 'kind']
    10  date: 2019-07-11
    11  slug: kindly-running-contour
    12  ---
    13  
    14  [kind][1] is a tool for running local Kubernetes clusters using Docker container “nodes.” Primarily designed for testing Kubernetes 1.11 or later, kind is initially targeting the upstream Kubernetes conformance tests, which are run to verify if a cluster meets standard expectations. It is also an excellent tool for creating a Kubernetes cluster locally on many platforms (Linux, macOS, or Windows), especially since it can create multi-node clusters quickly and reliably.
    15  
    16  This blog post demonstrates how to install kind, create a cluster, deploy Contour, and deploy a sample application, all locally on your machine which enables running applications locally the same way they are deployed to production.  
    17  
    18  
    19  ![image](/img/posts/kind-contour.png)
    20   
    21  *Example of a four worker node cluster with a single control plane.*
    22  
    23  Here's a quick video demonstration of how to install kind, create a cluster, deploy Contour, and deploy a sample application.
    24  
    25  [![image](/img/posts/kind-contour-video.png)][4]
    26  
    27  ## Install Kind
    28  
    29  There are a number of ways to [install kind][5]. Here is a simple way to grab the latest release for a Darwin architecture. The following commands downloads the latest binary, makes it executable, and moves it to your local bin path.  
    30  
    31  Note: You may want to update some portions of the commands to match your local operating system and configuration.
    32  
    33  ```bash
    34  $ curl -Lo ./kind-darwin-amd64 https://github.com/kubernetes-sigs/kind/releases/download/v0.6.0/kind-darwin-amd64
    35  $ chmod +x ./kind-darwin-amd64
    36  $ sudo mv ./kind-darwin-amd64 /usr/local/bin/kind
    37  ```
    38  
    39  ## Create a Cluster
    40  
    41  Now that we have kind installed, let’s create a cluster. Running the command `kind create cluster` generates a single node cluster. This command is the simplest way of creating a cluster, but for this example, we want to pass an additional configuration to the cluster creation step to map Ports 80 on the Kubernetes worker node to Port 80 on the local Docker network.
    42  
    43  Save the following yaml to a file named `kind.config.yaml` and run the create cluster command:
    44  
    45  ```bash
    46  $ kind create cluster --config kind.config.yaml
    47  ```
    48  
    49  ```yaml
    50  # Save to 'kind.config.yaml'
    51  kind: Cluster
    52  apiVersion: kind.sigs.k8s.io/v1alpha3
    53  nodes:
    54  - role: control-plane
    55  - role: worker
    56    extraPortMappings:
    57    - containerPort: 80
    58      hostPort: 80
    59      listenAddress: "0.0.0.0"
    60    - containerPort: 443
    61      hostPort: 443
    62      listenAddress: "0.0.0.0"
    63  ```
    64  
    65  Note: You can only have a single worker with this configuration because you can’t map multiple Docker containers (i.e., worker nodes) to the same port on a single Docker instance.
    66  
    67  
    68  After the cluster comes up, you should have two nodes in the cluster, a worker node and a control plane node:
    69    
    70    
    71  ![image](/img/posts/kind-contour2.png)
    72  
    73  
    74  ## Deploy Contour
    75  
    76  Next, we’ll deploy Contour into our freshly created cluster. We are going to use a "split" deployment, which configures [Envoy][7] as a DaemonSet.
    77  
    78  Contour is the configuration server for Envoy --- Contour, that is, exposes an xDS API for Envoy. Contour watches the Kubernetes cluster for changes to services, end points, secrets, ingress, and HTTPProxies. Contour generates a set of configurations that is streamed to Envoy via the xDS gRPC connection. All data travels through Envoy, which is running on every node in the cluster (a single node in our example).
    79  
    80  Additionally, the Envoy DaemonSet will be configured to use `HostNetworking` to bind Envoy's ports directly to the worker node.
    81  
    82  Deploy contour:
    83  
    84  ```bash
    85  $ git clone https://github.com/projectcontour/contour.git
    86  $ kubectl apply -f contour/examples/contour
    87  ```
    88  
    89  Since our deployment of kind is binding ports 80 and 443 to our laptop, when we curl `localhost:80` or `localhost:443`, the request will arrive at the Envoy pod. But to enable Envoy to route these requests, we need to deploy some ingress resources, which we will do as part of deploying the sample application. 
    90  
    91  ## Deploy the Sample Application
    92  
    93  Finally, we’ll deploy a sample application to to verify the network ingress path is functional to an application. By deploying this way, we are matching how we would deploy an application in production within Kubernetes, so any testing done locally inside the `kind` cluster should match how the application will perform once deployed. Since we already cloned the Contour repo in the previous step, let’s deploy the [kuard][8] sample application, which is an example workload in the repo.
    94  
    95  Deploy the application:
    96  
    97  ```bash
    98  $ kubectl apply -f https://projectcontour.io/examples/kuard-httpproxy.yaml
    99  ```
   100  
   101  Now that the application is up and running, we need a way to route to it. The sample we just deployed uses `kuard.local` for the domain name.
   102  
   103  ```yaml
   104  apiVersion: projectcontour.io/v1
   105  kind: HTTPProxy
   106  metadata: 
   107    labels:
   108      app: kuard
   109    name: kuard
   110    namespace: default
   111  spec: 
   112    virtualhost:
   113      fqdn: kuard.local
   114    routes: 
   115      - conditions:
   116        - path: /
   117        services:
   118          - name: kuard
   119            port: 80
   120  ```
   121  
   122  Let’s create an entry in our local `/etc/hosts` to route `kuard.local` to `127.0.0.1` (i.e., Envoy running in kind).
   123  
   124  ```bash
   125  ##
   126  # Host Database
   127  #
   128  # localhost is used to configure the loopback interface
   129  # when the system is booting.  Do not change this entry.
   130  ##
   131  127.0.0.1          localhost
   132  255.255.255.255    broadcasthost
   133  ::1                localhost
   134  127.0.0.1          kuard.local   # <--- add this!
   135  ```
   136  
   137  Now open a browser and go to: `http://kuard.local`
   138  ![image](/img/posts/kind-contour3.png)
   139  
   140  What's happening is that the request to `http://kuard.local` is resolved to `127.0.0.1` via the entry the `/etc/hosts` file. That request is then sent to Envoy running on the single Kubernetes worker node in the `kind` cluster. Envoy is configured to send any request to `kuard.local/` to the `kuard` application in the cluster. The request then gets routed to an instance of `kuard` and the response is sent back to the user. 
   141  
   142  This blog post helps you enable Contour in your local development environment by allowing you to match the way you'd deploy your application in production. Any testing done locally inside the `kind` cluster should match how the application will perform once deployed reducing the time required testing in production. I hope this blog post better equip your usage of Contour!
   143  
   144  
   145  [1]: https://github.com/kubernetes-sigs/kind
   146  [4]: https://youtu.be/j97MueCYcvc
   147  [5]: https://github.com/kubernetes-sigs/kind#installation-and-usage
   148  [7]: https://envoyproxy.io
   149  [8]: https://github.com/kubernetes-up-and-running/kuard
   150  
   151