Skip to content
Please note that GitHub no longer supports Internet Explorer.

We recommend upgrading to the latest Microsoft Edge, Google Chrome, or Firefox.

Learn more
API-aware Networking and Security using eBPF and XDP
Go C Shell Makefile Ruby Python Other
Branch: master
Clone or download
tklauser and borkmann docs: add libelf-devel to development setup
Otherwise I get the following error when building cilium:

  gcc -Wall -O2 -Wno-format-truncation -I include/ cilium-map-migrate.c -lelf -o cilium-map-migrate
/usr/bin/ld: cannot find -lelf

Signed-off-by: Tobias Klauser <tklauser@distanz.ch>
Latest commit a41fc6e Feb 3, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github .github: rename github-actions file Dec 17, 2019
.travis .travis: disable go modules download when installing dependencies Oct 22, 2019
Documentation docs: add libelf-devel to development setup Feb 3, 2020
api/v1 add 2020 copyright Jan 28, 2020
bpf bpf, sock: only attach v6 hooks in v4-only mode when v6 is available Feb 3, 2020
bugtool cilium: encryption bugtool should remove aead, comp and auth-trunk keys Dec 9, 2019
cilium-health health: Quieten health launch log Nov 1, 2019
cilium bpf, sock: reduce xlation for externalTrafficPolicy=Local to host_id Jan 23, 2020
common common: Remove misleading comment of NewCiliumIPv6 Dec 18, 2019
contrib backporting: add 'upstream-prs' tag for code block Feb 3, 2020
daemon bpf, sock: only attach v6 hooks in v4-only mode when v6 is available Feb 3, 2020
envoy Makefiles: Tidy up output Jan 24, 2019
examples Improve the 'Setting up Cluster Mesh' page. Dec 10, 2019
hack add 2020 copyright Jan 28, 2020
install/kubernetes nodeinit/templates: fix indentation of sys-fs-bpf Feb 3, 2020
jenkinsfiles CI: Determine and set K8s version in GKE pipeline Feb 3, 2020
operator operator: fix getOldestLeases logic Jan 31, 2020
pkg bpf, sock: only attach v6 hooks in v4-only mode when v6 is available Feb 3, 2020
plugins cni: Fix noisy warning "Unknown CNI chaining configuration" Jan 22, 2020
proxylib policy: Translate TLS contexts into PerEpData Dec 20, 2019
test CI: Determine and set K8s version in GKE pipeline Feb 3, 2020
tests vagrant: Remove workaround to MASQ traffic from k8s2 Dec 4, 2019
tools tools: Remove ring-dump tool Nov 25, 2019
vendor envoy: Use TypedConfig for Envoy filters Jan 29, 2020
.authors.aux docs: update authors Sep 17, 2018
.dockerignore test: Keep box in test/.vagrant/ Nov 26, 2019
.gitignore test: Keep box in test/.vagrant/ Nov 26, 2019
.gitmodules envoy: Envoy integration. Nov 22, 2017
.mailmap docs, minor: update mailmap and authors file Jan 14, 2020
.travis.yml golang: update to 1.13.7 Jan 29, 2020
.travis.yml.tmpl Makefile: add automated way to update golang in Dockerfiles Aug 16, 2019
AUTHORS docs, minor: update mailmap and authors file Jan 14, 2020
CODEOWNERS api: Add /ip endpoint for listing IP cache entries Oct 1, 2019
CONTRIBUTING.md docs: Fix broken contributing links Aug 29, 2019
Dockerfile golang: update to 1.13.7 Jan 29, 2020
Dockerfile.builder golang: update to 1.13.7 Jan 29, 2020
FURTHER_READINGS.rst docs: extend further readings section to a separate file Sep 12, 2019
GO_VERSION Update GO_VERSION to match builder version Jan 30, 2020
Jenkinsfile.nightly contrib/vagrant: fix reading VM_MEMORY/VM_CPUS from env vars Jan 23, 2020
LICENSE LICENSE: Update copyright column Jun 26, 2018
MAINTAINERS.rst Add MAINTAINERS file Nov 13, 2019
Makefile golang: update to 1.13.7 Jan 29, 2020
Makefile.defs vendor: add go-mod support Oct 18, 2019
Makefile.quiet bpf: Add 'build_all' target for macro permutations Jul 11, 2019
README.rst README: update weekly meeting hours Jan 13, 2020
SECURITY.md SECURITY.md: update versions of supported releases Jan 13, 2020
USERS.md Updating USERS.md to include CENGN Jan 22, 2020
VERSION Prepare for v1.7 development Jul 24, 2019
Vagrantfile vagrant: remove unnecessary print statements Jan 22, 2020
cilium-docker-plugin.Dockerfile golang: update to 1.13.7 Jan 29, 2020
cilium-operator.Dockerfile golang: update to 1.13.7 Jan 29, 2020
docs.Jenkinsfile CI: Longer git clone timeouts May 28, 2019
flannel.Jenkinsfile Revert "Revert "[CI] add timeout to vm boot retries"" Jan 27, 2020
ginkgo-kubernetes-all.Jenkinsfile Set CILIUM_REGISTRY in k8s provisioning scripts Feb 3, 2020
ginkgo.Jenkinsfile Set CILIUM_REGISTRY in provisioning scritps Jan 29, 2020
go.mod k8s: update libraries to v1.17.1 Jan 16, 2020
go.sum k8s: update libraries to v1.17.1 Jan 16, 2020
kubernetes-upstream.Jenkinsfile Revert "Revert "[CI] add timeout to vm boot retries"" Jan 27, 2020
vagrant_box_defaults.rb VMs: bump development VM images Jan 31, 2020

