Repository files navigation

spicedb-kubeapi-proxy is a proxy that runs in between clients and the kubeapiserver that can authorize requests and filter responses using an embedded orremote SpiceDB.

Theissues trackthe current state of the project, but the primary goals before 1.0 are:

• Stabilizing the API for configuring proxy rules
• Gaining operational experience and proving the system in production

• 🚀 Authorize any request to the Kubernetes cluster based on data in SpiceDB
• ✨ Filter responses (including lists) from the kubernetes cluster based on data in SpiceDB
• 🌶️ Write to both SpiceDB and Kubernetes in a single transaction (durably)
• 🪩 Use different user authentication in the proxy than you do in the base cluster
• 🎉 No syncing between SpiceDB and Kubernetes is required
• 🔒 Does not require admin permissions in the base cluster
• 📦 Run the proxy in-cluster or out-of-cluster
• 📡 Use an embedded SpiceDB or a remote SpiceDB
• 📜 Configure with a variety of different rules to control access to the cluster
• 📊 Metrics and tracing support

The proxy authenticates itself with the downstream kube-apiserver (client certsif running out-of-cluster, service account token if running in-cluster).The proxy is configured with a set of rules that define how to authorize requestsand how to filter responses by communicating with SpiceDB.

There are three basic types of rule:

• Check rules: these are used to authorize whether a request is allowed toproceed at all. For example, a rule might say that a user can only list podsin a namespacefoo if they have anamespace:foo#list@user:alice permissionin SpiceDB.
• Filter rules: these are used to filter the response from the kube-apiserverbased on the data in SpiceDB. For example, a rule might say that a user canonly see the pods in namespacefoo if there are corresponding relationshipsin SpiceDB that enumerate the allowed pods, likepod:foo/a#view@user:aliceandpod:foo/b#view@user:alice. In this example,alice would see podsaandb in namespacefoo, but no others.
• Update Relationship rules: these are used to write/delete data inSpiceDB based on the request that the proxy is authorizing. For example,ifalice creates a new podc in namespacefoo, a rule can determinethat a relationship should be written to SpiceDB that grants ownership,i.e.pod:foo/a#view@user:alice. Rules support both single relationshiptemplates andtupleSet expressions that can generate multiple relationshipsdynamically based on resource content (e.g., one relationship per containerin a Deployment).

Rules often work in tendem; for example, aCheck rule might authorize a requestto list pods in a namespace, and aFilter rule might further restrict theresponse to only include certain pods.

Note that the proxy does not assume anything about the structure of the data inSpiceDB. It is up to the user to define the data in SpiceDB and the rules thatthe proxy uses to authorize and filter requests.

The proxy rejects any request for which it doesn't find a matching rule.

This project usesmage to offer various development-related commands.

# run to get all available commandsbrew install magemage

Runs both unit and e2e tests

mage test:all

mage dev:up

This brings a development kind cluster with the proxy running in it with an embedded SpiceDB.A developmentdev.kubeconfig file will be generated so that you can configure your clientto talk to either the proxy or the upstream kind cluster.

Examples:

kubectl --kubeconfig$(pwd)/dev.kubeconfig --context proxy get namespace

or

export KUBECONFIG=$(pwd)/dev.kubeconfigkubectx proxykubectl get namespace

You can also talk to the upstream cluster to verify things by switching to the context nameadmin:

kubectl --kubeconfig$(pwd)/dev.kubeconfig --context admin get namespace

To clean everything up just run:

mage dev:clean

Sometimes you may want to debug the proxy. The easiest way would be to spin up the development environment withmage dev:upand then run the proxy targeting it as upstream:

mage dev:run

Alternatively if you want to run with delve or your IDE, do:

go run ./cmd/spicedb-kubeapi-proxy/main.go --bind-address=127.0.0.1 --secure-port=8443 --backend-kubeconfig$(pwd)/spicedb-kubeapi-proxy.kubeconfig --client-ca-file$(pwd)/client-ca.crt --requestheader-client-ca-file$(pwd)/client-ca.crt --spicedb-endpoint embedded://

You'll then be able to reach out to your local proxy instance with the contextlocal. Note TLS certs areauto-generated by Kube so--insecure-skip-tls-verify must be provided.

export KUBECONFIG=$(pwd)/dev.kubeconfigkubectx proxykubectl --insecure-skip-tls-verify get namespace

The proxy supports an embedded mode that allows direct in-process connections without network overhead.This is useful for applications that want to embed the proxy functionality directly.

In embedded mode:

• No TLS/network layer - requests go directly through handlers
• Authentication via configurable HTTP headers (programmatic configuration only)
• High performance with sub-microsecond latency
• Compatible with standard HTTP clients and kubernetes client-go

Embedded mode is designed for programmatic use when embedding the proxy in Go applications:

// Basic embedded mode setupopts:=proxy.NewOptions(proxy.WithEmbeddedProxy,proxy.WithEmbeddedSpiceDBEndpoint)// Complete configurationcompletedConfig,_:=opts.Complete(ctx)proxySrv,_:=proxy.NewServer(ctx,completedConfig)// Get client with automatic authentication headersclient:=proxySrv.GetEmbeddedClient(proxy.WithUser("alice"),proxy.WithGroups("developers","admin"),proxy.WithExtra("department","engineering"),)// Or get a basic client without authenticationbasicClient:=proxySrv.GetEmbeddedClient()

Seedocs/embedding.md for detailed usage examples.