diff --git a/README.md b/README.md index 783543c..83cb9b5 100644 --- a/README.md +++ b/README.md @@ -40,3 +40,4 @@ Web API: * [Monitoring and alerting with Prometheus](docs/3-monitoring.md) * [StatefulSets with local persistent volumes](docs/4-statefulsets.md) * [Canary Deployments and A/B Testing](docs/5-canary.md) +* [Expose Kubernetes services over HTTPS with Ngrok](docs/6-ngrok.md) diff --git a/docs/6-ngrok.md b/docs/6-ngrok.md new file mode 100644 index 0000000..32463a9 --- /dev/null +++ b/docs/6-ngrok.md @@ -0,0 +1,120 @@ +# Expose Kubernetes services over HTTPS with Ngrok + +Have you ever wanted to expose a Kubernetes service running on Minikube on the internet and have a +temporary HTTPS address for it? If so then Ngrok is the perfect solution to do that without any +firewall, NAT or DNS configurations. +If you are developing an application that works with webhooks or oauth callbacks +Ngrok can create a tunnel between your Kubernetes service and their cloud platform and provide you with +a unique HTTPS URL that you can use to test and debug your service. + +For this purpose I've made a Helm chart that you can use to deploy Ngrok on Kubernetes by specifying +a ClusterIP service that will get exposed on the internet. + +What follows is a step-by-step guide on how you can use Ngrok as a reverse proxy to +receive GitHub notifications via webhooks in an application hosted on your local Minikube. + +### Deploy podinfo demo app + +In order to receive notifications from GitHub you need a web application that exposes a +HTTP POST endpoint and accepts a JSON payload. [Podinfo](https://github.com/stefanprodan/k8s-podinfo) +is tiny web app made with Go that can receive any kind of payload on the `/echo` route. +Let's deploy podinfo using Helm. + +If you don't have Helm running on your Kubernetes cluster here how you can set it up. + +First install Helm CLI: + +```bash +brew install kubernetes-helm +``` + +Create a service account for Tiller: + +```bash +kubectl -n kube-system create sa tiller +``` + +Create a cluster role binding for Tiller: + +```bash +kubectl create clusterrolebinding tiller-cluster-rule \ + --clusterrole=cluster-admin \ + --serviceaccount=kube-system:tiller +``` + +Deploy Tiller in kube-system namespace: + +```bash +helm init --skip-refresh --upgrade --service-account tiller +``` + +The podinfo and ngrok charts are hosted on GitHub. Add the k8s-podinfo repo: + +```bash +helm repo add sp https://stefanprodan.github.io/k8s-podinfo +``` + +Install podinfo: + +```bash +helm install sp/podinfo --name webhook +``` + +This will deploy `podinfo` in the default namespace and +will create a ClusterIP service with the address `webhook-podinfo:9898`. + +### Deploy Ngrok reverse proxy + +Before you begin go to [ngrok.com](https://ngrok.com) and register for a free account. + +Ngrok will create a token for you, use it when installing Ngrok chart. + +Install Ngrok: + +```bash +$ helm install sp/ngrok --name tunnel \ + --set token=NGROK-TOKEN \ + --set service.type=NodePort \ + --set expose.service=webhook-podinfo:9898 +``` + +The above command will deploy Ngrok and will expose the Ngrok web UI on a random node port. +Find the port with: + +```bash +kubectl get --namespace default -o jsonpath="{.spec.ports[0].nodePort}" services tunnel-ngrok +``` + +Now open a browser and navigate to `http://:/status`. On the status page you +should see the public HTTPS address generated by Ngrok. + +Use curl to test if you can reach podinfo `/echo` route: + +```bash +curl -d '{"message": "testing ngrok"}' https://122261e6.ngrok.io/echo +``` + +On the status page you should see that the total number of connections has increased. + +![Ngrok Status](screens/ngrok-status.png) + +### Setup GitHub webhook + +Go to GitHub and create a new repository or use one that you already have. +On your repo page go to _Settings -> Webhooks -> Add Webhook_ and enter the Ngrok HTTPS URL adding +`/echo` at the end: + +![GitHub Webhook](screens/github-webhook.png) + +For Content-type select _application/json_, check _Send me everything_ and click on _Add webhook_. + +Once you hit the add button GitHub will make a call to the `/echo` URL. Using Ngrok web UI you can +inspect the GitHub payload. Navigate to `http://:/inspect/http` and you +should see the request body: + +![Ngrok Inspect](screens/ngrok-inspect.png) + +Ngrok not only make it very easy to expose Kubernetes services on the internet +but also gives a powerful tool to inspect the traffic to your applications. + + diff --git a/docs/index.md b/docs/index.md index 810cf42..6b07e65 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,3 +10,4 @@ that showcases best practices of running microservices in Kubernetes. * [Monitoring and alerting with Prometheus](3-monitoring.md) * [StatefulSets with local persistent volumes](4-statefulsets.md) * [Canary Deployments and A/B Testing](5-canary.md) +* [Expose Kubernetes services over HTTPS with Ngrok](6-ngrok.md) diff --git a/docs/screens/github-webhook.png b/docs/screens/github-webhook.png new file mode 100644 index 0000000..91b1033 Binary files /dev/null and b/docs/screens/github-webhook.png differ diff --git a/docs/screens/ngrok-inspect.png b/docs/screens/ngrok-inspect.png new file mode 100644 index 0000000..6385cc0 Binary files /dev/null and b/docs/screens/ngrok-inspect.png differ diff --git a/docs/screens/ngrok-status.png b/docs/screens/ngrok-status.png new file mode 100644 index 0000000..b428301 Binary files /dev/null and b/docs/screens/ngrok-status.png differ