WIP

README.md

@@ -14,7 +14,9 @@ across cloud providers, data centers, and edge sites.
 #### Contents
 
 * [Prerequisites](#prerequisites)
-* [Step 1: Experimenting](#step-1-experimenting)
+* [Step 1: Install the Skupper command-line tool](#step-1-install-the-skupper-command-line-tool)
+* [Step 2: Install the Skupper Ansible collection](#step-2-install-the-skupper-ansible-collection)
+* [Step 3: Experimenting](#step-3-experimenting)
 * [Next steps](#next-steps)
 * [About this example](#about-this-example)
 
@@ -29,9 +31,39 @@ across cloud providers, data centers, and edge sites.
 [install-kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
 [kube-providers]: https://skupper.io/start/kubernetes.html
 
-## Step 1: Experimenting
+## Step 1: Install the Skupper command-line tool
 
-_**Other:**_
+This example uses the Skupper command-line tool to deploy Skupper.
+You need to install the `skupper` command only once for each
+development environment.
+
+On Linux or Mac, you can use the install script (inspect it
+[here][install-script]) to download and extract the command:
+
+~~~ shell
+curl https://skupper.io/install.sh | sh
+~~~
+
+The script installs the command under your home directory.  It
+prompts you to add the command to your path if necessary.
+
+For Windows and other installation options, see [Installing
+Skupper][install-docs].
+
+[install-script]: https://github.com/skupperproject/skupper-website/blob/main/input/install.sh
+[install-docs]: https://skupper.io/install/
+
+## Step 2: Install the Skupper Ansible collection
+
+_**Terminal:**_
+
+~~~ shell
+ansible-galaxy collection install skupper.network
+~~~
+
+## Step 3: Experimenting
+
+_**Terminal:**_
 
 ~~~ shell
 ansible-playbook -i ansible/inventory.yml ansible/setup.yml ansible/test.yml ansible/teardown.yml

external/skewer/README.md

@@ -15,6 +15,7 @@ and produces two outputs: a `README.md` file and a test routine.
 * [Skewer YAML](#skewer-yaml)
 * [Standard steps](#standard-steps)
 * [Demo mode](#demo-mode)
+* [Troubleshooting](#troubleshooting)
 
 ## An example example
 
@@ -329,3 +330,24 @@ up and exiting, it pauses so you can inspect things.
 It is enabled by setting the environment variable `SKEWER_DEMO` to any
 value when you call `./plano run` or one of its variants.  You can
 also use `./plano demo`, which sets the variable for you.
+
+## Troubleshooting
+
+### Subnet is already used
+
+Error:
+
+~~~ console
+plano: notice: Starting Minikube
+plano: notice: Running command 'minikube start -p skewer --auto-update-drivers false'
+* Creating podman container (CPUs=2, Memory=16000MB) ...- E0229 05:44:29.821273   12224 network_create.go:113] error while trying to create podman network skewer 192.168.49.0/24: create podman network skewer 192.168.49.0/24 with gateway 192.168.49.1 and MTU of 0: sudo -n podman network create --driver=bridge --subnet=192.168.49.0/24 --gateway=192.168.49.1 --label=created_by.minikube.sigs.k8s.io=true --label=name.minikube.sigs.k8s.io=skewer skewer: exit status 125
+
+Error: subnet 192.168.49.0/24 is already used on the host or by another config
+~~~
+
+Remove the existing Podman network.  Note that it might belong to
+another user on the host.
+
+~~~ shell
+sudo podman network rm minikube
+~~~

external/skewer/python/skewer/main.py

@@ -627,7 +627,7 @@ def check(self):
         check_required_attributes(self, "platform")
         check_unknown_attributes(self)
 
-        if self.platform not in ("kubernetes", "podman"):
+        if self.platform not in ("kubernetes", "podman", None):
             fail(f"{self} attribute 'platform' has an illegal value: {self.platform}")
 
         if self.platform == "kubernetes":

skewer.yaml

@@ -13,14 +13,15 @@ sites:
     env:
       KUBECONFIG: /tmp/skewer/kubeconfig-east
   other:
-    title: Other
-    platform: podman
-    env:
-      SKUPPER_PLATFORM: podman
+    title: Terminal
+    platform: null
 steps:
+  - standard: general/install_the_skupper_command_line_tool
+  - title: Install the Skupper Ansible collection
+    commands:
+      other:
+        - run: ansible-galaxy collection install skupper.network
   - title: Experimenting
     commands:
       other:
-        - run: |
-            ansible-galaxy collection install skupper.network
-            ansible-playbook -i ansible/inventory.yml ansible/setup.yml ansible/test.yml ansible/teardown.yml
+        - run: ansible-playbook -i ansible/inventory.yml ansible/setup.yml ansible/test.yml ansible/teardown.yml