Skip to content

Commit ee1f601

Browse files
wazerywazery
committed
chore: enhance the asciinema demo creation script
1 parent b77b135 commit ee1f601

File tree

5 files changed

+429
-27
lines changed

5 files changed

+429
-27
lines changed

‎Makefile‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,22 @@ generate-charts: build ## Re-generate the helm chart testdata and docs samples
108108
(cd docs/book/src/cronjob-tutorial/testdata/project && ../../../../../../bin/kubebuilder edit --plugins=helm/v1-alpha)
109109
(cd docs/book/src/multiversion-tutorial/testdata/project && ../../../../../../bin/kubebuilder edit --plugins=helm/v1-alpha)
110110

111+
.PHONY: update-demo
112+
update-demo: ## Record and update the Kubebuilder demo using Asciinema
113+
@./scripts/demo/generate-demo.sh
114+
115+
.PHONY: setup-demo-cluster
116+
setup-demo-cluster: ## Set up Kind cluster for Kubebuilder demo
117+
@./scripts/demo/setup-kind.sh
118+
119+
.PHONY: clean-demo
120+
clean-demo: ## Clean up the demo Kind cluster and temporary directories
121+
@echo "Cleaning up demo cluster..."
122+
@kind delete cluster --name kubebuilder-demo || echo "Demo cluster was not found or already deleted"
123+
@echo "Cleaning up temporary demo directories..."
124+
@rm -rf /tmp/kubebuilder-demo-project /tmp/kb-demo-recording
125+
@echo "Demo cleanup completed"
126+
111127
.PHONY: check-docs
112128
check-docs: ## Run the script to ensure that the docs are updated
113129
./hack/docs/check.sh

‎scripts/demo/README.md‎

Lines changed: 101 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,120 @@
1-
This directory contains scripts to run a quick demo of Kubebuilder.
1+
# Kubebuilder Demo
22

3-
Steps to run demo:
3+
This directory contains scripts to run a comprehensive demo of Kubebuilder features with a local Kind cluster.
4+
5+
## Quick Demo (Manual)
6+
7+
To run the demo manually:
48

59
```sh
610
mkdir /tmp/kb-demo
711
cd /tmp/kb-demo
8-
DEMO_AUTO_RUN=1 ./run.sh
12+
DEMO_AUTO_RUN=1 /path/to/kubebuilder/scripts/demo/run.sh
13+
```
14+
15+
## Automated Demo Recording
16+
17+
To automatically record and update the demo using Asciinema:
18+
19+
```sh
20+
# From the root of the Kubebuilder repository
21+
make update-demo
22+
```
23+
24+
This will:
25+
1. Check for required dependencies (asciinema, svg-term, kind, kubectl)
26+
2. Set up a Kind cluster for the demo
27+
3. Record the demo session automatically
28+
4. Convert the recording to SVG format
29+
5. Update the demo file in `docs/gif/kb-demo.${VERSION}.svg`
30+
6. Clean up temporary files
31+
32+
## Setup Demo Cluster Only
33+
34+
If you just want to set up the Kind cluster for testing:
935

36+
```sh
37+
make setup-demo-cluster
1038
```
1139

12-
Instructions for producing the demo movie:
40+
## Clean Up Demo Cluster
41+
42+
To remove the demo Kind cluster when done:
1343

1444
```sh
45+
make clean-demo
46+
```
47+
48+
## Prerequisites for Recording
49+
50+
- `kind`: For creating local Kubernetes clusters
51+
```sh
52+
# macOS
53+
brew install kind
54+
# Linux
55+
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
56+
chmod +x ./kind && sudo mv ./kind /usr/local/bin/kind
57+
```
58+
59+
- `kubectl`: For interacting with Kubernetes
60+
```sh
61+
# macOS
62+
brew install kubectl
63+
# Other platforms: https://kubernetes.io/docs/tasks/tools/install-kubectl/
64+
```
65+
66+
- `asciinema`: For recording terminal sessions
67+
```sh
68+
# macOS
69+
brew install asciinema
70+
# Ubuntu/Debian
71+
sudo apt-get install asciinema
72+
```
73+
74+
- `svg-term`: For converting recordings to SVG
75+
```sh
76+
npm install -g svg-term-cli
77+
```
78+
79+
## What the Demo Shows
80+
81+
The current demo showcases:
82+
83+
1. **Cluster Setup**: Creates a local Kind cluster for testing
84+
2. **Installation**: Installing Kubebuilder from scratch
85+
3. **Project Initialization**: Creating a new operator project
86+
4. **API Creation**: Creating APIs with validation markers
87+
5. **Plugin System**: Using the deploy-image plugin
88+
6. **Modern Features**:
89+
- Validation markers (`+kubebuilder:validation`)
90+
- Multiple APIs in one project
91+
- Generated CRDs with OpenAPI schemas
92+
- Sample resource management
93+
7. **Development Workflow**: Install CRDs, apply samples, run controller
94+
8. **Cluster Integration**: Full integration with Kubernetes cluster
95+
96+
## Manual Recording Instructions (Legacy)
97+
98+
If you prefer to record manually:
99+
100+
```sh
101+
# Set up Kind cluster first
102+
./scripts/demo/setup-kind.sh
15103

16104
# Create temporary directory
17105
mkdir /tmp/kb-demo
18106
cd /tmp/kb-demo
19107

20-
asciinema rec
21-
<path-to-KB-repo>/scripts/demo/run.sh
22-
23-
# After each step, press <Enter> to proceed to the next step
108+
# Start recording
109+
asciinema rec --title "Kubebuilder Demo" kb-demo.cast
24110

25-
<CTRL-C> to terminate the script
26-
<CTRL-D> to terminate the asciinema recording
27-
<CTRL-C> to save the recording locally
111+
# Run the demo script
112+
DEMO_AUTO_RUN=1 /path/to/kubebuilder/scripts/demo/run.sh
28113

29-
# Edit the recorded file by editing the controller-gen path
30-
# Once you are happy with the recording, use svg-term program to generate the svg
114+
# Stop recording with Ctrl+C when done
115+
# Convert to SVG
116+
svg-term --in=kb-demo.cast --out=kb-demo.svg --window --width=120 --height=30
31117

32-
svg-term --in=<cast-file-path> --out demo.svg --window
118+
# Clean up when done
119+
kind delete cluster --name kubebuilder-demo
33120
```

