search

AvitalTamir / cyphernetes

A Kubernetes Query Language
https://cyphernet.es
Apache License 2.0
527 stars 11 forks source link

readme

Screenshot 2024-10-15 at 0 03 00

Cyphernetes Logo (3 5 x 1 2 in)

Go Report Card Go Reference License Artifact Hub

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

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

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. Additionally, there's a grammer folder which contains the yacc grammar for generating the parser.

.
├── cmd # The CLI (this is where the cyphernetes binary lives)
│   └── cyphernetes
│       └── ...
├── grammar # The yacc grammar for generating the parser
│   └── ...
├── operator # The operator
│   └── ...
├── pkg # The core Cyphernetes package (and parser)
│   └── parser
│       └── ...
├── web # The web client
│   └── src
│       └── ...

Prerequisites

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

Authors