diff --git a/docs/deploy/cloud.md b/docs/deploy/cloud.md new file mode 100644 index 00000000..c8640664 --- /dev/null +++ b/docs/deploy/cloud.md @@ -0,0 +1,170 @@ +--- +sidebar_position: 4 +description: "Learn how to use Restate Cloud." +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; + +# Restate Cloud + + + Restate Cloud is an early-access preview. Features may change, and we offer + no reliability SLAs at this time. Production usage is not recommended. + + +This page describes how to use Restate environments deployed on our early-access +[cloud platform](https://cloud.restate.dev). + +## Creating your first environment + +You can sign in to Cloud using Google or GitHub SSO. After signing up, you'll +be prompted to create an account, and an environment. An environment is a Restate instance that is unique to you, and managed by Restate. + + +Accounts and environments must have a name comprising of lowercase alphanumeric +characters or hyphens. For example, you can choose `dev` for your account and +`my-environment` for your environment. + + +You can start using your new environment straight away using the [CLI](/operate/cli): + +```bash +# authenticate to Cloud +restate cloud login +# set up your CLI to talk to your Cloud environment +restate cloud env configure +# check that everything is working! +restate whoami +``` + + +At any time, you can switch your CLI back to point to a Restate server running +on your machine with `restate config use-environment local`. See the +[CLI docs](/operate/cli#using-the-config-file) for more. + + +## Registering Restate services with your environment + +You can use your Cloud environment exactly as a self-hosted one; register +services with `restate deployments register `. + +However, currently your services must be accessible over the public internet for +Restate to be able to invoke them. If you want to develop using a +service running on your local machine, you can expose it to Restate Cloud using +[`ngrok`](https://ngrok.com/download): + +```bash +# expose localhost:9080 over the internet +ngrok http 9080 --app-protocol=http2 +# copy the ngrok url from the output +restate dp add https://c734-2a01-4b00-8588-9800-594-9137-39b2-ff13.ngrok-free.app +``` + +### AWS Lambda services + +To invoke services running on AWS Lambda, Restate Cloud needs to assume an AWS +identity in the same account that the Lambda is deployed to. Create a new role +that has permission to invoke your Lambdas and give it the following trust policy: + +```json +{ + "Sid": "AllowRestateCloudToAssumeRole", + "Effect": "Allow", + "Principal": { + "AWS": "AROAZQ3DNV5IY6KP4ODO4" + }, + "Action": ["sts:AssumeRole", "sts:TagSession"], + "Condition": { + "StringEquals": { + "sts:ExternalId": "$ENVIRONMENT_ID" + } + } +} +``` + + +This trust policy allows the Restate cloud `us.restate.cloud` region role ID (`AROAZQ3DNV5IY6KP4ODO4`) to assume your role, as long as it is using an ExternalId that matches your environment ID. The environment ID can be found in the UI and in the output of `restate whoami`. + + +You can now register your Lambda through the new role: + +```shell +restate dp add --assume-role-arn +``` + +If something isn't working, the environment logs in the cloud UI may help +you find the issue. + +## Invoking your services + +In the UI you can find the URL of your Restate environment. All requests must be +authenticated using a Bearer token. We suggest that humans use their SSO token +which is obtained by `restate cloud login`, and will be used automatically by +the CLI. If you want to test invocations using `curl` as described in the [invoke docs](/invoke/http), you can use a local authenticated proxy to expose +the Restate server as if it was running on your machine: + +```bash +restate cloud env proxy +curl localhost:8080/MyService/myHandler +``` + +### API tokens + +For programmatic invocation, awakeable completion, or admin API usage from +scripts, CI pipelines, API gateways, or services that exist outside Restate, +you can create an API key in the UI, selecting an appropriate role for your use +case. + +```bash +curl -H "Authorization: Bearer $MY_API_KEY" https://201hy10cd3h6426jy80tb32n6en.env.us.restate.cloud:8080/MyService/MyHandler +curl -H "Authorization: Bearer $MY_API_KEY" https://201hy10cd3h6426jy80tb32n6en.env.us.restate.cloud:9070/deployments +``` + +To use the CLI programmatically with this token: + +```bash +export RESTATE_HOST_SCHEME=https RESTATE_HOST=201hy10cd3h6426jy80tb32n6en.env.us.restate.cloud RESTATE_AUTH_TOKEN=$MY_API_KEY +restate whoami +``` + +## Securing your services + +### HTTP + +Restate invokes your services over the public internet. For production use cases +HTTPS must be used between Restate and your services. You can apply a +certificate to the service directly, but its likely easier to use a fronting +load balancer like an AWS NLB. + +It is also a good idea to secure access to your service so that only Restate can +call it. The easiest way to do this is with our native request identity feature. +environment. All requests to your service will contain a signature from a public key which can be seen in the UI. It's safe to include it directly in +your service code: + + + +```typescript TypeScript +restate + .endpoint() + .bind(myService) + .withIdentityV1("publickeyv1_8SyC5reu2eTUwGCH4CehFntZAnADvYU6PXZtFyKiTrWy") + .listen(); +``` + +```java Java +RestateHttpEndpointBuilder.builder() + .bind(new MyService()) + .withRequestIdentityVerifier(RequestIdentityVerifier.fromKey("publickeyv1_8SyC5reu2eTUwGCH4CehFntZAnADvYU6PXZtFyKiTrWy")) + .buildAndListen(); +``` + + + +### Lambda + +If your Lambda has an appropriate trust policy as described above, you do not +need to secure incoming requests any further. If you choose to however, the +`withIdentityV1` (TS) and `withRequestIdentityVerifier` (Java) functions will +work on Lambda endpoints as well. diff --git a/docs/deploy/overview.md b/docs/deploy/overview.md index 7840569c..b8d10b2d 100644 --- a/docs/deploy/overview.md +++ b/docs/deploy/overview.md @@ -20,7 +20,8 @@ The Restate Server is a single binary that contains everything you need to host There are a few options for hosting the Restate Server: - [Self-host on AWS](/deploy/lambda/self-hosted) -- [Self-host on Kubernetes](/deploy/kubernetes). +- [Self-host on Kubernetes](/deploy/kubernetes) +- [Use the early access of Restate Cloud](/deploy/cloud) The server will store metadata and RocksDB data under `./restate-data/`. `` is the name of the Restate server, which is set by the `--node-name` flag (defaults to hostname). diff --git a/docs/operate/cli.mdx b/docs/operate/cli.mdx index aff9b507..ee412c06 100644 --- a/docs/operate/cli.mdx +++ b/docs/operate/cli.mdx @@ -12,6 +12,7 @@ You can use the CLI to interact with Restate, and manage your services, deployme ## Installation ### Option 1: Using a package manager + Install the Restate CLI via: @@ -27,6 +28,7 @@ brew install restatedev/tap/restate ### Option 2: Download the binary + Use `curl` to download the binaries from the [releases page](https://github.com/restatedev/restate/releases/latest), and make them executable: @@ -78,10 +80,9 @@ restate --help Have a look at the [introspection page](/operate/introspection) for a list of useful commands . - ## Configuration -There are two ways to configure the CLI: via environment variables or via a configuration file. +There are 2 ways to configure the CLI: via environment variables or via a configuration file. ### Using environment variables @@ -102,8 +103,6 @@ RESTATE_HOST=myhost RESTATE_HOST_SCHEME=https restate You can find the full list of configuration variables in the [CLI GitHub repo](https://github.com/restatedev/restate/blob/main/cli/src/cli_env.rs). -### Using a configuration file - You can also specify the configuration in a `.env` file. The CLI will look for a `.env` file in its current directory. For example, to connect to a Restate admin server running at `http://myhost:9070`, save the following in a `.env` file: @@ -112,3 +111,40 @@ For example, to connect to a Restate admin server running at `http://myhost:9070 RESTATE_ADMIN_URL=http://myhost:9070 ``` +### Using the config file + +By default, the CLI will treat `$HOME/.config/restate` as its config directory. +This is configurable with `$RESTATE_CLI_CONFIG_HOME`. Restate will look for file +named `config.toml` inside this directory. You can edit this file with +`restate config edit`, or view its contents with `restate config view`. + +The config file has a native concept of 'enviroments' which are sets of +configuration intended to specify different instances of Restate. You can +list your configured environments: + +```bash +> restate config list-environments +CURRENT NAME ADMIN_BASE_URL +* local http://localhost:9070/ +``` + +By default, the CLI uses the `local` environment which is configured to point +at a Restate instance running on your local machine. Additional environments +can be specified as new blocks in `config.toml`: + +```toml config.toml +[myhost] +ingress_base_url = "http://myhost:8080" +admin_base_url = "http://myhost:9070" +bearer_token = "..." +``` + +The title of the block is the name of the environment. You can switch +between environments in various ways: + +1. With an argument: `restate -e myhost whoami` +2. With an environment variable: `RESTATE_ENVIRONMENT=myhost restate whoami` +3. With the command `restate config use-environment myhost`. This will write + the name of the environment to the CLI config directory, so that its used by + default for all CLI commands. You can switch back to `local` with + `restate config use-environment local`.