Elgato_dark/argo-cd
1
0
Fork 0
mirror of https://github.com/argoproj/argo-cd synced 2026-04-21 17:07:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 22

docs: Improve developer guide (#23669)

Browse source 
Signed-off-by: reggie-k <regina.voloshin@codefresh.io>
Signed-off-by: Regina Voloshin <regina.voloshin@codefresh.io>
Co-authored-by: Dan Garfield <dan@codefresh.io>
Co-authored-by: Nitish Kumar <justnitish06@gmail.com>
This commit is contained in:
Regina Voloshin 2025-07-22 19:09:00 +03:00 committed by GitHub
parent 36f1a59c09
commit 79943d8189
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 788 additions and 588 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

214
docs/developer-guide/contributors-quickstart.md
View file

@ -1,214 +0,0 @@
# Contributors Quick-Start
This guide is a starting point for first-time contributors running Argo CD locally for the first time.
It skips advanced topics such as codegen, which are covered in the [running locally guide](running-locally.md)
and the [toolchain guide](toolchain-guide.md).
## Getting Started
### Prerequisites
Before starting, ensure you have the following tools installed with the specified minimum versions:
* Git (v2.0.0+)
* Go (version specified in `go.mod` - check with `go version`)
* Docker (v20.10.0+) Or Podman (v3.0.0+)
* Kind (v0.11.0+) Or Minikube (v1.23.0+)
* Yarn (v1.22.0+)
* Goreman (latest version)
### Fork and Clone the Repository
1. Fork the Argo CD repository to your personal GitHub Account
2. Clone the forked repository:
```shell
git clone https://github.com/YOUR-USERNAME/argo-cd.git
```
Please note that the local build process uses GOPATH and that path should not be used, unless the Argo CD repository was directly cloned in it.
3. Add the upstream remote for rebasing:
```shell
cd argo-cd
git remote add upstream https://github.com/argoproj/argo-cd.git
```
### Install Required Tools
1. Install development tools:
```shell
make install-go-tools-local
make install-codegen-tools-local
```
### Install Go
<https://go.dev/doc/install/>
Install Go with a version equal to or greater than the version listed in `go.mod` (verify go version with `go version`).
### Install Docker or Podman
#### Installation guide for docker:
<https://docs.docker.com/engine/install/>
#### Installation guide for podman:
<https://podman.io/docs/installation>
### Install or Upgrade a Tool for Running Local Clusters (e.g. kind or minikube)
#### Installation guide for kind:
<https://kind.sigs.k8s.io/docs/user/quick-start/>
#### Installation guide for minikube:
<https://minikube.sigs.k8s.io/docs/start/>
### Start Your Local Cluster
For example, if you are using kind:
```shell
kind create cluster
```
Or, if you are using minikube:
```shell
minikube start
```
Or, if you are using minikube with podman driver:
```shell
minikube start --driver=podman
```
### Install Argo CD
```shell
kubectl create namespace argocd &&
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/install.yaml
```
Set kubectl config to avoid specifying the namespace in every kubectl command.
All following commands in this guide assume the namespace is already set.
```shell
kubectl config set-context --current --namespace=argocd
```
### Install `yarn`
<https://classic.yarnpkg.com/lang/en/docs/install/>
### Install `goreman`
<https://github.com/mattn/goreman#getting-started>
### Run Argo CD
```shell
cd argo-cd
make start-local ARGOCD_GPG_ENABLED=false
```
By default, Argo CD uses Docker. To use Podman instead, set the `DOCKER` environment variable to `podman` before running the `make` command:
```shell
cd argo-cd
DOCKER=podman make start-local ARGOCD_GPG_ENABLED=false
```
- Navigate to [localhost:4000](http://localhost:4000) in your browser to load the Argo CD UI
- It may take a few minutes for the UI to be responsive
!!! note
If the UI is not working, check the logs from `make start-local`. The logs are `DEBUG` level by default. If the logs are
too noisy to find the problem, try editing log levels for the commands in the `Procfile` in the root of the Argo CD repo.
## Common Make Targets
Here are some frequently used make targets (all will run on your machine):
### Local Toolchain Make Targets
* `make build-local` - Build Argo CD binaries
* `make test-local` - Run unit tests
* `make codegen-local` - Re-generate auto generated Swagger and Protobuf (after changing API code)
* `make lint-local` - Run linting
* `make pre-commit-local` - Run pre-commit checks
* `make start-e2e-local` - Start server for end-to-end tests
* `make test-e2e-local` - Run end-to-end tests
* `make serve-docs-local` - Serve documentation
* `make start-local` - Start Argo CD
### Virtualized Toolchain Make Targets
* `make build` - Build Argo CD binaries
* `make test` - Run unit tests
* `make codegen` - Re-generate auto generated Swagger and Protobuf (after changing API code)
* `make lint` - Run linting
* `make pre-commit` - Run pre-commit checks
* `make start-e2e` - Start server for end-to-end tests
* `make test-e2e` - Run end-to-end tests
* `make serve-docs` - Serve documentation
* `make start` - Start Argo CD
## Making Changes
### Before Submitting a PR
1. Rebase your branch against upstream main:
```shell
git fetch upstream
git rebase upstream/main
```
2. Run pre-commit checks:
```shell
make pre-commit-local
```
### Docs Changes
Modifying the docs auto-reloads the changes on the [documentation website](https://argo-cd.readthedocs.io/) that can be locally built using `make serve-docs` command.
Once running, you can view your locally built documentation on port 8000.
Read more about this [here](https://argo-cd.readthedocs.io/en/latest/developer-guide/docs-site/).
### UI Changes
Modifying the User-Interface (by editing .tsx or .scss files) auto-reloads the changes on port 4000.
### Backend Changes
Modifying the API server, repo server, or a controller requires restarting the current `make start-local` session to reflect the changes.
### CLI Changes
Modifying the CLI requires restarting the current `make start-local` session to reflect the changes.
To test most CLI commands, you will need to log in.
First, get the auto-generated secret:
```shell
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo
```
Then log in using that password and username `admin`:
```shell
dist/argocd login localhost:8080
```
---
Congrats on making it to the end of this runbook! 🚀
For more on Argo CD, find us in Slack - <https://slack.cncf.io/> [#argo-contributors](https://cloud-native.slack.com/archives/C020XM04CUW)

146
docs/developer-guide/debugging-locally.md Normal file
View file

@ -0,0 +1,146 @@
# Debugging a local Argo CD instance
## Prerequisites
1. [Development Environment](development-environment.md)
2. [Toolchain Guide](toolchain-guide.md)
3. [Development Cycle](development-cycle.md)
4. [Running Locally](running-locally.md)
## Preface
Please make sure you are familiar with running Argo CD locally using the [local toolchain](running-locally.md#start-local-services-local-toolchain).
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),
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.
For the next steps, we will use Argo CD `api-server` as an example of running a component in an IDE.
## Configure your IDE
### Locate your component configuration in `Procfile`
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.
Example for `api-server` configuration in `Procfile`:
``` text
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'}"
```
This configuration example will be used as the basis for the next steps.
!!! note
The Procfile for a component may change with time. Please go through the Procfile and make sure you use the latest configuration for debugging.
### Configure component env variables
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.
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.
Example for an `api-server.env` file:
``` bash
ARGOCD_BINARY_NAME=argocd-server
ARGOCD_FAKE_IN_CLUSTER=true
ARGOCD_GNUPGHOME=/tmp/argocd-local/gpg/keys
ARGOCD_GPG_DATA_PATH=/tmp/argocd-local/gpg/source
ARGOCD_GPG_ENABLED=false
ARGOCD_LOG_FORMAT_ENABLE_FULL_TIMESTAMP=1
ARGOCD_SSH_DATA_PATH=/tmp/argocd-local/ssh
ARGOCD_TLS_DATA_PATH=/tmp/argocd-local/tls
ARGOCD_TRACING_ENABLED=1
FORCE_LOG_COLORS=1
KUBECONFIG=/Users/<YOUR_USERNAME>/.kube/config # Must be an absolute full path
...
# and so on, for example: when you test the app-in-any-namespace feature,
# you'll need to add ARGOCD_APPLICATION_NAMESPACES to this list
# only for testing this functionality and remove it afterwards.
```
### Install DotENV / EnvFile plugin
Using the market place / plugin manager of your IDE. The below example configurations require the plugin to be installed.
### Configure component IDE launch configuration
#### VSCode example
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.
Example for an `api-server` launch configuration, based on our above example for `api-server` configuration in `Procfile`:
``` json
{
"name": "api-server",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "YOUR_CLONED_ARGO_CD_REPO_PATH/argo-cd/cmd",
"args": [
"--loglevel",
"debug",
"--redis",
"localhost:6379",
"--repo-server",
"localhost:8081",
"--dex-server",
"http://localhost:5556",
"--port",
"8080",
"--insecure"
],
"envFile": "YOUR_ENV_FILES_PATH/api-server.env", # Assuming you installed DotENV plugin
}
```
#### Goland example
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.
Example for an `api-server` launch configuration snippet, based on our above example for `api-server` configuration in `Procfile`:
``` xml
<component name="ProjectRunConfigurationManager">
<configuration default="false" name="api-server" type="GoApplicationRunConfiguration" factoryName="Go Application">
<module name="argo-cd" />
<working_directory value="$PROJECT_DIR$" />
<parameters value="--loglevel debug --redis localhost:6379 --insecure --dex-server http://localhost:5556 --repo-server localhost:8081 --port 8080" />
<EXTENSION ID="net.ashald.envfile"> <!-- Assuming you installed the EnvFile plugin-->
<option name="IS_ENABLED" value="true" />
<option name="IS_SUBST" value="false" />
<option name="IS_PATH_MACRO_SUPPORTED" value="false" />
<option name="IS_IGNORE_MISSING_FILES" value="false" />
<option name="IS_ENABLE_EXPERIMENTAL_INTEGRATIONS" value="false" />
<ENTRIES>
<ENTRY IS_ENABLED="true" PARSER="runconfig" IS_EXECUTABLE="false" />
<ENTRY IS_ENABLED="true" PARSER="env" IS_EXECUTABLE="false" PATH="<YOUR_ENV_FILES_PATH>/api-server.env" />
</ENTRIES>
</EXTENSION>
<kind value="DIRECTORY" />
<directory value="$PROJECT_DIR$/cmd" />
<filePath value="$PROJECT_DIR$" />
<method v="2" />
</configuration>
</component>
```
!!! note
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)
## Run Argo CD without the debugged component
Next, we need to run all Argo CD components, except for the debugged component (cause we will run this component separately in the IDE).
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.
Below are the different options.
### Run the other components locally
#### Run with "make start-local"
`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.
So for the case of debugging the `api-server`, run:
`make start-local ARGOCD_START="notification applicationset-controller repo-server redis dex controller ui"`
#### Run with "make run"
`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.
So for the case of debugging the `api-server`, run:
`make run exclude=api-server`
#### Run with "goreman start"
`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.
To debug the `api-server`, run:
`goreman start notification applicationset-controller repo-server redis dex controller ui`
## Run Argo CD debugged component from your IDE
Finally, run the component you wish to debug from your IDE and make sure it does not have any errors.
## Important
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.

62
docs/developer-guide/dependencies.md
View file

@ -33,21 +33,61 @@ After your GitOps Engine PR has been merged, ArgoCD needs to be updated to pull
- See https://github.com/argoproj/argo-cd/pull/4434 as an example
- The PR might require additional, dependent changes in ArgoCD that are directly impacted by the changes made in the engine.
## Argo UI Components
## Notifications Engine (`github.com/argoproj/notifications-engine`)
### Repository
https://github.com/argoproj/argo-ui
[notifications-engine](https://github.com/argoproj/notifications-engine)
### Pulling changes from Argo UI into Argo CD
### Pulling changes from `notifications-engine`
If you make changes to the Argo UI component, and your Argo CD changes depend on those changes, follow these steps:
After your Notifications Engine PR has been merged, ArgoCD needs to be updated to pull in the version of the notifications engine that contains your change. Here are the steps:
1. Make changes to Argo UI and submit the PR request.
2. Also, prepare your Argo CD changes, but don't create the PR just yet.
3. **After** the Argo UI PR has been merged to master, then as part of your Argo CD changes:
- Run `yarn add git+https://github.com/argoproj/argo-ui.git` in the `ui/` directory, and then,
- Check in the regenerated `yarn.lock` file as part of your Argo CD commit
4. Create the Argo CD PR when you are ready. The PR build and test checks should pass.
- Retrieve the SHA hash for your commit. You will use this in the next step.
- From the `argo-cd` folder, run the following command
If your Argo UI change is a 'stand-alone' fix, and you simply want Argo CD to pull in your change, then simply create an Argo CD PR with the `yarn.lock` file change.
`go get github.com/argoproj/notifications-engine@<git-commit-sha>`
If you get an error message `invalid version: unknown revision` then you got the wrong SHA hash
- Run:
`go mod tidy`
- The following files are changed:
- `go.mod`
- `go.sum`
- If your notifications engine PR included docs changes, run `make codegen` or `make codegen-local`.
- Create an ArgoCD PR with a `refactor:` type in its title for the above file changes.
## Argo UI Components (`github.com/argoproj/argo-ui`)
### Contributing to Argo CD UI
Argo CD, along with Argo Workflows, uses shared React components from [Argo UI](https://github.com/argoproj/argo-ui). Examples of some of these components include buttons, containers, form controls,
and others. Although you can make changes to these files and run them locally, in order to have these changes added to the Argo CD repo, you will need to follow these steps.
1. Fork and clone the [Argo UI repository](https://github.com/argoproj/argo-ui).
2. `cd` into your `argo-ui` directory, and then run `yarn install`.
3. Make your file changes.
4. Run `yarn start` to start a [storybook](https://storybook.js.org/) dev server and view the components in your browser. Make sure all your changes work as expected.
5. Use [yarn link](https://classic.yarnpkg.com/en/docs/cli/link/) to link Argo UI package to your Argo CD repository. (Commands below assume that `argo-ui` and `argo-cd` are both located within the same parent folder)
* `cd argo-ui`
* `yarn link`
* `cd ../argo-cd/ui`
* `yarn link argo-ui`
Once the `argo-ui` package has been successfully linked, test changes in your local development environment.
6. Commit changes and open a PR to [Argo UI](https://github.com/argoproj/argo-ui).
7. Once your PR has been merged in Argo UI, `cd` into your `argo-cd/ui` folder and run `yarn add git+https://github.com/argoproj/argo-ui.git`. This will update the commit SHA in the `ui/yarn.lock` file to use the latest master commit for argo-ui.
8. Submit changes to `ui/yarn.lock`in a PR to Argo CD.

119
docs/developer-guide/development-cycle.md Normal file
View file

@ -0,0 +1,119 @@
# The Development Cycle
## Prerequisites
1. [Development Environment](development-environment.md)
2. [Toolchain Guide](toolchain-guide.md)
## Preface
When you have developed and possibly manually tested the code you want to contribute, you should ensure that everything builds correctly. Commit your changes locally and perform the following steps, for each step the commands for both local and virtualized toolchain are listed.
### Docker priviliges for virtualized toolchain users
[These instructions](toolchain-guide.md#docker-privileges) are relevant for most of the steps below
### Using Podman for virtualized toolchain users
[These instructions](toolchain-guide.md#using-podman) are relevant for most of the steps below
## Development cycle steps
### Set kubectl context to argocd namespace
Setting kubectl config to the argocd namespace is required for these steps to succeed.
All following commands in this guide assume the namespace is already set.
```shell
kubectl config set-context --current --namespace=argocd
```
### Pull in all build dependencies
As build dependencies change over time, you have to synchronize your development environment with the current specification. In order to pull in all required dependencies, issue:
* `make dep-ui` or `make dep-ui-local`
Argo CD recently migrated to Go modules. Usually, dependencies will be downloaded at build time, but the Makefile provides two targets to download and vendor all dependencies:
* `make mod-download` or `make mod-download-local` will download all required Go modules and
* `make mod-vendor` or `make mod-vendor-local` will vendor those dependencies into the Argo CD source tree
### Generate API glue code and other assets
Argo CD relies on Google's [Protocol Buffers](https://developers.google.com/protocol-buffers) for its API, and this makes heavy use of auto-generated glue code and stubs. Whenever you touched parts of the API code, you must re-generate the auto generated code.
* Run `make codegen` or `make codegen-local`, this might take a while
* Check if something has changed by running `git status` or `git diff`
* Commit any possible changes to your local Git branch, an appropriate commit message would be `Changes from codegen`, for example.
!!!note
There are a few non-obvious assets that are auto-generated. You should not change the autogenerated assets, as they will be overwritten by a subsequent run of `make codegen`. Instead, change their source files. Prominent examples of non-obvious auto-generated code are `swagger.json` or the installation manifest YAMLs.
### Build your code and run unit tests
After the code glue has been generated, your code should build and the unit tests should run without any errors. Execute the following statements:
* `make build` or `make build-local`
* `make test` or `make test-local`
These steps are non-modifying, so there's no need to check for changes afterward.
### Lint your code base
In order to keep a consistent code style in our source tree, your code must be well-formed in accordance to some widely accepted rules, which are applied by a Linter.
The Linter might make some automatic changes to your code, such as indentation fixes. Some other errors reported by the Linter have to be fixed manually.
* Run `make lint` or `make lint-local` and observe any errors reported by the Linter
* Fix any of the errors reported and commit to your local branch
* Finally, after the Linter reports no errors, run `git status` or `git diff` to check for any changes made automatically by Lint
* If there were automatic changes, commit them to your local branch
If you touched UI code, you should also run the Yarn linter on it:
* Run `make lint-ui` or `make lint-ui-local`
* Fix any of the errors reported by it
### Run end-to-end tests
The final step is running the End-to-End testsuite, which ensures that your Kubernetes dependencies are working properly. This will involve starting all the Argo CD components on your computer. The end-to-end tests consists of two parts: a server component, and a client component.
* First, start the End-to-End server: `make start-e2e` or `make start-e2e-local`. This will spawn a number of processes and services on your system.
* When all components have started, run `make test-e2e` or `make test-e2e-local` to run the end-to-end tests against your local services.
To run a single test with a local toolchain, you can use `TEST_FLAGS="-run TestName" make test-e2e-local`.
For more information about End-to-End tests, refer to the [End-to-End test documentation](test-e2e.md).
## Common Make Targets
Here are some frequently used make targets (all will run on your machine):
### Local Toolchain Make Targets
* `make install-tools-local` - Install testing and building tools for the local toolchain
* `make build-local` - Build Argo CD binaries
* `make test-local` - Run unit tests
* `make codegen-local` - Re-generate auto generated Swagger and Protobuf (after changing API code)
* `make lint-local` - Run linting
* `make pre-commit-local` - Run pre-commit checks
* `make start-e2e-local` - Start server for end-to-end tests
* `make test-e2e-local` - Run end-to-end tests
* `make serve-docs-local` - Serve documentation
* `make start-local` - Start Argo CD
* `make cli-local` - Build Argo CD CLI binary
### Virtualized Toolchain Make Targets
* `make verify-kube-connect` - Test whether the virtualized toolchain has access to your K8s cluster
* `make test-tools-image` - Prepare the environment of the virtualized chain
* `make build` - Build Argo CD binaries
* `make test` - Run unit tests
* `make codegen` - Re-generate auto generated Swagger and Protobuf (after changing API code)
* `make lint` - Run linting
* `make pre-commit` - Run pre-commit checks
* `make start-e2e` - Start server for end-to-end tests
* `make test-e2e` - Run end-to-end tests
* `make serve-docs` - Serve documentation
* `make start` - Start Argo CD
---
Congrats on making it to the end of this runbook! 🚀
For more on Argo CD, find us in Slack - <https://slack.cncf.io/> [#argo-contributors](https://cloud-native.slack.com/archives/C020XM04CUW)

120
docs/developer-guide/development-environment.md Normal file
View file

@ -0,0 +1,120 @@
# Setting Up the Development Environment
## Required Tools Overview
You will need to install the following tools with the specified minimum versions:
* Git (v2.0.0+)
* Go (version specified in `go.mod` - check with `go version`)
* Docker (v20.10.0+) Or Podman (v3.0.0+)
* Kind (v0.11.0+) Or Minikube (v1.23.0+) Or K3d (v5.7.3+)
## Install Required Tools
### Install Git
Obviously, you will need a `git` client for pulling source code and pushing back your changes.
<https://github.com/git-guides/install-git>
### Install Go
You will need a Go SDK and related tools (such as GNU `make`) installed and working on your development environment.
<https://go.dev/doc/install/>
Install Go with a version equal to or greater than the version listed in `go.mod` (verify go version with `go version`).
We will assume that your Go workspace is at `~/go`.
Verify: run `go version`
### Install Docker or Podman
#### Installation guide for docker
<https://docs.docker.com/engine/install/>
You will need a working Docker runtime environment, to be able to build and run images. Argo CD is using multi-stage builds.
Verify: run `docker version`
#### Installation guide for podman
<https://podman.io/docs/installation>
### Install a Local K8s Cluster
You won't need a fully blown multi-master, multi-node cluster, but you will need something like K3S, K3d, Minikube, Kind or microk8s. You will also need a working Kubernetes client (`kubectl`) configuration in your development environment. The configuration must reside in `~/.kube/config`.
#### Kind
##### [Installation guide](https://kind.sigs.k8s.io/docs/user/quick-start)
You can use `kind` to run Kubernetes inside Docker. But pointing to any other development cluster works fine as well as long as Argo CD can reach it.
##### Start the Cluster
```shell
kind create cluster
```
#### Minikube
##### [Installation guide](https://minikube.sigs.k8s.io/docs/start)
##### Start the Cluster
```shell
minikube start
```
Or, if you are using minikube with podman driver:
```shell
minikube start --driver=podman
```
#### K3d
##### [Installation guide](https://k3d.io/stable/#quick-start)
### Verify cluster installation
* Run `kubectl version`
## Fork and Clone the Repository
1. Fork the Argo CD repository to your personal GitHub Account
2. Clone the forked repository:
```shell
git clone https://github.com/YOUR-USERNAME/argo-cd.git
```
Please note that the local build process uses GOPATH and that path should not be used, unless the Argo CD repository was directly cloned in it.
3. While everyone has their own Git workflow, the author of this document recommends to create a remote called `upstream` in your local copy pointing to the original Argo CD repository. This way, you can easily keep your local branches up-to-date by merging in latest changes from the Argo CD repository, i.e. by doing a `git pull upstream master` in your locally checked out branch.
To create the remote, run:
```shell
cd argo-cd
git remote add upstream https://github.com/argoproj/argo-cd.git
```
## Install Additional Required Development Tools
```shell
make install-go-tools-local
make install-codegen-tools-local
```
## Install Latest Argo CD on Your Local Cluster
```shell
kubectl create namespace argocd &&
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/install.yaml
```
Set kubectl config to avoid specifying the namespace in every kubectl command.
```shell
kubectl config set-context --current --namespace=argocd
```

99
docs/developer-guide/index.md
View file

@ -1,25 +1,102 @@
# Overview
!!! warning "You probably don't want to be reading this section of the docs."
This part of the manual is aimed at helping people contribute to Argo CD, the documentation, or to develop third-party applications that interact with Argo CD, e.g.
!!! warning "As an Argo CD user, you probably don't want to be reading this section of the docs."
This part of the manual is aimed at helping people contribute to Argo CD, documentation, or to develop third-party applications that interact with Argo CD, e.g.
* A chat bot
* A Slack integration
## Contributing to Argo CD
* [Code Contribution Guide](code-contributions/)
* [Contributors Quickstart](contributors-quickstart/)
* [Running Argo CD Locally](running-locally/)
## Preface
#### Understand the [Code Contribution Guide](code-contributions.md)
#### Understand the [Code Contribution Preface](submit-your-pr.md#preface)
## Contributing to Argo CD documentation
This guide will help you get started quickly with contributing documentation changes, performing the minimum setup you'll need.
For backend and frontend contributions, that require a full building-testing-running-locally cycle, please refer to [Contributing to Argo CD backend and frontend ](index.md#contributing-to-argo-cd-backend-and-frontend)
### Fork and clone Argo CD repository
- [Fork and clone Argo CD repository](development-environment.md#fork-and-clone-the-repository)
### Submit your PR
- [Before submitting a PR](submit-your-pr.md#before-submitting-a-pr)
- [Choose a correct title for your PR](submit-your-pr.md#choose-a-correct-title-for-your-pr)
- [Perform the PR template checklist](submit-your-pr.md#perform-the-PR-template-checklist)
## Contributing to Argo CD Notifications documentation
This guide will help you get started quickly with contributing documentation changes, performing the minimum setup you'll need.
The notificaions docs are located in [notifications-engine](https://github.com/argoproj/notifications-engine) Git repository and require 2 pull requests: one for the `notifications-engine` repo and one for the `argo-cd` repo.
For backend and frontend contributions, that require a full building-testing-running-locally cycle, please refer to [Contributing to Argo CD backend and frontend ](index.md#contributing-to-argo-cd-backend-and-frontend)
### Fork and clone Argo CD repository
- [Fork and clone Argo CD repository](development-environment.md#fork-and-clone-the-repository)
### Submit your PR to notifications-engine
- [Before submitting a PR](submit-your-pr.md#before-submitting-a-pr)
- [Choose a correct title for your PR](submit-your-pr.md#choose-a-correct-title-for-your-pr)
- [Perform the PR template checklist](submit-your-pr.md#perform-the-PR-template-checklist)
### Install Go on your machine
- [Install Go](development-environment.md#install-go)
### Submit your PR to argo-cd
- [Contributing to notifications-engine](dependencies.md#notifications-engine-githubcomargoprojnotifications-engine)
- [Before submitting a PR](submit-your-pr.md#before-submitting-a-pr)
- [Choose a correct title for your PR](submit-your-pr.md#choose-a-correct-title-for-your-pr)
- [Perform the PR template checklist](submit-your-pr.md#perform-the-PR-template-checklist)
## Contributing to Argo CD backend and frontend
This guide will help you set up your build & test environment, so that you can start developing and testing bug fixes and feature enhancements without having to make too much effort in setting up a local toolchain.
As is the case with the development process, this document is under constant change. If you notice any error, or if you think this document is out-of-date, or if you think it is missing something: Feel free to submit a PR or submit a bug to our GitHub issue tracker.
### Set up your development environment
- [Install required tools (Git, Go, Docker, etc)](development-environment.md#install-required-tools)
- [Install and start a local K8s cluster (Kind, Minikube or K3d)](development-environment.md#install-a-local-k8s-cluster)
- [Fork and clone Argo CD repository](development-environment.md#fork-and-clone-the-repository)
- [Install additional required development tools](development-environment.md#install-additional-required-development-tools)
- [Install latest Argo CD on your local cluster](development-environment.md#install-latest-argo-cd-on-your-local-cluster)
### Set up a development toolchain (local or virtualized)
- [Understand the differences between the toolchains](toolchain-guide.md#local-vs-virtualized-toolchain)
- Choose a development toolchain
- Either [set up a local toolchain](toolchain-guide.md#setting-up-a-local-toolchain)
- Or [set up a virtualized toolchain](toolchain-guide.md#setting-up-a-virtualized-toolchain)
### Perform the development cycle
- [Set kubectl context to argocd namespace](development-cycle.md#set-kubectl-context-to-argocd-namespace)
- [Pull in all build dependencies](development-cycle.md#pull-in-all-build-dependencies)
- [Generate API glue code and other assets](development-cycle.md#generate-API-glue-code-and-other-assets)
- [Build your code and run unit tests](development-cycle.md#build-your-code-and-run-unit-tests)
- [Lint your code base](development-cycle.md#lint-your-code-base)
- [Run e2e tests](development-cycle.md#run-end-to-end-tests)
- How to contribute to documentation: [build and run documentation site](docs-site/) on your machine for manual testing
### Run and debug Argo CD locally
- [Run Argo CD on your machine for manual testing](running-locally.md)
- [Debug Argo CD in an IDE on your machine](debugging-locally.md)
### Submit your PR
- [Before submitting a PR](submit-your-pr.md#before-submitting-a-pr)
- [Understand the Continuous Integration process](submit-your-pr.md#understand-the-continuous-integration-process)
- [Choose a correct title for your PR](submit-your-pr.md#choose-a-correct-title-for-your-pr)
- [Perform the PR template checklist](submit-your-pr.md#perform-the-PR-template-checklist)
- [Understand the CI automated builds & tests](submit-your-pr.md#automated-builds-&-tests)
- [Understand & make sure your PR meets the CI code test coverage requirements](submit-your-pr.md#code-test-coverage)
Need help? Start with the [Contributors FAQ](faq/)
## Contributing to the Documentation
* [Building and Running Documentation Site Locally](docs-site/)
## Contributing to Argo CD dependencies
- [Contributing to argo-ui](dependencies.md#argo-ui-components-githubcomargoprojargo-ui)
- [Contributing to gitops-engine](dependencies.md#gitops-engine-githubcomargoprojgitops-engine)
- [Contributing to notifications-engine](dependencies.md#notifications-engine-githubcomargoprojnotifications-engine)
## Extensions and Third-Party Applications
* [UI Extensions](ui-extensions/)
* [Proxy Extensions](proxy-extensions/)
* [UI Extensions](extensions/ui-extensions.md)
* [Proxy Extensions](extensions/proxy-extensions.md)
* [Config Management Plugins](../operator-manual/config-management-plugins/)
## Contributing to Argo Website

20
docs/developer-guide/mac-users.md Normal file
View file

@ -0,0 +1,20 @@
# MacOS users
Below are known issues specific to macOS
## Port 5000
You may get an error listening on port 5000 on macOS:
```text
docker: Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:5000 -> 0.0.0.0:0: listen tcp 0.0.0.0:5000: bind: address already in use.
```
In that case, you can disable "AirPlay Receiver" in macOS System Preferences.
## Firewall dialogs
If you get firewall dialogs, you can click "Deny", since no access from outside your computer is typically desired.
## Exec format error for virtualized toolchain make targets
If you get `/go/src/github.com/argoproj/argo-cd/dist/mockery: cannot execute binary file: Exec format error`, this typically means that you ran a virtualized `make` target after you ran the a local `make` target.
To fix this and continue with the virtualized toolchain, delete the contents of `argo-cd/dist` folder.
If later on you wish to run `make` targets of the local toolchain again, run `make install-tools-local` to re-populate the contents of the `argo-cd/dist` folder.

173
docs/developer-guide/running-locally.md
View file

@ -1,14 +1,21 @@
# Running Argo CD locally
## Run Argo CD outside of Kubernetes
## Prerequisites
1. [Development Environment](development-environment.md)
2. [Toolchain Guide](toolchain-guide.md)
3. [Development Cycle](development-cycle.md)
During development, it might be viable to run Argo CD outside a Kubernetes cluster. This will greatly speed up development, as you don't have to constantly build, push and install new Argo CD Docker images with your latest changes.
## Preface
During development, it is recommended to start with Argo CD running locally (outside of a K8s cluster). This will greatly speed up development, as you don't have to constantly build, push and install new Argo CD Docker images with your latest changes.
You will still need a working Kubernetes cluster, as described in the [Toolchain Guide](toolchain-guide.md), where Argo CD will store all of its resources and configuration.
After you have tested locally, you can move to the second phase of building a docker image, running Argo CD in your cluster and testing further.
If you followed the [Toolchain Guide](toolchain-guide.md) in setting up your toolchain, you can run Argo CD locally with these simple steps:
For both cases, you will need a working K8s cluster, where Argo CD will store all of its resources and configuration.
### Install Argo CD resources to your cluster
In order to have all the required resources in your cluster, you will deploy Argo CD from your development branch and then scale down all it's instances.
This will ensure you have all the relevant configuration (such as Argo CD Config Maps and CRDs) in the cluster while the instances themselves are stopped.
### Deploy Argo CD resources to your cluster
First push the installation manifest into argocd namespace:
@ -17,6 +24,12 @@ kubectl create namespace argocd
kubectl apply -n argocd --force -f manifests/install.yaml
```
The services you will start later assume you are running in the namespace where Argo CD is installed. You can set the current context default namespace as follows:
```bash
kubectl config set-context --current --namespace=argocd
```
### Scale down any Argo CD instance in your cluster
Make sure that Argo CD is not running in your development cluster by scaling down the deployments:
@ -31,34 +44,32 @@ kubectl -n argocd scale deployment/argocd-applicationset-controller --replicas 0
kubectl -n argocd scale deployment/argocd-notifications-controller --replicas 0
```
### Start local services (virtualized toolchain inside Docker)
The started services assume you are running in the namespace where Argo CD is installed. You can set the current context default namespace as follows:
```bash
kubectl config set-context --current --namespace=argocd
```
## Running Argo CD locally, outside of K8s cluster
#### Prerequisites
1. [Deploy Argo CD resources to your cluster](running-locally.md#deploy-argo-cd-resources-to-your-cluster)
2. [Scale down any Argo CD instance in your cluster](running-locally.md#scale-down-any-argo-cd-instance-in-your-cluster)
### Start local services (virtualized toolchain)
When you use the virtualized toolchain, starting local services is as simple as running
```bash
cd argo-cd
make start
```
By default, Argo CD uses Docker. To use Podman instead, set the `DOCKER` environment variable to `podman` before running the `make` command:
```shell
cd argo-cd
DOCKER=podman make start
```
This will start all Argo CD services and the UI in a Docker container and expose the following ports to your host:
* The Argo CD API server on port 8080
* The Argo CD UI server on port 4000
* The Helm registry server on port 5000
You may get an error listening on port 5000 on macOS:
```text
docker: Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:5000 -> 0.0.0.0:0: listen tcp 0.0.0.0:5000: bind: address already in use.
```
In that case, you can disable "AirPlay Receiver" in macOS System Preferences.
You can now use either the web UI by pointing your browser to `http://localhost:4000` or use the CLI against the API at `http://localhost:8080`. Be sure to use the `--insecure` and `--plaintext` options to the CLI. Webpack will take a while to bundle resources initially, so the first page load can take several seconds or minutes.
As an alternative to using the above command line parameters each time you call `argocd` CLI, you can set the following environment variables:
@ -68,51 +79,33 @@ export ARGOCD_SERVER=127.0.0.1:8080
export ARGOCD_OPTS="--plaintext --insecure"
```
### Start local services (running on local machine)
### Start local services (local toolchain)
When you use the local toolchain, starting local services can be performed in 3 ways:
The `make start` command of the virtualized toolchain runs the build and programs inside a Docker container using the test tools image. That makes everything repeatable, but can slow down the development workflow. Particularly on macOS where Docker and the Linux kernel run inside a VM, you may want to try developing fully locally.
Docker should be installed already. Assuming you manage installed software using [Homebrew](https://brew.sh/), you can install other prerequisites like this:
```sh
# goreman is used to start all needed processes to get a working Argo CD development
# environment (defined in `Procfile`)
brew install goreman
# You can use `kind` to run Kubernetes inside Docker. But pointing to any other
# development cluster works fine as well as long as Argo CD can reach it.
brew install kind
#### With "make start-local"
```shell
cd argo-cd
make start-local ARGOCD_GPG_ENABLED=false
```
To set up Kubernetes, you can use kind:
```sh
kind create cluster --kubeconfig ~/.kube/config-kind
# The started services assume you are running in the namespace where Argo CD is
# installed. Set the current context default namespace.
export KUBECONFIG=~/.kube/config-kind
kubectl config set-context --current --namespace=argocd
#### With "make run"
```shell
cd argo-cd
make run ARGOCD_GPG_ENABLED=false
```
Follow the above sections "Install Argo CD resources to your cluster" and "Scale down any Argo CD instance in your cluster" to deploy all needed manifests such as config maps.
Start local services:
```sh
# Ensure you point to the correct Kubernetes cluster as shown above. For example:
export KUBECONFIG=~/.kube/config-kind
make start-local
#### With "goreman start"
```shell
cd argo-cd
ARGOCD_GPG_ENABLED=false && goreman start
```
This will start all Argo CD services and the UI in a Docker container and expose the following ports to your host:
Any of those options will start all Argo CD services and the UI:
* The Argo CD API server on port 8080
* The Argo CD UI server on port 4000
* The Helm registry server on port 5000
If you get firewall dialogs, for example on macOS, you can click "Deny", since no access from outside your computer is typically desired.
Check that all programs have started:
@ -123,23 +116,9 @@ $ goreman run status
[...]
```
If some of the processes fail to start (not marked with `*`), check logs to see why they are not running.
If some of the processes fail to start (not marked with `*`), check logs to see why they are not running. The logs are on `DEBUG` level by default. If the logs are too noisy to find the problem, try editing log levels for the commands in the `Procfile` in the root of the Argo CD repo.
In case of an error like `gpg: key generation failed: Unknown elliptic curve` (a [gnupg bug](https://dev.gnupg.org/T5444)), disable GPG verification before running `make start-local`:
```sh
export ARGOCD_GPG_ENABLED=false
```
You may get an error listening on port 5000 on macOS:
```text
docker: Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:5000 -> 0.0.0.0:0: listen tcp 0.0.0.0:5000: bind: address already in use.
```
In that case, you can disable "AirPlay Receiver" in macOS System Preferences.
You can now use either the web UI by pointing your browser to `http://localhost:4000` or use the CLI against the API at `http://localhost:8080`. Be sure to use the `--insecure` and `--plaintext` options to the CLI. Webpack will take a while to bundle resources initially, so the first page load can take several seconds or minutes.
You can now use either use the web UI by pointing your browser to `http://localhost:4000` or use the CLI against the API at `http://localhost:8080`. Be sure to use the `--insecure` and `--plaintext` options to the CLI. Webpack will take a while to bundle resources initially, so the first page load can take several seconds or minutes.
As an alternative to using the above command line parameters each time you call `argocd` CLI, you can set the following environment variables:
@ -147,37 +126,67 @@ As an alternative to using the above command line parameters each time you call
export ARGOCD_SERVER=127.0.0.1:8080
export ARGOCD_OPTS="--plaintext --insecure"
```
### Making code changes while Argo CD is running on your machine
After making a code change, ensure to rebuild and restart the respective service:
#### Docs Changes
Modifying the docs auto-reloads the changes on the [documentation website](https://argo-cd.readthedocs.io/) that can be locally built using `make serve-docs-local` command.
Once running, you can view your locally built documentation on port 8000.
Read more about this [here](https://argo-cd.readthedocs.io/en/latest/developer-guide/docs-site/).
#### UI Changes
Modifying the User-Interface (by editing .tsx or .scss files) auto-reloads the changes on port 4000.
#### Backend Changes
Modifying the API server, repo server, or a controller requires restarting the current `make start` for virtualized toolchain.
For `make start-local` with the local toolchain, it is enough to rebuild and restart only the respective service:
```sh
# Example for working on the repo server Go code, see other service names in `Procfile`
goreman run restart repo-server
```
Clean up when you're done:
#### CLI Changes
```sh
kind delete cluster; rm -f ~/.kube/config-kind
Modifying the CLI requires restarting the current `make start` or `make start-local` session to reflect the changes. Those targets also rebuild the CLI.
To test most CLI commands, you will need to log in.
First, get the auto-generated secret:
```shell
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo
```
Then log in using that password and username `admin`:
```shell
dist/argocd login localhost:8080
```
## Running Argo CD inside of K8s cluster
### Scale up Argo CD in your cluster
Once you have finished testing your changes locally and want to bring back Argo CD in your development cluster, simply scale the deployments up again:
```bash
kubectl -n argocd scale statefulset/argocd-application-controller --replicas 1
kubectl -n argocd scale deployment/argocd-applicationset-controller --replicas 1
kubectl -n argocd scale deployment/argocd-dex-server --replicas 1
kubectl -n argocd scale deployment/argocd-repo-server --replicas 1
kubectl -n argocd scale deployment/argocd-server --replicas 1
kubectl -n argocd scale deployment/argocd-redis --replicas 1
kubectl -n argocd scale deployment/argocd-notifications-controller --replicas 1
```
## Run your own Argo CD images on your cluster
### Run your own Argo CD images on your cluster
For your final tests, it might be necessary to build your own images and run them in your development cluster.
### Create Docker account and login
#### Create Docker account and login
You might need to create an account on [Docker Hub](https://hub.docker.com) if you don't have one already. Once you created your account, login from your development environment:
@ -185,7 +194,7 @@ You might need to create an account on [Docker Hub](https://hub.docker.com) if y
docker login
```
### Create and push Docker images
#### Create and push Docker images
You will need to push the built images to your own Docker namespace:
@ -205,7 +214,7 @@ Then you can build & push the image in one step:
DOCKER_PUSH=true make image
```
### Configure manifests for your image
#### Configure manifests for your image
With `IMAGE_NAMESPACE` and `IMAGE_TAG` still set, run:
@ -213,12 +222,18 @@ With `IMAGE_NAMESPACE` and `IMAGE_TAG` still set, run:
make manifests
```
to build a new set of installation manifests which include your specific image reference.
or
```bash
make manifests-local
```
(depending on your toolchain) to build a new set of installation manifests which include your specific image reference.
!!!note
Do not commit these manifests to your repository. If you want to revert the changes, the easiest way is to unset `IMAGE_NAMESPACE` and `IMAGE_TAG` from your environment and run `make manifests` again. This will re-create the default manifests.
### Configure your cluster with custom manifests
#### Configure your cluster with custom manifests
The final step is to push the manifests to your cluster, so it will pull and run your image:

86
docs/developer-guide/submit-your-pr.md Normal file
View file

@ -0,0 +1,86 @@
# Submitting PRs
## Prerequisites
1. [Development Environment](development-environment.md)
2. [Toolchain Guide](toolchain-guide.md)
3. [Development Cycle](development-cycle.md)
## Preface
!!!note "Before you start"
The Argo CD project continuously grows, both in terms of features and community size. It gets adopted by more and more organizations which entrust Argo CD to handle their critical production workloads. Thus, we need to take great care with any changes that affect compatibility, performance, scalability, stability and security of Argo CD. For this reason, every new feature or larger enhancement must be properly designed and discussed before it gets accepted into the code base.
We do welcome and encourage everyone to participate in the Argo CD project, but please understand that we can't accept each and every contribution from the community, for various reasons. If you want to submit code for a great new feature or enhancement, we kindly ask you to take a look at the
[code contribution guide](code-contributions.md#) before you start to write code or submit a PR.
If you want to submit a PR, please read this document carefully, as it contains important information guiding you through our PR quality gates.
If you need guidance with submitting a PR, or have any other questions regarding development of Argo CD, do not hesitate to [join our Slack](https://argoproj.github.io/community/join-slack) and get in touch with us in the `#argo-cd-contributors` channel!
## Before Submitting a PR
1. Rebase your branch against upstream main:
```shell
git fetch upstream
git rebase upstream/main
```
2. Run pre-commit checks:
```shell
make pre-commit-local
```
## Continuous Integration process
When you submit a PR against Argo CD's GitHub repository, a couple of CI checks will be run automatically to ensure your changes will build fine and meet certain quality standards. Your contribution needs to pass those checks in order to be merged into the repository.
!!!note
Please make sure that you always create PRs from a branch that is up-to-date with the latest changes from Argo CD's master branch. Depending on how long it takes for the maintainers to review and merge your PR, it might be necessary to pull in latest changes into your branch again.
Please understand that we, as an Open Source project, have limited capacities for reviewing and merging PRs to Argo CD. We will do our best to review your PR and give you feedback as soon as possible, but please bear with us if it takes a little longer as expected.
The following read will help you to submit a PR that meets the standards of our CI tests:
## Title of the PR
Please use a meaningful and concise title for your PR. This will help us to pick PRs for review quickly, and the PR title will also end up in the Changelog.
We use [PR title checker](https://github.com/marketplace/actions/pr-title-checker) to categorize your PR into one of the following categories:
* `fix` - Your PR contains one or more code bug fixes
* `feat` - Your PR contains a new feature
* `docs` - Your PR improves the documentation
* `chore` - Your PR improves any internals of Argo CD, such as the build process, unit tests, etc
Please prefix the title of your PR with one of the valid categories. For example, if you chose the title your PR `Add documentation for GitHub SSO integration`, please use `docs: Add documentation for GitHub SSO integration` instead.
## PR template checklist
Upon opening a PR, the details will contain a checklist from a template. Please read the checklist, and tick those marks that apply to you.
## Automated builds & tests
After you have submitted your PR, and whenever you push new commits to that branch, GitHub will run a number of Continuous Integration checks against your code. It will execute the following actions, and each of them has to pass:
* Build the Go code (`make build`)
* Generate API glue code and manifests (`make codegen`)
* Run a Go linter on the code (`make lint`)
* Run the unit tests (`make test`)
* Run the End-to-End tests (`make test-e2e`)
* Build and lint the UI code (`make lint-ui`)
* Build the `argocd` CLI (`make cli`)
If any of these tests in the CI pipeline fail, it means that some of your contribution is considered faulty (or a test might be flaky, see below).
## Code test coverage
We use [CodeCov](https://codecov.io) in our CI pipeline to check for test coverage, and once you submit your PR, it will run and report on the coverage difference as a comment within your PR. If the difference is too high in the negative, i.e. your submission introduced a significant drop in code coverage, the CI check will fail.
Whenever you develop a new feature or submit a bug fix, please also write appropriate unit tests for it. If you write a completely new module, please aim for at least 80% of coverage.
If you want to see how much coverage just a specific module (i.e. your new one) has, you can set the `TEST_MODULE` to the (fully qualified) name of that module with `make test`, i.e.:
```bash
make test TEST_MODULE=github.com/argoproj/argo-cd/server/cache
...
ok github.com/argoproj/argo-cd/server/cache 0.029s coverage: 89.3% of statements
```

329
docs/developer-guide/toolchain-guide.md
View file

@ -1,109 +1,22 @@
# Development toolchain
# Development Toolchain
## Preface
!!!note "Before you start"
The Argo CD project continuously grows, both in terms of features and community size. It gets adopted by more and more organisations which entrust Argo CD to handle their critical production workloads. Thus, we need to take great care with any changes that affect compatibility, performance, scalability, stability and security of Argo CD. For this reason, every new feature or larger enhancement must be properly designed and discussed before it gets accepted into the code base.
We do welcome and encourage everyone to participate in the Argo CD project, but please understand that we can't accept each and every contribution from the community, for various reasons. If you want to submit code for a great new feature or enhancement, we kindly ask you to take a look at the
[code contribution guide](code-contributions.md#) before you start to write code or submit a PR.
We want to make contributing to Argo CD as simple and smooth as possible.
This guide shall help you in setting up your build & test environment, so that you can start developing and testing bug fixes and feature enhancements without having to make too much effort in setting up a local toolchain.
If you want to submit a PR, please read this document carefully, as it contains important information guiding you through our PR quality gates.
As is the case with the development process, this document is under constant change. If you notice any error, or if you think this document is out-of-date, or if you think it is missing something: Feel free to submit a PR or submit a bug to our GitHub issue tracker.
If you need guidance with submitting a PR, or have any other questions regarding development of Argo CD, do not hesitate to [join our Slack](https://argoproj.github.io/community/join-slack) and get in touch with us in the `#argo-cd-contributors` channel!
## Before you start
You will need at least the following things in your toolchain in order to develop and test Argo CD locally:
* A Kubernetes cluster. You won't need a fully blown multi-master, multi-node cluster, but you will need something like K3S, Minikube or microk8s. You will also need a working Kubernetes client (`kubectl`) configuration in your development environment. The configuration must reside in `~/.kube/config` and the API server URL must point to the IP address of your local machine (or VM), and **not** to `localhost` or `127.0.0.1` if you are using the virtualized development toolchain (see below)
* You will also need a working Docker runtime environment, to be able to build and run images. The Docker version must be 17.05.0 or higher, to support multi-stage builds.
* Obviously, you will need a `git` client for pulling source code and pushing back your changes.
* Last but not least, you will need a Go SDK and related tools (such as GNU `make`) installed and working on your development environment. The minimum required Go version for building and testing Argo CD is **v1.17**.
* We will assume that your Go workspace is at `~/go`.
!!! note
**Attention minikube users**: By default, minikube will create Kubernetes client configuration that uses authentication data from files. This is incompatible with the virtualized toolchain. So if you intend to use the virtualized toolchain, you have to embed this authentication data into the client configuration. To do so, start minikube using `minikube start --embed-certs`. Please also note that minikube using the Docker driver is currently not supported with the virtualized toolchain, because the Docker driver exposes the API server on 127.0.0.1 hard-coded. If in doubt, run `make verify-kube-connect` to find out.
## Submitting PRs
### Continuous Integration process
When you submit a PR against Argo CD's GitHub repository, a couple of CI checks will be run automatically to ensure your changes will build fine and meet certain quality standards. Your contribution needs to pass those checks in order to be merged into the repository.
!!!note
Please make sure that you always create PRs from a branch that is up-to-date with the latest changes from Argo CD's master branch. Depending on how long it takes for the maintainers to review and merge your PR, it might be necessary to pull in latest changes into your branch again.
Please understand that we, as an Open Source project, have limited capacities for reviewing and merging PRs to Argo CD. We will do our best to review your PR and give you feedback as soon as possible, but please bear with us if it takes a little longer as expected.
The following read will help you to submit a PR that meets the standards of our CI tests:
### Title of the PR
Please use a meaningful and concise title for your PR. This will help us to pick PRs for review quickly, and the PR title will also end up in the Changelog.
We use [PR title checker](https://github.com/marketplace/actions/pr-title-checker) to categorize your PR into one of the following categories:
* `fix` - Your PR contains one or more code bug fixes
* `feat` - Your PR contains a new feature
* `docs` - Your PR improves the documentation
* `chore` - Your PR improves any internals of Argo CD, such as the build process, unit tests, etc
Please prefix the title of your PR with one of the valid categories. For example, if you chose the title your PR `Add documentation for GitHub SSO integration`, please use `docs: Add documentation for GitHub SSO integration` instead.
### PR template checklist
Upon opening a PR, the details will contain a checklist from a template. Please read the checklist, and tick those marks that apply to you.
### Automated builds & tests
After you have submitted your PR, and whenever you push new commits to that branch, GitHub will run a number of Continuous Integration checks against your code. It will execute the following actions, and each of them has to pass:
* Build the Go code (`make build`)
* Generate API glue code and manifests (`make codegen`)
* Run a Go linter on the code (`make lint`)
* Run the unit tests (`make test`)
* Run the End-to-End tests (`make test-e2e`)
* Build and lint the UI code (`make lint-ui`)
* Build the `argocd` CLI (`make cli`)
If any of these tests in the CI pipeline fail, it means that some of your contribution is considered faulty (or a test might be flaky, see below).
### Code test coverage
We use [CodeCov](https://codecov.io) in our CI pipeline to check for test coverage, and once you submit your PR, it will run and report on the coverage difference as a comment within your PR. If the difference is too high in the negative, i.e. your submission introduced a significant drop in code coverage, the CI check will fail.
Whenever you develop a new feature or submit a bug fix, please also write appropriate unit tests for it. If you write a completely new module, please aim for at least 80% of coverage.
If you want to see how much coverage just a specific module (i.e. your new one) has, you can set the `TEST_MODULE` to the (fully qualified) name of that module with `make test`, i.e.:
```bash
make test TEST_MODULE=github.com/argoproj/argo-cd/server/cache
...
ok github.com/argoproj/argo-cd/server/cache 0.029s coverage: 89.3% of statements
```
## Prerequisites
[Development Environment](development-environment.md)
## Local vs Virtualized toolchain
Argo CD provides a fully virtualized development and testing toolchain using Docker images. It is recommended to use those images, as they provide the same runtime environment as the final product, and it is much easier to keep up-to-date with changes to the toolchain and dependencies. But as using Docker comes with a slight performance penalty, you might want to set up a local toolchain.
Argo CD provides a fully virtualized development and testing toolchain using Docker images. Those images provide the same runtime environment as the final product, and it is much easier to keep up-to-date with changes to the toolchain and dependencies. The virtualized toolchain runs the build and programs inside a Docker container using the test tools image. That makes everything repeatable. The dynamic nature of requirements is another reason to choose this toolchain. This setup may also require configuring the default K8s API URL that comes with installing a local K8s cluster.
Most relevant targets for the build & test cycles in the `Makefile` provide two variants, one of them suffixed with `-local`. For example, `make test` will run unit tests in the Docker container, `make test-local` will run it natively on your local system.
The local toolchain results in a faster development and testing cycle. Particularly on macOS where Docker and the Linux kernel run inside a VM, you may want to try developing fully locally. Local toolchain also requires installing additional tools on your machine. This toolchain is a good choice for working with an IDE debugger.
Most relevant targets for the build & test cycles in the `Makefile` provide two variants, one of them suffixed with `-local`. For example, `make test` will run unit tests in the Docker container (virtualized toolchain), `make test-local` (local toolchain) will run it natively on your local system.
### Setting up a virtualized toolchain
If you are going to use the virtualized toolchain, please bear in mind the following things:
* Your Kubernetes API server must listen on the interface of your local machine or VM, and not on `127.0.0.1` only.
* Your Kubernetes client configuration (`~/.kube/config`) must not use an API URL that points to `localhost` or `127.0.0.1`.
You can test whether the virtualized toolchain has access to your Kubernetes cluster by running `make verify-kube-connect` (*after* you have set up your development environment, as described below), which will run `kubectl version` inside the Docker container used for running all tests.
* Your Kubernetes API server must listen on the interface of your local machine or VM, and not on `127.0.0.1` or `localhost` only.
* Your Kubernetes client configuration (`~/.kube/config`) must not use an API URL that points to `localhost`, `127.0.0.1` or `0.0.0.0`
The Docker container for the virtualized toolchain will use the following local mounts from your workstation, and possibly modify its contents:
@ -112,78 +25,43 @@ The Docker container for the virtualized toolchain will use the following local
* `~/.kube` - Your Kubernetes client configuration (no modifications)
* `/tmp` - Your system's temp directory (modifications expected)
## Setting up your development environment
#### Known issues on macOS
[Known issues](mac-users.md)
The following steps are required no matter whether you chose to use a virtualized or a local toolchain.
#### Docker privileges
!!!note "Docker privileges"
If you opt in to use the virtualized toolchain, you will need to have the
appropriate privileges to interact with the Docker daemon. It is not
recommended to work as the root user, and if your user does not have the
permissions to talk to the Docker user, but you have `sudo` setup on your
system, you can set the environment variable `SUDO` to `sudo` in order to
have the build scripts make any calls to the `docker` CLI using sudo,
without affecting the other parts of the build scripts (which should be
executed with your normal user privileges).
If you opt in to use the virtualized toolchain, you will need to have the appropriate privileges to interact with the Docker daemon. It is not recommended to work as the root user, and if your user does not have the permissions to talk to the Docker user, but you have `sudo` setup on your system, you can set the environment variable `SUDO` to `sudo` in order to have the build scripts make any calls to the `docker` CLI using sudo, without affecting the other parts of the build scripts (which should be executed with your normal user privileges).
You can either set this before calling `make`, like so for example:
You can either set this before calling `make`, like so for example:
```
SUDO=sudo make sometarget
```
```
SUDO=sudo make sometarget
```
Or you can opt to export this permanently to your environment, for example
```
export SUDO=sudo
```
Or you can opt to export this permanently to your environment, for example
```
export SUDO=sudo
```
If you have podman installed, you can also leverage its rootless mode. In
order to use podman for running and testing Argo CD locally, set the
`DOCKER` environment variable to `podman` before you run `make`, e.g.
#### Using Podman
In order to use podman for running and testing Argo CD locally, set the `DOCKER` environment variable to `podman` before you run `make`, e.g:
```
DOCKER=podman make start
```
```
DOCKER=podman make start
```
If you have podman installed, you can leverage its rootless mode.
### Clone the Argo CD repository from your personal fork on GitHub
* `git clone https://github.com/YOUR-USERNAME/argo-cd`
* `cd argo-cd`
### Optional: Set up an additional Git remote
While everyone has their own Git workflow, the author of this document recommends to create a remote called `upstream` in your local copy pointing to the original Argo CD repository. This way, you can easily keep your local branches up-to-date by merging in latest changes from the Argo CD repository, i.e. by doing a `git pull upstream master` in your locally checked out branch. To create the remote, run `git remote add upstream https://github.com/argoproj/argo-cd`
### Install the must-have requirements
Make sure you fulfill the pre-requisites above and run some preliminary tests. Neither of them should report an error.
* Run `kubectl version`
* Run `docker version`
* Run `go version`
### Build the required Docker image
#### Build the required Docker image
Build the required Docker image by running `make test-tools-image`. This image offers the environment of the virtualized toolchain.
The `Dockerfile` used to build these images can be found at `test/container/Dockerfile`.
### Test connection from build container to your K8s cluster
#### Configure your K8s cluster for connection from the build container
##### K3d
K3d is a minimal Kubernetes distribution, in docker. Because it's running in a docker container, you're dealing with docker's internal networking rules when using k3d. A typical Kubernetes cluster running on your local machine is part of the same network that you're on, so you can access it using **kubectl**. However, a Kubernetes cluster running within a docker container (in this case, the one launched by make) cannot access 0.0.0.0 from inside the container itself, when 0.0.0.0 is a network resource outside the container itself (and/or the container's network). This is the cost of a fully self-contained, disposable Kubernetes cluster.
Run `make verify-kube-connect`, it should execute without error.
If you receive an error similar to the following:
```
The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?
make: *** [Makefile:386: verify-kube-connect] Error 1
```
you should edit your `~/.kube/config` and modify the `server` option to point to your correct K8s API (as described above).
### Using k3d
[k3d](https://github.com/rancher/k3d) is a lightweight wrapper to run [k3s](https://github.com/rancher/k3s), a minimal Kubernetes distribution, in docker. Because it's running in a docker container, you're dealing with docker's internal networking rules when using k3d. A typical Kubernetes cluster running on your local machine is part of the same network that you're on, so you can access it using **kubectl**. However, a Kubernetes cluster running within a docker container (in this case, the one launched by make) cannot access 0.0.0.0 from inside the container itself, when 0.0.0.0 is a network resource outside the container itself (and/or the container's network). This is the cost of a fully self-contained, disposable Kubernetes cluster. The following steps should help with a successful `make verify-kube-connect` execution.
The configuration you will need for Argo CD virtualized toolchain:
1. Find your host IP by executing `ifconfig` on Mac/Linux and `ipconfig` on Windows. For most users, the following command works to find the IP address.
@ -203,103 +81,45 @@ you should edit your `~/.kube/config` and modify the `server` option to point to
Keep in mind that this IP is dynamically assigned by the router so if your router restarts for any reason, your IP might change.
2. Edit your ~/.kube/config and replace 0.0.0.0 with the above IP address.
2. Edit your ~/.kube/config and replace 0.0.0.0 with the above IP address, delete the cluster cert and add `insecure-skip-tls-verify: true`
3. Execute a `kubectl version` to make sure you can still connect to the Kubernetes API server via this new IP. Run `make verify-kube-connect` and check if it works.
3. Execute a `kubectl version` to make sure you can still connect to the Kubernetes API server via this new IP.
4. Finally, so that you don't have to keep updating your kube-config whenever you spin up a new k3d cluster, add `--api-port $IP:6550` to your **k3d cluster create** command, where $IP is the value from step 1. An example command is provided here:
##### Minikube
By default, minikube will create Kubernetes client configuration that uses authentication data from files. This is incompatible with the virtualized toolchain. So if you intend to use the virtualized toolchain, you have to embed this authentication data into the client configuration. To do so, start minikube using `minikube start --embed-certs`. Please also note that minikube using the Docker driver is currently not supported with the virtualized toolchain, because the Docker driver exposes the API server on 127.0.0.1 hard-coded.
#### Test connection from the build container to your K8s cluster
You can test whether the virtualized toolchain has access to your Kubernetes cluster by running `make verify-kube-connect` which will run `kubectl version` inside the Docker container used for running all tests.
If you receive an error similar to the following:
```
k3d cluster create my-cluster --wait --k3s-arg '--disable=traefik@server:*' --api-port $IP:6550 -p 443:443@loadbalancer
The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?
make: *** [Makefile:386: verify-kube-connect] Error 1
```
!!!note
For k3d versions less than v5.0.0, the example command flags `--k3s-arg` and `'--disable=traefik@server:*'` should change to `--k3s-server-arg` and `'--disable=traefik'`, respectively.
you should edit your `~/.kube/config` and modify the `server` option to point to your correct K8s API (as described above).
## The development cycle
### Setting up a local toolchain
When you have developed and possibly manually tested the code you want to contribute, you should ensure that everything will build correctly. Commit your changes to the local copy of your Git branch and perform the following steps:
#### Install `node`
### Pull in all build dependencies
<https://nodejs.org/en/download>
As build dependencies change over time, you have to synchronize your development environment with the current specification. In order to pull in all required dependencies, issue:
#### Install `yarn`
* `make dep-ui`
<https://classic.yarnpkg.com/lang/en/docs/install/>
Argo CD recently migrated to Go modules. Usually, dependencies will be downloaded on build time, but the Makefile provides two targets to download and vendor all dependencies:
#### Install `goreman`
* `make mod-download` will download all required Go modules and
* `make mod-vendor` will vendor those dependencies into the Argo CD source tree
<https://github.com/mattn/goreman#getting-started>
### Generate API glue code and other assets
Goreman is used to start all needed processes to get a working Argo CD development environment (defined in `Procfile`)
Argo CD relies on Google's [Protocol Buffers](https://developers.google.com/protocol-buffers) for its API, and this makes heavy use of auto-generated glue code and stubs. Whenever you touched parts of the API code, you must re-generate the auto generated code.
* Run `make codegen`, this might take a while
* Check if something has changed by running `git status` or `git diff`
* Commit any possible changes to your local Git branch, an appropriate commit message would be `Changes from codegen`, for example.
!!!note
There are a few non-obvious assets that are auto-generated. You should not change the autogenerated assets, as they will be overwritten by a subsequent run of `make codegen`. Instead, change their source files. Prominent examples of non-obvious auto-generated code are `swagger.json` or the installation manifest YAMLs.
### Build your code and run unit tests
After the code glue has been generated, your code should build and the unit tests should run without any errors. Execute the following statements:
* `make build`
* `make test`
These steps are non-modifying, so there's no need to check for changes afterward.
### Lint your code base
In order to keep a consistent code style in our source tree, your code must be well-formed in accordance to some widely accepted rules, which are applied by a Linter.
The Linter might make some automatic changes to your code, such as indentation fixes. Some other errors reported by the Linter have to be fixed manually.
* Run `make lint` and observe any errors reported by the Linter
* Fix any of the errors reported and commit to your local branch
* Finally, after the Linter reports no errors anymore, run `git status` or `git diff` to check for any changes made automatically by Lint
* If there were automatic changes, commit them to your local branch
If you touched UI code, you should also run the Yarn linter on it:
* Run `make lint-ui`
* Fix any of the errors reported by it
## Contributing to Argo CD UI
Argo CD, along with Argo Workflows, uses shared React components from [Argo UI](https://github.com/argoproj/argo-ui). Examples of some of these components include buttons, containers, form controls,
and others. Although you can make changes to these files and run them locally, in order to have these changes added to the Argo CD repo, you will need to follow these steps.
1. Fork and clone the [Argo UI repository](https://github.com/argoproj/argo-ui).
2. `cd` into your `argo-ui` directory, and then run `yarn install`.
3. Make your file changes.
4. Run `yarn start` to start a [storybook](https://storybook.js.org/) dev server and view the components in your browser. Make sure all your changes work as expected.
5. Use [yarn link](https://classic.yarnpkg.com/en/docs/cli/link/) to link Argo UI package to your Argo CD repository. (Commands below assume that `argo-ui` and `argo-cd` are both located within the same parent folder)
* `cd argo-ui`
* `yarn link`
* `cd ../argo-cd/ui`
* `yarn link argo-ui`
Once `argo-ui` package has been successfully linked, test out changes in your local development environment.
6. Commit changes and open a PR to [Argo UI](https://github.com/argoproj/argo-ui).
7. Once your PR has been merged in Argo UI, `cd` into your `argo-cd/ui` folder and run `yarn add git+https://github.com/argoproj/argo-ui.git`. This will update the commit SHA in the `ui/yarn.lock` file to use the latest master commit for argo-ui.
8. Submit changes to `ui/yarn.lock`in a PR to Argo CD.
## Setting up a local toolchain
For development, you can either use the fully virtualized toolchain provided as Docker images, or you can set up the toolchain on your local development machine. Due to the dynamic nature of requirements, you might want to stay with the virtualized environment.
### Install required dependencies and build-tools
#### Install required dependencies and build-tools
!!!note
The installations instructions are valid for Linux hosts only. Mac instructions will follow shortly.
@ -316,36 +136,3 @@ Additionally, you have to install at least the following tools via your OS's pac
* Git LFS plugin
* GnuPG version 2
### Install Go dependencies
You need to pull in all required Go dependencies. To do so, run
* `make mod-download-local`
* `make mod-vendor-local`
### Test your build toolchain
The first thing you can do to test whether your build toolchain is set up correctly is by generating the glue code for the API and after that, run a normal build:
* `make codegen-local`
* `make build-local`
This should return without any error.
### Run unit-tests
The next thing is to make sure that unit tests are running correctly on your system. These will require that all dependencies, such as Helm, Kustomize, Git, GnuPG, etc. are correctly installed and fully functioning:
* `make test-local`
### Run end-to-end tests
The final step is running the End-to-End testsuite, which makes sure that your Kubernetes dependencies are working properly. This will involve starting all the Argo CD components locally on your computer. The end-to-end tests consists of two parts: a server component, and a client component.
* First, start the End-to-End server: `make start-e2e-local`. This will spawn a number of processes and services on your system.
* When all components have started, run `make test-e2e-local` to run the end-to-end tests against your local services.
To run a single test, you can use `TEST_FLAGS="-run TestName" make test-e2e-local`.
For more information about End-to-End tests, refer to the [End-to-End test documentation](test-e2e.md).

2
docs/developer-guide/use-gitpod.md
View file

@ -2,4 +2,4 @@
Gitpod is not currently available for Argo CD development.
See the [Contributors Quickstart](contributors-quickstart.md) guide to set up a minimal development environment.
See the [Overview](index.md) guide to set up a development environment.

6
mkdocs.yml
View file

@ -204,14 +204,18 @@ nav:
- Application Specification Reference: user-guide/application-specification.md
- Developer Guide:
- developer-guide/index.md
- Development Environment: developer-guide/development-environment.md
- Development Cycle: developer-guide/development-cycle.md
- Submit Your PR: developer-guide/submit-your-pr.md
- Architecture:
- developer-guide/architecture/authz-authn.md
- developer-guide/architecture/components.md
- Code Contribution Guide: developer-guide/code-contributions.md
- Toolchain Guide: developer-guide/toolchain-guide.md
- developer-guide/contributors-quickstart.md
- developer-guide/mac-users.md
- developer-guide/release-process-and-cadence.md
- developer-guide/running-locally.md
- developer-guide/debugging-locally.md
- developer-guide/debugging-remote-environment.md
- developer-guide/api-docs.md
- developer-guide/test-e2e.md