Update Skewer

external/skewer-main/README.md

@@ -10,9 +10,9 @@ and produces two outputs: a `README.md` file and a test routine.
 
 ## An example example
 
-[Example `skewer.yaml` file](test-example/skewer.yaml)
+[Example `skewer.yaml` file](example/skewer.yaml)
 
-[Example `README.md` output](test-example/README.md)
+[Example `README.md` output](example/README.md)
 
 ## Setting up Skewer for your own example
 

external/skewer-main/test-example/README.md → external/skewer-main/example/README.md

@@ -23,10 +23,9 @@ across cloud providers, data centers, and edge sites.
 * [Step 6: Check the status of your namespaces](#step-6-check-the-status-of-your-namespaces)
 * [Step 7: Link your namespaces](#step-7-link-your-namespaces)
 * [Step 8: Fail on demand](#step-8-fail-on-demand)
-* [Step 9: Deploy the frontend and backend services](#step-9-deploy-the-frontend-and-backend-services)
-* [Step 10: Expose the backend service](#step-10-expose-the-backend-service)
-* [Step 11: Expose the frontend service](#step-11-expose-the-frontend-service)
-* [Step 12: Test the application](#step-12-test-the-application)
+* [Step 9: Deploy and expose the frontend](#step-9-deploy-and-expose-the-frontend)
+* [Step 10: Deploy and expose the backend](#step-10-deploy-and-expose-the-backend)
+* [Step 11: Test the application](#step-11-test-the-application)
 * [Accessing the web console](#accessing-the-web-console)
 * [Cleaning up](#cleaning-up)
 * [Summary](#summary)
@@ -35,27 +34,11 @@ across cloud providers, data centers, and edge sites.
 
 ## Overview
 
-This example is a very simple multi-service HTTP application that can
-be deployed across multiple Kubernetes clusters using Skupper.
-
-It contains two services:
-
-* A backend service that exposes an `/api/hello` endpoint.  It
-  returns greetings of the form `Hi, <your-name>.  I am <my-name>
-  (<pod-name>)`.
-
-* A frontend service that sends greetings to the backend and
-  fetches new greetings in response.
-
-With Skupper, you can place the backend in one cluster and the
-frontend in another and maintain connectivity between the two
-services without exposing the backend to the public internet.
-
-<img src="images/entities.svg" width="640"/>
+An overview
 
 ## Prerequisites
 
-Custom prerequisites
+Some prerequisites
 
 ## Step 1: Install the Skupper command-line tool
 
@@ -193,6 +176,7 @@ skupper status
 _Sample output:_
 
 ~~~ console
+$ skupper status
 Skupper is enabled for namespace "<namespace>" in interior mode. It is connected to 1 other site. It has 1 exposed service.
 The site console url is: <console-url>
 The credentials for internal console-auth mode are held in secret: 'skupper-console-users'
@@ -261,84 +245,63 @@ if [ -n "${SKEWER_FAIL}" ]; then expr 1 / 0; fi
 
 ~~~
 
-## Step 9: Deploy the frontend and backend services
+## Step 9: Deploy and expose the frontend
 
-Use `kubectl create deployment` to deploy the frontend service
-in `west` and the backend service in `east`.
+We have established connectivity between the two namespaces and
+made the backend in `east` available to the frontend in `west`.
+Before we can test the application, we need external access to the
+frontend.
+
+Use `kubectl create deployment` to deploy the frontend service in
+West.  Use `kubectl expose` with `--type LoadBalancer` to open
+network access to the frontend service.
 
 _**Console for West:**_
 
 ~~~ shell
 kubectl create deployment frontend --image quay.io/skupper/hello-world-frontend
+kubectl expose deployment/frontend --port 8080 --type LoadBalancer
 ~~~
 
 _Sample output:_
 
 ~~~ console
 $ kubectl create deployment frontend --image quay.io/skupper/hello-world-frontend
 deployment.apps/frontend created
-~~~
-
-_**Console for East:**_
 
-~~~ shell
-kubectl create deployment backend --image quay.io/skupper/hello-world-backend --replicas 3
-~~~
-
-_Sample output:_
-
-~~~ console
-$ kubectl create deployment backend --image quay.io/skupper/hello-world-backend --replicas 3
-deployment.apps/backend created
+$ kubectl expose deployment/frontend --port 8080 --type LoadBalancer
+service/frontend exposed
 ~~~
 
-## Step 10: Expose the backend service
+## Step 10: Deploy and expose the backend
 
 We now have two namespaces linked to form a Skupper network, but
 no services are exposed on it.  Skupper uses the `skupper
 expose` command to select a service from one namespace for
 exposure on all the linked namespaces.
 
-Use `skupper expose` to expose the backend service to the
+Use `kubectl create deployment` to deploy the backend service in
+East.  Use `skupper expose` to expose the backend service to the
 frontend service.
 
 _**Console for East:**_
 
 ~~~ shell
+kubectl create deployment backend --image quay.io/skupper/hello-world-backend --replicas 3
 skupper expose deployment/backend --port 8080
 ~~~
 
 _Sample output:_
 
 ~~~ console
+$ kubectl create deployment backend --image quay.io/skupper/hello-world-backend --replicas 3
+deployment.apps/backend created
+
 $ skupper expose deployment/backend --port 8080
 deployment backend exposed as backend
 ~~~
 
-## Step 11: Expose the frontend service
-
-We have established connectivity between the two namespaces and
-made the backend in `east` available to the frontend in `west`.
-Before we can test the application, we need external access to
-the frontend.
-
-Use `kubectl expose` with `--type LoadBalancer` to open network
-access to the frontend service.
-
-_**Console for West:**_
-
-~~~ shell
-kubectl expose deployment/frontend --port 8080 --type LoadBalancer
-~~~
-
-_Sample output:_
-
-~~~ console
-$ kubectl expose deployment/frontend --port 8080 --type LoadBalancer
-service/frontend exposed
-~~~
-
-## Step 12: Test the application
+## Step 11: Test the application
 
 Now we're ready to try it out.  Use `kubectl get service/frontend`
 to look up the external IP of the frontend service.  Then use
@@ -425,27 +388,11 @@ kubectl delete deployment/backend
 
 ## Summary
 
-This example locates the frontend and backend services in different
-namespaces, on different clusters.  Ordinarily, this means that they
-have no way to communicate unless they are exposed to the public
-internet.
-
-Introducing Skupper into each namespace allows us to create a virtual
-application network that can connect services in different clusters.
-Any service exposed on the application network is represented as a
-local service in all of the linked namespaces.
-
-The backend service is located in `east`, but the frontend service
-in `west` can "see" it as if it were local.  When the frontend
-sends a request to the backend, Skupper forwards the request to the
-namespace where the backend is running and routes the response back to
-the frontend.
-
-<img src="images/sequence.svg" width="640"/>
+A summary
 
 ## Next steps
 
-Custom next steps
+Some next steps
 
 ## About this example
 

external/skewer-main/example/skewer.yaml

@@ -0,0 +1,42 @@
+title: Skupper Hello World
+subtitle: A minimal HTTP application deployed across Kubernetes clusters using Skupper
+github_actions_url: https://github.com/skupperproject/skewer/actions/workflows/main.yaml
+overview: |
+  An overview
+prerequisites: |
+  Some prerequisites
+sites:
+  west:
+    title: West
+    platform: kubernetes
+    namespace: west
+    env:
+      KUBECONFIG: ~/.kube/config-west
+  east:
+    title: East
+    platform: kubernetes
+    namespace: east
+    env:
+      KUBECONFIG: ~/.kube/config-east
+steps:
+  - standard: install_the_skupper_command_line_tool
+  - standard: configure_separate_console_sessions
+  - standard: access_your_clusters
+  - standard: set_up_your_namespaces
+  - standard: install_skupper_in_your_namespaces
+  - standard: check_the_status_of_your_namespaces
+  - standard: link_your_namespaces
+  - title: Fail on demand
+    commands:
+      west:
+        - run: |
+            if [ -n "${SKEWER_FAIL}" ]; then expr 1 / 0; fi
+  - standard: hello_world/deploy_and_expose_the_frontend
+  - standard: hello_world/deploy_and_expose_the_backend
+  - standard: hello_world/test_the_application
+  - standard: accessing_the_web_console
+  - standard: hello_world/cleaning_up
+summary: |
+  A summary
+next_steps: |
+  Some next steps

external/skewer-main/python/skewer/main.py

@@ -177,7 +177,7 @@ def run_steps_minikube(skewer_file, debug=False):
         run("minikube -p skewer delete")
 
 def run_steps(skewer_file, kubeconfigs=None, debug=False):
-    notice(f"Running steps (skewer_file='{get_absolute_path(skewer_file)}')")
+    notice(f"Running steps (skewer_file='{skewer_file}')")
 
     check_environment()
 
@@ -317,11 +317,13 @@ def pause_for_demo(skewer_data):
             pass
 
 def generate_readme(skewer_file, output_file):
-    notice("Generating the readme")
-    notice("  Skewer file: " + get_absolute_path(skewer_file))
-    notice("  Output file: " + get_absolute_path(output_file))
+    notice(f"Generating the readme (skewer_file='{skewer_file}', output_file='{output_file}')")
 
     skewer_data = read_yaml(skewer_file)
+
+    for site in get_sites(skewer_data):
+        site.check()
+
     out = list()
 
     out.append(f"# {skewer_data['title']}")
@@ -568,9 +570,9 @@ def __init__(self, name, data):
 
         self.name = name
         self.title = data.get("title", capitalize(self.name))
-        self.platform = data["platform"]
+        self.platform = data.get("platform")
         self.namespace = data.get("namespace")
-        self.env = data["env"]
+        self.env = data.get("env")
 
     def __enter__(self):
         self._logging_context = logging_context(self.name)
@@ -586,15 +588,30 @@ def __exit__(self, exc_type, exc_value, traceback):
         self._logging_context.__exit__(exc_type, exc_value, traceback)
 
     def check(self):
-        assert self.platform in ("kubernetes", "podman"), self.platform
+        if self.platform is None:
+            fail(f"{self} has no 'platform' attribute")
+
+        if self.platform not in ("kubernetes", "podman"):
+            fail(f"{self} attribute 'platform' has an illegal value: {self.platform}")
 
         if self.platform == "kubernetes":
-            assert self.namespace is not None
-            assert "KUBECONFIG" in self.env
+            if self.namespace is None:
+                fail(f"Kubernetes {self} has no 'namespace' attribute")
+
+            if "KUBECONFIG" not in self.env:
+                fail(f"Kubernetes {self} has no KUBECONFIG environment variable")
 
         if self.platform == "podman":
-            assert "SKUPPER_PLATFORM" in self.env
-            assert self.env["SKUPPER_PLATFORM"] == "podman"
+            if "SKUPPER_PLATFORM" not in self.env:
+                fail(f"Podman {self} has no SKUPPER_PLATFORM environment variable")
+
+            platform = self.env["SKUPPER_PLATFORM"]
+
+            if platform != "podman":
+                fail(f"Podman {self} environment variable SKUPPER_PLATFORM has an illegal value: {platform}")
+
+    def __repr__(self):
+        return f"site '{self.name}'"
 
 def get_steps(skewer_data):
     for step_data in skewer_data["steps"]: