Skip to content

Commit

Permalink
Skewer update
Browse files Browse the repository at this point in the history
  • Loading branch information
@ssorj
ssorj committed Feb 27, 2024
1 parent 218cd3c commit 3abe253
Show file tree
Hide file tree
Showing 7 changed files with 212 additions and 234 deletions.
59 changes: 16 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ 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)
Expand Down Expand Up @@ -82,12 +82,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/

Expand Down Expand Up @@ -137,9 +137,8 @@ kubectl config set-context --current --namespace east
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 `west` and the backend in namespace
`east`.
Use `kubectl create deployment` to deploy the frontend in West
and the backend in East.

_**West:**_

Expand Down Expand Up @@ -229,9 +228,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 West to generate the
token. Then, use `skupper link create` in site East to link
the sites.
First, use `skupper token create` in West to generate the
token. Then, use `skupper link create` in East to link the
sites.

_**West:**_

Expand Down Expand Up @@ -293,43 +292,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`.

_**West:**_

~~~ 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

Expand Down
142 changes: 84 additions & 58 deletions external/skewer/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,14 @@ 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)

## An example example

[Example `skewer.yaml` file](example/skewer.yaml)
Expand Down Expand Up @@ -89,7 +97,7 @@ commands:

## Skewer YAML

The top level:
The top level of the `skewer.yaml` file:

~~~ yaml
title: # Your example's title (required)
Expand All @@ -103,7 +111,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**:

Expand Down Expand Up @@ -167,12 +186,69 @@ steps:
west: <list-of-commands>
~~~

Or you can use a named step from the library of standard steps:
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" (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.
The `output` field is used as sample output only, not for any kind of
testing.

The `apply` field is useful when you want the readme instructions to
be different from the test procedure, or you simply want to omit
something.

There are also some special "await" commands that you can use to pause
for a condition you require before going to the next step. They are
used only for testing and do not impact the README.

~~~ yaml
- await_resource: # A resource for which to await readiness (optional)
# Example: await_resource: deployment/frontend
- await_ingress: # A service for which to await an external hostname or IP (optional)
# Example: await_ingress: service/frontend
- await_http_ok: # A service and URL template for which to await an HTTP OK response (optional)
# Example: await_http_ok: [service/frontend, "http://{}:8080/api/hello"]
~~~

Example commands:

~~~ yaml
- standard: configure_separate_console_sessions
commands:
east:
- run: skupper expose deployment/backend --port 8080
output: |
deployment backend exposed as backend
west:
- await_resource: service/backend
- run: kubectl get service/backend
output: |
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
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:
Expand All @@ -181,13 +257,13 @@ They are the following:
general/install_the_skupper_command_line_tool
general/link_your_sites
general/cleaning_up
kubernetes/set_up_your_namespaces
kubernetes/set_up_your_kubernetes_namespace # One namespace only
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_network
podman/set_up_your_podman_environment
hello_world/deploy_the_frontend_and_backend
hello_world/expose_the_backend
hello_world/access_the_frontend
Expand Down Expand Up @@ -236,7 +312,7 @@ example might look like this:
~~~ yaml
steps:
- standard: general/install_the_skupper_command_line_tool
- standard: kubernetes/set_up_your_namespaces
- standard: kubernetes/set_up_your_clusters
<your-custom-deploy-step>
- standard: kubernetes/create_your_sites
- standard: kubernetes/link_your_sites
Expand All @@ -245,56 +321,6 @@ steps:
- standard: kubernetes/cleaning_up
~~~

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.

A **command**:

~~~ yaml
- run: # A shell command (required)
apply: # Use this command only for "readme" or "test" (optional, default is both)
output: # Sample output to include in the README (optional)
~~~

Only the `run` and `output` fields are used in the README content.
The `output` field is used as sample output only, not for any kind of
testing.

The `apply` field is useful when you want the readme instructions to
be different from the test procedure, or you simply want to omit
something.

There are also some special "await" commands that you can use to pause
for a condition you require before going to the next step. They are
used only for testing and do not impact the README.

~~~ yaml
- await_resource: # A resource for which to await readiness (optional)
# Example: await_resource: deployment/frontend
- await_ingress: # A service for which to await an external hostname or IP (optional)
# Example: await_ingress: service/frontend
- await_http_ok: # A service and URL template for which to await an HTTP OK response (optional)
# Example: await_http_ok: [service/frontend, "http://{}:8080/api/hello"]
~~~

Example commands:

~~~ yaml
commands:
east:
- run: skupper expose deployment/backend --port 8080
output: |
deployment backend exposed as backend
west:
- await_resource: service/backend
- run: kubectl get service/backend
output: |
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
backend ClusterIP 10.102.112.121 <none> 8080/TCP 30s
~~~

## Demo mode

Skewer has a mode where it executes all the steps, but before cleaning
Expand Down
Loading

0 comments on commit 3abe253

Please sign in to comment.