github.com/argoproj/argo-cd/v3@v3.2.1/docs/developer-guide/toolchain-guide.md (about)

     1  # Development Toolchain
     2  
     3  ## Prerequisites
     4  [Development Environment](development-environment.md)
     5  
     6  ## Local vs Virtualized toolchain
     7  
     8  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.
     9  
    10  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. 
    11  
    12  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.
    13  
    14  ### Setting up a virtualized toolchain
    15  
    16  If you are going to use the virtualized toolchain, please bear in mind the following things:
    17  
    18  * 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.
    19  * 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`
    20  
    21  The Docker container for the virtualized toolchain will use the following local mounts from your workstation, and possibly modify its contents:
    22  
    23  * `~/go/src` - Your Go workspace's source directory (modifications expected)
    24  * `~/.cache/go-build` - Your Go build cache (modifications expected)
    25  * `~/.kube` - Your Kubernetes client configuration (no modifications)
    26  
    27  #### Known issues on macOS
    28  [Known issues](mac-users.md)
    29  
    30  #### Docker privileges
    31  
    32  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).
    33  
    34  You can either set this before calling `make`, like so for example:
    35  
    36  ```
    37  SUDO=sudo make sometarget
    38  ```
    39  
    40  Or you can opt to export this permanently to your environment, for example
    41  ```
    42  export SUDO=sudo
    43  ```
    44  
    45  #### Using Podman
    46  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:
    47  
    48  ```
    49  DOCKER=podman make start
    50  ```
    51  If you have podman installed, you can leverage its rootless mode.
    52  
    53  #### Build the required Docker image
    54  
    55  Build the required Docker image by running `make test-tools-image`. This image offers the environment of the virtualized toolchain.
    56  
    57  The `Dockerfile` used to build these images can be found at `test/container/Dockerfile`.
    58  
    59  #### Configure your K8s cluster for connection from the build container
    60  ##### K3d
    61  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.
    62  
    63  The configuration you will need for Argo CD virtualized toolchain:
    64  
    65  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.
    66  
    67      * For Mac:
    68  
    69      ```
    70      IP=`ifconfig en0 | grep inet | grep -v inet6 | awk '{print $2}'`
    71      echo $IP
    72      ```
    73  
    74      * For Linux:
    75  
    76      ```
    77      IP=`ifconfig eth0 | grep inet | grep -v inet6 | awk '{print $2}'`
    78      echo $IP
    79      ```
    80  
    81      Keep in mind that this IP is dynamically assigned by the router so if your router restarts for any reason, your IP might change.
    82  
    83  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`
    84  
    85  3. Execute a `kubectl version` to make sure you can still connect to the Kubernetes API server via this new IP. 
    86  
    87  ##### Minikube
    88  
    89  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.
    90  
    91  #### Test connection from the build container to your K8s cluster
    92  
    93  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.
    94  
    95  
    96  If you receive an error similar to the following:
    97  
    98  ```
    99  The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?
   100  make: *** [Makefile:386: verify-kube-connect] Error 1
   101  ```
   102  
   103  you should edit your `~/.kube/config` and modify the `server` option to point to your correct K8s API (as described above).
   104  
   105  ### Setting up a local toolchain
   106  
   107  #### Install `node`
   108  
   109  <https://nodejs.org/en/download>
   110  
   111  #### Install `yarn`
   112  
   113  <https://classic.yarnpkg.com/lang/en/docs/install/>
   114  
   115  #### Install `goreman`
   116  
   117  <https://github.com/mattn/goreman#getting-started>
   118  
   119  Goreman is used to start all needed processes to get a working Argo CD development environment (defined in `Procfile`)
   120  
   121  #### Install required dependencies and build-tools
   122  
   123  !!!note
   124      The installations instructions are valid for Linux hosts only. Mac instructions will follow shortly.
   125  
   126  For installing the tools required to build and test Argo CD on your local system, we provide convenient installer scripts. By default, they will install binaries to `/usr/local/bin` on your system, which might require `root` privileges.
   127  
   128  You can change the target location by setting the `BIN` environment before running the installer scripts. For example, you can install the binaries into `~/go/bin` (which should then be the first component in your `PATH` environment, i.e. `export PATH=~/go/bin:$PATH`):
   129  
   130  ```shell
   131  BIN=~/go/bin make install-tools-local
   132  ```
   133  
   134  Additionally, you have to install at least the following tools via your OS's package manager (this list might not be always up-to-date):
   135  
   136  * Git LFS plugin
   137  * GnuPG version 2