Skip to content

Commit b7d39b5

Browse files
reggie-ktodaywasawesomenitishfy
authored
docs: Improve developer guide cherry-pick (#23916)
Signed-off-by: reggie-k <[email protected]> Signed-off-by: Regina Voloshin <[email protected]> Co-authored-by: Dan Garfield <[email protected]> Co-authored-by: Nitish Kumar <[email protected]>
1 parent 9f18ff1 commit b7d39b5

12 files changed

+781
-581
lines changed

‎docs/developer-guide/contributors-quickstart.md

Lines changed: 0 additions & 214 deletions
This file was deleted.

‎docs/developer-guide/debugging-locally.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Debugging a local Argo CD instance
2+
3+
## Prerequisites
4+
1. [Development Environment](development-environment.md)
5+
2. [Toolchain Guide](toolchain-guide.md)
6+
3. [Development Cycle](development-cycle.md)
7+
4. [Running Locally](running-locally.md)
8+
9+
## Preface
10+
Please make sure you are familiar with running Argo CD locally using the [local toolchain](running-locally.md#start-local-services-local-toolchain).
11+
12+
When running Argo CD locally for manual tests, the quickest way to do so is to run all the Argo CD components together, as described in [Running Locally](running-locally.md),
13+
14+
However, when you need to debug a single Argo CD component (for example, `api-server`, `repo-server`, etc), you will need to run this component separately in your IDE, using your IDE launch and debug configuration, while the other components will be running as described previously, using the local toolchain.
15+
16+
For the next steps, we will use Argo CD `api-server` as an example of running a component in an IDE.
17+
18+
## Configure your IDE
19+
20+
### Locate your component configuration in `Procfile`
21+
The `Procfile` is used by Goreman when running Argo CD locally with the local toolchain. The file is located in the top-level directory in your cloned Argo CD repo folder, you can view it's latest version [here](https://github.com/argoproj/argo-cd/blob/master/Procfile). It contains all the needed component run configuration, and you will need to copy parts of this configuration to your IDE.
22+
23+
Example for `api-server` configuration in `Procfile`:
24+
``` text
25+
api-server: [ "$BIN_MODE" = 'true' ] && COMMAND=./dist/argocd || COMMAND='go run ./cmd/main.go' && sh -c "GOCOVERDIR=${ARGOCD_COVERAGE_DIR:-/tmp/coverage/api-server} FORCE_LOG_COLORS=1 ARGOCD_FAKE_IN_CLUSTER=true ARGOCD_TLS_DATA_PATH=${ARGOCD_TLS_DATA_PATH:-/tmp/argocd-local/tls} ARGOCD_SSH_DATA_PATH=${ARGOCD_SSH_DATA_PATH:-/tmp/argocd-local/ssh} ARGOCD_BINARY_NAME=argocd-server $COMMAND --loglevel debug --redis localhost:${ARGOCD_E2E_REDIS_PORT:-6379} --disable-auth=${ARGOCD_E2E_DISABLE_AUTH:-'true'} --insecure --dex-server http://localhost:${ARGOCD_E2E_DEX_PORT:-5556} --repo-server localhost:${ARGOCD_E2E_REPOSERVER_PORT:-8081} --port ${ARGOCD_E2E_APISERVER_PORT:-8080} --otlp-address=${ARGOCD_OTLP_ADDRESS} --application-namespaces=${ARGOCD_APPLICATION_NAMESPACES:-''} --hydrator-enabled=${ARGOCD_HYDRATOR_ENABLED:='false'}"
26+
```
27+
This configuration example will be used as the basis for the next steps.
28+
29+
!!! note
30+
The Procfile for a component may change with time. Please go through the Procfile and make sure you use the latest configuration for debugging.
31+
32+
### Configure component env variables
33+
The component that you will run in your IDE for debugging (`api-server` in our case) will need env variables. Copy the env variables from `Procfile`, located in the `argo-cd` root folder of your development branch. The env variables are located before the `$COMMAND` section in the `sh -c` section of the component run command.
34+
You can keep them in `.env` file and then have the IDE launch configuration point to that file. Obviously, you can adjust the env variables to your needs when debugging a specific configuration.
35+
36+
Example for an `api-server.env` file:
37+
``` bash
38+
ARGOCD_BINARY_NAME=argocd-server
39+
ARGOCD_FAKE_IN_CLUSTER=true
40+
ARGOCD_GNUPGHOME=/tmp/argocd-local/gpg/keys
41+
ARGOCD_GPG_DATA_PATH=/tmp/argocd-local/gpg/source
42+
ARGOCD_GPG_ENABLED=false
43+
ARGOCD_LOG_FORMAT_ENABLE_FULL_TIMESTAMP=1
44+
ARGOCD_SSH_DATA_PATH=/tmp/argocd-local/ssh
45+
ARGOCD_TLS_DATA_PATH=/tmp/argocd-local/tls
46+
ARGOCD_TRACING_ENABLED=1
47+
FORCE_LOG_COLORS=1
48+
KUBECONFIG=/Users/<YOUR_USERNAME>/.kube/config # Must be an absolute full path
49+
...
50+
# and so on, for example: when you test the app-in-any-namespace feature,
51+
# you'll need to add ARGOCD_APPLICATION_NAMESPACES to this list
52+
# only for testing this functionality and remove it afterwards.
53+
```
54+
55+
### Install DotENV / EnvFile plugin
56+
Using the market place / plugin manager of your IDE. The below example configurations require the plugin to be installed.
57+
58+
59+
### Configure component IDE launch configuration
60+
#### VSCode example
61+
Next, you will need to create a launch configuration, with the relevant args. Copy the args from `Procfile`, located in the `argo-cd` root folder of your development branch. The args are located after the `$COMMAND` section in the `sh -c` section of the component run command.
62+
Example for an `api-server` launch configuration, based on our above example for `api-server` configuration in `Procfile`:
63+
``` json
64+
{
65+
"name": "api-server",
66+
"type": "go",
67+
"request": "launch",
68+
"mode": "auto",
69+
"program": "YOUR_CLONED_ARGO_CD_REPO_PATH/argo-cd/cmd",
70+
"args": [
71+
"--loglevel",
72+
"debug",
73+
"--redis",
74+
"localhost:6379",
75+
"--repo-server",
76+
"localhost:8081",
77+
"--dex-server",
78+
"http://localhost:5556",
79+
"--port",
80+
"8080",
81+
"--insecure"
82+
],
83+
"envFile": "YOUR_ENV_FILES_PATH/api-server.env", # Assuming you installed DotENV plugin
84+
}
85+
```
86+
87+
#### Goland example
88+
Next, you will need to create a launch configuration, with the relevant parameters. Copy the parameters from `Procfile`, located in the `argo-cd` root folder of your development branch. The parameters are located after the `$COMMAND` section in the `sh -c` section of the component run command.
89+
Example for an `api-server` launch configuration snippet, based on our above example for `api-server` configuration in `Procfile`:
90+
``` xml
91+
<component name="ProjectRunConfigurationManager">
92+
<configuration default="false" name="api-server" type="GoApplicationRunConfiguration" factoryName="Go Application">
93+
<module name="argo-cd" />
94+
<working_directory value="$PROJECT_DIR$" />
95+
<parameters value="--loglevel debug --redis localhost:6379 --insecure --dex-server http://localhost:5556 --repo-server localhost:8081 --port 8080" />
96+
<EXTENSION ID="net.ashald.envfile"> <!-- Assuming you installed the EnvFile plugin-->
97+
<option name="IS_ENABLED" value="true" />
98+
<option name="IS_SUBST" value="false" />
99+
<option name="IS_PATH_MACRO_SUPPORTED" value="false" />
100+
<option name="IS_IGNORE_MISSING_FILES" value="false" />
101+
<option name="IS_ENABLE_EXPERIMENTAL_INTEGRATIONS" value="false" />
102+
<ENTRIES>
103+
<ENTRY IS_ENABLED="true" PARSER="runconfig" IS_EXECUTABLE="false" />
104+
<ENTRY IS_ENABLED="true" PARSER="env" IS_EXECUTABLE="false" PATH="<YOUR_ENV_FILES_PATH>/api-server.env" />
105+
</ENTRIES>
106+
</EXTENSION>
107+
<kind value="DIRECTORY" />
108+
<directory value="$PROJECT_DIR$/cmd" />
109+
<filePath value="$PROJECT_DIR$" />
110+
<method v="2" />
111+
</configuration>
112+
</component>
113+
```
114+
115+
!!! note
116+
As an alternative to importing the above file to Goland, you can create a Run/Debug Configuration using the official [Goland docs](https://www.jetbrains.com/help/go/go-build.html) and just copy the `parameters`, `directory` and `PATH` sections from the example above (specifying `Run kind` as `Directory` in the Run/Debug Configurations wizard)
117+
118+
## Run Argo CD without the debugged component
119+
Next, we need to run all Argo CD components, except for the debugged component (cause we will run this component separately in the IDE).
120+
There is a mix-and-match approach to running the other components - you can run them in your K8s cluster or locally with the local toolchain.
121+
Below are the different options.
122+
123+
### Run the other components locally
124+
#### Run with "make start-local"
125+
`make start-local` runs all the components by default, but it is also possible to run it with a whitelist of components, enabling the separation we need.
126+
127+
So for the case of debugging the `api-server`, run:
128+
`make start-local ARGOCD_START="notification applicationset-controller repo-server redis dex controller ui"`
129+
130+
#### Run with "make run"
131+
`make run` runs all the components by default, but it is also possible to run it with a blacklist of components, enabling the separation we need.
132+
133+
So for the case of debugging the `api-server`, run:
134+
`make run exclude=api-server`
135+
136+
#### Run with "goreman start"
137+
`goreman start` runs all the components by default, but it is also possible to run it with a whitelist of components, enabling separation as needed.
138+
139+
To debug the `api-server`, run:
140+
`goreman start notification applicationset-controller repo-server redis dex controller ui`
141+
142+
## Run Argo CD debugged component from your IDE
143+
Finally, run the component you wish to debug from your IDE and make sure it does not have any errors.
144+
145+
## Important
146+
When running Argo CD components separately, ensure components aren't creating conflicts - each component needs to be up exactly once, be it running locally with the local toolchain or running from your IDE. Otherwise you may get errors about ports not available or even debugging a process that does not contain your code changes.

0 commit comments

Comments
 (0)