From 882d7944ca2ee8dd78a3e1e87edc3bc59551883b Mon Sep 17 00:00:00 2001 From: Thomas Tacquet Date: Fri, 29 Nov 2024 14:20:40 +0100 Subject: [PATCH 1/7] feat(containers): concepts improvements --- serverless/containers/concepts.mdx | 81 ++++++++++++++++++++++++++---- 1 file changed, 70 insertions(+), 11 deletions(-) diff --git a/serverless/containers/concepts.mdx b/serverless/containers/concepts.mdx index 02959e8264..15b92c37fc 100644 --- a/serverless/containers/concepts.mdx +++ b/serverless/containers/concepts.mdx @@ -31,35 +31,73 @@ Refer to the [dedicated documentation](/serverless/containers/reference-content/ ## Container -A container is a package of software that includes all dependencies: code, runtime, configuration, and system libraries so that it can run on any host system. Scaleway provides custom Docker images that are entirely handled for you in the cloud. With Containers, you can rely on your favorite technologies such as Django, or Ruby on Rails. +A container is a package of software that includes all dependencies: code, runtime, configuration, and system libraries so that it can run on any host system. Scaleway provides custom Docker images that are entirely handled for you in the cloud. ## Container Registry -Container Registry is the place where your images are stored before being deployed. +Container Registry is the place where your images are stored before being deployed, we recommend using Scaleway Container Registry for a better integration. [Migration guide](/serverless/containers/api-cli/migrate-external-image-to-scaleway-registry/). ## CRON trigger -A CRON trigger is a mechanism used to automatically invoke a Serverless Function at a specific time on a recurring schedule. It works similarly to a traditional Linux [cron job](https://en.wikipedia.org/wiki/Cron), using the `* * * * *` format, and uses the **UTC** time zone. Refer to our [cron schedules reference](/serverless/containers/reference-content/cron-schedules/) for more information. +A CRON trigger is a mechanism used to automatically invoke a Serverless Function at a specific time on a recurring schedule. + +It works similarly to a traditional Linux [cron job](https://en.wikipedia.org/wiki/Cron), using the `* * * * *` format, and uses the **UTC** time zone. Refer to our [cron schedules reference](/serverless/containers/reference-content/cron-schedules/) for more information. + +## Custom domain + +By default a generated endpoint is assigned to your Serverless ressource and custom domains allows you to use your own domain read [custom domain documentation](/serverless/containers/how-to/add-a-custom-domain-to-a-container). + +## Deployment + +Some parameters requires a new deployment of the Container to take affect and it creates a Deployment. Rollout of a deployment will not cause downtime and the traffic switches smoothly to the newest revision. + +## Endpoint + +An endpoint is the URL generated to access your ressource, it can be customised with Custom Domains. ## Environment variables -An environment variable is a variable whose value is set outside the program, typically through functionality built into the operating system, or microservice. An environment variable is made up of a name/value pair, and any number may be created and available for reference at a point in time. +Environment variables are key/value pairs injected in your container. It's useful to share informations such as configuration with your container. Some names are reserved [details about reserved names](/serverless/containers/reference-content/containers-limitations/#configuration-restrictions). ## Ephemeral storage -In addition to vCPU and RAM, Serverless Containers also provide a storage volume for the duration of the task. This storage space allows to hold the data retrieved by the job, and disappears once the execution is complete. The maximum size of the ephemeral storage is tied to the allocated memory. +In addition to vCPU and RAM, Serverless Containers also provide a storage volume for the duration of the task. This storage space allows to hold the data retrieved by the job, and disappears once the execution is complete. + +The maximum size of the ephemeral storage is tied to the allocated memory. ## GB-s Unit used to measure the resource consumption of a container. It reflects the amount of memory consumed over time. -## Image +## gRPC + +gRPC is supported on Serverless Containers, it requires to enable http2 (`h2c`) protocol. + +## Healthcheck + +To determine the `Status` of a Serverless Containers, default healthecks automatically checks if basic requirements are met to define the status as `ready`. -An image is a blueprint from which an arbitrary number of brand-new containers can be started. You can start a container from an image, perform operations in it, and save another image based on the latest state of the container. +It's possible to define custom healthecks rules with a specific endpoint via the API: [read API doc](https://www.scaleway.com/en/developers/api/serverless-containers/#path-containers-create-a-new-container). + +## Instance + +Depending incoming requests, min scale and max scale, a Serverless Container instance processes incoming requests. ## JWT Token -JWT (JSON Web Token) is an access token you can create from the console or API to enable an application to access your Private Container. Consult the [Developer documentation](https://www.scaleway.com/en/developers/api/serverless-containers/#path-tokens) for more details. +JWT (JSON Web Token) is an access token you can create from the console or API to enable an application to access your Private Container. [More details about how to secure a Container](/serverless/containers/how-to/secure-a-container/#restrict-access-to-your-containers) + +## Load balancing + +Incoming request traffic is managed by the Serverless infrastructure. In some cases such as rapid traffic changes or load testing, depending max scale parameter the ressources are automatically allocated to manage the traffic. + +## Max scale + +It's the maximum number of instances of your Container. Define this parameter according to the traffic spikes of your Container. In some cases you may want to limit the max scale for cost control reasons. + +## Min scale + +Customizing min scale for Serverless can be useful to keep an instance warm and limit cold starts. It also have an impact on costs of your Serverless Container. ## mvCPU @@ -67,7 +105,9 @@ A [vCPU](#vcpu) (Virtual Central Processing Unit) is equivalent to 1000 mvCPU. ## Namespace -A namespace is a project that allows you to [group your containers](/serverless/containers/how-to/create-manage-delete-containers-namespace/). Containers in the same namespace can share environment variables and access tokens, defined at the namespace level. +A namespace is a project that allows you to [group your containers](/serverless/containers/how-to/create-manage-delete-containers-namespace/). + +Containers in the same namespace can share environment variables, secrets and access tokens, defined at the namespace level. ## NATS trigger @@ -86,6 +126,10 @@ The value defined in the port parameter will then be passed to your container du A container's privacy policy defines whether a container may be invoked anonymously (**public**) or only via an authentication mechanism provided by the [Scaleway API](https://www.scaleway.com/en/developers/api/serverless-containers/#authentication) (**private**). +## Registry endpoint + +Registry endpoint parameter is the ressource link to the container image used in the Serverless Container. + ## Sandbox A sandbox is an isolation area for your container. Serverless Containers offer two sandboxing environments: @@ -110,7 +154,11 @@ Serverless allows you to deploy your Functions (FaaS) and Containerized Applicat ## Serverless Framework -Serverless.com (Serverless Framework) is a tool that allows you to deploy serverless applications without having to manage Serverless Container’s API call. Write and deploy a YAML configuration file, everything else is handled automatically, even the image building. +Serverless.com (Serverless Framework) is a tool that allows you to deploy serverless applications without having to manage Serverless Container's API call. Write and deploy a YAML configuration file, everything else is handled automatically, even the image building. + +## Serverless Job + +Serverless Jobs are close to Serverless Containers but it's more adapted to run long workloads, see [comparaison between Serverless products](/serverless/containers/reference-content/difference-jobs-functions-containers.mdx). ## SQS trigger @@ -123,6 +171,17 @@ The container can then process the message and perform any required actions, suc A stateless application is a computer program that does not save client data between sessions. Data generated in one session is not saved for use in the next session with that client. All applications deployed on Serverless Containers are stateless. +## Status + +A Serverless Container can be: +* **Ready**: your Serverless Container is operational to serve requests. +* **Pending**: your ressource is under deployment. +* **Error**: something failed in the deploymen process, [open troubleshooting documentation](/serverless/containers/troubleshooting/cannot-deploy-image.mdx). + +## Terraform + +Terraform is an infrastructure as code tool, [read terraform documentation of Serverless Containers](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/resources/container). + ## Timeout The timeout is the maximum length of time your container can spend processing a request before being stopped. This value must be in the range 10s to 900s. @@ -138,4 +197,4 @@ Unit used to measure the resource consumption of a container. It reflects the am ## Protocol -Serverless Containers supports **http1** (default) and **http2** (`h2c`). Use HTTP/2 if your container application is configured to listen for HTTP/2 requests, such as a gRPC service or a web server that uses HTTP/2 features like multiplexing, otherwise HTTP/1 is recommended. +Serverless Containers supports **http1** (default) and **http2** (`h2c`). Use HTTP/2 if your container application is configured to listen for HTTP/2 requests, such as a **gRPC** service or a web server that uses HTTP/2 features like multiplexing, otherwise HTTP/1 is recommended. From 6fabae94c64bac6a7403f91ad7fdcfea62deac0f Mon Sep 17 00:00:00 2001 From: Thomas Tacquet Date: Fri, 29 Nov 2024 14:42:17 +0100 Subject: [PATCH 2/7] update tags --- serverless/containers/concepts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverless/containers/concepts.mdx b/serverless/containers/concepts.mdx index 15b92c37fc..d1030b340e 100644 --- a/serverless/containers/concepts.mdx +++ b/serverless/containers/concepts.mdx @@ -5,7 +5,7 @@ meta: content: h1: Containers - Concepts paragraph: Key concepts of Scaleway Serverless Containers. -tags: containers cold-start concurrency container-registry gbs environment-variables jwt vcpu +tags: containers cold-start concurrency container-registry environment-variables jwt vcpu serverless scale autoscaling dates: validation: 2024-11-14 categories: From 1c72634dbe97a7357b08918f639dfcebe04bed0d Mon Sep 17 00:00:00 2001 From: Thomas Tacquet Date: Fri, 29 Nov 2024 17:44:38 +0100 Subject: [PATCH 3/7] stateless --- serverless/containers/concepts.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/serverless/containers/concepts.mdx b/serverless/containers/concepts.mdx index d1030b340e..a7ab97edfe 100644 --- a/serverless/containers/concepts.mdx +++ b/serverless/containers/concepts.mdx @@ -169,7 +169,9 @@ The container can then process the message and perform any required actions, suc ## Stateless application -A stateless application is a computer program that does not save client data between sessions. Data generated in one session is not saved for use in the next session with that client. All applications deployed on Serverless Containers are stateless. +A stateless application is a computer program that does not save client data between sessions. Data generated in one session is not saved for use in the next session with that client. + +To store data persistently, use products like Databases or Object Storage. ## Status From a3302f001c5d603f0630a1fe07fdb1f69b428b96 Mon Sep 17 00:00:00 2001 From: Thomas TACQUET Date: Mon, 2 Dec 2024 11:23:28 +0100 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: nerda-codes <87707325+nerda-codes@users.noreply.github.com> --- serverless/containers/concepts.mdx | 36 +++++++++++++++--------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/serverless/containers/concepts.mdx b/serverless/containers/concepts.mdx index a7ab97edfe..bce00aae32 100644 --- a/serverless/containers/concepts.mdx +++ b/serverless/containers/concepts.mdx @@ -45,23 +45,23 @@ It works similarly to a traditional Linux [cron job](https://en.wikipedia.org/wi ## Custom domain -By default a generated endpoint is assigned to your Serverless ressource and custom domains allows you to use your own domain read [custom domain documentation](/serverless/containers/how-to/add-a-custom-domain-to-a-container). +By default a generated endpoint is assigned to your Serverless resource and custom domains allows you to use your own domain read [custom domain documentation](/serverless/containers/how-to/add-a-custom-domain-to-a-container). ## Deployment -Some parameters requires a new deployment of the Container to take affect and it creates a Deployment. Rollout of a deployment will not cause downtime and the traffic switches smoothly to the newest revision. +Some parameter changes require a new deployment of the container to take effect. The deployment happens without causing downtime, as traffic is switched to the newest version. ## Endpoint -An endpoint is the URL generated to access your ressource, it can be customised with Custom Domains. +An endpoint is the URL generated to access your resource, it can be customized with custom domains. ## Environment variables -Environment variables are key/value pairs injected in your container. It's useful to share informations such as configuration with your container. Some names are reserved [details about reserved names](/serverless/containers/reference-content/containers-limitations/#configuration-restrictions). +Environment variables are key/value pairs injected in your container. They are useful to share informations such as a configuration, with your container. Some names are reserved. [See details about reserved names](/serverless/containers/reference-content/containers-limitations/#configuration-restrictions). ## Ephemeral storage -In addition to vCPU and RAM, Serverless Containers also provide a storage volume for the duration of the task. This storage space allows to hold the data retrieved by the job, and disappears once the execution is complete. +In addition to vCPU and RAM, Serverless Containers also provide a storage volume for the duration of the task. This storage space allows you to hold the data retrieved by the job, and disappears once the execution is complete. The maximum size of the ephemeral storage is tied to the allocated memory. @@ -75,29 +75,29 @@ gRPC is supported on Serverless Containers, it requires to enable http2 (`h2c`) ## Healthcheck -To determine the `Status` of a Serverless Containers, default healthecks automatically checks if basic requirements are met to define the status as `ready`. +To determine the status of a container, default healthcheck automatically checks if basic requirements are met to define the status as `ready`. -It's possible to define custom healthecks rules with a specific endpoint via the API: [read API doc](https://www.scaleway.com/en/developers/api/serverless-containers/#path-containers-create-a-new-container). +You can define custom healthcheck rules with a [specific endpoint via the Scaleway API](https://www.scaleway.com/en/developers/api/serverless-containers/#path-containers-create-a-new-container). ## Instance -Depending incoming requests, min scale and max scale, a Serverless Container instance processes incoming requests. +A Serverless Container instance handles incoming requests based on factors like the request volume, min scale, and max scale parameters. ## JWT Token -JWT (JSON Web Token) is an access token you can create from the console or API to enable an application to access your Private Container. [More details about how to secure a Container](/serverless/containers/how-to/secure-a-container/#restrict-access-to-your-containers) +JWT (JSON Web Token) is an access token you can create from the console or API to enable an application to access your Private Container. [Find out how to secure a container](/serverless/containers/how-to/secure-a-container/#restrict-access-to-your-containers) ## Load balancing -Incoming request traffic is managed by the Serverless infrastructure. In some cases such as rapid traffic changes or load testing, depending max scale parameter the ressources are automatically allocated to manage the traffic. +The Serverless infrastructure manages incoming request traffic. In scenarios like sudden traffic spikes or load testing, resources are automatically scaled based on the max scale parameter to handle the load. ## Max scale -It's the maximum number of instances of your Container. Define this parameter according to the traffic spikes of your Container. In some cases you may want to limit the max scale for cost control reasons. +This parameter sets the maximum number of container instances. Adjust it based on your container's traffic spikes, but you might also limit the max scale to manage costs effectively. ## Min scale -Customizing min scale for Serverless can be useful to keep an instance warm and limit cold starts. It also have an impact on costs of your Serverless Container. +Customizing the minimum scale for Serverless can help ensure that an instance remains pre-allocated and ready to handle requests, reducing delays associated with cold starts. However, this setting also impacts the costs of your Serverless Container. ## mvCPU @@ -128,7 +128,7 @@ A container's privacy policy defines whether a container may be invoked anonymou ## Registry endpoint -Registry endpoint parameter is the ressource link to the container image used in the Serverless Container. +The registry endpoint parameter is the resource linked to the container image used in your Serverless Container. ## Sandbox @@ -158,7 +158,7 @@ Serverless.com (Serverless Framework) is a tool that allows you to deploy server ## Serverless Job -Serverless Jobs are close to Serverless Containers but it's more adapted to run long workloads, see [comparaison between Serverless products](/serverless/containers/reference-content/difference-jobs-functions-containers.mdx). +Serverless Jobs are similar to Serverless Containers but are better suited for running longer workloads. See [the comparaison between Serverless products](/serverless/containers/reference-content/difference-jobs-functions-containers) for more information. ## SQS trigger @@ -175,14 +175,14 @@ To store data persistently, use products like Databases or Object Storage. ## Status -A Serverless Container can be: +A Serverless Container can have the following statuses: * **Ready**: your Serverless Container is operational to serve requests. -* **Pending**: your ressource is under deployment. -* **Error**: something failed in the deploymen process, [open troubleshooting documentation](/serverless/containers/troubleshooting/cannot-deploy-image.mdx). +* **Pending**: your resource is under deployment. +* **Error**: something went wrong during the deployment process. [Check our troubleshooting documentation](/serverless/containers/troubleshooting/cannot-deploy-image) to solve the issue. ## Terraform -Terraform is an infrastructure as code tool, [read terraform documentation of Serverless Containers](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/resources/container). +Terraform is a tool for managing infrastructure using code. [Read the Terraform documentation for Serverless Containers](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/resources/container). ## Timeout From fba66ef13d717766401832835ad788535334f4a1 Mon Sep 17 00:00:00 2001 From: Thomas TACQUET Date: Mon, 2 Dec 2024 12:46:58 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Rowena Jones <36301604+RoRoJ@users.noreply.github.com> --- serverless/containers/concepts.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/serverless/containers/concepts.mdx b/serverless/containers/concepts.mdx index bce00aae32..d590bd97ca 100644 --- a/serverless/containers/concepts.mdx +++ b/serverless/containers/concepts.mdx @@ -35,7 +35,7 @@ A container is a package of software that includes all dependencies: code, runti ## Container Registry -Container Registry is the place where your images are stored before being deployed, we recommend using Scaleway Container Registry for a better integration. [Migration guide](/serverless/containers/api-cli/migrate-external-image-to-scaleway-registry/). +Container Registry is the place where your images are stored before being deployed, we recommend using Scaleway Container Registry for optimal integration. [Migration guide](/serverless/containers/api-cli/migrate-external-image-to-scaleway-registry/). ## CRON trigger @@ -45,7 +45,7 @@ It works similarly to a traditional Linux [cron job](https://en.wikipedia.org/wi ## Custom domain -By default a generated endpoint is assigned to your Serverless resource and custom domains allows you to use your own domain read [custom domain documentation](/serverless/containers/how-to/add-a-custom-domain-to-a-container). +By default, a generated endpoint is assigned to your Serverless resource. Custom domains allows you to use your own domain - see our [custom domain documentation](/serverless/containers/how-to/add-a-custom-domain-to-a-container) for full details. ## Deployment @@ -53,11 +53,11 @@ Some parameter changes require a new deployment of the container to take effect. ## Endpoint -An endpoint is the URL generated to access your resource, it can be customized with custom domains. +An endpoint is the URL generated to access your resource. It can be customized with [custom domains](#custom-domain). ## Environment variables -Environment variables are key/value pairs injected in your container. They are useful to share informations such as a configuration, with your container. Some names are reserved. [See details about reserved names](/serverless/containers/reference-content/containers-limitations/#configuration-restrictions). +Environment variables are key/value pairs injected in your container. They are useful to share information such as configurations with your container. Some names are reserved. [See details about reserved names](/serverless/containers/reference-content/containers-limitations/#configuration-restrictions). ## Ephemeral storage @@ -71,11 +71,11 @@ Unit used to measure the resource consumption of a container. It reflects the am ## gRPC -gRPC is supported on Serverless Containers, it requires to enable http2 (`h2c`) protocol. +gRPC is supported on Serverless Containers, as long as you have enabled http2 (`h2c`) protocol. ## Healthcheck -To determine the status of a container, default healthcheck automatically checks if basic requirements are met to define the status as `ready`. +To determine the status of a container, the default healthcheck automatically checks if basic requirements are met, to define the status as `ready`. You can define custom healthcheck rules with a [specific endpoint via the Scaleway API](https://www.scaleway.com/en/developers/api/serverless-containers/#path-containers-create-a-new-container). @@ -85,7 +85,7 @@ A Serverless Container instance handles incoming requests based on factors like ## JWT Token -JWT (JSON Web Token) is an access token you can create from the console or API to enable an application to access your Private Container. [Find out how to secure a container](/serverless/containers/how-to/secure-a-container/#restrict-access-to-your-containers) +JWT (JSON Web Token) is an access token you can create from the console or API to enable an application to access your private container. [Find out how to secure a container](/serverless/containers/how-to/secure-a-container/#restrict-access-to-your-containers). ## Load balancing @@ -93,7 +93,7 @@ The Serverless infrastructure manages incoming request traffic. In scenarios lik ## Max scale -This parameter sets the maximum number of container instances. Adjust it based on your container's traffic spikes, but you might also limit the max scale to manage costs effectively. +This parameter sets the maximum number of container instances. You should adjust it based on your container's traffic spikes, keeping in mind that you may wish to limit the max scale to manage costs effectively. ## Min scale @@ -171,7 +171,7 @@ The container can then process the message and perform any required actions, suc A stateless application is a computer program that does not save client data between sessions. Data generated in one session is not saved for use in the next session with that client. -To store data persistently, use products like Databases or Object Storage. +To store data persistently, use products like [Managed Databases]/managed-databases/) or [Object Storage](/storage/object/). ## Status From 937d63d0253192f4d1896f100228ae28b28cc293 Mon Sep 17 00:00:00 2001 From: Thomas Tacquet Date: Mon, 2 Dec 2024 16:47:14 +0100 Subject: [PATCH 6/7] precision sandbox --- serverless/containers/concepts.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/serverless/containers/concepts.mdx b/serverless/containers/concepts.mdx index d590bd97ca..a7dad8120d 100644 --- a/serverless/containers/concepts.mdx +++ b/serverless/containers/concepts.mdx @@ -133,8 +133,8 @@ The registry endpoint parameter is the resource linked to the container image us ## Sandbox A sandbox is an isolation area for your container. Serverless Containers offer two sandboxing environments: -- **v2** - Recommended for faster cold starts. -- **v1** - Legacy sandboxing with slower cold starts, but fully supports Linux system call interface. +- **v2** - Recommended for faster cold starts. Can introduce some overhead on specifc worklows with consequent amount of *syscalls*. +- **v1** - Legacy sandboxing with slower cold starts, but fully supports Linux system call interface. Prefer this option when processing large amount of *syscalls*. ## Scale to zero From fcfa6a1577d73fe33d5d1e834f33cb9cde7336df Mon Sep 17 00:00:00 2001 From: Thomas TACQUET Date: Mon, 2 Dec 2024 17:03:37 +0100 Subject: [PATCH 7/7] Update serverless/containers/concepts.mdx Co-authored-by: Emilie BOUIN <48752456+Bemilie@users.noreply.github.com> --- serverless/containers/concepts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/serverless/containers/concepts.mdx b/serverless/containers/concepts.mdx index a7dad8120d..e576b272a9 100644 --- a/serverless/containers/concepts.mdx +++ b/serverless/containers/concepts.mdx @@ -133,7 +133,7 @@ The registry endpoint parameter is the resource linked to the container image us ## Sandbox A sandbox is an isolation area for your container. Serverless Containers offer two sandboxing environments: -- **v2** - Recommended for faster cold starts. Can introduce some overhead on specifc worklows with consequent amount of *syscalls*. +- **v2** - Recommended for faster cold starts. Can introduce some overhead on specific worklows with consequent amount of *syscalls*. - **v1** - Legacy sandboxing with slower cold starts, but fully supports Linux system call interface. Prefer this option when processing large amount of *syscalls*. ## Scale to zero