README.rst

Cilium Logo

CII Best Practices Build Status Cilium pulls Join the Cilium slack channel Go Report Card GoDoc Read the Docs Apache licensed GPL licensed

Cilium is open source software for providing and transparently securing network connectivity and loadbalancing between application workloads such as application containers or processes. Cilium operates at Layer 3/4 to provide traditional networking and security services as well as Layer 7 to protect and secure use of modern application protocols such as HTTP, gRPC and Kafka. Cilium is integrated into common orchestration frameworks such as Kubernetes and Mesos.

A new Linux kernel technology called BPF is at the foundation of Cilium. It supports dynamic insertion of BPF bytecode into the Linux kernel at various integration points such as: network IO, application sockets, and tracepoints to implement security, networking and visibility logic. BPF is highly efficient and flexible. To learn more about BPF, read more in our extensive BPF and XDP Reference Guide.

https://cdn.rawgit.com/cilium/cilium/master/Documentation/images/cilium-arch.png

Stable Releases

The Cilium community maintains minor stable releases for the last three major Cilium versions. Older Cilium stable versions from major releases prior to that are considered EOL. Listed below are the actively maintained release branches along with their latest minor release, corresponding image pull tags and their release notes:

v1.6 2019-12-17 docker.io/cilium/cilium:v1.6.5 Release Notes General Announcement
v1.5 2019-12-17 docker.io/cilium/cilium:v1.5.11 Release Notes General Announcement
v1.4 2019-12-17 docker.io/cilium/cilium:v1.4.10 Release Notes General Announcement

Functionality Overview

Protect and secure APIs transparently

Ability to secure modern application protocols such as REST/HTTP, gRPC and Kafka. Traditional firewalls operates at Layer 3 and 4. A protocol running on a particular port is either completely trusted or blocked entirely. Cilium provides the ability to filter on individual application protocol requests such as:

  • Allow all HTTP requests with method GET and path /public/.*. Deny all other requests.
  • Allow service1 to produce on Kafka topic topic1 and service2 to consume on topic1. Reject all other Kafka messages.
  • Require the HTTP header X-Token: [0-9]+ to be present in all REST calls.

See the section Layer 7 Policy in our documentation for the latest list of supported protocols and examples on how to use it.

Secure service to service communication based on identities

Modern distributed applications rely on technologies such as application containers to facilitate agility in deployment and scale out on demand. This results in a large number of application containers to be started in a short period of time. Typical container firewalls secure workloads by filtering on source IP addresses and destination ports. This concept requires the firewalls on all servers to be manipulated whenever a container is started anywhere in the cluster.

In order to avoid this situation which limits scale, Cilium assigns a security identity to groups of application containers which share identical security policies. The identity is then associated with all network packets emitted by the application containers, allowing to validate the identity at the receiving node. Security identity management is performed using a key-value store.

Secure access to and from external services

Label based security is the tool of choice for cluster internal access control. In order to secure access to and from external services, traditional CIDR based security policies for both ingress and egress are supported. This allows to limit access to and from application containers to particular IP ranges.

Simple Networking

A simple flat Layer 3 network with the ability to span multiple clusters connects all application containers. IP allocation is kept simple by using host scope allocators. This means that each host can allocate IPs without any coordination between hosts.

