cyphernetes

README

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;

How?

Cyphernetes is a Cypher-inspired query language for Kubernetes. Cypher is a mixture of ASCII-art, SQL and JSON that lets us express graph operations in an efficeint way that is also fun and creative. Cyphernetes extends Cypher with Kubernetes-specific syntax and features. It allows you to query and mutate Kubernetes resources in a natural way, 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. Creating a Cyphernetes DynamicOperator using the cyphernetes-operator to define powerful Kubernetes workflows on-the-fly
5. Using the Cyphernetes API in your own Go programs. See our integration guide for more details.

To learn more about how to use Cyphernetes, refer to these documents:

• LANGUAGE.md - a crash-course in Cyphernetes language syntax
• CLI.md - a guide to using Cyphernetes shell, query command and macros
• OPERATOR.md - a guide to using Cyphernetes DynamicOperator

Examples (from the Cyphernetes Shell)

# 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
│       └── ...
├── operator # The operator
│   └── ...
├── pkg # The core Cyphernetes package (parser and engine behind the language features)
│   └── core
│       └── ...
│   └── provider # An interface for different backend implementations and a default implementation for an api-server client
│       └── ...
├── 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
• Enhancements, Bug fixes - James Kim
• Enhancements, Bug fixes - Naor Peled