diff --git a/docs/content/sips/001-spin-deploy.md b/docs/content/sips/001-spin-deploy.md new file mode 100644 index 0000000000..116694c475 --- /dev/null +++ b/docs/content/sips/001-spin-deploy.md @@ -0,0 +1,81 @@ +title = "SIP 001 - Spin Deploy" +template = "main" +date = "" + +Summary: A Spin CLI command that will deploy a Spin application to the cloud + +Owner: michelle@fermyon.com + +Created: March 18, 2022 + +Updated: March 31, 2022 + +## Background + +A Spin application — (currently described as a spin.toml file) — is a collection of one or more components, each invoked as a result of an event generated by a trigger. The Spin CLI currently enables running a Spin application locally via the `spin up` command. The Spin CLI also offers a set of commands enabling users to package and push a Spin application to a [Bindle](https://github.com/deislabs/bindle) registry. + +[Hippo](https://github.com/deislabs/hippo) is a self-hosted, open source, Web Assembly PaaS that allows users to deploy and scale Web Assembly applications. Hippo takes a reference to a bindle, deploys it to the cloud and makes it publicly available. Hippo currently only works with Wagi applications and can currently deploy Wagi applications on a Nomad cluster with Traefik for routing. Additionally, Hippo has a concept called “channels” enabling users to track different version categories of an application (ex. alpha, beta, stable, pre-releases, minor versions, etc.). + +A desired feature is to be able to deploy a Spin application to the cloud using Hippo so that it is accessible via a publicly available domain or IP address. + +## Proposal + +Create a `spin deploy` command. This command packages a Spin application as a bindle, pushes it to a bindle registry and instructs Hippo to deploy the application to the cloud. + +### Configuration + +This command needs the following configuration to be passed via either flags or environment variables or config file (config file to be defined at a later date) to deploy the application properly and to the right place: + +- Bindle server information + - Environment variable: BINDLE_SERVER_URL + - Flag: --bindle-server +- Hippo URL information + - Environment variable: HIPPO_URL + - Flag: --hippo-url + +#### Authentication with Hippo + +Hippo authentication information. A token is needed to communicate with the Hippo server. This can be +retrieved either from requesting it from the Hippo server with a username and password, from the Hippo config file on the system (if a user has already logged in) or from the user if they already know the +token information. The following flags and environment variables support authenticating with Hippo. + +- Hippo token + - Environment variable: HIPPO_TOKEN + - Flag: --hippo-token +- Hippo username + - Environment variable: HIPPO_USERNAME + - Flag: --hippo-username +- Hippo password + - Environment variable: HIPPO_PASSWORD + - Flag: --hippo-password + +The `--hippo-token` flag cannot be set in combination with the `--hippo-username` and `--hippo-password` flags. If so, Spin will return an error. If the username/password flags are set, Spin will request a token from the Hippo server and use it. If the username flag was provided but the password was not, Spin will prompt the user for a password. If none of the Hippo auth flags are provided, Spin will find the Hippo token in the Hippo config file on disk. If Hippo cannot find the file or the token in the file is expired, Spin will prompt the user for username/password. + +### Flow + +As part of the deploy flow, Spin will: + +1. Create and push a bindle for the Spin app +2. Create a Hippo app with the name given in the Spin.toml file. If app exists, it will use the existing app's ID for the next step. _Note: Should we even be re-using an app? or should we create a unique app per deploy? I'm leaning towards the latter?_ +3. Create a Hippo channel called "spin-deploy" (might be something we should allow for configuration via a flag). If the channel already exists, ensure that revision information is configured to pick up the new bindle version. +4. Register a revision with Hippo so that the relevant channel(s) deploy the application. + +#### Pre-requsites + +In order to use the `spin deploy` command, a user must already have Hippo installed and running using the nomad scheduler and a bindle url. + +#### Bindle versioning + +A bindle is immutable once pushed and the tag cannot be overwritten. Therefore, we'll need a way to construct unique tags. One way to do this is to hash the bindle invoice that is generated. +_Note: I believe Hippo only allows semver versions though and in that case, this would not work or we'd need to see if we can make Hippo pick up non-semver bindle tags._ + +### Assumptions about the Hippo Platform + +The following is a list of assumptions we are making about the Hippo platform that we would need to build in order for this command to work. + +- There needs to be a single endpoint on the Hippo API Server that takes the Spin application information and creates a Hippo application with a default channel configured to watch the correct bindle reference. See [hippo-cli issue #97](https://github.com/deislabs/hippo-cli/issues/97). +- Hippo needs to support running Spin applications and not only Wagi applications. See [hippo issue #579](https://github.com/deislabs/hippo/issues/579). + +### Additional Consideration: Plugin Model + +In the future, we should make this command a plugin for the Spin CLI. People may not want to use the Spin deploy command to deploy to Hippo. They may want to deploy to a different target using a different platform. They should be able to do that via plugins. However, there is no plugin system in Spin at this time and that may require further debate and discussion and consideration, so it's best to continue with `spin deploy` as a built-in subcommand for the time being to be focused about the scope of work. diff --git a/docs/content/sips/index.md b/docs/content/sips/index.md index 5d824935e1..0895a3036a 100644 --- a/docs/content/sips/index.md +++ b/docs/content/sips/index.md @@ -6,4 +6,5 @@ date = "2022-03-22T14:53:30Z" # Spin Improvement Proposals -[Application Configuration](002-app-config.md) \ No newline at end of file +[Spin Deploy](001-spin-deploy.md) +[Application Configuration](002-app-config.md)