Carbon QL Cookbook (pre-release alpha)

The Carbon Query Language (colloquially, CarbonQL) is a query interface for Kubernetes resources. It makes it easy to answer questions like:

• Operations:
  • Which applications are scheduled on nodes that report high memory pressure?
  • What is the difference between the last two rollouts of a Deployment?
  • Which applications are currently emitting logs that contain the text "ERROR:", and why?
• Security and Compliance:
  • Which Service Accounts have access to this Secret?
  • Which CertificateSigningRequests were approved this week, and what are they being used for?
• Governance:
  • Which Services are publicly exposed to the Internet?
  • How many distinct versions of the mysql container are running in all of my clusters?

One way to think about CarbonQL is as an ORM for the Kubernetes API.

How does it work?

The user writes a program in one of the supported languages, against the CarbonQL client library. In the following example, we programmatically build up a query using the CarbonQL TypeScript client library, to find all versions of the MySQL container running in the cluster:

import {Client, query} from "carbonql";

const c = Client.fromFile(<string>process.env.KUBECONFIG);
const mySqlVersions = c.core.v1.Pod
  .list("default")
  // Obtain all container image names running in all pods.
  .flatMap(pod => pod.spec.containers)
  .map(container => container.image)
  // Filter image names that don't include "mysql", return distinct.
  .filter(imageName => imageName.includes("mysql"))
  .distinct();

// Prints the distinct container image tags.
mySqlVersions.forEach(console.log);

Currently supported languages:

• Javascript (node.js)
• Typescript (node.js)

Considering supporting the following languages:

• Go
• Python

Experimental syntax extensions for JavaScript

In addition to supporting vanilla TypeScript and JavaScript, the CarbonQL client provides a Babel plugin that allows users to use SQL keywords directly in their JavaScript programs. The previous TypeScript example would be re-written as:

import {Client, query} from "carbonql";

const c = Client.fromFile(<string>process.env.KUBECONFIG);
const mySqlVersions =
  from pod in c.core.v1.Pod.list("default")
  from container in pod.spec.containers
  // Filter image names that don't include "mysql", return distinct.
  where container.image.includes("mysql")
  // Return just the container image.
  select container.image;

mySqlVersions.distinct().forEach(console.log);

We are currently gathering feedback about the syntax of this extension, so it's not currently part of mainline, but if you're interested you should drop us a note at [email protected] and [email protected].

Structure of this gitbook

This document is meant mostly to provide some simple example queries demonstrating what is possible with the CarbonQL client today.

Because we are still figuring out what we want the syntax to look like, the book is split into two sections:

• A TypeScript section containing examples written in TypeScript. It is possible to run these queries out of the box, today.

• A Babel section containing the exact same examples, except written using an experimental Babel plugin, which extends the JavaScript language to have SQL-like keywords, making it easier for people to write queries even if they're not programmers.

  For example, consider the following code snippet which would finds all distinct versions of the mysql container running in a Kubernetes cluster. (Copied from an example in the "governance" section.)

  NOTE: Because this syntax is not fully baked yet, it is not yet available. If feedback is positive, it soon will be.