Skip to content

updating requirements on default label #1545

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.

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

Merged
merged 3 commits into from
May 14, 2025
Merged

Conversation

macolso
Copy link
Contributor

@macolso macolso commented May 12, 2025

Content must go through a pre-merge checklist.

Pre-Merge Content Checklist

This documentation has been checked to ensure that:

  • The title, template, and date are all set
  • Does this PR have a new menu item (anywhere in templates/*.hbs files) that points to a document .md that is set to publish in the future? If so please only publish the .md and .hbs changes in real-time (otherwise there will be a menu item pointing to a .md file that does not exist)
  • File does not use CRLF, but uses plain LF (hint: use cat -ve <filename> | grep $'\r' | wc -l and expect 0 as a result)
  • Has passed bart check
  • Has been manually tested by running in Spin/Bartholomew (hint: use PREVIEW_MODE=1 and run npm run styles to update styling)
  • Headings are using Title Case
  • Code blocks have the programming language set to properly highlight syntax and the proper copy directive
  • Have tested with npm run test and resolved all errors
  • Relates to an existing (potentially outdated) blog article? If so please add URL in blog to point to this content.

@macolso macolso requested review from lann and kate-goldenring May 12, 2025 18:26
@macolso macolso added documentation Improvements or additions to documentation chore Tidying up doNotMergeYet labels May 12, 2025
@@ -45,7 +46,7 @@ $ npm install

## Grant Key Value Store Permission

To enable a component in Spin to use a key value store, you need to [grant it the necessary permissions in the application's manifest](https://spinframework.dev/kv-store-api-guide#granting-key-value-store-permissions-to-components) (`spin.toml`) by adding a key-value store label. This both grants the component access to the key value store and signals _Fermyon Wasm Functions_ (FWF) to provision one for the application. In this tutorial, we’ll use the label "default", but you can choose any label that works best for you.
To enable a component in Spin to use a Key value Store, you need to [grant it the necessary permissions in the application's manifest](https://spinframework.dev/kv-store-api-guide#granting-key-value-store-permissions-to-components) (`spin.toml`) by adding a label. A label is a developer-defined string that links your component to an external resource. In this case, the resource is a Key Value Store. When deploying to _Fermyon Wasm Functions_, the label must be set to "default" to signal the platform to automatically provision a Key Value Store for your Spin application. While other labels besides "default" can be used for linking to existing resources in a local developer workflow, "default" is required for automatic key value provisioning on _Fermyon Wasm Functions_.
Copy link
Contributor

Choose a reason for hiding this comment

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

Key value Store

I preferred the original "key value store", but if we are going to capitalise it then it should be Key Value Store or Key-Value Store - the lower case "value" looks out of place.

Copy link
Contributor

Choose a reason for hiding this comment

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

I feel like this buries the key point ("you can only use default") in the middle of a rather long and complicated paragraph. Would you be open to something like e.g.

Suggested change
To enable a component in Spin to use a Key value Store, you need to [grant it the necessary permissions in the application's manifest](https://spinframework.dev/kv-store-api-guide#granting-key-value-store-permissions-to-components) (`spin.toml`) by adding a label. A label is a developer-defined string that links your component to an external resource. In this case, the resource is a Key Value Store. When deploying to _Fermyon Wasm Functions_, the label must be set to "default" to signal the platform to automatically provision a Key Value Store for your Spin application. While other labels besides "default" can be used for linking to existing resources in a local developer workflow, "default" is required for automatic key value provisioning on _Fermyon Wasm Functions_.
To enable a component in Spin to use a key-value store, you need to [grant it the necessary permissions in the application's manifest](https://spinframework.dev/kv-store-api-guide#granting-key-value-store-permissions-to-components) (`spin.toml`). To do this, add the label of the store to the component's `key_value_stores` in `spin.toml`.
In Fermyon Wasm Functions, the only label allowed is `"default"`.
> In a local developer workflow, applications can use other labels besides "default", but these have to be manually mapped to physical stores, and so you won't be able to deploy such applications to Fermyon Wasm Functions.

I might even strike that last note because it breaks up the "you gotta add the label" explanation from the "here is what that looks like" example.

Copy link
Contributor

Choose a reason for hiding this comment

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

I like @itowlson's suggestion but I'd maybe preserve a little more detail, e.g.:

In Fermyon Wasm Functions, the only label allowed is "default", a Key Value Store automatically provisioned for your application.

Copy link
Contributor

Choose a reason for hiding this comment

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

+1 to Ivan's suggestion and Lann's addition of saying that a kv store is provisioned for you

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes, I like pairing down the language to just the context the user needs to take action.

Looks like capitalization of the term "key value store" was inconsistent across the article, @itowlson . I went through and standardized on "key value store."

Copy link
Contributor

@itowlson itowlson left a comment

Choose a reason for hiding this comment

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

LGTM (the one styling nit is non-blocking) - thanks!

Co-authored-by: itowlson <[email protected]>
Signed-off-by: MacKenzie Olson <[email protected]>
@macolso
Copy link
Contributor Author

macolso commented May 13, 2025

@lann is there a PR or GH issue I can keep an eye on that tracks the KV changes so I can merge the documentation accordingly?

Copy link
Contributor

@kate-goldenring kate-goldenring left a comment

Choose a reason for hiding this comment

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

@macolso the change to only allow default stores is in production so you should be good to merge. I am updating the plugin now to warn against non-default stores

@macolso macolso merged commit 6d55797 into fermyon:main May 14, 2025
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
chore Tidying up documentation Improvements or additions to documentation doNotMergeYet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants