### Install Cyphernetes using Go Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/installation.md Install Cyphernetes using Go's install command. ```bash go install github.com/avitaltamir/cyphernetes/cmd/cyphernetes@latest ``` -------------------------------- ### Verify Cyphernetes Installation Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/installation.md Check that Cyphernetes is installed correctly by displaying its version. ```bash cyphernetes --version ``` -------------------------------- ### Build Cyphernetes from Source Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/installation.md Build Cyphernetes from source. Requires Go (Latest), Make, NodeJS (Latest), and pnpm (9+). The binary will be available in the dist/ directory. ```bash # Clone the repository git clone https://github.com/avitaltamir/cyphernetes.git # Navigate to the project directory cd cyphernetes # Build the project make # The binary will be available in the dist/ directory sudo mv dist/cyphernetes /usr/local/bin/cyphernetes ``` -------------------------------- ### Install kubectl-cypher with krew Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Recommended installation method. Requires krew to be installed first. ```bash kubectl krew install cypher ``` -------------------------------- ### Start local development server with yarn start Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/README.md Starts a local development server and opens a browser window. Most changes are reflected live without restarting the server. ```bash $ yarn start ``` -------------------------------- ### Download Cyphernetes Binary for Linux Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/installation.md Download and install the pre-compiled binary for Linux (AMD64 and ARM64). ```bash # For AMD64 curl -LO https://github.com/avitaltamir/cyphernetes/releases/latest/download/cyphernetes-linux-amd64 chmod +x cyphernetes-linux-amd64 sudo mv cyphernetes-linux-amd64 /usr/local/bin/cyphernetes # For ARM64 curl -LO https://github.com/avitaltamir/cyphernetes/releases/latest/download/cyphernetes-linux-arm64 chmod +x cyphernetes-linux-arm64 sudo mv cyphernetes-linux-arm64 /usr/local/bin/cyphernetes ``` -------------------------------- ### Download Cyphernetes Binary for macOS Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/installation.md Download and install the pre-compiled binary for macOS (AMD64 and ARM64). ```bash # For AMD64 curl -LO https://github.com/avitaltamir/cyphernetes/releases/latest/download/cyphernetes-darwin-amd64 chmod +x cyphernetes-darwin-amd64 sudo mv cyphernetes-darwin-amd64 /usr/local/bin/cyphernetes # For ARM64 (Apple Silicon) curl -LO https://github.com/avitaltamir/cyphernetes/releases/latest/download/cyphernetes-darwin-arm64 chmod +x cyphernetes-darwin-arm64 sudo mv cyphernetes-darwin-arm64 /usr/local/bin/cyphernetes ``` -------------------------------- ### Deployment Management Queries in Cyphernetes Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/examples.md Examples for working with deployments: scale replicas, find mismatched replicas, list pods for a deployment, and update container images. ```graphql // Scale deployments in a namespace MATCH (d:Deployment {namespace: "production"}) SET d.spec.replicas = 3; // Find deployments with mismatched replicas MATCH (d:Deployment) WHERE d.status.availableReplicas < d.spec.replicas RETURN d.metadata.name, d.spec.replicas, d.status.availableReplicas; // List pods for a specific deployment MATCH (d:Deployment {app: "my-app"})->(:ReplicaSet)->(p:Pod) RETURN p.metadata.name, p.status.phase; // Update container images MATCH (d:Deployment {app: "my-app"}) SET d.spec.template.spec.containers[0].image = "nginx:latest" RETURN d.metadata.name; ``` -------------------------------- ### Install Cyphernetes via Go Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md Installs the Cyphernetes CLI using the Go toolchain. Requires Go to be installed and configured. ```bash go install github.com/avitaltamir/cyphernetes/cmd/cyphernetes@latest ``` -------------------------------- ### Run Cyphernetes Single Query Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/installation.md Execute a single Cypher query against Kubernetes resources. ```bash cyphernetes query "MATCH (p:Pod) RETURN p" ``` -------------------------------- ### Start the Cyphernetes web server Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/cli.md Run `cyphernetes web` to start a web server. Visit `http://localhost:8080` in your browser to interact with Cyphernetes. ```bash cyphernetes web ``` -------------------------------- ### Install Cyphernetes via Homebrew Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md Installs the Cyphernetes CLI using Homebrew. Requires Homebrew to be installed on your system. ```bash brew install cyphernetes ``` -------------------------------- ### Combining ORDER BY, SKIP, and LIMIT for pagination Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Combine ORDER BY, SKIP, and LIMIT to implement pagination. This example gets the second page of deployments (items 11-20). ```graphql // Get the second page of deployments (items 11-20) MATCH (d:Deployment) RETURN d.metadata.name AS name, d.spec.replicas AS replicas ORDER BY name SKIP 10 LIMIT 10 ``` -------------------------------- ### Install dependencies with yarn Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/README.md Run this command in the website directory to install all required dependencies for the Docusaurus site. ```bash $ yarn ``` -------------------------------- ### Basic kubectl-cypher usage examples Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Shows common query patterns: basic pod query, namespace selection, all namespaces, context selection, YAML output, and dry-run mode. ```bash # Basic pod query kubectl cypher "MATCH (p:Pod) RETURN p" # Query with namespace kubectl cypher -n kube-system "MATCH (p:Pod) RETURN p.metadata.name" # Query all namespaces kubectl cypher -A "MATCH (p:Pod) WHERE p.metadata.name CONTAINS 'nginx' RETURN p" # Query against a specific kubeconfig context kubectl cypher --context staging "MATCH (p:Pod) RETURN p.metadata.name" # Output in YAML format kubectl cypher --format yaml "MATCH (s:Service) RETURN s" # Dry-run mode kubectl cypher --dry-run "MATCH (p:Pod) SET p.metadata.labels.new='value' RETURN p" ``` -------------------------------- ### Verify kubectl-cypher installation Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Check the installed plugin version. ```bash kubectl cypher --version ``` -------------------------------- ### Pod Management Queries in Cyphernetes Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/examples.md Examples for managing pods: delete non-running pods, find pods without a node, find pods with specific labels (escaped dots), and find pods with high restart counts. ```graphql // Delete all pods that aren't running MATCH (p:Pod) WHERE p.status.phase != "Running" DELETE p; // Find pods with no node assigned MATCH (p:Pod) WHERE p.spec.nodeName = NULL RETURN p.metadata.name; // Find pods with specific labels (with escaped dots) MATCH (p:Pod) WHERE p.metadata.labels.kubernetes\.io/name = "nginx" RETURN p.metadata.name; // Find pods with high restart counts MATCH (p:Pod) WHERE p.status.containerStatuses[0].restartCount > 5 RETURN p.metadata.name, p.status.containerStatuses[0].restartCount; ``` -------------------------------- ### Template DynamicOperator with CLI Source: https://github.com/avitaltamir/cyphernetes/blob/main/operator/README.md Generates a DynamicOperator manifest using the Cyphernetes CLI and pipes it to kubectl apply. The example uses --on-create with a Cypher query. ```bash cyphernetes operator create my-operator --on-create "MATCH (n) RETURN n" | kubectl apply -f - ``` -------------------------------- ### Service and Endpoint Analysis in Cyphernetes Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/examples.md Examples for analyzing services: find services without endpoints, with specific labels, and in multiple contexts using the IN clause. ```graphql // Find services without endpoints MATCH (s:Service) WHERE NOT (s)->(:core.Endpoints) RETURN s.metadata.name; // Find services with specific labels MATCH (s:Service {app: "frontend"}) RETURN s.metadata.name; // Find services in multiple contexts IN production, staging MATCH (s:Service {name: "api"}) RETURN s.metadata.name, s.spec.clusterIP; ``` -------------------------------- ### Cluster Maintenance Queries in Cyphernetes Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/examples.md Examples for cluster maintenance: find unused configmaps, orphaned PVCs, and delete old non-running pods. ```graphql // Find configmaps not used by any pod MATCH (cm:ConfigMap) WHERE NOT (cm)->(:Pod) RETURN cm.metadata.name; // Find orphaned PersistentVolumeClaims MATCH (pvc:PersistentVolumeClaim) WHERE NOT (pvc)->(:PersistentVolume) AND pvc.status.phase != "Bound" RETURN pvc.metadata.name; // Delete pods that are not running and were created more than 7 days ago MATCH (p:Pod) WHERE p.status.phase != "Running" AND p.metadata.creationTimestamp < datetime() - duration("P7D") DELETE p; ``` -------------------------------- ### ORDER BY with relationship patterns Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Ordering works with relationship patterns; this example orders deployment->pod relationships by pod name. ```graphql // Find deployment->pod relationships, ordered by pod name MATCH (d:Deployment)->(rs:ReplicaSet)->(p:Pod) RETURN d.metadata.name AS deployment, p.metadata.name AS pod ORDER BY pod DESC LIMIT 5 ``` -------------------------------- ### DynamicOperator example: ingress-activator-operator Source: https://github.com/avitaltamir/cyphernetes/blob/main/operator/README.md Defines a DynamicOperator that watches deployments and updates the ingress class name based on replica count. Uses the onUpdate field with Cypher queries; supports onCreate and onDelete fields as well. ```yaml apiVersion: cyphernetes-operator.cyphernet.es/v1 kind: DynamicOperator metadata: name: ingress-activator-operator spec: resourceKind: deployments namespace: default onUpdate: | MATCH (d:Deployment {name: "{{$.metadata.name}}"})->(s:Service)->(i:Ingress) WHERE d.spec.replicas = 0 SET i.spec.ingressClassName = "inactive"; MATCH (d:Deployment {name: "{{$.metadata.name}}"})->(s:Service)->(i:Ingress) WHERE d.spec.replicas > 0 SET i.spec.ingressClassName = "active"; ``` -------------------------------- ### Execute a macro in the shell Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/cli.md Run a macro by typing ':' in the shell. This example shows the output of the built-in ':getpo' macro, which lists pods. The output includes a JSON array of pods with fields like Age, IP, Name, Node, and Status, followed by the execution time. ```graphql > :getpo { "pods": [ { "Age": "2024-08-06T21:29:05Z", "IP": "10.244.0.5", "Name": "nginx-bf5d5cf98-m69mz", "Node": "kind-control-plane", "Status": "Running" } ] } Macro executed in 14.971875ms ``` -------------------------------- ### Provision first DynamicOperator resource Source: https://github.com/avitaltamir/cyphernetes/blob/main/operator/README.md YAML manifest to start watching deployments in the default namespace. The operator updates ingress class names based on replica count; supports onCreate and onDelete fields. ```yaml apiVersion: cyphernetes-operator.cyphernet.es/v1 kind: DynamicOperator metadata: name: ingress-activator-operator namespace: default spec: resourceKind: deployments namespace: default onUpdate: | MATCH (d:Deployment {name: "{{$.metadata.name}}"})->(s:Service)->(i:Ingress) WHERE d.spec.replicas = 0 SET i.spec.ingressClassName = "inactive"; MATCH (d:Deployment {name: "{{$.metadata.name}}"})->(s:Service)->(i:Ingress) WHERE d.spec.replicas > 0 SET i.spec.ingressClassName = "active"; ``` -------------------------------- ### Install operator via Helm Source: https://github.com/avitaltamir/cyphernetes/blob/main/operator/README.md Commands to pull and install the cyphernetes-operator Helm chart. Requires editing values.yaml to configure RBAC rules; by default the operator has no permissions. ```bash helm pull oci://ghcr.io/avitaltamir/cyphernetes/cyphernetes-operator tar -xvf cyphernetes-operator-*.tgz cd cyphernetes-operator helm upgrade --install cyphernetes-operator . --namespace cyphernetes-operator --create-namespace ``` -------------------------------- ### Resource Relationships in Cyphernetes Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/examples.md Demonstrates different ways to express relationships between resources: right direction, left direction, chained, anonymous, and complex chains. Relationship direction does not matter. ```graphql // Right direction relationship MATCH (p:Pod)->(s:Service) RETURN p.metadata.name, s.metadata.name; // Relationship direction doesn't matter MATCH (p:Pod)<-(s:Service) RETURN p.metadata.name, s.metadata.name; // Chained relationships MATCH (d:Deployment)->(rs:ReplicaSet)->(p:Pod) RETURN d.metadata.name, rs.metadata.name, p.metadata.name; // Anonymous, kindless relationships MATCH (d:Deployment)->()->(p:Pod) RETURN d.metadata.name, p.metadata.name; // Find all resources related to a deployment MATCH (d:Deployment {app: "my-app"})->(x) RETURN d, x.kind, x.metadata.name; // Complex relationship chains MATCH (d:Deployment {app: "my-app"})->(rs:ReplicaSet)->(p:Pod)->(s:Service)->(i:Ingress) RETURN d.metadata.name, rs.metadata.name, p.metadata.name, s.metadata.name, i.metadata.name; ``` -------------------------------- ### Start the Cyphernetes shell Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/cli.md Run this command to launch the interactive Cyphernetes shell. The shell supports syntax highlighting, autocompletion, and history; use tab to autocomplete keywords, labels, and jsonPaths. By default it runs in multiline mode, executing queries when a semicolon (;) is typed. ```bash cyphernetes shell ``` -------------------------------- ### Query resources across namespaces with namespace property Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Query resources in different namespaces by specifying the `namespace` property on each node. This example retrieves replica counts from deployments in `staging` and `production` namespaces. ```graphql MATCH (d:Deployment {namespace: "staging"}), (d2:Deployment {namespace: "production"}) RETURN d.spec.replicas, d2.spec.replicas ``` -------------------------------- ### Basic Node Patterns in Cyphernetes Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/examples.md Shows basic node patterns: simple match, node with properties, anonymous nodes, and kindless nodes. Use these as building blocks for more complex queries. ```graphql // Basic node pattern MATCH (p:Pod) RETURN p; // Node with properties MATCH (d:Deployment {metadata: {name: "nginx"}}) RETURN d; // Anonymous nodes MATCH (p:Pod)->(:Service)->(e:Endpoints) RETURN p, e; // Kindless nodes (without specified resource type) MATCH (d:Deployment {metadata: {name: "nginx"}})->(x) RETURN p, x.kind; ``` -------------------------------- ### Install operator with Cyphernetes CLI Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/operator.md Installs the operator using the Cyphernetes CLI for development and testing. Use 'cyphernetes operator remove' to uninstall. ```bash cyphernetes operator deploy ``` ```bash cyphernetes operator remove ``` -------------------------------- ### Deploy operator via Cyphernetes CLI Source: https://github.com/avitaltamir/cyphernetes/blob/main/operator/README.md Installs the operator using the Cyphernetes CLI, intended for development and testing. Use 'cyphernetes operator remove' to remove it. ```bash cyphernetes operator deploy ``` -------------------------------- ### Match by Any Field with WHERE Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Filter results by any field using the WHERE clause. The example filters Deployments with replicas equal to 4. ```graphql MATCH (d:Deployment {app: "nginx", namespace: "default"}) WHERE d.spec.replicas=4 RETURN d.spec.replicas ``` ```json { "d": [ { "name": "nginx", "spec": { "replicas": 4 } } ] } ``` -------------------------------- ### Matching Multiple Nodes with Commas Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Match two or more nodes using commas. The example returns replicas and clusterIP from Deployments and Services. ```graphql MATCH (d:Deployment), (s:Service) RETURN d.spec.replicas, s.spec.clusterIP ``` ```json { "d": [ { "name": "nginx", "spec": { "replicas": 4 } }, { "name": "nginx-internal", "spec": { "replicas": 2 } } ], "s": [ { "name": "nginx", "spec": { "clusterIP": "10.96.0.1" } }, { "name": "nginx-internal", "spec": { "clusterIP": "10.96.0.2" } } ] } ``` -------------------------------- ### :getjob - List Jobs Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists jobs with success/failure counts, completions, start time, and completion time. ```cypher :getjob // List jobs MATCH (jobs:Job) RETURN jobs.metadata.name, jobs.status.succeeded AS Succeeded, jobs.status.failed AS Failed, jobs.spec.completions AS Completions, jobs.status.startTime AS StartTime, jobs.status.completionTime AS CompletionTime; ``` -------------------------------- ### Clone Cyphernetes Repository Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md Clones the Cyphernetes repository from GitHub. Use this to get the source code for development. ```bash git clone https://github.com/avitaltamir/cyphernetes.git ``` -------------------------------- ### Get desired and running replicas for all deployments Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md A Cyphernetes query that retrieves the desired and running replicas for all deployments. The output shows the JSON result and the query execution time. ```graphql // Get the desired and running replicas for all deployments MATCH (d:Deployment) RETURN d.spec.replicas AS desiredReplicas, d.status.availableReplicas AS runningReplicas; ``` ```json { "d": [ { "desiredReplicas": 2, "name": "coredns", "runningReplicas": 2 } ] } ``` ```text Query executed in 9.081292ms ``` -------------------------------- ### Remove operator via Cyphernetes CLI Source: https://github.com/avitaltamir/cyphernetes/blob/main/operator/README.md Removes the operator installed via the Cyphernetes CLI. ```bash cyphernetes operator remove ``` -------------------------------- ### WHERE Operators: Not Equal Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Get all pods that are not running using the != operator. ```graphql // Get all pods that are not running MATCH (p:Pod) WHERE p.status.phase != "Running" RETURN p.metadata.name, p.status.phase ``` -------------------------------- ### Define custom relationships in relationships.yaml Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/cli.md Example `~/.cyphernetes/relationships.yaml` file defining custom relationships between Kubernetes resources. Supports fields like `kindA`, `kindB`, `relationship`, `matchCriteria`, and `defaultProps`. Custom relationships are loaded on startup. ```yaml relationships: - kindA: applications.argoproj.io kindB: services relationship: ARGOAPP_SYNC_SERVICE matchCriteria: - fieldA: "$.spec.source.targetRevision" fieldB: "$.metadata.labels.targetRevision" comparisonType: ExactMatch - fieldA: "$.spec.project" fieldB: "$.metadata.labels.project" comparisonType: ExactMatch - kindA: pods kindB: deployments relationship: DEPLOYMENT_OWN_POD matchCriteria: - fieldA: "$.metadata.name" fieldB: "$.metadata.name" comparisonType: StringContains ``` -------------------------------- ### Example GetOpenAPIResourceSpecs output Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/integration.md Shows the expected JSON structure returned by GetOpenAPIResourceSpecs: a map from plural kind names to a list of JSONPaths. This is used by the parser to infer relationships between resources. ```json { ... "pods": [ // Plural name of the kind ... "$.metadata.name", "$.spec.containers[*].name", "$.spec.containers[*].resources.requests.cpu", "$.spec.containers[*].resources.requests.memory", "$.spec.containers[*].resources.limits.cpu", "$.spec.containers[*].resources.limits.memory" ... ], ... } ``` -------------------------------- ### Define a macro in ~/.cyphernetes/macros Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/cli.md User macros are defined in the '~/.cyphernetes/macros' file. The syntax is ':macro [] [// description]' followed by a Cyphernetes query. Multi-line queries are supported, as shown in the second example. ```plaintext :macro [] [// description] MATCH (p:Pods) RETURN p.metadata.name; // Multi-line queries are supported :macro my-macro // Return all pod names MATCH (p:Pods) RETURN p.metadata.name; ``` -------------------------------- ### WHERE Operators: Greater Than Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Get all deployments with more than 2 replicas using the > operator. ```graphql // Get all deployments with more than 2 replicas MATCH (d:Deployment) WHERE d.spec.replicas > 2 RETURN d.metadata.name, d.spec.replicas ``` -------------------------------- ### Query using custom relationships Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/cli.md Custom relationships can be used in Cyphernetes queries just like built-in ones. This example matches Deployments and their Pods using a custom relationship. ```graphql MATCH (d:Deployment)->(p:Pod) RETURN d.metadata.name, p.metadata.name ``` -------------------------------- ### Multi-cluster query result payload Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Example JSON output from a multi-cluster query. Results are prefixed with the context name followed by an underscore, e.g., `staging_d` and `production_d`. ```json { "staging_d": [ { "name": "coredns", "spec": { "replicas": 2 } } ], "production_d": [ { "name": "coredns", "spec": { "replicas": 2 } } ] } ``` -------------------------------- ### Escaping Dots in JSONPaths Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Use backslash to escape dots in JSONPaths for fields with dots in their names. The example queries an annotation with a dot in the key. ```graphql MATCH (d:Deployment {name: "nginx-internal"}) WHERE d.metadata.annotations.meta\.cyphernet\.es/foo-bar = "baz" RETURN d.metadata.annotations.meta\.cyphernet\.es/foo-bar ``` ```json { "d": [ { "name": "nginx-internal", "metadata": { "annotations": { "meta.cyphernet.es/foo-bar": "baz" } } } ] } ``` -------------------------------- ### Build Web Client with Make Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md Builds the web client static assets using the make target. ```bash make web-build ``` -------------------------------- ### Using core.Parse with APIServerProvider Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/integration.md Shows how to import pkg/core and pkg/provider/apiserver, create an APIServerProvider, instantiate a QueryExecutor, and call Parse with a Cyphernetes query. The result contains data and a graph of nodes and edges. Errors are handled with log.Fatalf. ```go import ( "github.com/avitaltamir/cyphernetes/pkg/core" "github.com/avitaltamir/cyphernetes/pkg/provider/apiserver" ) provider := apiserver.NewAPIServerProvider() executor := core.NewQueryExecutor(provider) query := "MATCH (p:Pod) WHERE p.status.phase != 'Running' RETURN p.metadata.name" result, err := executor.Parse(query) if err != nil { log.Fatalf("Error parsing query: %v", err) } fmt.Printf("Result: %+v\n", result) ``` -------------------------------- ### Build Core Project with Make Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md Runs the default make target, which builds operator manifests and web client static assets, then builds the binary and runs tests. ```bash make ``` -------------------------------- ### Build kubectl-cypher from source Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Clone the repository, build the plugin (defaults to version "dev"), optionally specify a version, and copy the binary to your PATH. ```bash # Clone the repository git clone https://github.com/avitaltamir/cyphernetes.git cd cyphernetes # Build the kubectl plugin (defaults to version "dev") make build-kubectl-plugin # Or build with a specific version VERSION=1.0.0 make build-kubectl-plugin # Copy to your PATH (choose a directory in your PATH) cp dist/kubectl-cypher /usr/local/bin/kubectl-cypher ``` -------------------------------- ### Download pre-built kubectl-cypher binary Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Download the appropriate tar.gz for your platform from the releases page, extract, make executable, move to PATH, and clean up. Includes commands for macOS, Linux, and Windows. ```bash # macOS Intel curl -L -o kubectl-cypher.tar.gz https://github.com/avitaltamir/cyphernetes/releases/latest/download/kubectl-cypher-darwin-amd64.tar.gz # macOS Apple Silicon curl -L -o kubectl-cypher.tar.gz https://github.com/avitaltamir/cyphernetes/releases/latest/download/kubectl-cypher-darwin-arm64.tar.gz # Linux Intel/AMD64 curl -L -o kubectl-cypher.tar.gz https://github.com/avitaltamir/cyphernetes/releases/latest/download/kubectl-cypher-linux-amd64.tar.gz # Linux ARM64 curl -L -o kubectl-cypher.tar.gz https://github.com/avitaltamir/cyphernetes/releases/latest/download/kubectl-cypher-linux-arm64.tar.gz # Windows Intel/AMD64 curl -L -o kubectl-cypher.tar.gz https://github.com/avitaltamir/cyphernetes/releases/latest/download/kubectl-cypher-windows-amd64.tar.gz # Windows ARM64 curl -L -o kubectl-cypher.tar.gz https://github.com/avitaltamir/cyphernetes/releases/latest/download/kubectl-cypher-windows-arm64.tar.gz # Extract the package tar -xzf kubectl-cypher.tar.gz # Make it executable (Unix-like systems) chmod +x kubectl-cypher # or kubectl-cypher.exe on Windows # Move to your PATH mv kubectl-cypher /usr/local/bin/kubectl-cypher # Unix-like systems # or move kubectl-cypher.exe to a directory in your PATH on Windows # Clean up rm kubectl-cypher.tar.gz LICENSE # Remove the downloaded files ``` -------------------------------- ### List all pods in the current namespace Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Returns pod names and phases. ```bash kubectl cypher "MATCH (p:Pod) RETURN p.metadata.name, p.status.phase" ``` -------------------------------- ### CREATE with RETURN clause Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Create a Deployment and return the created resource using a RETURN clause. ```graphql CREATE (d:Deployment { "name": "nginx", "metadata": { "labels": { "app": "nginx" } }, "spec": { "replicas": 4, "selector": { "matchLabels": { "app": "nginx" } }, "template": { "metadata": { "labels": { "app": "nginx" } }, "spec": { "containers": [ {"name": "nginx", "image": "nginx"} ] } } } }) RETURN d ``` -------------------------------- ### Build static site with yarn build Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/README.md Generates static content into the `build` directory, which can be served using any static content hosting service. ```bash $ yarn build ``` -------------------------------- ### Create resource by relationship Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Create a Service related to an existing Deployment. One side of the relationship must reference a node from a MATCH clause; the other side is the new node. Equivalent to `kubectl expose deployment nginx --type=ClusterIP`. ```graphql MATCH (d:Deployment {name: "nginx"}) CREATE (d)->(s:Service) ``` -------------------------------- ### Create a standalone Deployment Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Create a standalone Deployment resource with full manifest. Properties must be valid JSON. ```graphql CREATE (d:Deployment { "name": "nginx", "metadata": { "labels": { "app": "nginx" } }, "spec": { "replicas": 4, "selector": { "matchLabels": { "app": "nginx" } }, "template": { "metadata": { "labels": { "app": "nginx" } }, "spec": { "containers": [ {"name": "nginx", "image": "nginx"} ] } } } }) ``` -------------------------------- ### Navigate to Cyphernetes Project Directory Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md Changes the current directory to the cloned Cyphernetes project. Run after cloning the repository. ```bash cd cyphernetes ``` -------------------------------- ### :expose - Expose Deployment as Service Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Exposes a deployment as a service. Takes a deployment name parameter. Creates a service and returns its details. ```cypher :expose deploymentName // Expose a deployment as a service MATCH (deployment:Deployment {name: "$deploymentName"}) CREATE (deployment)->(service:Service); MATCH (services:Service {name: "$deploymentName"}) RETURN services.metadata.name, services.spec.type AS Type, services.spec.clusterIP AS ClusterIP; ``` -------------------------------- ### :deployexposure macro - examine deployment exposure Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Macro to examine a deployment and its associated services and ingress. Takes deploymentName argument. Returns pod, deployment, service, and ingress details. ```cypher :deployexposure deploymentName // Examine a deployment and its services and ingress MATCH (pods:Pod)->(replicaSets:ReplicaSet)->(deployments:Deployment {name: "$deploymentName"})->(services:Service)->(ingresses:Ingress) RETURN pods.metadata.name, deployments.metadata.name AS Deployment, services.metadata.name AS Service, services.spec.type AS Type, services.spec.clusterIP AS ClusterIP, ingresses.metadata.name AS Ingress, ingresses.spec.rules[0].host AS Host, ingresses.spec.rules[0].http.paths[0].path AS Path, ingresses.spec.rules[0].http.paths[0].backend.service.name AS IngressBackend; ``` -------------------------------- ### CREATE statement syntax Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Create a resource with the CREATE statement. Properties must be valid JSON (temporary limitation). ```graphql CREATE (k:Kind {"k": "v", "k2": "v2", ...}) ``` -------------------------------- ### Deploy website via SSH with USE_SSH=true yarn deploy Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/README.md Deploys the website using SSH. Convenient for GitHub Pages hosting; builds the website and pushes to the `gh-pages` branch. ```bash $ USE_SSH=true yarn deploy ``` -------------------------------- ### Find pods connected to services Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Queries relationships between pods and services. ```bash kubectl cypher "MATCH (p:Pod)->(s:Service) RETURN p.metadata.name, s.metadata.name" ``` -------------------------------- ### Selecting a Kubernetes Context with --context Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/cli.md Use the global `--context` flag to target a different Kubernetes context per invocation, similar to `kubectl --context`. It works with every command (`query`, `shell`, `web`, `operator`) and respects the `KUBECONFIG` environment variable. ```bash cyphernetes --context staging query 'MATCH (p:Pod) RETURN p.metadata.name' cyphernetes --context staging shell ``` -------------------------------- ### Match by Name and Labels Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Query a Deployment by name and label properties. The output shows the returned fields with labels and image. ```graphql MATCH (d:Deployment {name: "nginx-internal", app: "nginx"}) RETURN d.metadata.labels, d.spec.template.spec.containers[0].image ``` ```json { "d": [ { "metadata": { "labels": { "app": "nginx", }, }, "name": "nginx-internal", "spec": { "template": { "spec": { "containers[0]": { "image": "nginx" } } } } } ] } ``` -------------------------------- ### :getcm - List Config Maps Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists config maps with name, namespace, creation timestamp, and the pods that use them. Uses relationship to pods. ```cypher :getcm // List config maps MATCH (configMaps:ConfigMap)->(pods:Pod) RETURN configMaps.metadata.name, configMaps.metadata.namespace AS Namespace, configMaps.metadata.creationTimestamp AS Age pods.metadata.name AS UsedIn; ``` -------------------------------- ### Run a Cyphernetes query from the command line Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/cli.md Use the `query` command to execute a single Cyphernetes query. The `-r, --raw-output` flag disables colorized JSON output. ```bash cyphernetes query 'MATCH (d:Deployment {name: "nginx"}) RETURN d' ``` -------------------------------- ### Query specific resource types Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Filters deployments with more than one replica. ```bash kubectl cypher "MATCH (d:Deployment) WHERE d.spec.replicas > 1 RETURN d.metadata.name, d.spec.replicas" ``` -------------------------------- ### :getdeploy - List Deployments Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists deployments with replica counts and creation timestamp. Useful for checking deployment status. ```cypher :getdeploy // List deployments MATCH (deployments:Deployment) RETURN deployments.metadata.name, deployments.status.replicas AS Ready, deployments.spec.replicas AS DesiredReplicas, deployments.status.updatedReplicas AS UpToDate, deployments.status.availableReplicas AS Available, deployments.metadata.creationTimestamp AS Age; ``` -------------------------------- ### Deploy website without SSH using GIT_USER Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/README.md Deploys the website without SSH by specifying your GitHub username. Convenient for GitHub Pages hosting; builds the website and pushes to the `gh-pages` branch. ```bash $ GIT_USER= yarn deploy ``` -------------------------------- ### MATCH/RETURN with multiple fields Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Queries all Deployments and returns a custom payload with labels and replicas. The result is a JSON object with a key per RETURN variable, each containing a list of matched resources. ```graphql MATCH (d:Deployment) RETURN d.metadata.labels, d.spec.replicas ``` ```json { "d": [ { "metadata": { "labels": { "app": "nginx", }, }, "name": "nginx", "spec": { "replicas": 4 } }, { "metadata": { "labels": { "app": "nginx", }, }, "name": "nginx-internal", "spec": { "replicas": 2 } } ] } ``` -------------------------------- ### Match Multiple Nodes and Relationships with Output Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Matches a Deployment, its Service, the Ingress routing to it, and an Istio VirtualService using a label fallback. Returns Ingress rules and VirtualService paths. ```graphql MATCH (vs:VirtualService), (d:Deployment {name: "my-app"})->(s:Service)->(i:Ingress) WHERE vs.metadata.labels.app="my-app" RETURN i.spec.rules, vs.spec.http.paths ``` ```json { "i": [ { "name": "my-app", "spec": { "rules": [ { "host": "my-app.example.com", "http": { "paths": [ { "backend": { "serviceName": "my-app", "servicePort": 80 }, "path": "/" } ] } } ] } } ] "vs": [ { "name": "my-app", "spec": { "http": { "paths": [ { "backend": { "serviceName": "my-app", "servicePort": 80 }, "path": "/" } ] } } } ] } ``` -------------------------------- ### Build Operator with Make Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md Builds the operator using the make target. ```bash make operator-build ``` -------------------------------- ### :getpo - List Pods Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists pods with name, status phase, node, IP, and creation timestamp. Use as a default macro to quickly inspect pods. ```cypher :getpo // List pods MATCH (pods:Pod) RETURN pods.metadata.name, pods.status.phase AS Status, pods.spec.nodeName AS Node, pods.status.podIP AS IP, pods.metadata.creationTimestamp AS Age; ``` -------------------------------- ### :exposepublic macro - expose deployment as service and ingress Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Macro to expose a deployment as a service and ingress. Takes deploymentName and hostname arguments. Creates a Service and Ingress, then returns service and ingress details. ```cypher :exposepublic deploymentName hostname // Expose a deployment as a service and ingress MATCH (deployment:Deployment {name: "$deploymentName"}) CREATE (deployment)->(service:Service); MATCH (services:Service {name: "$deploymentName"}) CREATE (services)->(i:ingress {"spec":{"rules": [{"host": "$hostname"}]}}); MATCH (deployments:Deployment {name: "$deploymentName"})->(services:Service)->(ingresses:Ingress) RETURN services.metadata.name, services.spec.type AS Type, services.spec.clusterIP AS ClusterIP, ingresses.spec.rules[0].host AS Host, ingresses.spec.rules[0].http.paths[0].path AS Path, ingresses.spec.rules[0].http.paths[0].backend.service.name AS Service; ``` -------------------------------- ### :getpv - List Persistent Volumes Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists persistent volumes with capacity, access modes, storage class, and status phase. ```cypher :getpv // List persistent volumes MATCH (persistentVolumes:PersistentVolume) RETURN persistentVolumes.metadata.name, persistentVolumes.spec.capacity.storage AS Capacity, persistentVolumes.spec.accessModes AS AccessModes, persistentVolumes.spec.storageClassName AS StorageClass, persistentVolumes.status.phase AS Status; ``` -------------------------------- ### :getns - List Namespaces Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists namespaces with status phase and creation timestamp. Useful for namespace overview. ```cypher :getns // List namespaces MATCH (namespaces:Namespace) RETURN namespaces.metadata.name, namespaces.status.phase AS Status, namespaces.metadata.creationTimestamp AS Age; ``` -------------------------------- ### Create a Service for an nginx Deployment Source: https://github.com/avitaltamir/cyphernetes/blob/main/README.md A Cyphernetes query that creates a Service for an nginx Deployment, similar to `kubectl expose`. It uses the CREATE clause with a relationship arrow to connect the Deployment to the Service. The output shows the created resource and execution time. ```graphql // This is similar to `kubectl expose` MATCH (d:Deployment {name: "nginx"}) CREATE (d)->(s:Service); ``` ```text Created services/nginx Query executed in 30.692208ms ``` -------------------------------- ### :getsvc - List Services Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists services with type, cluster IP, external IPs, ports, and creation timestamp. Useful for service discovery. ```cypher :getsvc // List services MATCH (services:Service) RETURN services.metadata.name, services.spec.type AS Type, services.spec.clusterIP AS ClusterIP, services.spec.externalIPs AS ExternalIP, services.spec.ports AS Ports, services.metadata.creationTimestamp AS Age; ``` -------------------------------- ### MATCH/RETURN with comments and replicas Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Queries all Deployments and returns the desired replica count. Comments in Cyphernetes support both single-line and multi-line syntax. The result includes the resource name in the special 'name' field. ```graphql // Single-line comments are supported /* ...and so are multi-line comments */ MATCH (d:Deployment) RETURN d.spec.replicas ``` ```json { "d": [ { "name": "nginx", "spec": { "replicas": 4 }, }, { "name": "nginx-internal", "spec": { "replicas": 2 }, } ] } ``` -------------------------------- ### :geting - List Ingresses Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists ingresses with host, path, backend service, and creation timestamp. Uses first rule and path. ```cypher :geting // List ingresses MATCH (ingresses:Ingress) RETURN ingresses.metadata.name, ingresses.spec.rules[0].host AS Host, ingresses.spec.rules[0].http.paths[0].path AS Path, ingresses.spec.rules[0].http.paths[0].backend.serviceName AS Service, ingresses.metadata.creationTimestamp AS Age; ``` -------------------------------- ### :createdeploy macro - create deployment Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Macro to create a deployment. Takes deploymentName and image arguments. Creates a Deployment with RollingUpdate strategy and labels. ```cypher :createdeploy deploymentName image // Create a deployment CREATE (deployment:Deployment {"metadata": {"name": "$deploymentName", "labels": {"app": "$deploymentName"}}, "spec": {"strategy": {"type": "RollingUpdate", "rollingUpdate": {"maxUnavailable": 1, "maxSurge": 1}}, "selector": {"matchLabels": {"app": "$deploymentName"}}, "template": {"metadata": {"labels": {"app": "$deploymentName"}}, "spec": {"containers": [{"name": "$deploymentName", "image": "$image"}]}}}}); ``` -------------------------------- ### Combining ORDER BY, LIMIT, and SKIP Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md The ORDER BY, LIMIT, and SKIP/OFFSET clauses can be combined to implement pagination. The order of LIMIT and SKIP/OFFSET can be reversed. ```APIDOC ## Combining ORDER BY, LIMIT, and SKIP ### Description The ORDER BY, LIMIT, and SKIP/OFFSET clauses can be combined to implement pagination. The order of LIMIT and SKIP/OFFSET can be reversed. ### Query Syntax (SKIP then LIMIT) ```graphql MATCH (d:Deployment) RETURN d.metadata.name AS name, d.spec.replicas AS replicas ORDER BY name SKIP 10 LIMIT 10 ``` ### Query Syntax (LIMIT then OFFSET) ```graphql MATCH (d:Deployment) RETURN d.metadata.name AS name, d.spec.replicas AS replicas ORDER BY name LIMIT 10 OFFSET 10 ``` ``` -------------------------------- ### :getpvc - List Persistent Volume Claims Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Lists persistent volume claims with volume name, capacity, status phase, and creation timestamp. ```cypher :getpvc // List persistent volume claims MATCH (persistentVolumeClaims:PersistentVolumeClaim) RETURN persistentVolumeClaims.metadata.name, persistentVolumeClaims.spec.volumeName AS Volume, persistentVolumeClaims.spec.resources.requests.storage AS Capacity, persistentVolumeClaims.status.phase AS Status, persistentVolumeClaims.metadata.creationTimestamp AS Age; ``` -------------------------------- ### Filter pods by creation time using datetime and duration Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Use temporal expressions to filter resources based on creation time. The datetime() function returns the current time in ISO 8601, and duration() returns a duration. Subtract durations to find pods created within a time window or delete older ones. ```graphql // Find pods that were created in the last 24 hours MATCH (p:Pod) WHERE p.metadata.creationTimestamp > datetime() - duration("PT24H") RETURN p.metadata.name; // Delete pods that were created more than 7 days ago MATCH (p:Pod) WHERE p.metadata.creationTimestamp < datetime() - duration("P7D") DELETE p; ``` -------------------------------- ### WHERE Operators: Regex Matching Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Find all deployments that end with "api" using the =~ regex operator. ```graphql // Find all deployments that end with "api" MATCH (d:Deployment) WHERE d.metadata.name =~ "^.*api$" RETURN d.spec ``` -------------------------------- ### Basic Relationship Match with Output Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Matches a Service related to a Deployment named 'nginx' and returns its ports. The output shows the Service's spec.ports. ```graphql MATCH (d:Deployment {name: "nginx"})->(s:Service) RETURN s.spec.ports ``` ```json { "s": [ { "name": "nginx", "spec": { "ports": [ { "port": 80, "protocol": "TCP", "targetPort": 80 } ] } } ] } ``` -------------------------------- ### Update resources (dry-run) Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/kubectl-cypher/README.md Sets a label on a specific pod in dry-run mode. ```bash kubectl cypher --dry-run "MATCH (p:Pod) WHERE p.metadata.name = 'my-pod' SET p.metadata.labels.environment = 'production'" ``` -------------------------------- ### Return full resource with MATCH/RETURN Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Returns the full resource object by using the variable name alone. The payload includes all fields of the matched resource, not just the name. ```graphql MATCH (d:Deployment) RETURN d ``` -------------------------------- ### Kindless Node Query for Related Resources Source: https://github.com/avitaltamir/cyphernetes/blob/main/docs/docs/language.md Finds all resources related to a Deployment named 'nginx' using a kindless node `(x)`. Cyphernetes expands the query to all possible kinds. Chaining or standalone kindless nodes are not supported. ```graphql // Find all resources related to a deployment MATCH (d:Deployment {name: "nginx"})->(x) RETURN x.kind ``` -------------------------------- ### :scale - Scale Workload Source: https://github.com/avitaltamir/cyphernetes/blob/main/cmd/cyphernetes/default_macros.txt Scales a deployment or statefulset to a specified replica count. Takes kind, name, and count parameters. ```cypher :scale kind name count // Scale a deployment or statefulset MATCH (workload:$kind {name: "$name"}) SET workload.spec.replicas = $count; ```