This document introduces using Jupyter Notebooks or .NET Interactive Books to create interactive troubleshooting guides and documentation for Kubernetes deployments. Notebooks allow including executable code blocks alongside Markdown text in a way that supports collaboration and version control. They provide benefits over traditional static documentation formats by allowing readers to execute code and see output. Examples are given of using Notebooks to manage local and Azure Kubernetes Service clusters through demonstrations of common Kubernetes tasks like plotting metrics from kubectl. PowerShell is used as the shell language but other options like bash are also supported.

1. Troubleshooting
guides and team docs
for your Kubernetes
deployments
using Notebooks

2. ✨
Want to follow along? Go here:
https://github.com/TylerLeonhardt/Manning-Kubernetes-Notebooks

3. @TylerLeonhardt – Software Engineer - Microsoft

5. I’m not a Kubernetes expert
(But I like to think I know a thing or two about docs and running commands)

6. Is this you/your team?
• Have misc onboarding docs for your project
• Have troubleshooting guides for when stuff goes wrong
• Probably in OneNote, Notion, Google Docs, Plain markdown

7. You can do better…
• OneNote, Notion, Google Docs
• Doesn’t have real source control so change tracking is hard
• Code formatting is a little tricky
• Markdown
• Better than the others since it can be next to code in a git repo
• Requires an extra step to render it usually
• All of these are static – copy paste commands into your terminal

8. Picture this…
Markdown,
with
executable
code blocks

9. Backed by a JSON file
or readable text format
for source control

10. Notebooks 📒📓📔📕📗📘📙

11. Data
professionals
have been
using
Notebooks for
years

12. WHY?
• The interactive
experience came first
(run code, see output)
• Rich output – plotting

17. .NET Interactive will be
our backend
• Can act as a Juypter kernel
• Provides PowerShell support out of the box
• PowerShell can run native executables like
bash/zsh can
• Provides plotting out of the box for
PowerShell too

18. Notebooks Demo
📒📓📔📕📗📘📙

19. A Notebook is an abstract concept
When I talk about Notebooks, I’m talking about the user experience
Markdown as docs
Code that you can execute

20. Jupyter Notebooks
• File extension: ipynb
• File format: json
• File contains last output: yes

21. .NET Interactive Books
• File extension: dib
• File format: ”scriptwich”
• File contains last output: no

22. Choose your own adventure
Cloud (only
ipynb's for
now...)
Jupyter Lab
MyBinder
Self hosted
somewhere
Local
ipynbs
Jupyter Lab nteract
Azure Data
Studio
(in the
future…) Visual
Studio Code
dibs
Visual Studio
Code

23. Demos
• Managing a local Kubernetes cluster
• Managing an AKS cluster locally
• Managing an AKS cluster using Az Shell
• Plotting output of kubectl

24. My use of PowerShell…
PowerShell is just a shell and scripting language – like bash, zsh, fish.
The syntax is a bit different… but one-off commands you run in bash
should work the same (I hope my examples have shown that)
You may even come to like PowerShell’s syntax… and if not, you can of
course run bash from PowerShell:
PS > bash -c ’echo 5’

25. My advice
• Use the GitHub template if you can
• Comes with everything you need and is easy to customize
• Can be used in MyBinder when you’re on the move or locally via Docker
• Can be opened in Jupyter Lab or Azure Data Studio locally
• If you don’t want to install Python, use dibs
• They’ll only become more powerful in time
• They work in VS Code already
• Try Azure Data Studio if you want to use ipynb’s and don’t mind
installing Python

26. Big slide of links
• .NET Interactive – https://github.com/dotnet/interactive
• Editors
• Jupyter Lab - https://github.com/jupyterlab/jupyterlab#getting-started
• Visual Studio Code Insiders - https://code.visualstudio.com/insiders/
• .NET Interactive Notebooks extension: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-
vscode
• Azure Data Studio Insiders - https://github.com/microsoft/azuredatastudio#try-out-the-latest-insiders-build-from-main
• nteract - https://nteract.io/
• Sample Notebooks repo – https://github.com/TylerLeonhardt/JupyterNotebooks
• Sample DIBs repo – https://github.com/TylerLeonhardt/dotnet-interactive-books
• K8s docs and guides used in this talk
• https://github.com/feiskyer/kubernetes-handbook/blob/master/en/troubleshooting/index.md
• https://github.com/kubernetes/website/blob/master/content/en/docs/tasks/debug-application-cluster/debug-application-
introspection.md
• PowerShell – https://github.com/PowerShell/PowerShell
• Fastpages (Notebooks for blogging!) - https://github.com/fastai/fastpages