node/

README

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.

Get Started Developing Calico

Contributions to this code are welcome! Before starting, make sure you've read the Calico contributor guide.

Dependencies

The entire build can be run within a container, which means the only dependencies you'll need are a functioning Docker 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.

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 <target>

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

For fv packaged scoped tests, node uses:

• Golang (>=1.7)
• 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.

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

1. 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

1. 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
  • Manipulate the system ARP cache
  • Package: net-tools
• /usr/sbin/conntrack
  • Netfilter connection tracking
  • Package: conntrack
• /bin/ip
  • Show / manipulate routing, devices, policy routing and tunnels
  • Package: iproute2
• /usr/sbin/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
  • 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
  • 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
  • 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
  • Snapshot of the current processes
  • Package: procps
• /bin/kmod
  • Manage Linux Kernel modules
  • soft link for depmod, insmod, lsmod, modinfo, modprobe, rmmo
  • Package: kmod
• /sbin/runit
  • Init scheme with service supervision
  • Package: runit
• /usr/sbin/runsvchdir
  • Starts and monitors a collection of runsv processes
  • Package: runit

License

Calico binaries are licensed under the Apache v2.0 license, with the exception of some GPL licensed eBPF programs.

Calico imports packages with a number of apache-compatible licenses. For more information, see filesystem/licenses. In addition, the base container image contains pre-packaged software with a variety of licenses.