[![Go Report Card](https://goreportcard.com/badge/github.com/projectcalico/node)](https://goreportcard.com/report/github.com/projectcalico/node) # calico/node This repository contains the source for the `calico/node` container. ## Get Started Using Calico For users who want to learn more about the project or get started with Calico, see the documentation on [docs.projectcalico.org](https://docs.projectcalico.org). ## Get Started Developing Calico Contributions to this code are welcome! Before starting, make sure you've read [the Calico contributor guide][contrib]. ### Dependencies The entire build can be run within a container, which means the only dependencies you'll need are a [functioning Docker installation](https://docs.docker.com/engine/installation/). ### Building The code in this repository can be built and tested using the Makefile. - `make calico/node` will produce the `calico/node` docker image. For more information, see `make help`. [contrib]: https://github.com/projectcalico/calico/blob/master/CONTRIBUTING.md ## How can I run tests? Tests for this repo are divided into the following categories: - `fv`: Package scoped tests - `st`: System integration tests - `k8s-test`: Kubernetes integration tests Assuming you have installed the necessary dependencies (see below for details), you can run any of the above categories using: ``` make ``` Where `target` is one of `fv`, `st`, or `k8s-test`. You can also use `test`, which aggregates `fv` and `st`. ### Dependencies for running tests If you want to be able to run tests locally, you will need to install: - GNU make For `st` system integration tests, node uses: - Python (>= 2.7 ???) - [Nose](https://nose.readthedocs.io/en/latest/) For `fv` packaged scoped tests, node uses: - Golang (>=1.7) - [Ginkgo](https://github.com/onsi/ginkgo) You will also need to install Ginkgo explicitly: ``` go get -u github.com/Masterminds/glide go get -u github.com/onsi/ginkgo/ginkgo ``` For `k8s-test` Kubernetes tests, you will need to have `kubectl` setup on your machine. Go here for [instructions on setting up `kubectl` for your environment](https://kubernetes.io/docs/tasks/tools/install-kubectl/). ## How can I run a subset of the tests? If you want to run tests for a specific package for more iterative development, you can filter down into a subset of tests using the following parameters: - For filtering `st` tests, use `ST_TO_RUN` - For filtering `k8s-test` tests, use `K8ST_TO_RUN` For example, the following only runs tests within the `bgp` subfolder of the `st` category: ``` make st ST_TO_RUN="tests/st/bgp/" ``` To only run tests from a single file (e.g. `test_bgp.py`), use the following: ``` make st ST_TO_RUN="tests/st/bgp/test_bgp.py" ``` To only run a single test within a test file use the below syntax: ``` make st ST_TO_RUN="tests/st/bgp/test_bgp.py:TestReadiness.test_readiness_multihost" ``` The above examples should apply in the same fashion if you are using `K8ST_TO_RUN` instead for the `k8s-test` category. ## How do I debug tests? There are a number of possible avenues you can use to debug failing tests. 1. Review the diagnostic logs after the tests finish running - These only show for failed tests - Be warned the logs are quite verbose 2. Use the parameter `DEBUG_FAILURES` with the Makefile ``` make st DEBUG_FAILURES=true ``` - This only applies to `st` tests - A subset of the `st` are wrapped by `debug_failures(fn)` function found in `./tests/st/utils/utils.py` - You should be able to wrap whatever test you want - Uses Python's `pdb.set_trace()` library function, allows you to halt executing and step into the containers involved in the test for debugging 3. Use manual breakpoints - A more primitive approach is just to add your own breakpoints (using something like `time.sleep(x)`) - You should know where to add these after reviewing the diagnostic logs for failed tests (by looking at the stacktraces) ## Linux Dependencies Below is a listing of userspace tools packaged into the node container. The list is not exhaustive, but highlights some of the key dependencies required for node to operate correctly. - [`/usr/sbin/arp`](http://man7.org/linux/man-pages/man8/arp.8.html) - Manipulate the system ARP cache - Package: `net-tools` - [`/usr/sbin/conntrack`](http://man7.org/linux/man-pages/man8/arp.8.html) - Netfilter connection tracking - Package: `conntrack` - [`/bin/ip`](https://linux.die.net/man/8/ip) - Show / manipulate routing, devices, policy routing and tunnels - Package: `iproute2` - [`/usr/sbin/iptables`](https://linux.die.net/man/8/iptables) - Admin tool for IPv4 packet filtering and NAT - Note, we're using the legacy version `iptables-legacy → xtables-legacy-multi` (divergence introduced in `iptables v1.8.2`) - Package: `iptables` - [`/usr/sbin/iptables-restore`](https://linux.die.net/man/8/iptables-restore) - Note, we're using the legacy version `iptables-legacy-restore → xtables-legacy-multi` (divergence introduced in `iptables v1.8.2`) - Package: `iptables` - [`/usr/sbin/iptables-save`](https://linux.die.net/man/8/iptables-save) - Note, we're using the legacy version `iptables-legacy-save → xtables-legacy-multi` (divergence introduced in `iptables v1.8.2`) - Package: `iptables` - [`/usr/sbin/ip6tables`](https://linux.die.net/man/8/ip6tables) - Admin tool for IPv6 packet filtering and NAT - Note, we're using the legacy version `ip6tables-legacy → xtables-legacy-multi` (divergence introduced in `iptables v1.8.2`) - Package: `iptables` - `/usr/sbin/ip6tables-restore` - Note, we using the legacy version `ip6tables-legacy-restore → xtables-legacy-multi` (divergence introduced in `iptables v1.8.2`) - Package: `iptables` - `/usr/sbin/ip6tables-save` - Note, we using the legacy version `ip6tables-legacy-save → xtables-legacy-multi` (divergence introduced in `iptables v1.8.2`) - Package: `iptables` - [`/bin/ps`](https://linux.die.net/man/1/ps) - Snapshot of the current processes - Package: `procps` - [`/bin/kmod`](http://man7.org/linux/man-pages/man8/kmod.8.html) - Manage Linux Kernel modules - soft link for `depmod`, `insmod`, `lsmod`, `modinfo`, `modprobe`, `rmmo` - Package: `kmod` - [`/sbin/runit`](http://smarden.org/runit/) - Init scheme with service supervision - Package: `runit` - [`/usr/sbin/runsvchdir`](http://smarden.org/runit/runsvdir.8.html) - Starts and monitors a collection of runsv processes - Package: `runit` ### License Calico binaries are licensed under the [Apache v2.0 license](LICENSE), with the exception of some [GPL licensed eBPF programs](https://github.com/projectcalico/felix/tree/master/bpf-gpl). Calico imports packages with a number of apache-compatible licenses. For more information, see [licenses](/licenses). In addition, the base container image contains pre-packaged software with a variety of licenses.