The following multi node networking models are supported:

  • Overlay: Encapsulation-based virtual network spanning all hosts. Currently VXLAN and Geneve are baked in but all encapsulation formats supported by Linux can be enabled.

    When to use this mode: This mode has minimal infrastructure and integration requirements. It works on almost any network infrastructure as the only requirement is IP connectivity between hosts which is typically already given.

  • Native Routing: Use of the regular routing table of the Linux host. The network is required to be capable to route the IP addresses of the application containers.

    When to use this mode: This mode is for advanced users and requires some awareness of the underlying networking infrastructure. This mode works well with:

    • Native IPv6 networks
    • In conjunction with cloud network routers
    • If you are already running routing daemons

Load balancing

Distributed load balancing for traffic between application containers and to external services. The loadbalancing is implemented using BPF using efficient hashtables allowing for almost unlimited scale and supports direct server return (DSR) if the loadbalancing operation is not performed on the source host. Note: load balancing requires connection tracking to be enabled. This is the default.

Monitoring and Troubleshooting

The ability to gain visibility and to troubleshoot issues is fundamental to the operation of any distributed system. While we learned to love tools like tcpdump and ping and while they will always find a special place in our hearts, we strive to provide better tooling for troubleshooting. This includes tooling to provide:

  • Event monitoring with metadata: When a packet is dropped, the tool doesn't just report the source and destination IP of the packet, the tool provides the full label information of both the sender and receiver among a lot of other information.
  • Policy decision tracing: Why is a packet being dropped or a request rejected. The policy tracing framework allows to trace the policy decision process for both, running workloads and based on arbitrary label definitions.
  • Metrics export via Prometheus: Key metrics are exported via Prometheus for integration with your existing dashboards.
  • Hubble: An observability platform specifically written for Cilium. It provides service dependency maps, operational monitoring and alerting, and application and security visibility based on flow logs.

Integrations

Getting Started

What is eBPF and XDP?

Berkeley Packet Filter (BPF) is a Linux kernel bytecode interpreter originally introduced to filter network packets, e.g. for tcpdump and socket filters. The BPF instruction set and surrounding architecture has recently been significantly reworked with additional data structures such as hash tables and arrays for keeping state as well as additional actions to support packet mangling, forwarding, encapsulation, etc. Furthermore, a compiler back end for LLVM allows for programs to be written in C and compiled into BPF instructions. An in-kernel verifier ensures that BPF programs are safe to run and a JIT compiler converts the BPF bytecode to CPU architecture specific instructions for native execution efficiency. BPF programs can be run at various hooking points in the kernel such as for incoming packets, outgoing packets, system calls, kprobes, uprobes, tracepoints, etc.

BPF continues to evolve and gain additional capabilities with each new Linux release. Cilium leverages BPF to perform core data path filtering, mangling, monitoring and redirection, and requires BPF capabilities that are in any Linux kernel version 4.8.0 or newer (the latest current stable Linux kernel is 4.14.x).

Many Linux distributions including CoreOS, Debian, Docker's LinuxKit, Fedora, openSUSE and Ubuntu already ship kernel versions >= 4.8.x. You can check your Linux kernel version by running uname -a. If you are not yet running a recent enough kernel, check the Documentation of your Linux distribution on how to run Linux kernel 4.9.x or later.

To read up on the necessary kernel versions to run the BPF runtime, see the section Prerequisites.

https://cdn.rawgit.com/cilium/cilium/master/Documentation/images/bpf-overview.png

XDP is a further step in evolution and enables to run a specific flavor of BPF programs from the network driver with direct access to the packet's DMA buffer. This is, by definition, the earliest possible point in the software stack, where programs can be attached to in order to allow for a programmable, high performance packet processor in the Linux kernel networking data path.

Further information about BPF and XDP targeted for developers can be found in the BPF and XDP Reference Guide.

To know more about Cilium, it's extensions and use cases around Cilium and BPF take a look at Further Readings section.

Community

Slack

Join the Cilium Slack channel to chat with Cilium developers and other Cilium users. This is a good place to learn about Cilium, ask questions, and share your experiences.

Special Interest Groups (SIG)

See Special Interest groups for a list of all SIGs and their meeting times.

Weekly Developer meeting

  • The developer community is hanging out on zoom on a weekly basis to chat. Everybody is welcome.
  • Weekly, Monday, 8:00 am PT, 11:00 am ET, 5:00 pm CEST
  • Join zoom

License

The cilium user space components are licensed under the Apache License, Version 2.0. The BPF code templates are licensed under the General Public License, Version 2.0.

You can’t perform that action at this time.