‎scripts/demo/generate-demo.sh‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
#!/usr/bin/env bash
2+
3+
# Copyright 2023 The Kubernetes Authors.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -e
18+
19+
SCRIPT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
20+
PROJECT_ROOT="$(cd "${SCRIPT_ROOT}/../.." && pwd)"
21+
22+
# Colors for output
23+
RED='\033[0;31m'
24+
GREEN='\033[0;32m'
25+
YELLOW='\033[1;33m'
26+
NC='\033[0m' # No Color
27+
28+
log() {
29+
echo -e "${GREEN}[INFO]${NC} $1"
30+
}
31+
32+
warn() {
33+
echo -e "${YELLOW}[WARN]${NC} $1"
34+
}
35+
36+
error() {
37+
echo -e "${RED}[ERROR]${NC} $1"
38+
exit 1
39+
}
40+
41+
check_prerequisites() {
42+
log "Checking prerequisites..."
43+
44+
local missing_tools=()
45+
46+
if ! command -v asciinema &> /dev/null; then
47+
missing_tools+=("asciinema (install with: brew install asciinema)")
48+
fi
49+
50+
if ! command -v svg-term &> /dev/null; then
51+
missing_tools+=("svg-term (install with: npm install -g svg-term-cli)")
52+
fi
53+
54+
if ! command -v kind &> /dev/null; then
55+
missing_tools+=("kind (install with: brew install kind)")
56+
fi
57+
58+
if ! command -v kubectl &> /dev/null; then
59+
missing_tools+=("kubectl (install from: https://kubernetes.io/docs/tasks/tools/install-kubectl/)")
60+
fi
61+
62+
if [ ${#missing_tools[@]} -ne 0 ]; then
63+
error "Missing required tools:\n$(printf ' - %s\n' "${missing_tools[@]}")"
64+
fi
65+
66+
log "All prerequisites are installed ✓"
67+
}
68+
69+
setup_cluster() {
70+
log "Setting up Kind cluster for demo..."
71+
"${SCRIPT_ROOT}/setup-kind.sh"
72+
73+
log "Verifying cluster connection..."
74+
kubectl cluster-info --context kind-kubebuilder-demo > /dev/null
75+
log "Cluster connection verified ✓"
76+
}
77+
78+
record_demo() {
79+
local recording_dir="/tmp/kb-demo-recording"
80+
81+
log "Cleaning up any previous recording files..."
82+
rm -rf "$recording_dir"
83+
mkdir -p "$recording_dir"
84+
85+
log "Starting demo recording in 3 seconds..."
86+
sleep 3
87+
88+
cd "$recording_dir"
89+
asciinema rec \
90+
--command "${SCRIPT_ROOT}/run.sh" \
91+
--env "DEMO_AUTO_RUN=1" \
92+
--title "Kubebuilder Demo" \
93+
--idle-time-limit 2 \
94+
kb-demo.cast
95+
}
96+
97+
convert_to_svg() {
98+
local recording_dir="/tmp/kb-demo-recording"
99+
local version
100+
version=$(git -C "$PROJECT_ROOT" describe --tags --abbrev=0 2>/dev/null || echo "v4.0.0")
101+
local svg_file="${PROJECT_ROOT}/docs/gif/kb-demo.${version}.svg"
102+
103+
log "Converting recording to SVG..."
104+
svg-term \
105+
--in="${recording_dir}/kb-demo.cast" \
106+
--out="$svg_file" \
107+
--window \
108+
--width=120 \
109+
--height=30
110+
111+
log "Demo updated! New file: docs/gif/kb-demo.${version}.svg"
112+
return 0
113+
}
114+
115+
update_readme() {
116+
local version
117+
version=$(git -C "$PROJECT_ROOT" describe --tags --abbrev=0 2>/dev/null || echo "v4.0.0")
118+
119+
log "Updating README.md with new demo..."
120+
if [[ "$OSTYPE" == "darwin"* ]]; then
121+
# macOS
122+
sed -i '' "s|docs/gif/kb-demo\.v[^)]*\.svg|docs/gif/kb-demo.${version}.svg|g" "${PROJECT_ROOT}/README.md"
123+
else
124+
# Linux
125+
sed -i "s|docs/gif/kb-demo\.v[^)]*\.svg|docs/gif/kb-demo.${version}.svg|g" "${PROJECT_ROOT}/README.md"
126+
fi
127+
128+
log "README.md updated with new demo file ✓"
129+
}
130+
131+
cleanup() {
132+
log "Cleaning up temporary files..."
133+
rm -rf /tmp/kb-demo-recording
134+
log "To clean up the demo cluster, run: make clean-demo"
135+
}
136+
137+
main() {
138+
log "Starting Kubebuilder demo generation..."
139+
140+
check_prerequisites
141+
setup_cluster
142+
record_demo
143+
convert_to_svg
144+
update_readme
145+
cleanup
146+
147+
log "Demo generation completed successfully! 🎉"
148+
}
149+
150+
main "$@"

‎scripts/demo/run.sh‎

Lines changed: 54 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -13,31 +13,72 @@
1313
# See the License for the specific language governing permissions and
1414
# limitations under the License.
1515

16+
# Set up working directory in /tmp for clean demo
17+
cd /tmp
18+
rm -rf kubebuilder-demo-project
19+
mkdir kubebuilder-demo-project
20+
cd kubebuilder-demo-project
21+
1622
clear
1723
. $(dirname ${BASH_SOURCE})/util.sh
1824

19-
desc "Initialize Go modules"
20-
run "go mod init demo.kubebuilder.io"
25+
desc "Check if Kubebuilder is installed"
26+
run "kubebuilder version"
27+
28+
desc "Initialize Go modules for our project"
29+
run "go mod init demo.kubebuilder.io/webapp-operator"
30+
31+
desc "Initialize a new Kubebuilder project with custom domain"
32+
run "kubebuilder init --domain demo.kubebuilder.io --repo demo.kubebuilder.io/webapp-operator"
33+
clear
34+
35+
desc "Examine the scaffolded project structure"
36+
run "tree -L 2 ."
37+
clear
38+
39+
desc "Create our first API - a Guestbook with validation markers"
40+
run "kubebuilder create api --group webapp --version v1 --kind Guestbook"
41+
clear
2142

22-
desc "Let's initialize the project"
23-
run "kubebuilder init --domain tutorial.kubebuilder.io"
43+
desc "Let's explore the generated files structure"
44+
run "tree api/ internal/controller/"
2445
clear
2546

26-
desc "Examine scaffolded files..."
27-
run "tree ."
47+
desc "Look at the API definition - notice the validation markers"
48+
run "cat api/v1/guestbook_types.go"
2849
clear
2950

30-
desc "Create our custom cronjob api"
31-
run "kubebuilder create api --group batch --version v1 --kind CronJob"
51+
desc "Now let's create a second API using the modern deploy-image plugin"
52+
run "kubebuilder create api --group webapp --version v1alpha1 --kind Busybox --image=busybox:1.36.1 --plugins=deploy-image/v1-alpha"
3253
clear
3354

34-
desc "Let's take a look at the API and Controller files"
35-
run "tree ./api ./internal/controller"
55+
desc "Generate manifests including CRDs with OpenAPI validation schemas"
56+
run "make manifests"
57+
58+
desc "Examine the generated CRD with validation rules"
59+
run "head -60 config/crd/bases/webapp.demo.kubebuilder.io_guestbooks.yaml"
3660
clear
3761

38-
desc "Install CRDs in Kubernetes cluster"
62+
desc "Install our Custom Resource Definitions into the cluster"
3963
run "make install"
64+
65+
desc "Verify our CRDs are installed"
66+
run "kubectl get crd --context kind-kubebuilder-demo"
67+
clear
68+
69+
desc "Look at the sample resources that were generated"
70+
run "ls config/samples/"
71+
72+
desc "Show a sample resource"
73+
run "cat config/samples/webapp_v1_guestbook.yaml"
74+
clear
75+
76+
desc "Apply the sample resources to test our APIs"
77+
run "kubectl apply -k config/samples/webapp_v1alpha1_busybox.yaml --context kind-kubebuilder-demo"
78+
79+
desc "Check the created custom resources in the cluster"
80+
run "kubectl get guestbooks,busyboxes -A --context kind-kubebuilder-demo"
4081
clear
4182

42-
desc "Run controller manager locally"
43-
run "make run"
83+
desc "Demo completed! The controller can be run with 'make run'"
84+
run "echo 'To run the controller: make run'"

0 commit comments

Comments
 (0)