From aa2b8bbdb36b9570bc7611ff80b55e8617617bcc Mon Sep 17 00:00:00 2001 From: Patrick Derks Date: Fri, 13 Feb 2026 16:01:02 +0100 Subject: [PATCH] feat: Add more information about the k8s meta package fixes: #2100 fixes: #2101 --- .wordlist.txt | 2 + .../paas/shopware/fundamentals/k8s-meta.md | 84 +++++++++++++++++++ .../shopware/get-started/prepare-codebase.md | 15 +++- 3 files changed, 98 insertions(+), 3 deletions(-) create mode 100644 products/paas/shopware/fundamentals/k8s-meta.md diff --git a/.wordlist.txt b/.wordlist.txt index 3af4e5b67..1099e4fd5 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1557,6 +1557,7 @@ memoization memoized mercure mergeWith +metapackage middleware middlewares minPurchase @@ -1826,6 +1827,7 @@ stateId stateMachineState statesfacade statusCode +stderr stdin stdout stemmer diff --git a/products/paas/shopware/fundamentals/k8s-meta.md b/products/paas/shopware/fundamentals/k8s-meta.md new file mode 100644 index 000000000..843a428ff --- /dev/null +++ b/products/paas/shopware/fundamentals/k8s-meta.md @@ -0,0 +1,84 @@ +--- +nav: + title: K8s Meta Package + position: 90 +--- + +# K8s Meta Package + +The `shopware/k8s-meta` Composer package prepares your Shopware project for running on Shopware PaaS Native. It is a metapackage that installs the required dependencies and configuration files via a Symfony Flex recipe. + +## Version compatibility + +Use the version that matches your Shopware installation: + +| Shopware version | k8s-meta version | +|------------------|------------------| +| 6.6 | `^1.0` | +| 6.7 | `^2.0` | + +Install it with: + +```sh +composer require shopware/k8s-meta:^2.0 --ignore-platform-reqs +``` + +:::info +The `--ignore-platform-reqs` flag ensures that all necessary recipes are installed, even if your local PHP version differs from the required platform version. +::: + +## What it installs + +### Dependencies + +The metapackage pulls in the following dependencies: + +| Package | Purpose | +|--------------------------------------|----------------------------------------------------| +| `league/flysystem-async-aws-s3` | S3-compatible filesystem for media and assets | +| `open-telemetry/exporter-otlp` | OpenTelemetry tracing export | +| `open-telemetry/transport-grpc` | gRPC transport for OpenTelemetry | +| `shopware/opentelemetry` | Shopware OpenTelemetry integration | +| `shopware/docker` | Docker and deployment helper tooling | +| `symfony/redis-messenger` | Redis-based message queue transport | + +### Configuration files + +The Symfony Flex recipe creates the file `config/packages/operator.yaml`. After installation, verify that this file exists in your project. + +This file configures Shopware for the PaaS Native infrastructure: + +- **S3 object storage** for public, private, theme, and sitemap filesystems +- **Redis** for application cache and session storage +- **Cluster mode** settings (`cluster_setup: true`, `runtime_extension_management: false`) +- **Admin worker** disabled (queues are processed externally) +- **Elasticsearch/OpenSearch** replica and shard settings +- **Monolog** logging to stderr in JSON format + +Additionally, files in `config/packages/prod/` configure production-specific behavior: + +| File | Purpose | +|-----------------------|--------------------------------------------------| +| `fastly.yaml` | Fastly CDN reverse proxy and cache purging | +| `monolog.yaml` | Error-level logging to stderr in JSON format | +| `opentelemetry.yaml` | OpenTelemetry profiler integration | + +## Overriding configuration + +:::warning +The default configuration is tuned for the PaaS Native infrastructure. Changing values can break your application if you are not familiar with the underlying services. Only override settings when you have a clear reason to do so. +::: + +You can override any value from `operator.yaml` using the standard Symfony configuration override mechanism. Place a YAML file in `config/packages/prod/` with the same configuration keys, and its values will take precedence. + +For example, to enable soft purge with stale cache serving, create or edit a file in `config/packages/prod/`: + +```yaml +# config/packages/prod/shopware.yaml +shopware: + http_cache: + stale_while_revalidate: 300 + stale_if_error: 3600 +``` + +For more details on how Symfony merges configuration files, refer to the [Symfony configuration documentation](https://symfony.com/doc/current/configuration.html#configuration-environments). diff --git a/products/paas/shopware/get-started/prepare-codebase.md b/products/paas/shopware/get-started/prepare-codebase.md index 5e135f0e3..30c53b230 100644 --- a/products/paas/shopware/get-started/prepare-codebase.md +++ b/products/paas/shopware/get-started/prepare-codebase.md @@ -52,17 +52,26 @@ If you're working with an already created Shopware project, simply navigate into cd ``` -Ensure the required Kubernetes metadata package is installed to enable compatibility with the [Shopware Operator](https://github.com/shopware/shopware-operator): +Install the `shopware/k8s-meta` package that prepares your project for PaaS Native. Use the version that matches your Shopware installation: + +| Shopware version | k8s-meta version | +|------------------|------------------| +| 6.6 | `^1.0` | +| 6.7 | `^2.0` | ```sh -composer require shopware/k8s-meta --ignore-platform-reqs +# For Shopware 6.6 +composer require shopware/k8s-meta:^1.0 --ignore-platform-reqs + +# For Shopware 6.7 +composer require shopware/k8s-meta:^2.0 --ignore-platform-reqs ``` :::info The `--ignore-platform-reqs` flag ensures that all necessary recipes are installed, even if your local PHP version differs from the required platform version. ::: -This package installs essential configuration files, including those required for deploying your shop via the Shopware Operator. After installation, verify that the file `config/packages/operator.yaml` has been created. +After installation, verify that the file `config/packages/operator.yaml` has been created. For details on what this package installs and how to override its configuration, see the [K8s Meta Package](../fundamentals/k8s-meta.md) page. ### Create the `application.yaml` File