edgelesssys · m1ghtym0 · Mar 10, 2023 · Feb 8, 2023 · Feb 8, 2023 · Feb 10, 2023
@@ -1,5 +1,13 @@
 # Configure your cluster
 
+:::info
+This recording presents the essence of this page. It's recommended to read it in full for the motivation and all details.
+:::
+
+<asciinemaWidget src="/constellation/assets/configure-cluster.cast" rows="20" cols="112" idleTimeLimit="3" preload="true" theme="edgeless" />
+
+---
+
 Before you can create your cluster, you need to configure the identity and access management (IAM) for your cloud service provider (CSP) and choose machine types for the nodes.
 
 ## Creating the configuration file

@@ -1,5 +1,13 @@
 # Create your cluster
 
+:::info
+This recording presents the essence of this page. It's recommended to read it in full for the motivation and all details.
+:::
+
+<asciinemaWidget src="/constellation/assets/create-cluster.cast" rows="20" cols="112" idleTimeLimit="3" preload="true" theme="edgeless" />
+
+---
+
 Creating your cluster requires two steps:
 
 1. Creating the necessary resources in your cloud environment

@@ -1,5 +1,9 @@
 # Consume software bill of materials (SBOMs)
 
+<asciinemaWidget src="/constellation/assets/check-sbom.cast" rows="20" cols="112" idleTimeLimit="3" preload="true" theme="edgeless" />
+
+---
+
 Constellation builds produce a [software bill of materials (SBOM)](https://www.ntia.gov/SBOM) for each generated [artifact](../architecture/microservices.md).
 You can use SBOMs to make informed decisions about dependencies and vulnerabilities in a given application. Enterprises rely on SBOMs to maintain an inventory of used applications, which allows them to take data-driven approaches to managing risks related to vulnerabilities.
 

@@ -1,5 +1,13 @@
 # Terminate your cluster
 
+:::info
+This recording presents the essence of this page. It's recommended to read it in full for the motivation and all details.
+:::
+
+<asciinemaWidget src="/constellation/assets/terminate-cluster.cast" rows="20" cols="112" idleTimeLimit="3" preload="true" theme="edgeless" />
+
+---
+
 You can terminate your cluster using the CLI. For this, you need the Terraform state directory named [`constellation-terraform`](../reference/terraform.md) in the current directory.
 
 :::danger

@@ -1,5 +1,13 @@
 # Verify the CLI
 
+:::info
+This recording presents the essence of this page. It's recommended to read it in full for the motivation and all details.
+:::
+
+<asciinemaWidget src="/constellation/assets/verify-cli.cast" rows="20" cols="112" idleTimeLimit="3" preload="true" theme="edgeless" />
+
+---
+
 Edgeless Systems uses [sigstore](https://www.sigstore.dev/) and [SLSA](https://slsa.dev) to ensure supply-chain security for the Constellation CLI and node images ("artifacts"). sigstore consists of three components: [Cosign](https://docs.sigstore.dev/cosign/overview), [Rekor](https://docs.sigstore.dev/rekor/overview), and Fulcio. Edgeless Systems uses Cosign to sign artifacts. All signatures are uploaded to the public Rekor transparency log, which resides at https://rekor.sigstore.dev/.
 
 :::note

@@ -19,6 +19,7 @@
     "@docusaurus/module-type-aliases": "^2.2.0",
     "@docusaurus/preset-classic": "^2.2.0",
     "
F438
;@mdx-js/react": "^1.6.22",
+    "asciinema-player": "^3.0.1",
     "clsx": "^1.2.1",
     "mdx-mermaid": "^1.3.2",
     "mermaid": "^9.2.2",

@@ -0,0 +1,2 @@
+recordings
+constellation
@@ -0,0 +1,61 @@
+# Screencast / Asciinema
+
+[Asciinema](https://github.com/asciinema/asciinema) is used to automatically generate
+terminal session recordings for our documentation. To fully automate this we use scripts
+that utilize [expect](https://linux.die.net/man/1/expect) to interface with different
+CLI tools, and run them inside a [container](docker/Dockerfile).
+
+## Usage
+
+```sh
+mkdir -P constellation
+./generate-screencasts.sh
+sudo chown -R $USER:$USER ./constellation
+cd constellation && constellation iam destroy
+cd .. && rm -rf ./constellation
+```
+
+This will:
++ build the container
++ run the expect based scripts
++ copy recordings into the assets folder of our docs
+
+To replay the output you can use `asciinema play recordings/verify-cli.cast`.
+
+Include the generated screencast into our docs using the [`AsciinemaWidget`](../src/components/AsciinemaWidget/index.js):
+
+```md
+import AsciinemaWidget from '../../src/components/AsciinemaWidget';
+
+<AsciinemaWidget src="/constellation/assets/verify-cli.cast" fontSize={16} rows={20} cols={112} idleTimeLimit={3} preload={true} theme={'edgeless'} />
+```
+
+Then [re-build and locally host the docs](../README.md).
+
+## Styling
+
+There are three different locations were styling is applied:
+
+1. **The prompt** is styled using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
+More explanation and the actual color codes can be found in [Dockerfile](docker/Dockerfile).
+2. **Player dimensions** are passed to the [`AsciinemaWidget`](../src/components/AsciinemaWidget/index.js)
+when it's [embedded in the docs](../docs/workflows/verify-cli.md#5). Check the `asciinema-player` for a
+[full list of options](https://github.com/asciinema/asciinema-player#options).
+1. **Everything else** is [styled via CSS](../src/css/custom.css). This includes the option to build a custom
+[player theme](https://github.com/asciinema/asciinema-player/wiki/Custom-terminal-themes).
+
+###
+
+## GitHub README.md
+
+The GitHub `README.md` doesn't support embedding the JavaScript `asciinema-player`, therefore we generate an
+`svg` file for that use case.
+
+```sh
+# Make sure to install the converter.
+# https://github.com/nbedos/termtosvg
+pip3 install termtosvg
+
+# Generate SVG. This takes ~10min, since it actually creates a cluster in GCP.
+./generate-readme-svg.sh
+```
@@ -0,0 +1,47 @@
+FROM ubuntu:20.04
+
+# Install requirements
+RUN apt-get update && apt-get install -y software-properties-common &&\
+    apt-add-repository ppa:zanchey/asciinema && apt-get update &&\
+    apt-get install -y curl expect asciinema sudo unzip &&\
+    rm -rf /var/lib/apt/lists/*
+
+RUN curl -sLO https://github.com/mikefarah/yq/releases/download/v4.30.8/yq_linux_amd64 &&\
+    sudo install yq_linux_amd64 /usr/local/bin/yq && rm yq_linux_amd64
+
+RUN curl -sLO https://dl.k8s.io/release/v1.26.0/bin/linux/amd64/kubectl &&\
+    sudo install kubectl /usr/local/bin/kubectl && rm kubectl
+
+RUN curl -sLO https://releases.hashicorp.com/terraform/1.3.8/terraform_1.3.8_linux_amd64.zip &&\
+    unzip terraform_1.3.8_linux_amd64.zip &&\
+    sudo install terraform /usr/local/bin/terraform && rm terraform terraform_1.3.8_linux_amd64.zip
+
+RUN curl -fsSLO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-amd64 &&\
+    sudo install constellation-linux-amd64 /usr/local/bin/constellation &&\
+    rm constellation-linux-amd64
+
+# As mount point for $HOME/.config/gcloud
+RUN mkdir /root/.config
+
+# Disable spinner when running Constellation CLI commands
+ENV CONSTELL_NO_SPINNER=1
+# Enable RGB colors in PS1
+ENV TERM=xterm-256color
+# Set width of terminal, default is ~80 and leads to broken lines for long lines,
+# e.g., curl & cosign commands.
+ENV COLUMNS=512
+# For PS1 to work shell needs to specified
+ENV SHELL=/bin/bash
+# ANSI color codes are used to control PS1 prompt. We use "\033[38;2;<r>;<g>;<b>m"
+# to control the foreground color with RBG colors [1]. Non-printable characters
+# need to  be escaped with additional \[ and \], see [2].
+# [1]: https://stackoverflow.com/a/33206814/2306355
+# [2]: https://stackoverflow.com/a/19501528/2306355
+RUN echo 'export PS1="\[\033[38;2;139;4;221m\]$\[\033[0m\] "' >> /root/.bashrc
+
+# Copy install scripts
+COPY ./*.expect /scripts/
+
+WORKDIR /constellation
+ENTRYPOINT ["/usr/bin/expect", "-f"]
+CMD ["/scripts/verify-cli.expect"]
@@ -0,0 +1,61 @@
+#!/usr/bin/expect -f
+# Note: Expects to be able to run 'sudo install' without a password
+
+set timeout -1
+set send_human {0.05 0 1 0.05 0.3}
+set CTRLC \003
+set record_name [lindex $argv 0];
+
+proc expect_prompt {} {
+    # This matches the trailing 0m of our ANSI control sequence. See PS1 in Dockerfile.
+    expect "0m "
+}
+
+proc run_command {cmd} {
+    send -h "$cmd"
+    send "\r"
+    expect -timeout 1
+}
+
+# Start recording
+spawn asciinema rec --overwrite /recordings/check-sbom.cast
+send "\r"
+expect_prompt
+
+run_command "# Step 1: Install SLSA verifier"
+expect_prompt
+run_command "curl -sLO https://github.com/slsa-framework/slsa-verifier/releases/latest/download/slsa-verifier-linux-amd64"
+expect_prompt
+run_command "sudo install slsa-verifier-linux-amd64 /usr/local/bin/slsa-verifier"
+expect_prompt
+
+run_command "# Step 2: Download Constellation SBOM and provenance"
+expect_prompt
+run_command "curl -sLO https://github.com/edgelesssys/constellation/releases/latest/download/constellation.spdx.sbom"
+expect_prompt
+run_command "curl -sLO https://github.com/edgelesssys/constellation/releases/latest/download/constellation.intoto.jsonl"
+expect_prompt
+
+run_command "# Step 3: Check integrity of SBOM"
+expect_prompt
+run_command "slsa-verifier verify-artifact constellation.spdx.sbom --provenance-path constellation.intoto.jsonl --source-uri github.com/edgelesssys/constellation"
+expect_prompt
+
+run_command "# Step 4: Install grype (security scanner)"
+expect_prompt
+run_command "curl -sLO https://github.com/anchore/grype/releases/download/v0.56.0/grype_0.56.0_linux_amd64.tar.gz"
+expect_prompt
+run_command "tar -xvzf grype_0.56.0_linux_amd64.tar.gz"
+expect_prompt
+run_command "sudo install grype /usr/local/bin/grype"
+expect_prompt
+run_command "grype --help"
+expect_prompt
+
+run_command "# Step 5: Check for vulnerabilities"
+expect_prompt
+run_command "grype constellation.spdx.sbom -o table -q"
+expect_prompt
+
+# Stop recording
+send "exit"
@@ -0,0 +1,35 @@
+#!/usr/bin/expect -f
+# Note: Expects to be able to run 'sudo install' without a password
+
+set timeout -1
+set send_human {0.05 0 1 0.05 0.3}
+set CTRLC \003
+set CTRLX \030
+set record_name [lindex $argv 0];
+
+proc expect_prompt {} {
+    # This matches the trailing 0m of our ANSI control sequence. See PS1 in Dockerfile.
+    expect "0m "
+}
+
+proc run_command {cmd} {
+    send -h "$cmd"
+    send "\r"
+    expect -timeout 1
+}
+
+# Start recording
+spawn asciinema rec --overwrite /recordings/configure-cluster.cast
+send "\r"
+expect_prompt
+
+run_command "# Step 1: Create IAM configuration and Constellation configuration file"
+expect_prompt
+run_command "constellation iam create gcp --generate-config --projectID constellation-331613 --serviceAccountID constellation-demo --zone europe-west3-b"
+expect -re "y\/n"
+send "y"
+send "\r"
+expect_prompt
+
+# Stop recording
+send "exit"
@@ -0,0 +1,53 @@
+#!/usr/bin/expect -f
+# Note: Expects to be able to run 'sudo install' without a password
+
+set timeout -1
+set send_human {0.05 0 1 0.05 0.3}
+set CTRLC \003
+set CTRLX \030
+set record_name [lindex $argv 0];
+
+proc expect_prompt {} {
+    # This matches the trailing 0m of our ANSI control sequence. See PS1 in Dockerfile.
+    expect "0m "
+}
+
+proc run_command {cmd} {
+    send -h "$cmd"
+    send "\r"
+    expect -timeout 1
+}
+
+# Start recording
+spawn asciinema rec --overwrite /recordings/create-cluster.cast
+send "\r"
+expect_prompt
+
+run_command "# Step 1: Create cloud environment"
+expect_prompt
+run_command "constellation create --control-plane-nodes 3 --worker-nodes 2"
+expect -re "y\/n"
+send "y"
+send "\r"
+expect_prompt
+
+run_command "# Step 2: Initialize Constellation"
+expect_prompt
+run_command "constellation init"
+expect_prompt
+
+run_command "# Wait for cluster to finish bootstrapping..."
+expect_prompt
+# Without a sleep we only see a single node, not 5.
+run_command "sleep 300"
+expect_prompt
+
+run_command "# Step 3: Connect to Constellation"
+expect_prompt
+run_command "export KUBECONFIG=/constellation/constellation-admin.conf"
+expect_prompt
+run_command "kubectl get nodes"
+expect_prompt
+
+# Stop recording
+send "exit"