[Sandbox] Runme Notebooks for DevOps

[admc]

Application contact emails

[email protected]

Project Summary

Runme is a toolchain that turns Markdown into interactive, cloud-native, runnable Notebook experiences for DevOps.

Project Description

Runme: DevOps Notebooks Built with Markdown

Runme consolidates operational documentation and executable commands/code into interactive Notebooks or TUIs, seamlessly integrating with cloud-native infrastructure. The toolchain empowers engineering teams to build and maintain reliable, shareable documentation that can be tested in CI/CD.

Key Features:

• Cloud Integration: Supports AWS, GCP, and GitHub Actions for managing deployments and automating cloud workflows directly from within Notebooks.
• GitOps-Ready: Runme stores operational steps in Git-managed Markdown files, ensuring that runbooks, playbooks, and scripts are synchronized with infrastructure-as-code (IaC), tests, and GitOps processes, encouraging reviews/knowledge-sharing and keeping documentation up to date.
• DevOps Tooling: Integrates with Kubernetes, Terraform, Helm, Docker, Dagger, and Argo CD for seamless orchestration and automation of infrastructure.
• Environment Validation: Runme enables users to define and validate .ENV dependencies, ensuring all required resources and configurations are present before execution. Combined with devContainers, this delivers the most innovative and effective approach to repeatable, reliable documentation experiences.

Use Cases:

1. Runbooks and Playbooks: Document and execute operational processes like deployments, infrastructure management, or incident response directly from Notebooks, ensuring consistency and repeatability.
2. Automation: Automate workflows with tools like Terraform, Helm, Dagger, and Argo CD. Runme allows users to interact with these automated workflows one task (or category) at a time, without requiring the workflow to be a pipeline (although it can be run there as well).
3. Interactive Control Panels: Build real-time dashboards for monitoring and tuning systems, enabling interactive control over infrastructure.

Runme’s kernel, exposed over gRPC, converts between Markdown and Notebook formats (as required by the client) and maintains the .ENV state across Notebook sessions, transforming Markdown into an interactive and reliable docs experience. Delivered as a VS Code platform compatible extension, Runme makes it easy to distribute Notebooks across environments like Codespaces, Gitpod, and VSCodium.

For more, visit the Runme Documentation.

Org repo URL (provide if all repos under the org are in scope of the application)

N/A

Project repo URL in scope of application

https://github.com/stateful/runme

Additional repos in scope of the application

https://github.com/stateful/vscode-runme
https://github.com/stateful/runme.dev
https://github.com/stateful/docs.runme.dev
https://github.com/stateful/runme-action

Website URL

https://runme.dev

Roadmap

https://github.com/stateful/runme/issues

Roadmap context

Roadmap is currently managed by prioritizing work in Github issues, but soon we'll be doing this using a project kanban.

The roadmap content is prioritized as follows:

• Build, test, deploy process
• Bugs blocking adoption from community
• Feature requests from community
• Cloud-native tools integrations and support
• Cloud-provider integrations and support
• Expansion of VS Code platform compatibility

Contributing Guide

https://github.com/stateful/runme/blob/main/CONTRIBUTING.md

Code of Conduct (CoC)

https://github.com/stateful/runme/blob/main/CODE_OF_CONDUCT.md

Adopters

No response

Contributing or Sponsoring Org

https://stateful.com

Maintainers file

https://github.com/stateful/runme/blob/main/MAINTAINERS.md

IP Policy

• If the project is accepted, I agree the project will follow the CNCF IP Policy

Trademark and accounts

• If the project is accepted, I agree to donate all project trademarks and accounts to the CNCF

Why CNCF?

Starting in my time at Buoyant I would attend Kubecon events, which have great energy. We've started exploring DevOpsDays, whose audience feels like the right place to build our community. Given the use-cases we see, it's clear that the intersection of devContainers, cloud-native, security/authorization and reproducible/reliable process for complex workflows is our bread and butter. We also see a lot of potential for partnering in the CNCF project landscape and adding value by lowering project barriers to entry, while collecting feedback to guide Runme to add the most tangible value.

Benefit to the Landscape

There is a huge opportunity for CNCF projects to embrace Runme as a more human friendly interface. Not just utilizing Runme for a nicer interface for their tool, but also to make the experience when using their tool more deeply integrated and intuitive. I continue to find it interesting that there are so many tools to support production cloud-native operations, but very little to support training, streamlining, educating and documenting the interfaces people need to really use them. Maybe it's time to open a new category?

Cloud Native 'Fit'

The simplest answer is that the tool is fairly agnostic and flexible about the specifics of the workflows being defined. But the reason that we moved from basic development flows to DevOps is because of how common it is for operators to build custom bash scripts to manage their day-to-day. We see a hole in the tooling landscape when it comes to reliable repeatable process that need to also exist outside of pipelines.

Here are some other components that make us a good fit for the CNCF landscape:

• We are building on Markdown that can be checked into Git as the basic philosophy
• Community building is a primary focus of the project and we work hard to operate in the open
• The primary components of these Notebooks are bash or code that either calls a project's CLI, or talks directly to APIs, many of these use cases interface with cloud-native tools or cloud providers already
• Out of the box we are a better way to share DevOps process that interacts with kubectl, terraform, helm, argo CD than what currently exists
• We have already built cloud provider integrations to enhance the operational experience for Notebooks using them
• Our Notebook data can be accessed over gRPC and consumed using Otel, making us a good fit for existing observability tooling
• We are also working to provide an even more cloud-native onboarding experience through revamping our CLI to allow Runme projects to be initialized and configured with an init that generates a YAML
• The Runme kernel is built with GoLang making it easy to be packaged, distributed and understood by our DevOps audience
• We are already members of the Linux foundation

Cloud Native 'Integration'

We feel that interactive Notebooks complement basically any CNCF project that has a CLI or cloud dashboard that the user needs to understand and configure. Both from an educational/onboarding and day-to-day operational perspective. A great example is the overhead in knowing and running the numerous 'kubectl' commands with all their flags and arguments. Codifying these workflows as a Notebook makes it easy to follow along while passing data down the line and make sure that you not only get them right but also that the output is formatted in a way that is fit for human consumption.

Cloud Native Overlap

It is still way too hard to codify operational knowledge, which leads to a relatively high bar and constant learning of the different available tools and interfaces. This makes it really hard to stay competent when it comes to the cloud-native toolchain. We think we can lower the bar for the whole ecosystem, enabling more people to both get involved, contribute and also more effectively do their jobs.

Similar projects

N/A

Landscape

No

Business Product or Service to Project separation

Runme is the open source project, Stateful is the commercial company/product, the only place there is overlap is that the Runme VS Code extension and CLI have an integration with the hosted product allowing users to authorize using the VS Code account manager and push their data (notebook results) to our cloud. There is absolutely no requirement, obligation or OSS feature withholding involved.

Project presentations

No response

Project champions

No response

Additional information

No response