cyphernetes

Cyphernetes turns this:

# Delete all pods that are not running

kubectl get pods --all-namespaces --field-selector 'status.phase!=Running' \
-o 'custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name' \
--no-headers | xargs -L1 -I {} bash -c 'set -- {}; kubectl delete pod $2 -n $1'

Into this:

// Do the same thing!

MATCH (p:Pod)
WHERE p.status.phase != "Running"
DELETE p;

Documentation

For comprehensive documentation, visit our official documentation site at https://cyphernet.es/docs.

How?

Cyphernetes is a Cypher-inspired query language for Kubernetes. A mixture of ASCII-art, SQL and JSONPath, it lets the user express Kubernetes graph operations in a fun and creative way. Cyphernetes works out-of-the-box with your CRDs, supports multi-cluster queries, and more.

There are multiple ways to run Cyphernetes queries:

1. Using the web client by running cyphernetes web from your terminal, then visiting http://localhost:8080
2. Using the interactive shell by running cyphernetes shell in your terminal
3. Running a single query from the command line by running cyphernetes query "your query" - great for scripting and CI/CD pipelines
4. Using the kubectl cypher plugin (install using Krew or download from latest release)
5. Creating a Cyphernetes DynamicOperator using the cyphernetes-operator to define powerful Kubernetes workflows on-the-fly
6. Using the Cyphernetes API in your own Go programs.

Examples

// Get the desired and running replicas for all deployments
MATCH (d:Deployment)
RETURN d.spec.replicas AS desiredReplicas, 
       d.status.availableReplicas AS runningReplicas;

{
  "d": [
    {
      "desiredReplicas": 2,
      "name": "coredns",
      "runningReplicas": 2
    }
  ]
}

Query executed in 9.081292ms

Cyphernetes' superpower is understanding the relationships between Kubernetes resource kinds. This feature is expressed using the arrows (->) you see in the example queries. Relationships let us express connected operations in a natural way, and without having to worry about the underlying Kubernetes API:

// This is similar to `kubectl expose`
MATCH (d:Deployment {name: "nginx"})
CREATE (d)->(s:Service);

Created services/nginx

Query executed in 30.692208ms

Get Cyphernetes

Using Homebrew:

brew install cyphernetes

Using go:

go install github.com/avitaltamir/cyphernetes/cmd/cyphernetes@latest

Alternatively, grab a binary from the Releases page.

Development

The Cyphernetes monorepo is a multi-package project that includes the core Cyphernetes Go package, a CLI, a web client, and an operator.

.
├── cmd # The CLI (this is where the cyphernetes binary lives)
│   └── cyphernetes
│       └── ...
├── docs # The cyphernet.es website
│   └── ...
├── operator # The operator
│   └── ...
├── pkg
│   └── core # The core Cyphernetes package (parser and engine behind the language features)
│   └── provider # An interface for different backend implementations
│       └── apiserver # A client for the Kubernetes API server
├── web # The web client
│   └── src
│       └── ...

Prerequisites

• Go (Latest)
• Make (for running make commands)
• NodeJS (Latest, for building the web client)
• pnpm (9+, for building the web client)

Getting Started

To get started with development:

Clone the repository:

git clone https://github.com/avitaltamir/cyphernetes.git

Navigate to the project directory:

cd cyphernetes

Building the Core Project

Running make will build the operator manifests and web client static assets, then build the binary and run the tests.

make

Building the Web Client

make web-build

Building the Operator

make operator-build

Contributing

Contributions are welcome! Please feel free to submit pull requests, open issues, and provide feedback.

License

Cyphernetes is open-sourced under the Apache 2.0 license. See the LICENSE file for details.

Acknowledgments

• Thanks to Neo4j for the inspiration behind the query language.
• Thanks to ggerganov for the dot-to-ascii project - it's the webserver that serves the ASCII art on https://ascii.cyphernet.es in case you want to host your own.
• Thanks to shlomif for the graph-easy project - it's the package that actually converts the dot graphs into ASCII art used by dot-to-ascii.
• Thanks anthonybrice and chenrui333 for getting us into Homebrew.

Authors

• Initial work - Avital Tamir
• Project maintainer - Naor Peled
• Enhancements, Bug fixes and Improvements:
  • James Kim
  • Vinicius Artur
  • Noé Tarbouriech
  • Michael Darin
  • Anand Francis Joseph