diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 6a8f4ff7..c39b1236 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -112,7 +112,7 @@ and providing it with the deployment endpoint of the service `http://localhost:8 ```shell curl -X POST http://localhost:9070/deployments -H 'content-type: application/json' -d '{"uri": "http://localhost:9080"}' ``` -Restate then sends a request to the deployment to ask which services and methods +Restate then sends a request to the service deployment to ask which services and methods are running behind this deployment and will keep track of these (including of the method signatures). After executing this curl request, you should see the discovered services and methods printed to your terminal. @@ -134,7 +134,7 @@ and providing it with the deployment endpoint of the service `http://host.docker ```shell curl -X POST http://localhost:9070/deployments -H 'content-type: application/json' -d '{"uri": "http://host.docker.internal:9080"}' ``` -Restate then sends a request to the deployment to ask which services and methods +Restate then sends a request to the service deployment to ask which services and methods are running behind this deployment and will keep track of these (including of the method signatures). After executing this curl request, you should see the discovered services and methods printed to your terminal. diff --git a/docs/references/restate-sql-introspection.mdx b/docs/references/restate-sql-introspection.mdx index 949a4718..2f3de3df 100644 --- a/docs/references/restate-sql-introspection.mdx +++ b/docs/references/restate-sql-introspection.mdx @@ -32,7 +32,7 @@ The schema of these tables is described in the following. | `invoked_by` | `Utf8` | Enum describing the invoker of this service: `ingress` = invoked externally / `service` = invoked by a service. | | | `invoked_by_service` | `Utf8` | The name of the invoking service. Or `null` if invoked via the ingress. | `com.example.Greeter` | | `invoked_by_id` | `Utf8` | The Invocation ID of the service that triggered this invocation. Or `null` if invoked externally. | | -| `pinned_deployment_id` | `Utf8` | The opaque deployment ID that has been committed for this invocation; this is set after the first journal entry is stored for this invocation. | | +| `pinned_deployment_id` | `Utf8` | The opaque service deployment ID that has been committed for this invocation; this is set after the first journal entry is stored for this invocation. | | | `trace_id` | `Utf8` | The ID of the trace that is assigned to this invocation. Only relevant when tracing is enabled. | | | `journal_size` | `UInt32` | The number of journal entries durably logged for this invocation. | | | `created_at` | `Date64` | Timestamp indicating the start of this invocation. | | @@ -49,7 +49,7 @@ The schema of these tables is described in the following. | `in_flight` | `Boolean` | Indicates whether there is currently an attempt running for this invocation. | | | `retry_count` | `UInt64` | The number of attempts since the last successful attempt of this invocation. Increments on start, so 2 or more means a failure occurred. | | | `last_start_at` | `Date64` | Timestamp indicating the start of the most recent attempt of this invocation. | | -| `last_attempt_deployment_id` | `Utf8` | The opaque deployment ID that was used in the most recent attempt of this invocation; this will be set before a journal entry is stored, but can change later. | | +| `last_attempt_deployment_id` | `Utf8` | The opaque service deployment ID that was used in the most recent attempt of this invocation; this will be set before a journal entry is stored, but can change later. | | | `next_retry_at` | `Date64` | Timestamp indicating the start of the next attempt of this invocation. | | | `last_failure` | `Utf8` | An error message describing the most recent failed attempt of this invocation, if any. | | | `last_error_code` | `Utf8` | The [error code](./errors) of the most recent failed attempt of this invocation, if any. | | diff --git a/docs/restate/deployment.md b/docs/restate/deployment.md index 44cf057f..6e683b3b 100644 --- a/docs/restate/deployment.md +++ b/docs/restate/deployment.md @@ -11,7 +11,7 @@ It exposes three services by default, each on different ports: | Name | Port | Description | Protocol | |----------|------|--------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| | Ingress | 8080 | Acts as an API gateway for all services registered with Restate | gRPC + [Connect Protocol](https://connect.build/) | -| Admin | 9070 | Allows for CRUD operations on service/deployment metadata, eg for service registration | REST | +| Admin | 9070 | Allows for CRUD operations on service/service deployment metadata, eg for service registration | REST | | Postgres | 9071 | Exposes Restate RocksDB read-only storage operations using the Postgres protocol. See [Introspection](/services/introspection) | Postgres | It will store metadata and RocksDB data in the relative directory of /target under the current working directory of the process. diff --git a/docs/restate/logging.md b/docs/restate/logging.md index 89d533b0..337895b6 100644 --- a/docs/restate/logging.md +++ b/docs/restate/logging.md @@ -27,7 +27,7 @@ The following components are producing relevant logs: * `restate_ingress_grpc`: The component ingesting gRPC/Connect HTTP requests inside Restate * `restate_meta`: The component responsible for holding the metadata informations and executing service discovery -* `restate_invoker`: The component interacting with deployed deployments +* `restate_invoker`: The component interacting with deployed service deployments * `restate_worker::partition::state_machine`: The state machine effects * `restate_storage`: Restate storage layer * `hyper`: The HTTP library diff --git a/docs/restate/managed_service.md b/docs/restate/managed_service.md index 19e1d1a9..cfdf1abe 100644 --- a/docs/restate/managed_service.md +++ b/docs/restate/managed_service.md @@ -134,6 +134,7 @@ Resource Policies, or you can create a role per account - Restate can assume a d Once you have a role that has permission to call the Lambda, and allows Restate to assume it, you just need to discover the Lambda: + ```shell curl -X POST http://:9070/deployments -H 'content-type: application/json' -d '{"arn": "", "assume_role_arn": "" }' ``` diff --git a/docs/restate/tracing.mdx b/docs/restate/tracing.mdx index 25bfafd1..fb2ee0a6 100644 --- a/docs/restate/tracing.mdx +++ b/docs/restate/tracing.mdx @@ -86,7 +86,7 @@ The traces contain detailed information about the context calls that were done d ![Understanding traces](/img/jaeger_tour_background_call_handler.png) -The initial `ingress_invoke` spans show when the gRPC/Connect HTTP request was received by Restate. The `invoke` span beneath it shows when Restate invoked the deployment to process the request. +The initial `ingress_invoke` spans show when the gRPC/Connect HTTP request was received by Restate. The `invoke` span beneath it shows when Restate invoked the service deployment to process the request. The tags of the spans contain the metadata of the context calls (e.g. call arguments, invocation id). diff --git a/docs/services/deployment/general.md b/docs/services/deployment/general.md index 38ff46dd..92bc05e1 100644 --- a/docs/services/deployment/general.md +++ b/docs/services/deployment/general.md @@ -5,13 +5,13 @@ description: "Learn how to deploy Restate services." # General -Restate services are deployed within *Deployments*. The Restate runtime interacts with deployments by sending requests to them using a custom protocol on top of HTTP. +Restate services are deployed within *Service deployments*. The Restate runtime interacts with service deployments by sending requests to them using a custom protocol on top of HTTP. -A deployment can be a Lambda function, a Kubernetes pod, a Knative Service, or any other process reachable at a specific URL. +A service deployment can be a Lambda function, a Kubernetes pod, a Knative Service, or any other process reachable at a specific URL. The URL (including path prefix) MUST be **unique**, meaning that no two deployments with the same URL can exist at the same time in a Restate instance. -Moreover, deployments are **immutable**, and are assumed to be reachable throughout the entire lifecycle of an invocation. To deploy any change to a service, either in the Protobuf definition or in the business logic, you should deploy a new deployment with a new URL. See the [versioning documentation](/services/upgrades-removal) for more details on how to update services. +Moreover, service deployments are **immutable**, and are assumed to be reachable throughout the entire lifecycle of an invocation. To deploy any change to a service, either in the Protobuf definition or in the business logic, you should deploy a new deployment with a new URL. See the [versioning documentation](/services/upgrades-removal) for more details on how to update services. :::info Running services locally diff --git a/docs/services/deployment/kubernetes.md b/docs/services/deployment/kubernetes.md index d03160ba..a8cc23a0 100644 --- a/docs/services/deployment/kubernetes.md +++ b/docs/services/deployment/kubernetes.md @@ -5,8 +5,8 @@ description: "Learn how to run Restate applications on Kubernetes." # Kubernetes -Deployments can be deployed like any gRPC service; a Deployment of more than one replica is generally appropriate. However, -like gRPC services, they must be appropriately load balanced at L7 if you want multiple deployment pods. Native Kubernetes +Service deployments can be deployed like any gRPC service; a Deployment of more than one replica is generally appropriate. However, +like gRPC services, they must be appropriately load balanced at L7 if you want multiple service deployment pods. Native Kubernetes ClusterIP load balancing will lead to the Restate binary sending all requests to a single pod, as HTTP2 connections are aggressively reused. This is fine for local testing, but in production an approach must be found. If your infrastructure already has an approach for L7 load balancing gRPC services, you can use the same approach here. @@ -66,7 +66,7 @@ L7 load balancing is not needed when there is only one pod, so it's acceptable t ## Knative -Restate supports Knative services. Knative allows scaling to zero when there are no in-flight invocations and automatically configures an L7 load balancer. There are no special requirements to deploy a deployment container with Knative: +Restate supports Knative services. Knative allows scaling to zero when there are no in-flight invocations and automatically configures an L7 load balancer. There are no special requirements to deploy a service deployment container with Knative: ```shell $ kn service create service-name --port h2c:9080 --image path.to/yourrepo:yourtag diff --git a/docs/services/introspection.md b/docs/services/introspection.md index 1b6e46e9..c5de4d7a 100644 --- a/docs/services/introspection.md +++ b/docs/services/introspection.md @@ -90,7 +90,7 @@ This following list contains some key queries on the `sys_status` table to give ## Inspecting the attempt status of an invocation -Invocations can be attempted against a deployment many times if the endpoint is failing. The metadata around +Invocations can be attempted against a service deployment many times if the endpoint is failing. The metadata around these attempts is not committed durably to storage, but is held in memory in the `invoker` component. The metadata includes reasons that an attempt might be failing, for example a permission error calling a Lambda endpoint. diff --git a/docs/services/invocation.md b/docs/services/invocation.md index 90454028..b07f696e 100644 --- a/docs/services/invocation.md +++ b/docs/services/invocation.md @@ -102,7 +102,7 @@ This feature can be especially useful when you need to invoke a service method i ## Private services -When registering a deployment, every service is by default accessible both by other services, and by sending requests to Restate using HTTP and/or gRPC. You can configure a service as `private`, such that you can't invoke it by sending requests to Restate, through the [Admin APIs](/references/admin-api): +When registering a service deployment, every service is by default accessible both by other services, and by sending requests to Restate using HTTP and/or gRPC. You can configure a service as `private`, such that you can't invoke it by sending requests to Restate, through the [Admin APIs](/references/admin-api): ```shell $ curl -X PATCH /services/ -H 'content-type: application/json' -d '{"public": false}' diff --git a/docs/services/registration.md b/docs/services/registration.md index 521b836e..cb3715b2 100644 --- a/docs/services/registration.md +++ b/docs/services/registration.md @@ -11,7 +11,7 @@ After deploying a service deployment, in order to use it, it must be registered $ curl /deployments --json '{"uri": ""}' ``` -When registering a deployment, Restate uses a mechanism similar to "reflections" to discover the available services and their schemas and properties. A service can be registered only once, and subsequent registration requests to the same deployment will fail. For more details on how to update services, check the [versioning documentation](/services/upgrades-removal). +When registering a service deployment, Restate uses a mechanism similar to "reflections" to discover the available services and their schemas and properties. A service can be registered only once, and subsequent registration requests to the same deployment will fail. For more details on how to update services, check the [versioning documentation](/services/upgrades-removal). The deployment creation can be forced to overwrite an existing deployment using curl (>v7.82.0): @@ -19,7 +19,7 @@ The deployment creation can be forced to overwrite an existing deployment using $ curl /deployments --json '{"uri": "", "force": true}' ``` -This will forcefully overwrite the existing deployment with the same uri, forcing the discovery process again. It will also remove services that were served by that deployment and are not available anymore. +This will forcefully overwrite the existing service deployment with the same uri, forcing the discovery process again. It will also remove services that were served by that deployment and are not available anymore. :::warning Forcing a deployment registration is a feature designed to simplify local Restate service development, and should never be used in a production Restate deployment, as it potentially breaks all the in-flight invocations to that deployment. diff --git a/docs/services/sdk/durable-timers.mdx b/docs/services/sdk/durable-timers.mdx index ef8c2d2b..784a75a2 100644 --- a/docs/services/sdk/durable-timers.mdx +++ b/docs/services/sdk/durable-timers.mdx @@ -37,7 +37,7 @@ ctx.sleep(Duration.ofSeconds(10)); :::note -For sleep to work properly, make sure that the system clock of the runtime is synchronized with the clock of the deployment and that they use the same time zone. When you do a timer-based action with the SDK (e.g. sleep, delayed calls), the duration gets calculated based on the system clock of the service. But subsequently, Restate registers this timer on its own system clock. So the system clock of the service and of Restate need to be synchronized. +For sleep to work properly, make sure that the system clock of the runtime is synchronized with the clock of the service deployment and that they use the same time zone. When you do a timer-based action with the SDK (e.g. sleep, delayed calls), the duration gets calculated based on the system clock of the service. But subsequently, Restate registers this timer on its own system clock. So the system clock of the service and of Restate need to be synchronized. ::: :::caution diff --git a/docs/services/service_type.mdx b/docs/services/service_type.mdx index 451c834d..5ade2f8e 100644 --- a/docs/services/service_type.mdx +++ b/docs/services/service_type.mdx @@ -174,4 +174,4 @@ Once you have the contract, the SDK uses it to generate the code to encode/decod The contract can also be used to generate gRPC/Connect clients to invoke Restate services from your webapp, mobile app, legacy system or in general from any system outside Restate services. Have a look at the [invocation docs](/services/invocation). You can check out the [gRPC](https://grpc.io/docs/languages/) and [Connect](https://connect.build/docs/introduction) documentation for more info on the available clients. -When [registering a deployment](/services/registration), Restate automatically _discovers_ all the available service contracts and stores them in an internal registry, no manual input is needed. +When [registering a service deployment](/services/registration), Restate automatically _discovers_ all the available service contracts and stores them in an internal registry, no manual input is needed. diff --git a/docs/services/upgrades-removal.md b/docs/services/upgrades-removal.md index 06fcacb2..6dbabd42 100644 --- a/docs/services/upgrades-removal.md +++ b/docs/services/upgrades-removal.md @@ -9,7 +9,7 @@ Restate comes with different solutions to update the services, to simplify devel ## Deploy a new service revision -As described in the [deployment documentation](/services/deployment/general), *deployments* are immutable, and are assumed to be reachable throughout the entire lifecycle of an invocation. In order to deploy any change to a service, either in the protobuf definition and/or in the business logic, a new deployment should be deployed and registered. +As described in the [deployment documentation](/services/deployment/general), *service deployments* are immutable, and are assumed to be reachable throughout the entire lifecycle of an invocation. In order to deploy any change to a service, either in the protobuf definition and/or in the business logic, a new deployment should be deployed and registered. When registering a new deployment, Restate will detect if it contains already registered services, and will treat them as new revisions. Any new invocations to that service will be executed by the newly registered deployment, thus guaranteeing that new invocations are always routed to the latest service revision, while *old* invocations will continue to use the previous deployment. It must be guaranteed that the old deployment lives until all the existing invocations complete. diff --git a/docs/tour.mdx b/docs/tour.mdx index 8958c074..e0460c61 100644 --- a/docs/tour.mdx +++ b/docs/tour.mdx @@ -171,7 +171,7 @@ curl -X POST http://localhost:9070/deployments -H 'content-type: application/jso -Restate will send a discovery request to the deployment to find the services and methods run behind this endpoint. Restate keeps track of which services run where (including of the method signatures). Restate also keeps track of multiple revisions as your APIs evolve, and routes requests appropriately. +Restate will send a discovery request to the service deployment to find the services and methods run behind this endpoint. Restate keeps track of which services run where (including of the method signatures). Restate also keeps track of multiple revisions as your APIs evolve, and routes requests appropriately. :::tip You can pipe the output of `curl` into the `jq` utility to reformat the JSON output and make it easier to read.