spicedb

module
v1.19.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 30, 2023 License: Apache-2.0

README

SpiceDB

CII Best Practices Container Image Docs Discord Server Twitter

SpiceDB is an open source, Google Zanzibar-inspired, database system for creating and managing security-critical application permissions.

Developers create a schema that models their permissions requirements and use any of the official or community maintained client libraries to apply the schema to the database, insert data into the database, and query the data to efficiently check permissions in their applications.

Features that distinguish SpiceDB from other systems include:

Have questions? Ask in our Discord.

Want to learn more about the inspiration for SpiceDB? We've annotated Google's Zanzibar Paper with our own commentary.

Looking to contribute? See CONTRIBUTING.md.

You can find issues by priority: Urgent, High, Medium, Low, Maybe. There are also good first issues.

Getting Started

Installing the binary

Binary releases are available for Linux, macOS, and Windows on AMD64 and ARM64 architectures.

Homebrew users for both macOS and Linux can install the latest binary releases of SpiceDB and zed using the official tap:

brew install authzed/tap/spicedb authzed/tap/zed

Debian-based Linux users can install SpiceDB packages by adding a new APT source:

sudo echo "deb [trusted=yes] https://apt.fury.io/authzed/ /" > /etc/apt/sources.list.d/authzed-fury.list
sudo apt update && apt install spicedb

RPM-based Linux users can install SpiceDB packages by adding a new YUM repository:

sudo cat << EOF >> /etc/yum.repos.d/Authzed-Fury.repo
[authzed-fury]
name=AuthZed Fury Repository
baseurl=https://yum.fury.io/authzed/
enabled=1
gpgcheck=0
EOF
sudo dnf install spicedb
Running a container

Container images are available for AMD64 and ARM64 architectures on the following registries:

Docker users can run the latest SpiceDB container with the following:

docker run --rm -p 50051:50051 authzed/spicedb serve --grpc-preshared-key "somerandomkeyhere"

SpiceDB containers use Chainguard Images to ship the bare minimum userspace which is a huge boon to security, but can complicate debugging. If you want to execute a user session into a running SpiceDB container and install packages, you can use one of our debug images.

Appending -debug to any tag will provide you an image that has a userspace with debug tooling:

docker run --rm -ti --entrypoint sh authzed/spicedb:latest-debug

Containers are also available for each git commit to the main branch under ${REGISTRY}/authzed/spicedb-git:${COMMIT}.

Deploying to Kubernetes

Production Kubernetes users should be relying on a stable release of the SpiceDB Operator. The Operator enforces not only best practices, but orchestrates SpiceDB updates without downtime.

If you're only experimenting, feel free to try out one of our community-maintained examples for testing SpiceDB on Kubernetes:

kubectl apply -f https://raw.githubusercontent.com/authzed/examples/main/kubernetes/example.yaml
Developing your own schema

You can try both SpiceDB and zed entirely in your browser on the Playground thanks to the power of WebAssembly.

If you don't want to start with the examples loadable from the Playground, you can follow a guide for developing a schema or review the the schema language design documentation.

To get a quick idea of schema development, you can watch the creators of SpiceDB writing a schema for GitHub:

Modeling GitHub YouTube Video Thumbnail

Trying out the API

For debugging or getting started, we recommend installing zed, the official command-line client. The Playground also has a tab for experimenting with zed all from within your browser.

When it's time to write code, we recommend using one of the existing client libraries whether it's official or community-maintained.

Because every millisecond counts, we recommend using libraries that leverage the gRPC API for production workloads.

To get an understanding of integrating an application with SpiceDB, you can follow the Protecting Your First App guide or review API documentation on the Buf Registry or Postman.

Acknowledgements

SpiceDB is a community project fueled by contributions from both organizations and individuals. We appreciate all contributions, large and small, and would like to thank all those involved.

In addition, we'd like to highlight a few notable contributions:

  • The GitHub Authorization Team for implementing and contributing the MySQL datastore

Directories

Path Synopsis
cmd
e2e module
internal
datastore/options
Code generated by github.com/ecordell/optgen.
Code generated by github.com/ecordell/optgen.
dispatch/combined
Package combined implements a dispatcher that combines caching, redispatching and optional cluster dispatching.
Package combined implements a dispatcher that combines caching, redispatching and optional cluster dispatching.
gateway
Package gateway implements an HTTP server that forwards JSON requests to an upstream SpiceDB gRPC server.
Package gateway implements an HTTP server that forwards JSON requests to an upstream SpiceDB gRPC server.
telemetry
Package telemetry implements a client for reporting telemetry data used to prioritize development of SpiceDB.
Package telemetry implements a client for reporting telemetry data used to prioritize development of SpiceDB.
pkg
cmd
cmd/datastore
Code generated by github.com/ecordell/optgen.
Code generated by github.com/ecordell/optgen.
cmd/server
Code generated by github.com/ecordell/optgen.
Code generated by github.com/ecordell/optgen.
cmd/testserver
Code generated by github.com/ecordell/optgen.
Code generated by github.com/ecordell/optgen.
schemadsl/dslshape
Package dslshape defines the types representing the structure of schema DSL.
Package dslshape defines the types representing the structure of schema DSL.
schemadsl/parser
parser package defines the parser for the Authzed Schema DSL.
parser package defines the parser for the Authzed Schema DSL.
testutil
Package testutil implements various utilities to reduce boilerplate in unit tests a la testify.
Package testutil implements various utilities to reduce boilerplate in unit tests a la testify.
zedtoken
Package zedtoken converts decimal.Decimal to zedtoken and vice versa
Package zedtoken converts decimal.Decimal to zedtoken and vice versa
tools
analyzers Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL