Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
ec72aa8
Rm internal-registry
MichalKalke Jul 2, 2025
db94531
Rm internal-registry v2
MichalKalke Jul 3, 2025
4ee881e
Adjust 06-20-serverless-cr
MichalKalke Jul 7, 2025
376cee0
Need to be finished - svrls architecture
MichalKalke Jul 8, 2025
7fa2591
Rm function-processing-stages
MichalKalke Jul 8, 2025
eb29bed
Adjust 07-80-av-presets
MichalKalke Jul 10, 2025
730b8bf
Rm cannot-build-fnc
MichalKalke Jul 10, 2025
ff786cc
Rm fnc-build-failing-k3d
MichalKalke Jul 10, 2025
1620b3b
Adjust 01-90-set-async-connection
MichalKalke Jul 13, 2025
175b50c
Adjust 00-20-cnfg-serverless
MichalKalke Jul 13, 2025
6abf2b5
Adjust 00-40-security
MichalKalke Jul 13, 2025
944458f
Adjust 00-40-security v2
MichalKalke Jul 13, 2025
14ea042
Adjust 00-500-limitations
MichalKalke Jul 13, 2025
c87aa51
Adjust sidebar
MichalKalke Jul 13, 2025
392f51f
Adjust root README
MichalKalke Jul 13, 2025
467547c
adjust 06-10-func-cr
MichalKalke Jul 13, 2025
f4f549d
Adjust 04-10-architecture
MichalKalke Jul 14, 2025
17390ce
Create .md with serverless updates
MichalKalke Jul 14, 2025
28cfc4b
Adjust _sidebar.md
MichalKalke Jul 14, 2025
6224686
Merge branch 'main' into adjust-docs-for-buildless
MichalKalke Jul 15, 2025
e5984b1
Update docs/user/technical-reference/03-10-architecture-updates.md
MichalKalke Jul 16, 2025
bae75d2
Update docs/user/technical-reference/03-10-architecture-updates.md
MichalKalke Jul 16, 2025
845c120
Update docs/user/technical-reference/03-10-architecture-updates.md
MichalKalke Jul 16, 2025
f430730
Update docs/user/technical-reference/03-10-architecture-updates.md
MichalKalke Jul 16, 2025
d74473b
Update docs/user/technical-reference/03-10-architecture-updates.md
MichalKalke Jul 16, 2025
5cb8c54
Merge branch 'main' into adjust-docs-for-buildless
MichalKalke Jul 16, 2025
5f260ef
Update docs/user/technical-reference/03-10-architecture-updates.md
MichalKalke Jul 22, 2025
9bd6b96
Update docs/user/technical-reference/03-10-architecture-updates.md
MichalKalke Jul 22, 2025
07ac589
Merge branch 'main' into adjust-docs-for-buildless
MichalKalke Jul 22, 2025
057fb0d
Adjust svls-architecture.svg
MichalKalke Jul 22, 2025
2056615
Restore ImageOverride, delete hpa in 06-10-function-cr
MichalKalke Jul 25, 2025
28d3df2
Adjust 04-10-architecture.md
MichalKalke Jul 25, 2025
cfc39ae
Revert "Rm function-processing-stages"
MichalKalke Jul 25, 2025
f04ca38
Merge branch 'main' into adjust-docs-for-buildless
MichalKalke Jul 25, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/assets/svls-architecture.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
141 changes: 0 additions & 141 deletions docs/user/00-20-configure-serverless.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,12 @@ The Serverless module has its own operator (Serverless Operator). It watches the

The Serverless CR is an API to configure the Serverless module. You can use it to perform the following actions:

