From 9a91ff76cc3f9adb101455be85df839c7d2e2ee6 Mon Sep 17 00:00:00 2001 From: Ian Luo Date: Tue, 20 Apr 2021 14:09:11 +0800 Subject: [PATCH] revise according to the review comments --- .../debugging/_index.md | 8 ++--- .../debugging/debug-k8s/_index.md | 2 +- .../debug-k8s/debug-dapr-services.md | 28 +++++++++++------- .../debugging/debug-k8s/debug-daprd.md | 29 +++++++++---------- 4 files changed, 36 insertions(+), 31 deletions(-) diff --git a/daprdocs/content/en/developing-applications/debugging/_index.md b/daprdocs/content/en/developing-applications/debugging/_index.md index a8b68ee44..d6d77e77d 100644 --- a/daprdocs/content/en/developing-applications/debugging/_index.md +++ b/daprdocs/content/en/developing-applications/debugging/_index.md @@ -1,7 +1,7 @@ --- type: docs -title: "Debug" -linkTitle: "Debug" -weight: 50 -description: "How to debug Dapr application and Dapr itself" +title: "Debugging Dapr applications and the Dapr control plane" +linkTitle: "Debugging" +weight: 60 +description: "Guides on how to debug Dapr applications and the Dapr control plane" --- \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/debugging/debug-k8s/_index.md b/daprdocs/content/en/developing-applications/debugging/debug-k8s/_index.md index aef6df1f1..896b4fab6 100644 --- a/daprdocs/content/en/developing-applications/debugging/debug-k8s/_index.md +++ b/daprdocs/content/en/developing-applications/debugging/debug-k8s/_index.md @@ -2,6 +2,6 @@ type: docs title: "Debug Dapr in Kubernetes mode" linkTitle: "Kubernetes" -weight: 2000 +weight: 200 description: "How to debug Dapr on your Kubernetes cluster" --- diff --git a/daprdocs/content/en/developing-applications/debugging/debug-k8s/debug-dapr-services.md b/daprdocs/content/en/developing-applications/debugging/debug-k8s/debug-dapr-services.md index 531231478..17f71eab5 100644 --- a/daprdocs/content/en/developing-applications/debugging/debug-k8s/debug-dapr-services.md +++ b/daprdocs/content/en/developing-applications/debugging/debug-k8s/debug-dapr-services.md @@ -1,24 +1,28 @@ --- type: docs -title: "Debug Dapr services on Kubernetes" -linkTitle: "Dapr services" -weight: 10000 -description: "How to debug Dapr services on your Kubernetes cluster" +title: "Debug Dapr control plane on Kubernetes" +linkTitle: "Dapr control plane" +weight: 1000 +description: "How to debug Dapr control plane on your Kubernetes cluster" --- ## Overview -Sometimes it is necessary to understand what's going on in Dapr Kubernetes services, including `dapr-sidecar-injector`, `dapr-operator`, `dapr-placement`, and `dapr-sentry`, especially when you diagnose your Dapr application and wonder if there's something gets wrong in Dapr itself, or when you contribute to Dapr relevant to Kubernetes support. +Sometimes it is necessary to understand what's going on in Dapr control plane (aka, Kubernetes services), including `dapr-sidecar-injector`, `dapr-operator`, `dapr-placement`, and `dapr-sentry`, especially when you diagnose your Dapr application and wonder if there's something wrong in Dapr itself. Additionally, you may be developing a new feature for Dapr on Kubernetes and want to debug your code. -If this is the case, Dapr has built-in Kubernetes debug support coming in to rescue. +This guide will cover how to use Dapr debugging binaries to debug the Dapr services on your Kubernetes cluster. -## Debug Dapr Kubernetes services +## Debugging Dapr Kubernetes services -Before read on, pls. refer [this guide]({{< ref kubernetes-deploy.md >}}) to learn how to deploy Dapr to your Kubernetes cluster. +### Pre-requisites + +- Familiarize yourself with [this guide]({{< ref kubernetes-deploy.md >}}) to learn how to deploy Dapr to your Kubernetes cluster. +- Setup your [dev environment](https://github.com/dapr/dapr/blob/master/docs/development/developing-dapr.md) +- [Helm](https://github.com/helm/helm/releases) ### 1. Build Dapr debugging binaries -In order to debug Dapr Kubernetes services, it's required to rebuild all Dapr binaries and Docker images to disable compiler optimization. To do this, pls. execute the following commands: +In order to debug Dapr Kubernetes services, it's required to rebuild all Dapr binaries and Docker images to disable compiler optimization. To do this, execute the following commands: ```bash git clone https://github.com/dapr/dapr.git @@ -26,6 +30,8 @@ cd dapr make release GOOS=linux GOARCH=amd64 DEBUG=1 ``` +>On Windows download [MingGW](https://sourceforge.net/projects/mingw/files/MinGW/Extension/make/mingw32-make-3.80-3/) and use `ming32-make.exe` instead of `make`. + In the above command, 'DEBUG' is specified to '1' to disable compiler optimization. 'GOOS=linux' and 'GOARCH=amd64' are also necessary since the binaries will be packaged into Linux-based Docker image in the next step. The binaries could be found under 'dist/linux_amd64/debug' sub-directory under the 'dapr' directory. @@ -51,7 +57,7 @@ If Dapr has already been installed in your Kubernetes cluster, uninstall it firs dapr uninstall -k ``` -We will use 'helm' to install Dapr debugging binaries. For more information pls. check [Install with Helm]({{< ref "kubernetes-deploy.md#install-with-helm-advanced" >}}). In the following sections, we will use Dapr operator as an example to demonstrate how to configure, install, and debug Dapr services in a Kubernetes environment. +We will use 'helm' to install Dapr debugging binaries. In the following sections, we will use Dapr operator as an example to demonstrate how to configure, install, and debug Dapr services in a Kubernetes environment. First configure a values file with these options: @@ -99,7 +105,7 @@ Forwarding from 127.0.0.1:40000 -> 40000 Forwarding from [::1]:40000 -> 40000 ``` -All done. Now you can point to port 40000 and start remote debug session from your favorite IDE. +All done. Now you can point to port 40000 and start a remote debug session from your favorite IDE. ## Related links diff --git a/daprdocs/content/en/developing-applications/debugging/debug-k8s/debug-daprd.md b/daprdocs/content/en/developing-applications/debugging/debug-k8s/debug-daprd.md index 10c11b1a3..b1b2806ff 100644 --- a/daprdocs/content/en/developing-applications/debugging/debug-k8s/debug-daprd.md +++ b/daprdocs/content/en/developing-applications/debugging/debug-k8s/debug-daprd.md @@ -2,34 +2,33 @@ type: docs title: "Debug daprd on Kubernetes" linkTitle: "Dapr sidecar" -weight: 20000 -description: "How to debug Dapr sidecar (daprd) on your Kubernetes cluster" +weight: 2000 +description: "How to debug the Dapr sidecar (daprd) on your Kubernetes cluster" --- ## Overview -Sometimes it is necessary to understand what's going on in Dapr sidecar (daprd) side by side to your application, especially when you diagnose your Dapr application and wonder if there's something gets wrong in Dapr sidecar itself, or when you contribute to Dapr relevant to Kubernetes support. +Sometimes it is necessary to understand what's going on in the Dapr sidecar (daprd), which runs as a sidecar next to your application, especially when you diagnose your Dapr application and wonder if there's something wrong in Dapr itself. Additionally, you may be developing a new feature for Dapr on Kubernetes and want to debug your code. -If this is the case, Dapr has built-in Kubernetes debug support coming in to rescue. +his guide will cover how to use built-in Dapr debugging to debug the Dapr sidecar in your Kubernetes pods. -## Build Dapr sidecar on Kubernetes +## Pre-requisites -Before read on, pls. refer [this guide]({{< ref kubernetes-deploy.md >}}) to learn how to deploy Dapr to your Kubernetes cluster. +- Refer to [this guide]({{< ref kubernetes-deploy.md >}}) to learn how to deploy Dapr to your Kubernetes cluster. +- Follow [this guide]({{< ref "debug-dapr-services.md">}}) to build the Dapr debugging binaries you will be deploying in the next step. -In order to debug Dapr Kubernetes services, it's required to rebuild and reinstall all Dapr binaries, pls. follow the instructions in [Debug Dapr services]({{< ref "debug-dapr-services.md">}}) to build and install Dapr into debug mode. -## Install daprd in debug mode +## Initialize Dapr in debug mode If Dapr has already been installed in your Kubernetes cluster, uninstall it first: ```bash dapr uninstall -k ``` +We will use 'helm' to install Dapr debugging binaries. For more information refer to [Install with Helm]({{< ref "kubernetes-deploy.md#install-with-helm-advanced" >}}). -We will use 'helm' to install Dapr debugging binaries. For more information pls. check [Install with Helm]({{< ref "kubernetes-deploy.md#install-with-helm-advanced" >}}). - -First configure a values file with these options: +First configure a values file named `values.yml` with these options: ```yaml global: @@ -37,13 +36,13 @@ global: tag: "dev-linux-amd64" ``` -Then step into 'dapr' directory which's cloned from GitHub in the beginning of this guide if you haven't, and execute the following command: +Then step into 'dapr' directory from your cloned [dapr/dapr repository](https://github.com/dapr/dapr) and execute the following command: ```bash helm install dapr charts/dapr --namespace dapr-system --values values.yml --wait ``` -To enable debug mode for daprd, you need to put extra annotations `dapr.io/enable-debug` in your application's deployment file. Let's use [quickstarts/hello-kubernetes](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes) as an example, modify 'deploy/node.yaml' like below: +To enable debug mode for daprd, you need to put an extra annotation `dapr.io/enable-debug` in your application's deployment file. Let's use [quickstarts/hello-kubernetes](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes) as an example. Modify 'deploy/node.yaml' like below: ```diff diff --git a/hello-kubernetes/deploy/node.yaml b/hello-kubernetes/deploy/node.yaml @@ -62,7 +61,7 @@ index 23185a6..6cdb0ae 100644 The annotation `dapr.io/enable-debug` will hint Dapr injector to inject Dapr sidecar into the debug mode. You can also specify the debug port with annotation `dapr.io/debug-port`, otherwise the default port will be "40000". -Deploy the application with the following command. For the complete guide, pls. refer to [Dapr Kubernetes Quickstart](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes): +Deploy the application with the following command. For the complete guide refer to the [Dapr Kubernetes Quickstart](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes): ```bash kubectl apply -f ./deploy/node.yaml @@ -86,7 +85,7 @@ Forwarding from 127.0.0.1:40000 -> 40000 Forwarding from [::1]:40000 -> 40000 ``` -All done. Now you can point to port 40000 and start remote debug session to daprd from your favorite IDE. +All done. Now you can point to port 40000 and start a remote debug session to daprd from your favorite IDE. ## Related links