Initial commit

Co-Authored-By: André Martins <[email protected]>
Co-Authored-By: Glib Smaga <[email protected]>
Co-Authored-By: John Fastabend <[email protected]>
Co-Authored-By: Michi Mutsuzaki <[email protected]>
Co-Authored-By: Sebastian Wicki <[email protected]>
Co-Authored-By: Sergey Generalov <[email protected]>
Co-Authored-By: Thomas Graf <[email protected]>

.github/workflows/unittests.yml

@@ -0,0 +1,27 @@
+name: Run unit tests
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+    - master
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+      with:
+        path: go/src/github.com/cilium/hubble
+    - uses: actions/setup-go@v1
+      with:
+        go-version: '1.13'
+    - name: Run unit tests
+      env:
+        GOPATH: /home/runner/work/hubble/go
+      run: |
+        export PATH=${PATH}:${GOPATH}/bin
+        go get -u github.com/golang/dep/cmd/dep
+        go get -u golang.org/x/lint/golint
+        dep check
+        make check-fmt lint test

.gitignore

@@ -0,0 +1,2 @@
+/hubble
+install/kubernetes/hubble.yaml

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing to Hubble
+
+## Contribution workflow
+
+Hubble uses GitHub for collaborative development. Please use GitHub issues to
+discuss proposals and use pull requests to suggest changes.
+
+## Slack
+
+Most Hubble developers are using Slack to communicate outside of GitHub. Join
+the `#hubble-devel` channel on [Cilium Slack](https://cilium.io/slack).
+
+## Code of conduct
+
+All members of the Hubble community must abide by the [Contributor
+Covenant](https://www.contributor-covenant.org/version/1/4/code-of-conduct)
+Code of Conduct. Only by respecting each other can we develop a productive,
+collaborative community. If you would like to report a violation of the code of
+contact, please contact any of the maintainers.
+
+## Development Requirements
+
+ * go dep >= 0.5.4 (`curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh`)

Dockerfile

@@ -0,0 +1,17 @@
+FROM docker.io/library/golang:1.12.8-alpine3.10 as builder
+WORKDIR /go/src/github.com/cilium/hubble
+RUN apk add --no-cache binutils git make \
+ && go get -d github.com/google/gops \
+ && cd /go/src/github.com/google/gops \
+ && git checkout -b v0.3.6 v0.3.6 \
+ && go install \
+ && strip /go/bin/gops
+COPY . .
+RUN make clean && make hubble
+
+FROM docker.io/library/alpine:3.10
+RUN addgroup -S hubble \
+ && apk add --no-cache bash curl jq
+COPY --from=builder /go/src/github.com/cilium/hubble/hubble /usr/bin
+COPY --from=builder /go/bin/gops /usr/bin
+CMD ["/usr/bin/hubble", "serve"]

Documentation/README.md

@@ -0,0 +1,16 @@
+# Hubble Documentation
+
+## Getting Started
+
+ * [Concepts](concepts.md)
+
+## Installation
+
+ * [Installation Instructions](installation.md)
+ * [Setting up Hubble Metrics with Grafana](../tutorials/deploy-hubble-and-grafana/)
+ * [Setting up Hubble with the service map](../tutorials/deploy-hubble-servicemap/)
+ * [Enabling DNS Visibility](dns_visibility.md)
+ * [Enabling HTTP Visibility](http_visibility.md)
+
+## Tutorials
+ * [Troubleshooting DNS resolution](../tutorials/troubleshooting-dns-resoluton/)

Documentation/concepts.md

@@ -0,0 +1,84 @@
+# What is Hubble?
+
+Hubble is a fully distributed networking and security observability platform
+for cloud native workloads. It is built on top of [Cilium] and [eBPF] to enable
+deep visibility into the communication and behavior of services as well as the
+networking infrastructure in a completely transparent manner.
+
+Hubble can answer questions such as:
+
+**Service dependencies & communication map:**
+ * What services are communicating with each other? How frequently? How does
+   the service dependency graph look like?
+ * What HTTP calls are being made? What Kafka topics does a service consume
+   from or produce to?
+
+**Operational monitoring & alerting:**
+ * Is any network communication failing? Why is communication failing? Is it
+   DNS? Is it an application or network problem? Is the communication broken on
+   layer 4 (TCP) or layer 7 (HTTP)?
+ * Which services have experienced a DNS resolution problems in the last 5
+   minutes? Which services have experienced an interrupted TCP connection
+   recently or have seen connections timing out? What is the rate of unanswered
+   TCP SYN requests?
+
+**Application monitoring:**
+ * What is the rate of 5xx or 4xx HTTP response codes for a particular service
+   or across all clusters?
+ * What is the 95th and 99th percentile latency between HTTP requests and
+   responses in my cluster? Which services are performing the worst? What is
+   the latency between two services?
+
+**Security observability:**
+ * Which services had connections blocked due to network policy? What services
+   have been accessed from outside the cluster? Which services have resolved a
+   particular DNS name?
+
+# Why Hubble?
+
+The Linux kernel technology [eBPF] is enabling visibility into systems and
+applications at a granularity and efficiency that was not possible before. It
+does so in a completely transparent way, without requiring the application to
+change or for the application to hide information. By building on top of
+[Cilium], Hubble can leverage [eBPF] for visibility. By relying on [eBPF], all
+visibility is programmable and allows for a dynamic approach that minimizes
+overhead while providing deep and detailed visibility where required. Hubble
+has been created and specifically designed to make best use of these new [eBPF]
+powers.
+
+# Hubble Architecture
+
+Hubble is a distributed platform and thus deployed on each worker node. It runs
+side by side to Cilium accesses the monitoring API of Cilium
+
+![Hubble Architecture](images/hubble_arch.png)
+
+In return, Hubble exposes metrics as well as flow query API. The following
+components make up Hubble:
+
+## Hubble Agent
+
+The Hubble agent is what runs on each worker node. It interacts with the Cilium
+agent running on the same node and serves the flow query API as well as the
+metrics.
+
+## Hubble Storage
+
+Hubble's storage layer consists of a in-memory storage able to store a fixed
+number of flows per node. The intent of the storage layer is to provide a brief
+history of flows for troubleshooting purposes.
+
+## Hubble CLI
+
+The Hubble CLI connects to the flow query API of a Hubble agent running on a
+particular node and allows to query the flows stored in the in-memory storage
+using server-side filtering.
+
+## Hubble UI
+
+The Hubble UI uses the flow query API to provide a graphical service
+communication map based on the observed flows. The service map is able to show
+service dependencies and visualize network and API calls on layer 3-7.
+
+[Cilium]: https://github.com/cilium/cilium
+[eBPF]: http://docs.cilium.io/en/stable/bpf/

Documentation/dns_visibility.md

@@ -0,0 +1,49 @@
+# Enabling DNS Visibility
+
+In order for Hubble to gain DNS visibility. Cilium must be configured to route
+DNS traffic via its own DNS proxy to extract DNS information.
+
+## With CiliumNetworkPolicy
+
+The following CiliumNetworkPolicy will redirect the traffic of all pods to
+CoreDNS via Cilium's DNS proxy to provide visibility. In order to not block any
+non-DNS traffic, the policy below also allows all other traffic. Adjust the
+policy accordingly if you are using other network policies.
+
+    apiVersion: cilium.io/v2
+    kind: CiliumNetworkPolicy
+    metadata:
+      name: dns-visibility
+    spec:
+      endpointSelector:
+        matchLabels: {}
+      egress:
+      - toEndpoints:
+        - matchLabels:
+            k8s:io.kubernetes.pod.namespace: kube-system
+            k8s:k8s-app: kube-dns
+        toPorts:
+        - ports:
+          - port: "53"
+            protocol: ANY
+          rules:
+            dns:
+            - matchPattern: '*'
+      - toFQDNs:
+        - matchPattern: '*'
+      - toEntities:
+        - cluster
+        - world
+
+All network policies are specific to a namespace. So the policy will have to be
+imported into each namespace separately.
+
+## With Pod Annotations
+
+An alternative to using CiliumNetworkPolicy, pods can be annotated to enable
+visibility:
+
+    kubectl annotate pod foo io.cilium.proxy-visibility="<Egress/53/UDP/DNS>"
+
+**Important:** Visibility via annotations is not compatible with network
+policies. You cannot use annotations while also using network policies.

Documentation/http_visibility.md

@@ -0,0 +1,44 @@
+# Enabling HTTP Visibility
+
+In order for Hubble to gain HTTP visibility. Cilium must be configured to route
+HTTP traffic via a Cilium managed Envoy proxy to extract HTTP information.
+
+## With CiliumNetworkPolicy
+
+The following CiliumNetworkPolicy will redirect the traffic of all pods on port
+80 to the HTTP proxy. In order to not block any non-HTTP traffic, the policy
+also allows all other traffic. Adjust the policy accordingly if you are using
+other network policies.
+
+    apiVersion: cilium.io/v2
+    kind: CiliumNetworkPolicy
+    metadata:
+      name: http-visibility
+    spec:
+      endpointSelector:
+        matchLabels: {}
+      ingress:
+      - fromEntities:
+        - all
+        toPorts:
+        - ports:
+          - port: "80"
+            protocol: TCP
+          rules:
+            http:
+            - {}
+      - fromEntities:
+        - all
+
+All network policies are specific to a namespace. So the policy will have to be
+imported into each namespace separately.
+
+## With Pod Annotations
+
+An alternative to using CiliumNetworkPolicy, pods can be annotated to enable
+visibility:
+
+    kubectl annotate pod foo io.cilium.proxy-visibility="<Ingress/80/TCP/HTTP>"
+
+**Important:** Visibility via annotations is not compatible with network
+policies. You cannot use annotations while also using network policies.

Documentation/installation.md

@@ -0,0 +1,58 @@
+# Installation of Hubble
+
+## Requirements
+
+ * [Cilium] Recommended: >= 1.7.0-rc1, Minimal: >= 1.6.3
+ * [Helm]
+ * [Kubernetes]
+
+## Install Cilium
+
+Install Cilium using the [Install instructions]. If you need help to
+troubleshoot installation issues, ping us on the [Cilium Slack].
+
+### Enable Datapath Aggregation
+
+Hubble relies on on aggregation of events in the eBPF datapath of Cilium.
+Please enable datapath aggregation by setting the value of
+`monitor-aggregation` in the `cilium-config` ConfigMap to `medium` or higher:
+
+    monitor-aggregation: medium
+
+This is the default setting for new installs of Cilium 1.6 or later.
+
+## Install Hubble
+
+Generate the deployment files using [Helm] and deploy it:
+
+    cd install/kubernetes
+    helm template hubble \
+        --namespace kube-system \
+        --set metrics.enabled="{dns,drop,tcp,flow,port-distribution,icmp,http}" \
+        > hubble.yaml
+
+Configure Hubble (Optional):
+
+ * [Configure metrics](metrics.md)
+
+Deploy Hubble:
+
+    kubectl apply -f hubble.yaml
+
+## Optional: Enable L7 Visibility
+
+ * [Enable DNS Visibility](dns_visibility.md)
+ * [Enable HTTP Visibility](http_visibility.md)
+
+## Next Steps
+
+ * [Configure Metrics with Prometheus & Grafana](../tutorials/deploy-hubble-and-grafana/)
+ * [Configure the service map UI](../tutorials/deploy-hubble-servicemap/)
+ * [Explore Flow Queries](../tutorials/explore-flow-queries/)
+ * [More Tutorials](../tutorials/README.md)
+
+[Install instructions]: http://docs.cilium.io/en/stable/gettingstarted/#installation
+[Cilium Slack]: https://slack.cilium.io/
+[Helm]: https://helm.sh/
+[Kubernetes]: https://kubernetes.io/
+[Cilium]: https://github.com/cilium/cilium

Documentation/metrics.md

@@ -0,0 +1,66 @@
+# Metrics
+
+Hubble provides extensive metrics to monitor network & applications behavior
+with respect to connectivity and security.
+
+## Installation
+
+While following the [installation instructions](installation.md), enable
+metrics with the `--set metrics.enabled`:
+
+    helm template hubble \
+        --namespace kube-system \
+        --set metrics.enabled="{dns:query;ignoreAAAA,drop,tcp,flow,port-distribution,icmp,http}" \
+        > hubble.yaml
+    kubectl apply -f hubble.yaml
+
+## Metric Options
+
+### Common Options
+
+#### Source & Destination Context
+
+Most metrics can be configured to source and/or destination context as a label.
+The options are called `sourceContext` and `destinationContext`. The possible
+values are:
+
+| Option Value  | Description                         |
+|---------------|-------------------------------------|
+| identity      | All Cilium security identity labels |
+| namespace     | Namespace name                      |
+| pod           | Pod name                            |
+
+### DNS
+
+| Option Key | Option Value  | Description                         |
+|------------|---------------|-------------------------------------|
+| query      | N/A           | Include the query as label "query"  |
+| ignoreAAAA | N/A           | Ignore any AAAA requests/responses  |
+
+## Example Grafana Dashboard
+
+The following is an example dashboard. The corresponding [JSON definition].
+
+### General Processing
+
+![General Processing](images/general_processing.png)
+
+### Networking
+
+![Networking](images/network.png)
+![TCP](images/tcp.png)
+![ICMP](images/icmp.png)
+
+### DNS
+
+![DNS](images/dns.png)
+
+### HTTP
+
+![HTTP](images/http.png)
+
+### Network Policy
+
+![Network Policy](images/network_policy.png)
+
+[JSON definition]: ./tutorials/deploy-hubble-and-grafana/grafana.json