- Enable or disable the internal Docker registry
- Configure the external Docker registry
- Override endpoint for traces collected by the Serverless Functions
- Override endpoint for Eventing
- Override the target CPU utilization percentage
- Override the Function requeue duration
- Override the Function build executor arguments
- Override the Function build max simultaneous jobs
- Override the healthz liveness timeout
- Override the Function request body limit
- Override the Function timeout
- Override the default build Job preset
- Override the default runtime Pod preset
- Override the default log level
- Override the default log format
Expand All @@ -34,85 +28,6 @@ The default configuration of the Serverless Module is following:
enableInternal: true
```

> [!CAUTION]
> The `spec.dockerRegistry` field is deprecated and will be removed in a future version of Serverless where Functions won't require building images.

## Configure Docker Registry

By default, Serverless uses PersistentVolume (PV) as the internal registry to store Docker images for Functions. The default storage size of a single volume is 20 GB. This internal registry is suitable for local development.

> [!ATTENTION]
> If you use Serverless for production purposes, it is recommended that you use an external registry, such as Docker Hub, Artifact Registry, or Azure Container Registry (ACR).

Follow these steps to use the external Docker registry in Serverless:

1. Create a Secret in the `kyma-system` namespace with the required data (`username`, `password`, `serverAddress`, and `registryAddress`):

```bash
kubectl create secret generic my-registry-config \
--namespace kyma-system \
--from-literal=username={USERNAME} \
--from-literal=password={PASSWORD} \
--from-literal=serverAddress={SERVER_URL} \
--from-literal=registryAddress={REGISTRY_URL}
```

> [!TIP]
> In case of DockerHub, usually the Docker registry address is the same as the account name.

Examples:

<!-- tabs:start -->

### **Docker Hub**

```bash
kubectl create secret generic my-registry-config \
--namespace kyma-system \
--from-literal=username={USERNAME} \
--from-literal=password={PASSWORD} \
--from-literal=serverAddress=https://index.docker.io/v1/ \
--from-literal=registryAddress={USERNAME}
```

### **Artifact Registry**

```bash
kubectl create secret generic my-registry-config \
--namespace kyma-system \
--from-literal=username=_json_key \
--from-literal=password={GCR_KEY_JSON} \
--from-literal=serverAddress=gcr.io \
--from-literal=registryAddress=gcr.io/{YOUR_GCR_PROJECT}
```

For more information on how to set up authentication for Docker with Artifact Registry, see the [Artifact Registry documentation](https://cloud.google.com/artifact-registry/docs/docker/authentication#json-key).

### **ACR**

```bash
kubectl create secret generic my-registry-config \
--namespace kyma-system \
--from-literal=username=00000000-0000-0000-0000-000000000000 \
--from-literal=password={ACR_TOKEN} \
--from-literal=serverAddress={AZ_REGISTRY_NAME}.azurecr.io \
--from-literal=registryAddress={AZ_REGISTRY_NAME}.azurecr.io
```

For more information on how to authenticate with ACR, see the [ACR documentation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-authentication?tabs=azure-cli#az-acr-login-with---expose-token).

<!-- tabs:end -->

2. Reference the Secret in the Serverless CR:

```yaml
spec:
dockerRegistry:
secretName: my-registry-config
```

The URL of the currently used Docker registry is visible in the Serverless CR status.

## Configure Trace Endpoint

By default, the Serverless operator checks if there is a trace endpoint available. If available, the detected trace endpoint is used as the trace collector URL in Functions.
Expand All @@ -138,18 +53,6 @@ By default `http://eventing-publisher-proxy.kyma-system.svc.cluster.local/publis
endpoint: http://eventing-publisher-proxy.kyma-system.svc.cluster.local/publish
```

## Configure Target CPU Utilization Percentage

You can set a custom target threshold for CPU utilization. The default value is set to `50%`.

```yaml
spec:
targetCPUUtilizationPercentage: 50
```

> [!CAUTION]
> The `spec.targetCPUUtilizationPercentage` field is deprecated and will be removed in a future version of Serverless, where automatic HPA creation will be disabled.

## Configure the Function Requeue Duration

By default, the Function associated with the default configuration will be requeued every 5 minutes.
Expand All @@ -159,38 +62,6 @@ By default, the Function associated with the default configuration will be reque
functionRequeueDuration: 5m
```

## Configure the Function Build Executor Arguments

