Skewer update

skupperproject · Mar 7, 2024 · 5b0f720 · 5b0f720
1 parent 710c0f9
commit 5b0f720
Show file tree

Hide file tree

Showing 11 changed files with 405 additions and 325 deletions.
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
@@ -35,11 +35,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.x"
-      - uses: manusa/actions-setup-minikube@v2.10.0
-        with:
-          minikube version: "v1.32.0"
-          kubernetes version: "v1.29.0"
-          github token: ${{secrets.GITHUB_TOKEN}}
+      - uses: medyagh/setup-minikube@latest
       - run: curl https://skupper.io/install.sh | bash -s -- --version ${{matrix.skupper-version}}
       - run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
       - run: ./plano test

diff --git a/README.md b/README.md
@@ -1,3 +1,5 @@
+<!-- NOTE: This file is generated from skewer.yaml.  Do not edit it directly. -->
+
 # Skupper Hello World public to private
 
 [![main](https://github.com/skupperproject/skupper-example-public-to-private/actions/workflows/main.yaml/badge.svg)](https://github.com/skupperproject/skupper-example-public-to-private/actions/workflows/main.yaml)
@@ -16,14 +18,13 @@ across cloud providers, data centers, and edge sites.
 * [Overview](#overview)
 * [Prerequisites](#prerequisites)
 * [Step 1: Install the Skupper command-line tool](#step-1-install-the-skupper-command-line-tool)
-* [Step 2: Set up your namespaces](#step-2-set-up-your-namespaces)
+* [Step 2: Set up your clusters](#step-2-set-up-your-clusters)
 * [Step 3: Deploy the frontend and backend](#step-3-deploy-the-frontend-and-backend)
 * [Step 4: Create your sites](#step-4-create-your-sites)
 * [Step 5: Link your sites](#step-5-link-your-sites)
 * [Step 6: Expose the backend](#step-6-expose-the-backend)
 * [Step 7: Access the frontend](#step-7-access-the-frontend)
 * [Cleaning up](#cleaning-up)
-* [Summary](#summary)
 * [Next steps](#next-steps)
 * [About this example](#about-this-example)
 
@@ -82,12 +83,12 @@ Skupper][install-docs].
 [install-script]: https://github.com/skupperproject/skupper-website/blob/main/input/install.sh
 [install-docs]: https://skupper.io/install/
 
-## Step 2: Set up your namespaces
+## Step 2: Set up your clusters
 
-Skupper is designed for use with multiple Kubernetes namespaces,
-usually on different clusters.  The `skupper` and `kubectl`
-commands use your [kubeconfig][kubeconfig] and current context to
-select the namespace where they operate.
+Skupper is designed for use with multiple Kubernetes clusters.
+The `skupper` and `kubectl` commands use your
+[kubeconfig][kubeconfig] and current context to select the cluster
+and namespace where they operate.
 
 [kubeconfig]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/
 
@@ -137,9 +138,8 @@ kubectl config set-context --current --namespace private
 This example runs the frontend and the backend in separate
 Kubernetes namespaces, on different clusters.
 
-Use `kubectl create deployment` to deploy the frontend in
-namespace `public` and the backend in namespace
-`private`.
+Use `kubectl create deployment` to deploy the frontend in Public
+and the backend in Private.
 
 _**Public:**_
 
@@ -229,9 +229,9 @@ that generated it.
 token can link to your site.  Make sure that only those you trust
 have access to it.
 
-First, use `skupper token create` in site Public to generate the
-token.  Then, use `skupper link create` in site Private to link
-the sites.
+First, use `skupper token create` in Public to generate the
+token.  Then, use `skupper link create` in Private to link the
+sites.
 
 _**Public:**_
 
@@ -293,43 +293,17 @@ deployment backend exposed as backend
 In order to use and test the application, we need external access
 to the frontend.
 
-Use `kubectl expose` with `--type LoadBalancer` to open network
-access to the frontend service.
-
-Once the frontend is exposed, use `kubectl get service/frontend`
-to look up the external IP of the frontend service.  If the
-external IP is `<pending>`, try again after a moment.
-
-Once you have the external IP, use `curl` or a similar tool to
-request the `/api/health` endpoint at that address.
-
-**Note:** The `<external-ip>` field in the following commands is a
-placeholder.  The actual value is an IP address.
+Use `kubectl port-forward` to make the frontend available at
+`localhost:8080`.
 
 _**Public:**_
 
 ~~~ shell
-kubectl expose deployment/frontend --port 8080 --type LoadBalancer
-kubectl get service/frontend
-curl http://<external-ip>:8080/api/health
-~~~
-
-_Sample output:_
-
-~~~ console
-$ kubectl expose deployment/frontend --port 8080 --type LoadBalancer
-service/frontend exposed
-
-$ kubectl get service/frontend
-NAME       TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)          AGE
-frontend   LoadBalancer   10.103.232.28   <external-ip>   8080:30407/TCP   15s
-
-$ curl http://<external-ip>:8080/api/health
-OK
+kubectl port-forward deployment/frontend 8080:8080
 ~~~
 
-If everything is in order, you can now access the web interface by
-navigating to `http://<external-ip>:8080/` in your browser.
+You can now access the web interface by navigating to
+[http://localhost:8080](http://localhost:8080) in your browser.
 
 ## Cleaning up
 
@@ -340,7 +314,6 @@ _**Public:**_
 
 ~~~ shell
 skupper delete
-kubectl delete service/frontend
 kubectl delete deployment/frontend
 ~~~
 

diff --git a/external/skewer/.github/workflows/main.yaml b/external/skewer/.github/workflows/main.yaml
@@ -16,11 +16,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.x"
-      - uses: manusa/actions-setup-minikube@v2.10.0
-        with:
-          minikube version: "v1.32.0"
-          kubernetes version: "v1.29.0"
-          github token: ${{secrets.GITHUB_TOKEN}}
+      - uses: medyagh/setup-minikube@latest
       - run: curl https://skupper.io/install.sh | bash -s -- --version ${{matrix.skupper-version}}
       - run: echo "$HOME/.local/bin" >> $GITHUB_PATH
       - run: ./plano test

diff --git a/external/skewer/README.md b/external/skewer/README.md
@@ -8,6 +8,15 @@ A `skewer.yaml` file describes the steps and commands to achieve an
 objective using Skupper.  Skewer takes the `skewer.yaml` file as input
 and produces two outputs: a `README.md` file and a test routine.
 
+#### Contents
+
+* [An example example](#an-example-example)
+* [Setting up Skewer for your own example](#setting-up-skewer-for-your-own-example)
+* [Skewer YAML](#skewer-yaml)
+* [Standard steps](#standard-steps)
+* [Demo mode](#demo-mode)
+* [Troubleshooting](#troubleshooting)
+
 ## An example example
 
 [Example `skewer.yaml` file](example/skewer.yaml)
@@ -89,7 +98,7 @@ commands:
 
 ## Skewer YAML
 
-The top level:
+The top level of the `skewer.yaml` file:
 
 ~~~ yaml
 title:              # Your example's title (required)
@@ -103,7 +112,18 @@ summary:            # Text to summarize what the user did (optional)
 next_steps:         # Text linking to more examples (optional, has default text)
 ~~~
 
-To disable the GitHub workflow, set it to `null`.
+For fields with default text such as `prerequisites` and `next_steps`,
+you can include the default text inside your custom text by using the
+`@default@` placeholder:
+
+~~~ yaml
+next_steps:
+    @default@
+
+    This Way to the Egress.
+~~~
+
+To disable the GitHub workflow and CI badge, set `workflow` to `null`.
 
 A **site**:
 
@@ -167,77 +187,25 @@ steps:
       west: <list-of-commands>
 ~~~
 
-Or you can use a named step from the library of standard steps:
-
-~~~ yaml
-- standard: configure_separate_console_sessions
-~~~
-
-The standard steps are defined in
-[python/skewer/standardsteps.yaml](python/skewer/standardsteps.yaml).
-Note that you should not edit this file.  Instead, in your
-`skewer.yaml` file, you can create custom steps based on the standard
-steps.  You can override the `title`, `preamble`, `commands`, or
-`postamble` field of a standard step by adding the field in addition
-to `standard`:
-
-~~~ yaml
-- standard: cleaning_up
-  commands:
-    east:
-     - run: skupper delete
-     - run: kubectl delete deployment/database
-    west:
-     - run: skupper delete
-~~~
-
-A typical mix of standard and custom steps might look like this:
-
-~~~ yaml
-steps:
-  - standard: install_the_skupper_command_line_tool
-  - standard: kubernetes/set_up_your_namespaces
-  <your-custom-deploy-step>
-  - standard: kubernetes/create_your_sites
-  - standard: kubernetes/link_your_sites
-  <your-custom-expose-step>
-  <your-custom-access-step>
-  - standard: cleaning_up
-~~~
-
-**Note:** The `link_your_sites` and `cleaning_up` steps are less
-generic than the other steps.  For example, `cleaning_up` doesn't
-delete any application workoads.  Check that the text and commands
-these steps produce are doing what you need for your example.  If not,
-you need to provide a custom step.
-
-There are some standard steps for examples based on the Skupper
-Hello World application:
-
-~~~ yaml
-- standard: hello_world/deploy_the_frontend_and_backend
-- standard: hello_world/expose_the_backend
-- standard: hello_world/access_the_frontend
-- standard: hello_world/cleaning_up
-~~~
-
-And finally there are some special cases:
-~~~ yaml
-- standard: kubernetes/set_up_your_kubernetes_namespace
-- standard: podman/set_up_your_podman_network
-~~~
-
 The step commands are separated into named groups corresponding to the
 sites.  Each named group contains a list of command entries.  Each
 command entry has a `run` field containing a shell command and other
 fields for awaiting completion or providing sample output.
 
+You can also use a named step from the library of [standard
+steps](#standard-steps):
+
+~~~ yaml
+- standard: kubernetes/set_up_your_clusters
+~~~
+
 A **command**:
 
 ~~~ yaml
 - run:              # A shell command (required)
-  apply:            # Use this command only for "readme" or "test" (optional, default is both)
+  apply:            # Use this command only for "readme" or "test" (default is both)
   output:           # Sample output to include in the README (optional)
+  expect_failure:   # If true, check that the command fails and keep going (default false)
 ~~~
 
 Only the `run` and `output` fields are used in the README content.
@@ -277,6 +245,83 @@ commands:
         backend       ClusterIP      10.102.112.121   <none>           8080/TCP        30s
 ~~~
 
+## Standard steps
+
+Skewer includes a library of standard steps with descriptive text and
+commands that we use a lot for our examples.
+
+The standard steps are defined in
+[python/skewer/standardsteps.yaml](python/skewer/standardsteps.yaml).
+They are the following:
+
+~~~
+general/install_the_skupper_command_line_tool
+general/link_your_sites
+general/cleaning_up
+kubernetes/set_up_your_clusters
+kubernetes/set_up_your_kubernetes_cluster  # One cluster only
+kubernetes/create_your_sites
+kubernetes/link_your_sites
+kubernetes/access_the_frontend
+kubernetes/cleaning_up
+podman/set_up_your_podman_environment
+hello_world/deploy_the_frontend_and_backend
+hello_world/expose_the_backend
+hello_world/access_the_frontend
+hello_world/cleaning_up
+~~~
+
+The `general` steps are generic (or pretty generic) with respect to
+platform and application.  The `kubernetes` and `podman` steps are
+coupled to their platform.  The `hello_world` steps are specific to
+the Skupper Hello World application.
+
+**Note:** The `link_your_sites` and `cleaning_up` steps are less
+generic than the other `general` steps.  For example, `cleaning_up`
+doesn't delete any application workoads.  Check that the text and
+commands these steps produce are doing what you need for your example.
+If not, you need to provide a custom step.
+
+You can create custom steps based on the standard steps by overriding
+the `title`, `preamble`, `commands`, or `postamble` fields.
+
+~~~ yaml
+- standard: kubernetes/cleaning_up
+  commands:
+    east:
+     - run: skupper delete
+     - run: kubectl delete deployment/database
+    west:
+     - run: skupper delete
+~~~
+
+For string fields such as `preamble` and `postamble`, you can include
+the standard text inside your custom text by using the `@default@`
+placeholder:
+
+~~~ yaml
+- standard: general/cleaning_up
+  preamble: |
+    @default@
+
+    Note: You may also want to flirp your krupke.
+~~~
+
+A typical mix of standard and custom steps for a Kubernetes-based
+example might look like this:
+
+~~~ yaml
+steps:
+  - standard: general/install_the_skupper_command_line_tool
+  - standard: kubernetes/set_up_your_clusters
+  <your-custom-deploy-step>
+  - standard: kubernetes/create_your_sites
+  - standard: kubernetes/link_your_sites
+  <your-custom-expose-step>
+  <your-custom-access-step>
+  - standard: kubernetes/cleaning_up
+~~~
+
 ## Demo mode
 
 Skewer has a mode where it executes all the steps, but before cleaning
@@ -285,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
+~~~