From d730ee571de16465e768d0f2b19669911764edac Mon Sep 17 00:00:00 2001 From: Jack Kleeman Date: Sun, 2 Jun 2024 14:46:12 +0200 Subject: [PATCH] Cloud documentation (#383) * Cloud documentation * Update docs/deploy/cloud.md Co-authored-by: Pavel Tcholakov * Update docs/deploy/cloud.md Co-authored-by: Pavel Tcholakov * Update docs/deploy/cloud.md Co-authored-by: Pavel Tcholakov * Update docs/operate/cli.mdx Co-authored-by: Pavel Tcholakov * Update docs/deploy/cloud.md Co-authored-by: Pavel Tcholakov * Unify proxy and tunnel * Use role name --------- Co-authored-by: Pavel Tcholakov --- docs/deploy/cloud.md | 169 ++++++++++++++++++++++++++++++++++++++++ docs/deploy/overview.md | 3 +- docs/operate/cli.mdx | 44 ++++++++++- 3 files changed, 211 insertions(+), 5 deletions(-) create mode 100644 docs/deploy/cloud.md diff --git a/docs/deploy/cloud.md b/docs/deploy/cloud.md new file mode 100644 index 00000000..0ebce785 --- /dev/null +++ b/docs/deploy/cloud.md @@ -0,0 +1,169 @@ +--- +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. + + +[Restate Cloud](https://cloud.restate.dev) is the early-access managed service of Restate, where we run an instance of the Restate server for you. This allows you to focus on your services, which you can deploy whereever you normally do - long-lived compute, or serverless platforms like Lambda. + +## Creating your first environment + +You can sign in to Cloud using an email address and password, or using Google or GitHub SSO. +After signing up, you'll be prompted to create an account, and an environment. An environment is an instance of the Restate server 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 using our tunnel +feature: +```bash +# expose localhost:9080 to Restate Cloud +restate cloud env tunnel --local-port 9080 +# copy the tunnel url from the output and register it to your environment +restate deployments register tunnel://example:9081 +``` + +### 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": "arn:aws:iam::654654156625:role/RestateCloud" + }, + "Action": ["sts:AssumeRole", "sts:TagSession"], + "Condition": { + "StringEquals": { + "sts:ExternalId": "$ENVIRONMENT_ID" + } + } +} +``` + + +This trust policy allows the Restate Cloud `us.restate.cloud` region principal 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 the tunnel command to expose +the ingress port of the Restate server as if it was running on your machine: + +```bash +restate cloud env tunnel --remote-port 8080 +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 terminate TLS at +the service endpoint directly, but it's likely easier to use a fronting +load balancer like an AWS NLB. + +You must 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. +All requests to your service will be signed with a unique environment-specific private +key. You can find the corresponding public key in the environment settings UI, under HTTP Services. +It is safe to include this public key 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..70c13ef9 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 it's used by + default for all CLI commands. You can switch back to `local` with + `restate config use-environment local`.