Use this label to choose the [arguments](https://github.com/GoogleContainerTools/kaniko?tab=readme-ov-file#additional-flags) passed to the Function build executor, for example:

- `--insecure` - executor operates in an insecure mode
- `--skip-tls-verify` - executor skips the TLS certificate verification
- `--skip-unused-stages` - executor skips any stages that aren't used for the current execution
- `--log-format=text` - executor uses logs in a given format
- `--cache=true` - enables caching for the executor
- `--compressed-caching=false` - prevents tar compression for cached layers. This increases the runtime of the build, but decrease the memory usage especially for large builds.
- `--use-new-run` - improves performance by avoiding the full filesystem snapshots.

```yaml
spec:
functionBuildExecutorArgs: "--insecure,--skip-tls-verify,--skip-unused-stages,--log-format=text,--cache=true,--use-new-run,--compressed-caching=false"
```

> [!CAUTION]
> The `spec.functionBuildExecutorArgs` field is deprecated and will be removed in a future version of Serverless where Functions won't require building images.

## Configure the Function Build Max Simultaneous Jobs

You can set a custom maximum number of simultaneous jobs which can run at the same time. The default value is set to `5`.

```yaml
spec:
functionBuildMaxSimultaneousJobs: 5
```

> [!CAUTION]
> The `spec.functionBuildMaxSimultaneousJobs` field is deprecated and will be removed in a future version of Serverless where Functions won't require building images.

## Configure the healthz Liveness Timeout

By default, Function is considered unhealthy if the liveness health check endpoint does not respond within 10 seconds.
Expand All @@ -200,18 +71,6 @@ By default, Function is considered unhealthy if the liveness health check endpoi
healthzLivenessTimeout: "10s"
```

## Configure the Default Build Job Preset

You can configure the default build Job preset to be used.

```yaml
spec:
defaultBuildJobPreset: "normal"
```

> [!CAUTION]
> The `spec.defaultBuildJobPreset` field is deprecated and will be removed in a future version of Serverless where Functions won't require building images.

## Configure the Default Runtime Pod Preset

You can configure the default runtime Pod preset to be used.
Expand Down
7 changes: 1 addition & 6 deletions docs/user/00-40-security-considerations.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,8 @@ To eliminate potential security risks when using Functions, bear in mind these f

- Kyma does not define any authorization policies that would restrict Functions' access to other resources within the namespace. If you deploy a Function in a given namespace, it can freely access all events and APIs of services within this namespace.

- Since Kubernetes is [moving from PodSecurityPolicies to PodSecurity Admission Controller](https://kubernetes.io/docs/tasks/configure-pod-container/migrate-from-psp/), Kyma Functions require running in namespaces with the `baseline` Pod security level. The `restricted` level is not currently supported due to the requirements of the Function building process.

- The Kyma Serverless components can run with the PodSecurity Admission Controller support in the `restricted` Pod security level when using an external registry. When the Internal Docker Registry is enabled, the Internal Registry DaemonSet requires elevated privileges to function correctly, exceeding the limitations of both the `restricted` and `baseline` levels.
- Since Kubernetes is [moving from PodSecurityPolicies to PodSecurity Admission Controller](https://kubernetes.io/docs/tasks/configure-pod-container/migrate-from-psp/), Kyma Functions require running in namespaces with the `baseline` Pod security level.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if the whole paragraph makes sence is buildldess mode.
restricted level was not working because of builds. So there is no need to say to the users that baseline (les restrictive) level is required for functions to run.
Please test if buildless functions work fine in namespaces where restricted pod security level is configured.

If it does work, we would need to change the message - not say what baseline is required but rather point out that by removing builds we are enable functions to be run in namespaces with more strict pod security level

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is working with adjustment in the deployment, PR - #1773


- All administrators and regular users who have access to a specific namespace in a cluster can also access:

- Source code of all Functions within this namespace
- Internal Docker registry that contains Function images
- Secrets allowing the build Job to pull and push images from and to the Docker registry (in non-system namespaces)

42 changes: 3 additions & 39 deletions docs/user/00-50-limitations.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,52 +5,19 @@
Function Ccontroller does not serve time-critical requests from users.
It reconciles Function custom resources (CR), stored at the Kubernetes API Server, and has no persistent state on its own.

Function Controller doesn't build or serve Functions using its allocated runtime resources. It delegates this work to the dedicated Kubernetes workloads. It schedules (build-time) jobs to build the Function Docker image and (runtime) Pods to serve them once they are built.
Function Controller doesn't serve Functions using its allocated runtime resources. It delegates this work to the dedicated Kubernetes workloads.
Refer to the [architecture](technical-reference/04-10-architecture.md) diagram for more details.

Having this in mind, also remember that Function Controller does not require horizontal scaling.
It scales vertically up to `160Mi` of memory and `500m` of CPU time.

## Namespace Setup Limitations

Be aware that if you apply [LimitRanges](https://kubernetes.io/docs/concepts/policy/limit-range/) in the target namespace where you create Functions, the limits also apply to the Function workloads and may prevent Functions from being built and run. In such cases, ensure that resources requested in the Function configuration are lower than the limits applied in the namespace.
Be aware that if you apply [LimitRanges](https://kubernetes.io/docs/concepts/policy/limit-range/) in the target namespace where you create Functions, the limits also apply to the Function workloads and may prevent Functions from being run. In such cases, ensure that resources requested in the Function configuration are lower than the limits applied in the namespace.

## Limitation for the Number of Functions

There is no upper limit of Functions that you can run on Kyma. Once you define a Function, its build jobs and runtime Pods are always requested by Function Controller. It's up to Kubernetes to schedule them based on the available memory and CPU time on the Kubernetes worker nodes. This is determined mainly by the number of the Kubernetes worker nodes (and the node auto-scaling capabilities) and their computational capacity.

## Build Phase Limitation

> [!NOTE]
> All measurements were taken on Kubernetes with five AWS worker nodes of type m5.xlarge (four CPU 3.1 GHz x86_64 cores, 16 GiB memory).

The time necessary to build a Function depends on the following elements:

- Selected [build profile](technical-reference/07-80-available-presets.md#build-jobs-resources) that determines the requested resources (and their limits) for the build phase
- Number and size of dependencies that must be downloaded and bundled into the Function image
- Cluster nodes specification

<!-- tabs:start -->

#### **Node.js**

| | local-dev | no profile (no limits for resource) |
|-----------------|-----------|-------------------------------------|
| no dependencies | 24 sec | 15 sec |
| 2 dependencies | 26 sec | 16 sec |

#### **Python**

| | local-dev | no profile (no limits for resource) |
|-----------------|-----------|-------------------------------------|
| no dependencies | 30 sec | 16 sec |
| 2 dependencies | 32 sec | 20 sec |

<!-- tabs:end -->

The shortest build time (the limit) is approximately 15 seconds and requires no limitation of the build job resources and a minimum number of dependencies that are pulled in during the build phase.

Running multiple Function build jobs at once (especially with no limits) may drain the cluster resources. To mitigate such risk, there is an additional limit of 5 simultaneous Function builds. If a sixth one is scheduled, it is built once there is a vacancy in the build queue.
There is no upper limit of Functions that you can run on Kyma. Once you define a Function and runtime Pods are always requested by Function Controller. It's up to Kubernetes to schedule them based on the available memory and CPU time on the Kubernetes worker nodes. This is determined mainly by the number of the Kubernetes worker nodes (and the node auto-scaling capabilities) and their computational capacity.

## Runtime Phase Limitations

Expand Down Expand Up @@ -88,6 +55,3 @@ The bigger the runtime profile, the more resources are available to serve the re
Function runtime Pods can be scaled horizontally from zero up to the limits of the available resources at the Kubernetes worker nodes.
See the [Use External Scalers](tutorials/01-130-use-external-scalers.md) tutorial for more information.

## In-Cluster Docker Registry

Serverless comes with an in-cluster Docker registry for the Function images. For more information on the Docker registry configuration, see [Serverless Configuration](00-20-configure-serverless.md#configure-docker-registry).
1 change: 0 additions & 1 deletion docs/user/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ The Serverless module provides the following features:
- Event-driven programming model
- Reduced implementation and operation effort
- Function management with Kubernetes resources like [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [Services](https://kubernetes.io/docs/concepts/services-networking/service/), and [HorizontalPodAutoscalers](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
- Docker image creation with [Kubernetes Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/job/)

## Architecture

Expand Down
6 changes: 1 addition & 5 deletions docs/user/_sidebar.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,19 +21,15 @@
* [Function CR](/serverless-manager/user/resources/06-10-function-cr.md)
* [Serverless CR](/serverless-manager/user/resources/06-20-serverless-cr.md)
* [Technical Reference](/serverless-manager/user/technical-reference/README.md)
* [Serverless Architecture Updates](/serverless-manager/user/technical-reference/serverless-architecture-updates.md)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you like a tittle "Buildless Serverless"
My idea would be to already start describing the build-less mode even though the regular mode is still used by default.

We could publish this part with next release of serverless, which will allow users to switch using annotation.
Please extract this document into separate PR

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, awesome title, I will move this part to separate PR

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR: #1774

* [Serverless Architecture](/serverless-manager/user/technical-reference/04-10-architecture.md)
* [Internal Docker Registry](/serverless-manager/user/technical-reference/04-20-internal-registry.md)
* [Environment Variables in Functions](/serverless-manager/user/technical-reference/05-20-env-variables.md)
* [Sample Functions](/serverless-manager/user/technical-reference/07-10-sample-functions.md)
* [Function Processing](/serverless-manager/user/technical-reference/07-20-function-processing-stages.md)
* [Git Source Type](/serverless-manager/user/technical-reference/07-40-git-source-type.md)
* [Function Configuration File](/serverless-manager/user/technical-reference/07-60-function-configuration-file.md)
* [Function's Specification](/serverless-manager/user/technical-reference/07-70-function-specification.md)
* [Available Presets](/serverless-manager/user/technical-reference/07-80-available-presets.md)
* [Troubleshooting Guides](/serverless-manager/user/troubleshooting-guides/README.md)
* [Functions Won't Build](/serverless-manager/user/troubleshooting-guides/03-10-cannot-build-functions.md)
* [Container Fails](/serverless-manager/user/troubleshooting-guides/03-20-failing-function-container.md)
* [Functions Failing To Build on k3d](/serverless-manager/user/troubleshooting-guides/03-40-function-build-failing-k3d.md)
* [Serverless Periodically Restarting](/serverless-manager/user/troubleshooting-guides/03-50-serverless-periodically-restaring.md)
* [Best Practices](/serverless-manager/user/08-10-best-practices.md)
<!-- markdown-link-check-enable -->
Loading
Loading