feat(containers): concepts improvements (#4059)

* feat(containers): concepts improvements

* update tags

* stateless

* Apply suggestions from code review

Co-authored-by: nerda-codes <[email protected]>

* Apply suggestions from code review

Co-authored-by: Rowena Jones <[email protected]>

* precision sandbox

* Update serverless/containers/concepts.mdx

Co-authored-by: Emilie BOUIN <[email protected]>

---------

Co-authored-by: nerda-codes <[email protected]>
Co-authored-by: Rowena Jones <[email protected]>
Co-authored-by: Emilie BOUIN <[email protected]>

Author: 4 people

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:
@@ -31,43 +31,83 @@ 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 optimal 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 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
+
+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 resource. It can be customized with [custom domains](#custom-domain).
 
 ## 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. 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
 
-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 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.
 
 ## GB-s
 
 Unit used to measure the resource consumption of a container. It reflects the amount of memory consumed over time.
 
-## Image
+## gRPC
 
-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.
+gRPC is supported on Serverless Containers, as long as you have enabled http2 (`h2c`) protocol.
+
+## Healthcheck
+
+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).
+
+## Instance
+
+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. 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. [Find out how to secure a container](/serverless/containers/how-to/secure-a-container/#restrict-access-to-your-containers).
+
+## Load balancing
+
+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
+
+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
+
+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
 
 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,11 +126,15 @@ 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
+
+The registry endpoint parameter is the resource linked to the container image used in your Serverless Container.
+
 ## 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 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
 
@@ -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 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
 
@@ -121,7 +169,20 @@ 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 [Managed Databases]/managed-databases/) or [Object Storage](/storage/object/).
+
+## Status
+
+A Serverless Container can have the following statuses:
+* **Ready**: your Serverless Container is operational to serve requests.
+* **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 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
 
@@ -138,4 +199,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.