Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[spin]: Rework trigger docs #1450

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
+684 −107
Draft

[spin]: Rework trigger docs #1450

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1d48460
chore: rework Spin trigger docs
ThorstenHans Jan 9, 2025
88967be
Update content/spin/v3/command-trigger.md
ThorstenHans Jan 9, 2025
887f8f0
Update content/spin/v3/community-kinesis-trigger.md
ThorstenHans Jan 9, 2025
453e9a3
Update content/spin/v3/triggers.md
ThorstenHans Jan 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 114 additions & 0 deletions content/spin/v3/command-trigger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
title = "The Spin Command Trigger"
template = "spin_main"
date = "2025-01-09T00:00:01Z"
enable_shortcodes = true
[extra]
url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/command-trigger.md"

---

- [Installing the Command Trigger](#installing-the-command-trigger)
- [Installing the Command Trigger Plugin](#installing-the-command-trigger-plugin)
- [Installing the Command Trigger Template](#installing-the-command-trigger-template)
- [Creating the Application](#creating-the-application)
- [Inspecting the Source Code](#inspecting-the-source-code)
- [Building and Running the Application](#building-and-running-the-application)
- [Learn more about the Spin Command Trigger](#learn-more-about-the-spin-command-trigger)
- [Additional Spin Triggers](#additional-spin-triggers)
- [Common Triggers](#common-triggers)
- [Community Triggers](#community-triggers)


Spin has experimental support for creating and running components once. Please note that there are only working Command Trigger app samples written in [Rust](https://github.com/fermyon/spin-trigger-command/tree/main/examples) at present.

> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `command` because non-HTTP triggers are not supported in Fermyon Cloud.

Let's look at how the [experimental Command trigger for Spin](https://github.com/fermyon/spin-trigger-command/) allows you to deploy an application that runs once to completion. The Command trigger specification references a specific component. For example:

<!-- @nocpy -->

```toml
[[trigger.command]]
component = "hello"
```

## Installing the Command Trigger

### Installing the Command Trigger Plugin

First, we install the plugin:

```bash
spin plugins update
spin plugin install trigger-command
```

### Installing the Command Trigger Template

Then, we install the template:

```bash
spin templates install --git https://github.com/fermyon/spin-trigger-command
```

## Creating the Application

With the plugin and template installed, we create a new application:

```bash
spin new -t command-rust hello --accept-defaults
```

### Inspecting the Source Code

The Rust source code for this application is as follows:

```Rust
fn main() {
println!("Hello, Fermyon!");
}
```

### Building and Running the Application

We can immediately run this pre-written (template) application and observe the time-driven execution:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

time-driven? Possible copypasta from cron?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am uncomfortable with "pre-written." "Template" or "starter" or "generated", but it's not really "pre-written".


```bash
cd hello
spin build --up

Building component hello with `cargo build --target wasm32-wasi --release`

...

Finished building all Spin components

Hello, Fermyon!
```

As we can see from the above output, our application is executed once to completion without the need for any incoming requests.

## Learn more about the Spin Command Trigger

<iframe width="560" height="315" src="https://www.youtube.com/embed/l2nh_xpjCiM?si=fBPaiqoIkJPQ95W_" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

If you would like to learn more about using the Spin Command Trigger, please check out the [Spin Command Trigger GitHub repository](https://github.com/fermyon/spin-trigger-command/).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to include a troubleshooting/gotchas section to cover how this doesn't play nice with multi-trigger applications?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the command trigger that is definitely super important and useful. Will add a corresponding paragraph

## Additional Spin Triggers

You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin.

### Common Triggers
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure what distinguishes a "common" trigger from a "community" one.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought separation would make sense. Although mqtt is mostly written by fermyon ppl, its not under the fermyon org.

If we don't care, we could roll with just a single (simple) list of all triggers

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we just need to rephrase "common" to align more with "Fermyon"? It currently sounds like it contrasts with "rare" which is clearly not your intent!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am wary of repeating this list on every trigger page. Could we maybe instead have a "See all Spin triggers" link to a top level page? Or nerd snip Karthik into giving us some kind of 'include from file' feature?


- [HTTP Trigger](./http-trigger.md)
- [Redis Trigger](./redis-trigger.md)
- [Command Trigger](./command-trigger.md)
- [Cron Trigger](./cron-trigger.md)
- [SQS Trigger](./sqs-trigger.md)

### Community Triggers

The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers:

- [Kinesis Trigger](./community-kinesis-trigger.md)
- [MQTT Trigger](./community-mqtt-trigger.md)
131 changes: 131 additions & 0 deletions content/spin/v3/community-kinesis-trigger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
title = "The Spin Kinesis Trigger (Community)"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure this needs to be in the title. It might work better in a boxout at the top of the page where you can explain the significance a la "not maintained by Fermyon" etc.

template = "spin_main"
date = "2025-01-09T00:00:01Z"
enable_shortcodes = true
[extra]
url = "https://github.com/fermyon/developer/blob/main/content/spin/v3/community-kinesis-trigger.md"

---

- [Installing the AWS Kinesis Trigger](#installing-the-aws-kinesis-trigger)
- [Installing the AWS Kinesis Trigger Plugin](#installing-the-aws-kinesis-trigger-plugin)
- [Installing the AWS Kinesis Trigger Template](#installing-the-aws-kinesis-trigger-template)
- [Creating the Application](#creating-the-application)
- [Inspecting the Source Code](#inspecting-the-source-code)
- [Building and Running the Application](#building-and-running-the-application)
- [Additional Spin Triggers](#additional-spin-triggers)
- [Common Triggers](#common-triggers)
- [Community Triggers](#community-triggers)


Spin has experimental support for creating and running components on real time data records streamed through [AWS Kinesis](https://docs.aws.amazon.com/streams/latest/dev/introduction.html). Please note that there are only working Kinesis Trigger app samples written in [Rust](https://github.com/ogghead/spin-trigger-kinesis).

> Please note: You can not `spin deploy` an application to Fermyon Cloud if it uses `kinesis` because non-HTTP triggers are not supported in Fermyon Cloud.

Let's look at how the [experimental Kinesis trigger for Spin](https://github.com/ogghead/spin-trigger-kinesis) allows you to deploy an application that runs based on real time data records streamed through AWS Kinesis. (Provisioning and configuring AWS Kinesis is out of scope for this article). The Kinesis trigger leverages AWS credentials from the standard AWS configuration environment variables and maps a AWS Kinesis stream to a specific component. For example:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we expand on what "runs based on real time data records" means?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could clarify this by saying something like "parses data records streamed through AWS Kinesis with customizable processing delay" -- but I wonder if it gets into the weeds a bit too much.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Going into the details of credential management seems a bit out of sync with this high level. Maybe a "configuring the Kinesis trigger" or "Kinesis trigger authentication and authorization" section further down?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe, I've almost no experience with AWS. Even the trigger repo does not provide further info

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ogghead would you have a moment to look over this and share any thoughts on how to structure the Kinesis trigger docs?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Knowing that an existing Kinesis stream and IAM credentials with permissions to read from it are prerequisites has benefit to readers if they are unfamiliar with AWS/are not ready to set those up. But it does also get into the weeds a bit.

Perhaps this information could live in a "prerequisites" subsection under "Installing the AWS Kinesis Trigger" before the sections on plugin installation/Spin configuration? Flexible on approach overall!

Unrelated, but it is potentially worth linking this AWS doc on credentials on "leverages AWS credentials from the standard AWS configuration environment variables" to help folks familiarize themselves with AWS credentials options.


<!-- @nocpy -->

```toml
[[trigger.kinesis]]
stream_arn = "arn:aws:kinesis:us-east-1:1234567890:stream/TestStream"
batch_size = 1000
shard_idle_wait_millis = 250
detector_poll_millis = 30000
shard_iterator_type = "TRIM_HORIZON"
component = "hello"
```

> Note: See [the list of all available configuration variables](https://github.com/ogghead/spin-trigger-kinesis?tab=readme-ov-file#spintoml) for the AWS Kinesis trigger.

## Installing the AWS Kinesis Trigger

### Installing the AWS Kinesis Trigger Plugin

First, we install the plugin:

```bash
spin plugins update
spin plugins install trigger-kinesis
```

### Installing the AWS Kinesis Trigger Template

Then, we install the template:

```bash
spin templates install --git https://github.com/ogghead/spin-trigger-kinesis
```

## Creating the Application

With the plugin and template installed, we create a new application:

```bash
spin new -t kinesis-rust hello --accept-defaults
```

As part of creating the new application, `spin` CLI will ask for the Amazon Resource Name (ARN). When asked, provide the ARN of your AWS Kinesis instance and confirm it with `[ENTER]`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
As part of creating the new application, `spin` CLI will ask for the Amazon Resource Name (ARN). When asked, provide the ARN of your AWS Kinesis instance and confirm it with `[ENTER]`.
As part of creating the new application, Spin asks for the Amazon Resource Name (ARN). When asked, provide the ARN of your AWS Kinesis instance and confirm it with `[ENTER]`.


### Inspecting the Source Code

The Rust source code for this application is as follows:

```Rust
use spin_kinesis_sdk::{kinesis_component, Error, KinesisRecord};

#[kinesis_component]
async fn handle_batch_records(records: Vec<KinesisRecord>) -> Result<(), Error> {
for record in records {
println!("I GOT A RECORD! ID: {:?}", record.sequence_number);
let data = String::from_utf8(record.data.inner).unwrap();
println!(" ... DATA: {:?}", data);
}

Ok(())
}

```

## Building and Running the Application

We can immediately run this pre-written (template) application and observe the time-driven execution:

```bash
cd hello
spin build --up

Building component hello with `cargo build --target wasm32-wasi --release`

...

Finished building all Spin components
Logging component stdio to ".spin/logs/"
I GOT A RECORD! ID: 101
... DATA: { "value" : "foo" }
I GOT A RECORD! ID: 102
... DATA: { "value" : "bar" }
```

As we can see from the above output, our application is now running and executing the function for each data record sent through your individual AWS Kinesis instance.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For each batch rather than for each record? The iteration is internal to "the function."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good callout @itowlson, agreed it might be worth rewording to clarify that function execution is per batch of records


If you would like to learn more about using the Spin Kinesis Trigger, please check out the ["How I wrote A Kinesis Trigger PLugin For Spin"](https://www.fermyon.com/blog/how-i-wrote-a-kinesis-trigger-plugin-for-spin) blog post and consult the [Spin Kinesis Trigger GitHub repository](https://github.com/ogghead/spin-trigger-kinesis/).

## Additional Spin Triggers

You can leverage different triggers as part of your Spin apps to address common requirements and build real-world, distributed applications with Spin.

### Common Triggers

- [HTTP Trigger](./http-trigger.md)
- [Redis Trigger](./redis-trigger.md)
- [Command Trigger](./command-trigger.md)
- [Cron Trigger](./cron-trigger.md)
- [SQS Trigger](./sqs-trigger.md)

### Community Triggers

The incredible Spin and [SpinKube](https://spinkube.dev) community, also provides the following, additional Spin triggers:

- [Kinesis Trigger](./community-kinesis-trigger.md)
- [MQTT Trigger](./community-mqtt-trigger.md)
Loading
Loading