Kubernetes is built on the foundation of APIs and abstraction, and Calico leverages its extensibility to deliver network security and observability in both its commercial and open source versions. APIs are the special sauce that help automate and operationalize your Kubernetes platforms as part of a CI/CD pipeline and other GitOps workflows.
Calico OSS 3.30, introduces numerous battle-tested observability and security tools from our commercial editions. This includes the following key features:
- Goldmane – A gRPC-based API for accessing and capturing flow logs and policy evaluation metrics
- Whisker – A web-based tool for viewing and filtering flow logs to troubleshoot connectivity issues and author and maintain Calico network security policies
- GlobalStagedNetworkPolicy and StagedNetworkPolicy – New custom resources that allow you to audit the behavior of a new policy before you actively enforce it
- Calico Ingress Gateway – Our 100% upstream, enterprise-ready implementation of the Gateway API that is based on Envoy Gateway
- Calico Cloud ready – Every OSS cluster includes the required components to connect to a stateless, read-only, and free version of Calico Cloud
You may know about the Calico REST API, which allows you to manage Calico resources, such as Calico network policy, Calico IPAM configurations and much more, but did you know there are two additional gRPC APIs available that allow you to take this integration even further?
In this blog, we will focus on one of these gRPC-based APIs, codenamed Goldmane—the new Calico API for interacting with network observability information. There is an interactive workshop at the end of this post that allows you to run the commands from your browser, and you can also use this GitHub repository if you like to learn how to interact with Goldmane in Python, and Golang.
Try Whisker
Before we get started I’d like to highlight that Calico observability comes with a new GUI called Calico Whisker, a simple but powerful solution that allows you to navigate, filter and observe your network flows.
Whisker is the recommended way for anyone who wants to access Flows generated by Calico in their cluster. It is also worth noting that we offer a free forever membership to our open source users with calicocloud.io that adds a lot more features to their arsenal.
Whisker Makes Observability Easy; Goldmane Makes It Customizable
If you are still interested to learn about gRPC and APIs then you are in the right place. Whisker is a great tool for most use cases but if you want to go deeper with custom workflows, Goldmane has you covered.
A direct channel to Goldmane allows you to filter, manipulate, export, and parse this information in your preferred environment.
Note: This blog post works alongside the accompanying GitHub repository, allowing you to run the example, gain hands-on experience in building a gRPC client for Goldmane, and establish a foundation for writing client for any software implementing gRPC services.
Installing Goldmane
Calico Goldmane is an aggregator that collects network flows and publishes them to its clients using secure gRPC channels. These channels are secured using certificates that are issued by the Tigera operator. Each client needs to be trusted using a signed certificate before they can communicate with Goldmane. The certificates are stored as Kubernetes secrets in your cluster.
To enable Goldmane in your environment you will need to create the following manifest which tells the Tigera operator to enable Goldmane and flows for your environment:
apiVersion: operator.tigera.io/v1
kind: Goldmane
metadata:
name: defaultThe Goldmane installation process adds any required certificates to the cluster and it also creates the deployment and services that are necessary for cluster components to talk to Goldmane.
Similar to other Calico resources, you can use the operator to verify Goldmane installation process:
kubectl get tigerastatus goldmaneYou can also use the following commands to see the actual resources that are part of Goldmane installation bundle:
kubectl get secret -n calico-system goldmane-key-pair
kubectl get svc -n calico-system goldmane
kubectl get deployment -n calico-system goldmanegRPC 101
To use gRPC services you need to know what services are supported by the server. There are two ways to find out what a server offers:
- gRPC reflection
- gRPC proto file
Currently Goldmane uses a protobuf file, and this file can be found in the Calico repository. Since gRPC implements its own standard we need a client that can communicate and understand gRPC. For this post we are going to use gRPCurl a simple command line utility that can be used to communicate with any gRPC server.
Deploying gRPCurl
Network flows are sensitive information and that is why we have taken security measures such as mTLS and default network security policies to make sure this information is only accessible to authorized users. Now, if someone has access to the right certificates and is permitted by network security policies to access goldmane they can use the ClusterIP service that is created by Tigera operator to access Goldmane inside the cluster.
Use the following command to create a gRPCurl deployment in your cluster:
kubectl create -f https://raw.githubusercontent.com/frozenprocess/calico-goldmane-grpc-examples/refs/heads/main/grpcurl/grpcurl.yamlAfter gRPCurl deployment is complete we can access it using kubectl.
Use the following command to access the gRPCurl deployment pod:
kubectl exec -it -n calico-system deployment/grpcurl -- /bin/shUse the following command to download the api.proto file:
wget https://raw.githubusercontent.com/projectcalico/calico/refs/heads/master/goldmane/proto/api.protoAfter downloading the api.proto file from the Calico repository we can use the gRPCurl to list the services that Goldmane offers.
Use the following command to see the services that Goldmane offers:
grpcurl -proto api.proto goldmane.calico-system.svc:7443 listGoldmane Services
At the time of writing this article, Goldmane implements three services:
- FlowCollector: used by Calico Felix (or any other program) to publish network flow information to Goldmane.
- Flows: which can be used by our client to get the network flows cached in Goldmane memory.
- Statistics: Which offers a detailed tally about your cluster policies with information such as packet allowed or denied.
Each of these services have functions that can be invoked, but the main ones of interest will be the Flows and Statistics APIs (unless you’re modifying Felix itself!).
For example, let’s go ahead and check what functions are available within the Flows services.
Use the following command to check the functions available:
grpcurl -proto api.proto goldmane.calico-system.svc:7443 describe goldmane.FlowsYou should see a result similar to the following:
service Flows {
// FilterHints can be used to discover available filter criteria, such as
// Namespaces and source / destination names. It allows progressive filtering of criteria based on
// other filters. i.e., return the flow destinations given a source namespace.
// Note that this API provides hints to the UI based on past flows and other values may be valid.
rpc FilterHints ( .goldmane.FilterHintsRequest ) returns ( .goldmane.FilterHintsResult );
// List is an API call to query for one or more Flows.
rpc List ( .goldmane.FlowListRequest ) returns ( .goldmane.FlowListResult );
// Stream is an API call to return a long running stream of new Flows as they are generated.
rpc Stream ( .goldmane.FlowStreamRequest ) returns ( stream .goldmane.FlowResult );
}Now let’s query one of the “List” function and see what happens
grpcurl -proto api.proto goldmane.calico-system.svc:7443 goldmane.Flows/ListYou should see an error similar to the following:
Failed to dial target host "goldmane.calico-system.svc:7443": tls: failed to verify certificate: x509: certificate signed by unknown authorityIt’s usually a certificate issue
You might be wondering why I got this error? If you recall earlier we talked about Goldmane expecting mTLS from its client, and this error message verifies that our service is in fact expecting a certificate as a form of authentication.
To fix this issue we can use the certificates that are mounted in this deployment.
Use the following command to scrape the information:
grpcurl -proto api.proto -cacert /etc/goldmane/certs/tls.crt -cert /etc/goldmane/certs/tls.crt -key /etc/goldmane/certs/tls.key goldmane.calico-system.svc:7443 goldmane.Flows/ListImportant note: In order to keep this story short we used the certificates that are issued by the Tigera operator for Goldmane. However, it is recommended that you implement your own certificates and use individual certificates for each application that needs to connect to Calico components. Use this guide to learn more about managing Calico certificates.
Querying flows and metrics
To walk through some examples of querying for flows metrics, try Goldmane in your browser in this interactive workshop.
Once you are comfortable with the APIs, you can begin to query Goldmane in your own cluster, integrate these data sources into your own tooling, or build a custom application that enables you and your team to better understand network connectivity and policy evaluation.
Conclusion
Calico v3.30 marks our biggest open source release yet, bringing a powerful suite of network observability tools, security resources and other enterprise grade features to every Kubernetes user.
At the heart of this release is Goldmane, a gRPC-based API that unlocks deep, real-time insights into your cluster’s network behavior.
By integrating directly with Goldmane, you move beyond dashboards and into full control of your observability pipeline. Whether you’re debugging a complex network policy, building a custom analytics tool, or feeding traffic data into a SIEM, Goldmane gives you the flexibility to make it happen programmatically, securely, and on your terms.
With Goldmane, you can:
- Query real-time flow data using fine-grained filters
- Export logs to external systems for long-term storage or analysis
- Monitor policy enforcement across namespaces with detailed stats
- Build custom tools and automations using gRPC clients in Go, Python, or any language you prefer
In short, Calico v3.30 puts enterprise-grade observability in the hands of every Kubernetes operator—no black boxes, no vendor lock-in, just pure, open-source control.
Ready to try Whisker? Try our interactive Observability workshop.
