Merging

docs/configuration/cli-reference.md

@@ -2,7 +2,7 @@
 runme:
   id: 01HX525D99NZJ6YPEFFBVMRTC6
   version: v3
-sidebar_position: 2
+sidebar_position: 3
 title: CLI reference
 ---
 

docs/configuration/telemetry.md

@@ -0,0 +1,14 @@
+---
+title: Telemetry
+---
+
+Your privacy is of utmost importance. Runme collects telemetry information, all of which is pseudo-anonymized (no PII). Runme respects both [VS Code's global "no telemetry"](https://code.visualstudio.com/docs/getstarted/telemetry) (id: `telemetry.telemetryLevel`) setting and the common `DO_NO_TRACK=1` environment variable.
+
+Telemetry collected includes:
+
+- Buttons clicked & commands triggered
+- Total cells and how many are executed
+- Extension activation and deactivation
+- Notebook opened and saved (incl. metadata; file names are obfuscated)
+
+If you don't wish to participate in telemetry, please deactivate it using the available settings.

docs/guide/k8s/k8s-secret.md

@@ -1,35 +1,35 @@
 ---
 runme:
-  id: 01J82VN641J9K3A3G98ASV75SR
+  id: 01J82Z98G1JA35Y4AAWMYDJW0T
   version: v3
 ---
 
 # Sealed Secrets
 
-Runme provides a platform for documenting processes and instructions. It integrates swiftly with cloud infrastructures, including Kubernetes and its resources.
-
-This guide will explore one such resource, Kubernetes secrets, with a specific focus on sealed secrets.
-
-[Sealed Secrets](https://archive.eksworkshop.com/beginner/200_secrets/installing-sealed-secrets/) is an open-source project that helps encrypt Kubernetes secrets, which can then be securely stored in your version control. Runme makes securing these secrets easier.
+This guide will explore Kubernetes secrets, with a specific focus on sealed secrets.
 
 In this guide, we will demonstrate the steps required to encrypt Kubernetes secrets with sealed secrets in Runme successfully.
 
 ## Prerequisites
 
 To get started, ensure you have the following:
 
-- **Clone the repository**: We created a [notebook repository](https://github.com/stateful/blog-examples/tree/main/kubernetes/k8s-secret/sealed-secret) containing all the instructions and commands required for this guide.
+### Clone the repository
+
+We created a [notebook repository](https://github.com/stateful/blog-examples/tree/main/kubernetes/k8s-secret/sealed-secret) containing all the instructions and commands required for this guide.
 
 ```sh {"id":"01HYBANSBEGDG8RCXAJB3P75FH"}
 git clone https://github.com/stateful/blog-examples.git
 cd kubernetes/k8s-secret/sealed-secret
 ```
 
-- **Install Runme**: Install the [Runme extension on VS Code](https://marketplace.visualstudio.com/items?itemName=stateful.runme) and set it as your [default Markdown viewer.](/installation/vscode#how-to-set-vs-code-as-your-default-markdown-viewer)
+### Install Runme
+
+Install the [Runme extension on VS Code](https://marketplace.visualstudio.com/items?itemName=stateful.runme) and set it as your [default Markdown viewer.](/installation/vscode#how-to-set-vs-code-as-your-default-markdown-viewer)
 
 This guide will focus on using the Mac specifications. If you use a Linux OS, follow the instructions in the [Linux Markdown files.](https://github.com/stateful/blog-examples/blob/main/kubernetes/k8s-secret/sealed-secret/linux-sealedsecrets.md)
 
-### Install all Dependencies
+### Install all dependencies
 
 To follow up on securing your secrets using Sealed Secrets, ensure you install the necessary dependencies in the notebook's prerequisite section. In your Runme cell, run the commands below to install all dependencies required for this guide.
 
@@ -44,15 +44,15 @@ brew install kubeseal
   <source src="/videos/sealed-secrets-runme.webm" type="video/webm" />
 </video>
 
-### Encrypt a Secret in Runme
+### Encrypt a secret in Runme
 
 To encrypt a secret, you must create a Kubernetes secret and then using `kubeseal` you can encrypt it. Run the command below in your Runme cell to encrypt your secret.
 
 ```sh {"id":"01HYBAVNNJQ40YSKKAXF3653J2"}
 kubectl create secret generic mysecret --from-literal=username=myuser --from-literal=password=mypassword --dry-run=client -o yaml | kubeseal > mysealedsecret.yaml
 ```
 
-Or you can encrypt manifest file containing mysecret.yaml your secret
+Or you can encrypt a manifest file mysecret.yaml (containing your secret).
 
 ```sh {"id":"01HYBAW0WC6R9QYK6W19NP6W34"}
 kubeseal < mysecret.yaml > mysealedsecret.yaml
@@ -64,9 +64,9 @@ Or you can use the sealed-secrets-controller installed in your cluster to encryp
 cat mysecret.yaml | kubeseal --controller-namespace kube-system --controller-name sealed-secrets-controller --format yaml > mysealedsecret.yaml
 ```
 
-Whichever one you run, Runme will automatically create a sealed secret resource containing the encrypted data, the **`mysealedsecret.yaml`**
+For all of the above, Runme will automatically create a sealed secret resource containing the encrypted data, the **`mysealedsecret.yaml`**
 
-### Adding New Value to A Secret
+### Adding a new value to a secret
 
 To add a new value to a secret, you only need to update your manifest file with the new values, re-encrypt the secrets, and then reapply them to the cluster. All of these can be executed in your Runme cell. To do this, run the command below
 
@@ -75,13 +75,13 @@ kubeseal --controller-namespace=kube-system --controller-name=sealed-secrets-con
 kubectl apply -f mysealedsecret.yaml
 ```
 
-Here is a pictorial representation of the command when executed in Runme.
+Here's what it looks like when the command is executed in Runme.
 
 ![add value](/img/guide-page/add-secret.png)
 
-From the output gotten, you can see that your new value has successfully been added.
+From the output you can see that your new value has successfully been added.
 
-### Decrypt a Secret
+### Decrypt a secret
 
 To retrieve the original version of `runme-secrets.yaml`, you can decrypt the encrypted secret, `mysealedsecret.yaml`. Run the command below
 
@@ -93,17 +93,13 @@ When you run the code in your Runme cell, here is what it looks like.
 
 ![decrypt sealed secret](/img/guide-page/decrypt-sealed-secrets.png)
 
-### Delete a Secret
-
-To delete the secret, use the `kubectl` command to delete the resource and run it in your Runme cell.
+### Delete a secret
 
 ```sh {"id":"01HYBANBSHN43RFRRNP3Q0KKFB"}
 kubectl delete -f mysealedsecret.yaml
 ```
 
-### Deploy the Sealed Secret
-
-To deploy your secret, execute the code below:
+### Deploy the sealed secret
 
 ```sh {"id":"01HYBANBSHN43RFRRNP5PR5P9S"}
 kubectl apply -f mysealedsecret.yaml
@@ -114,16 +110,3 @@ kubectl apply -f mysealedsecret.yaml
 The Sealed Secrets controller will decrypt the Sealed Secret and create a Kubernetes Secret with the decrypted data.
 
 Make sure to replace placeholders like **`mysecret.yaml`** and **`mysealedsecret.yaml`** with your secret and Sealed Secret filenames. Adjust controller-specific details such as the namespace and name according to your environment.
-
-## How Runme Improves Your Documentation Experience
-
-In this guide, we explored how to encrypt, decrypt, delete, deploy a Kubernetes secrtes using sealed secrets and Runme. Runme made the process of carrying all these operations out swiftly by utilizing its features.
-
-Some [key features](/usage) of Runme that make it stand out include:
-
-- Its ability to simplify the copying and pasting of commands and codes,
-- Run tasks in the background, interact with your terminal,
-- Render images and tables inside your markdown files,
-- Run code in your preferred language.
-
-These are just a few of the things you can achieve in Runme. To explore Runme more, visit the [Runme Documentation](https://docs.runme.dev/), where you can embark on a guided journey to a more secure Kubernetes environment.

docs/guide/k8s/kubectl.md

@@ -0,0 +1,237 @@
+# Kubectl
+
+In this guide, we will help you understand how to use `kubectl` in a Runme Notebook interact with your kubernetes cluster.
+
+## Prerequisites
+
+- The [Runme extension](https://marketplace.visualstudio.com/items?itemName=stateful.runme) in VS Code (make Runme your [default Markdown viewer](/installation/vscode#how-to-set-vs-code-as-your-default-markdown-viewer))
+- Basic knowledge of Kubernetes concepts (pods, services, deployments).
+- Access to a Kubernetes cluster (for this guide, we will be using a `kind` cluster).
+- Docker ( to create a cluster)
+- `kubectl` [official installation guide](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
+
+```sh {"id":"01J82YTHEHH70ZG99ZAZSW2PJF"}
+brew install kubectl
+```
+
+### Verify kubectl is Installed
+
+```bash {"id":"01J82YTHEHH70ZG99ZB2XP844G"}
+kubectl version --client
+```
+
+### Create a cluster (if you don't have one)
+
+```sh {"id":"01J82YTHEHH70ZG99ZB6Z8HBK4"}
+kind delete cluster --name kubectl-runme
+```
+
+### Create a cluster (locally), using kind, named `kubectl-runme`
+
+```sh {"id":"01J82YTHEHH70ZG99ZBAQR2V18"}
+kind create cluster --name kubectl-runme
+
+```
+
+### Check if your cluster is running
+
+```sh {"id":"01J82YTHEHH70ZG99ZBCAKWHEP"}
+kubectl get namespaces
+```
+
+## Basic commands
+
+Here are some essential Kubernetes commands to help you interact with and monitor your cluster:
+
+### Get Cluster Info
+
+```bash {"id":"01J82YTHEHH70ZG99ZBEYZDE5S"}
+kubectl cluster-info
+```
+
+### Viewing Nodes
+
+Nodes are the physical or virtual machines in your cluster.
+
+```bash {"id":"01J82YTHEHH70ZG99ZBJF5G5KJ"}
+kubectl get nodes
+```
+
+### Viewing Pods
+
+Pods are the smallest deployable units in Kubernetes. To list all pods:
+
+```bash {"id":"01J82YTHEHH70ZG99ZBP39658P"}
+kubectl get pods
+```
+
+For more detailed information about a pod:
+
+```bash {"id":"01J82YTHEHH70ZG99ZBP4FQRC7"}
+kubectl describe pod <pod-name>
+```
+
+### Viewing Services
+
+Services allow networking between different components in your cluster:
+
+```bash {"id":"01J82YTHEHH70ZG99ZBSSHK5FS"}
+kubectl get services
+```
+
+## Working with Deployments
+
+Deployments in Kubernetes allow you to automate the process of scaling, updating, and managing the lifecycle of your applications. Whether you’re deploying a new app or updating an existing one, deployments offer a reliable way to manage your applications with ease. Below are some key commands to help you create, scale, and manage your deployments.
+
+### Create a Deployment
+
+You can create a deployment using a YAML file or via the command line. Here’s an example of creating a deployment for an NGINX server:
+
+```bash {"id":"01J82YTHEHH70ZG99ZBXDDRXJT"}
+kubectl create deployment nginx --image=nginx
+```
+
+### Check Deployment Status
+
+```bash {"id":"01J82YTHEHH70ZG99ZBYV4GFR9"}
+kubectl get deployments
+```
+
+### Scale the Deployment
+
+You can easily scale your deployment to multiple replicas:
+
+```bash {"id":"01J82YTHEHH70ZG99ZC1XDZPHM"}
+kubectl scale deployment nginx --replicas=3
+```
+
+### Rolling Updates
+
+To update the image version for a deployment:
+
+```bash {"id":"01J82YTHEHH70ZG99ZC4BHEBTT"}
+kubectl set image deployment/nginx nginx=nginx:1.19
+```
+
+To monitor the progress of the update:
+
+```bash {"id":"01J82YTHEHH70ZG99ZC6S3EY9W"}
+kubectl rollout status deployment/nginx
+```
+
+To rollback in case of an issue:
+
+```bash {"id":"01J82YTHEHH70ZG99ZC8J3ZCF8"}
+kubectl rollout undo deployment/nginx
+```
+
+## Using YAML Configuration Files
+
+Most Kubernetes objects can be created using YAML files. Here’s an example of a simple pod definition:
+
+```sh {"id":"01J82YTHEHH70ZG99ZCC6GHAWX"}
+
+cat <<EOF | sudo tee ./runme-pod.yaml > /dev/null
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp-pod
+spec:
+  containers:
+  - name: myapp-container
+    image: nginx
+    ports:
+    - containerPort: 80
+
+EOF
+
+```
+
+To create this pod, save it to a file (e.g., `runme-pod.yaml`) and apply it using:
+
+```bash {"id":"01J82YTHEHH70ZG99ZCFBVCCND"}
+kubectl apply -f runme-pod.yaml
+```
+
+To delete resources defined by a YAML file:
+
+```bash {"id":"01J82YTHEHH70ZG99ZCG7Z04AV"}
+kubectl delete -f runme-pod.yaml
+```
+
+## Working with Pods
+
+### Running a Pod
+
+You can run a pod manually using the following command:
+
+```bash {"id":"01J82YTHEHH70ZG99ZCKDNGR11"}
+kubectl run myrunmeapp --image=nginx
+```
+
+To check the logs of a running pod:
+
+```bash {"id":"01J82YTHEHH70ZG99ZCPSWMDYR"}
+kubectl logs <pod-name>
+```
+
+If the pod has multiple containers, specify the container:
+
+```bash {"id":"01J82YTHEHH70ZG99ZCSEED9GA"}
+kubectl logs <pod-name> -c <container-name>
+```
+
+### Executing Commands Inside a Pod
+
+```bash {"id":"01J82YTHEHH70ZG99ZCTC6G9FR"}
+kubectl exec -it <pod-name> -- /bin/bash
+```
+
+This gives you a shell session in the pod's container.
+
+## Services and Exposing Pods
+
+To expose your deployment as a service:
+
+```bash {"id":"01J82YTHEHH70ZG99ZCXSV1YZ2"}
+kubectl expose deployment nginx --type=LoadBalancer --port=80
+```
+
+You can also expose it using NodePort for testing purposes on your local machine:
+
+```bash {"id":"01J82YTHEHH70ZG99ZCZKAAP4Z"}
+kubectl expose deployment nginx --type=NodePort --port=80
+```
+
+To view your exposed services:
+
+```bash {"id":"01J82YTHEHH70ZG99ZD308RHG3"}
+kubectl get services
+```
+
+## Monitoring and Debugging
+
+### Get Logs
+
+To get logs from a pod:
+
+```bash {"id":"01J82YTHEHH70ZG99ZD61WWJAJ"}
+kubectl logs <pod-name>
+```
+
+### Debugging
+
+If a pod crashes, inspect the last few logs:
+
+```bash {"id":"01J82YTHEHH70ZG99ZD9C62XMK"}
+kubectl logs <pod-name> --previous
+```
+
+### Check Resource Usage
+
+To check CPU and memory usage of nodes and pods:
+
+```bash {"id":"01J82YTHEHH70ZG99ZD9PPJZWT"}
+kubectl top nodes
+kubectl top pod
+```