From 7ae6d6f8d7b1895164e5887899a2f95d940d72e7 Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:42:24 -0500 Subject: [PATCH 01/12] docs: remove crash-inducing blobCache.enabled: false from K8s install example The blobCache stanza with enabled: false causes a crash loop due to Micronaut eager-loading related beans. The stanza must be omitted entirely when blob cache is not desired. Ref: FD-7221 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/install/kubernetes.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/install/kubernetes.md b/docs/install/kubernetes.md index 7d63ef49a..ab81d836e 100644 --- a/docs/install/kubernetes.md +++ b/docs/install/kubernetes.md @@ -124,9 +124,7 @@ data: # Security scanning configuration - disabled for Wave base installation scan: enabled: false - # Blob caching configuration - disabled for Wave base installation - blobCache: - enabled: false + # Blob caching configuration - disabled by default (omit the blobCache stanza entirely when not in use) # Database connection settings db: uri: "jdbc:postgresql://your-postgres-host:5432/wave" From e5c7a4e0fc65aa7f096aad93157cf52cedf5149a Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:43:11 -0500 Subject: [PATCH 02/12] docs: fix httpclient retry.multiplier default (1.0 -> 1.75) Source: application.yml overrides the @Value annotation default of 2.0 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index e0a15ab22..bd40d54cb 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -103,7 +103,7 @@ Configure the HTTP client with the following options: : Sets the maximum delay for HTTP client retries. `wave.httpclient.retry.multiplier` *(optional)* -: Sets the multiplier for HTTP client retries (default: `1.0`). +: Sets the multiplier for HTTP client retries (default: `1.75`). ## Container build process From 183d23831f067ca35ca6c251f4e1aeb8fc366d9a Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:43:38 -0500 Subject: [PATCH 03/12] docs: fix cleanup property name, remove phantom singularity-image-arm64, update image defaults - wave.build.cleanup -> wave.cleanup.strategy (CleanupConfig.groovy:40) - wave.build.singularity-image-arm64 removed (no longer exists in source) - buildkit image: moby/buildkit -> public.cr.seqera.io/wave/buildkit - singularity image: quay.io v3.11.4 -> public.cr.seqera.io/wave v4.2.1-r4 Source: application.yml, CleanupConfig.groovy Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index bd40d54cb..29fedf0f6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -110,7 +110,7 @@ Configure the HTTP client with the following options: Configure how Wave builds container images and manages associated logs for monitoring, troubleshooting, and delivery with the following options: `wave.build.buildkit-image` *(required)* -: Sets the [Buildkit](https://github.com/moby/buildkit) container image used in the Wave build process (default: `moby/buildkit:v0.25.2-rootless`). +: Sets the [Buildkit](https://github.com/moby/buildkit) container image used in the Wave build process (default: `public.cr.seqera.io/wave/buildkit:v0.25.2-rootless`). `wave.build.cache` *(optional)* : Sets the cache repository for images built by Wave. Supports both container registry paths and S3 bucket paths. @@ -131,7 +131,7 @@ Configure how Wave builds container images and manages associated logs for monit Example: `8` This setting is only used when `wave.build.cache` is configured with an S3 bucket path. -`wave.build.cleanup` *(optional)* +`wave.cleanup.strategy` *(optional)* : Sets the cleanup strategy after the build process. For example, set to `OnSuccess` for cleanup only if a build is successful. @@ -154,10 +154,7 @@ Configure how Wave builds container images and manages associated logs for monit : Sets the Docker container repository for the container images built by Wave. `wave.build.singularity-image` *(optional)* -: Sets the [Singularity](https://quay.io/repository/singularity/singularity?tab=tags) image used in the build process (default: `quay.io/singularity/singularity:v3.11.4-slim`). - -`wave.build.singularity-image-arm64` *(optional)* -: Sets the ARM64 version of the Singularity image for the build process (default: `quay.io/singularity/singularity:v3.11.4-slim-arm64`). +: Sets the [Singularity](https://quay.io/repository/singularity/singularity?tab=tags) image used in the build process (default: `public.cr.seqera.io/wave/singularity:v4.2.1-r4`). `wave.build.status.delay` *(optional)* : Sets the delay between build status checks (default: `5s`). From fc29b4b0c7a2ea65c40937bb7d2f2548dd42379f Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:44:07 -0500 Subject: [PATCH 04/12] docs: remove phantom logs.bucket and logs.prefix properties wave.build.logs.bucket does not exist in source code. wave.build.logs.prefix is auto-computed from wave.build.logs.path. Updated all references to clarify that logs.path and locks.path take full paths (S3 URIs or local). Source: BuildConfig.groovy lines 138, 146, 206 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 10 ++-------- docs/db-migration.md | 4 ++-- docs/migrations/1-21-0.md | 4 ++-- 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 29fedf0f6..b7e085321 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -263,19 +263,13 @@ wave: Configure how Wave stores and delivers build logs from containers and Kubernetes pods, which can be retrieved later or included in build completion emails, with the following options: `wave.build.locks.path` *(required)* -: Sets the path inside `wave.build.logs.bucket` where Wave will store Conda lock files. - -`wave.build.logs.bucket` *(required)* -: Sets the AWS S3 bucket where Wave will store build process logs. +: Sets the full path where Wave will store Conda lock files. Can be an S3 URI (e.g., `s3://my-bucket/wave/locks`) or a local filesystem path. `wave.build.logs.maxLength` *(optional)* : Determines the maximum number of bytes that can be read from a log file. If a log file exceeds this limit, it will be truncated (default: `100000` (100 KB)). `wave.build.logs.path` *(required)* -: Sets the path inside `wave.build.logs.bucket` where Wave will store build logs. - -`wave.build.logs.prefix` *(optional)* -: Sets the prefix for build process log files in the specified S3 bucket. +: Sets the full path where Wave will store build logs. Can be an S3 URI (e.g., `s3://my-bucket/wave/logs`) or a local filesystem path. When using an S3 URI, Wave automatically extracts the key prefix for log file organization. ### Kubernetes container build process diff --git a/docs/db-migration.md b/docs/db-migration.md index c132e5afa..380dfb709 100644 --- a/docs/db-migration.md +++ b/docs/db-migration.md @@ -117,7 +117,7 @@ You will need the following to get started: Add the following properties to your Wave configuration file: `wave.build.logs.path` -: Sets the path inside `wave.build.logs.bucket`, where build logs will be stored. +: Sets the full path where build logs will be stored. Can be an S3 URI (e.g., `s3://my-bucket/wave/logs`) or a local filesystem path. `wave.build.locks.path` -: Sets the path inside `wave.build.logs.bucket`, where conda lock files will be stored. +: Sets the full path where Conda lock files will be stored. Can be an S3 URI (e.g., `s3://my-bucket/wave/locks`) or a local filesystem path. diff --git a/docs/migrations/1-21-0.md b/docs/migrations/1-21-0.md index a06a16452..290379d20 100644 --- a/docs/migrations/1-21-0.md +++ b/docs/migrations/1-21-0.md @@ -14,5 +14,5 @@ To upgrade your existing data from SurrealDB to PostgreSQL: 1. Follow the steps in the [Wave database migration](../db-migration.md) guide. 2. Add the following properties to your Wave configuration file: - - `wave.build.logs.path`: Sets the path inside `wave.build.logs.bucket`, where build logs will be stored. - - `wave.build.locks.path`: Sets the path inside `wave.build.logs.bucket`, where conda lock files will be stored. + - `wave.build.logs.path`: Sets the full path where build logs will be stored (e.g., `s3://my-bucket/wave/logs` or a local path). + - `wave.build.locks.path`: Sets the full path where Conda lock files will be stored (e.g., `s3://my-bucket/wave/locks` or a local path). From a8096479fa91e06a0701648561fb52f8e45d6123 Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:44:20 -0500 Subject: [PATCH 05/12] docs: document node-selector value format (key=value) Source: K8sHelper.groovy line 96 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index b7e085321..77bd8d285 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -282,7 +282,7 @@ Configure Kubernetes-specific settings for Wave, where build and scan processes : Sets the Kubernetes namespace where Wave will run its build pods. `wave.build.k8s.node-selector` *(optional)* -: Sets the node selector for Wave build Kubernetes pods. +: Sets the node selector for Wave build Kubernetes pods. Value must be a map entry in `key=value` format (e.g., `service=wave-build`). `wave.build.k8s.resources.requests.cpu` *(optional)* : Sets the [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) to allocate to Wave build processes. From 21b84f1ab1f3f953ab84d2a9f029be71519101b8 Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:44:50 -0500 Subject: [PATCH 06/12] docs: fix scan.enabled default (false not true) and scanner image scan.enabled defaults to false per ScanEnabled.groovy. Scanner image is wave/scanner, not aquasec/trivy. Source: ScanEnabled.groovy:34, application.yml Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 77bd8d285..9d91c655f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -306,10 +306,10 @@ Configure Kubernetes-specific settings for Wave, where build and scan processes Configure how Wave's vulnerability scanning process uses a [Trivy Docker image](https://hub.docker.com/r/aquasec/trivy) with customizable tags and severity levels with the following options: `wave.scan.enabled` *(optional)* -: Enables vulnerability scanning (default: `true`). +: Enables vulnerability scanning (default: `false`). `wave.scan.image.name`  *(optional)* -: Sets the [Trivy Docker image](https://hub.docker.com/r/aquasec/trivy) to use for container security scanning (default: `aquasec/trivy:0.47.0`). +: Sets the container image used for security scanning (default: `public.cr.seqera.io/wave/scanner:v1-0.65.0-oras-1.3.0`). `wave.scan.reports.path` *(required)* : Sets the path inside the S3 bucket where Wave will store SBOM reports. From 8dbf8ec620b58b2efea1f931d7988cf047fbd538 Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:45:08 -0500 Subject: [PATCH 07/12] docs: fix rate limit defaults to match source code build.anonymous: 25/1d -> 10/1h, build.authenticated: 100/1h -> 10/1m, pull.anonymous: 250/1h -> 100/1h, pull.authenticated: 2000/1m -> 100/1m Source: RateLimiterConfig.groovy lines 44-59 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 9d91c655f..49f63d7d0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -336,16 +336,16 @@ Configure Wave scanning process resource requirements for Kubernetes deployments Configure how Wave controls rate limits for anonymous and authenticated user access with the following options: `rate-limit.build.anonymous` *(required)* -: Sets the rate limit for build requests from anonymous users (default: 25 build requests per day (`25/1d`); max: 25). +: Sets the rate limit for build requests from anonymous users (default: `10/1h`). `rate-limit.build.authenticated` *(required)* -: Sets the rate limit for build requests from authenticated users (default: 100 build requests per hour (`100/1h`); max: 100). +: Sets the rate limit for build requests from authenticated users (default: `10/1m`). `rate-limit.pull.anonymous` *(required)* -: Sets the rate limit for anonymous pull requests from anonymous users (default: 250 pull requests per hour (`250/1h`); max: 250). +: Sets the rate limit for pull requests from anonymous users (default: `100/1h`). `rate-limit.pull.authenticated` *(required)* -: Sets the rate limit for authenticated pull requests from authenticated users (default: 2k pull requests per minute (`2000/1m`); max: 2k). +: Sets the rate limit for pull requests from authenticated users (default: `100/1m`). ## Database and cache From 13f7a527ba3c308fe21d43a7a59e8ca8f38b1c41 Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:45:23 -0500 Subject: [PATCH 08/12] docs: fix urlSignatureDuration property path Property is bound as wave.blobCache.url-signature-duration, not nested under wave.blobCache.cloudflare. Source: BlobCacheConfig.groovy line 102 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 49f63d7d0..5270ed508 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -408,7 +408,7 @@ Configure how Wave caches container blobs to improve client performance and opti `wave.blobCache.cloudflare.secret-key` *(optional)* : Specifies the [Cloudflare secret](https://developers.cloudflare.com/waf/custom-rules/use-cases/configure-token-authentication/) to create the WAF token. -`wave.blobCache.cloudflare.urlSignatureDuration` *(optional)* +`wave.blobCache.url-signature-duration` *(optional)* : Sets the validity of the AWS S3 URL signature (default: `30m`). `wave.blobCache.enabled` *(optional)* From 6f606243931a69682b28c61007df83c361277576 Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:45:42 -0500 Subject: [PATCH 09/12] docs: fix blobCache resource property paths and add limits Property paths were flat (blobCache.requestsCpu) but the actual bindings are nested (blobCache.k8s.resources.requests.cpu). Also adds the undocumented limits.cpu and limits.memory properties. Source: BlobCacheConfig.groovy lines 86-99 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 5270ed508..469e925bc 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -414,11 +414,17 @@ Configure how Wave caches container blobs to improve client performance and opti `wave.blobCache.enabled` *(optional)* : Enables the blob cache (default: `false`). -`wave.blobCache.requestsCpu` *(optional)* -: Sets the amount of [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to the k8s pod used for blob binary transfers. +`wave.blobCache.k8s.resources.requests.cpu` *(optional)* +: Sets the amount of [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) requested for the Kubernetes pod used for blob binary transfers. -`wave.blobCache.requestsMemory` *(optional)* -: Sets the [memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to the k8s pod used for blob binary transfers. +`wave.blobCache.k8s.resources.requests.memory` *(optional)* +: Sets the [memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) requested for the Kubernetes pod used for blob binary transfers. + +`wave.blobCache.k8s.resources.limits.cpu` *(optional)* +: Sets the CPU resource [limit](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) for the Kubernetes pod used for blob binary transfers. + +`wave.blobCache.k8s.resources.limits.memory` *(optional)* +: Sets the memory resource [limit](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) for the Kubernetes pod used for blob binary transfers. `wave.blobCache.s5cmdImage` *(optional)* : Sets the container image that supplies the [s5cmd tool](https://github.com/peak/s5cmd) to upload blob binaries to the S3 bucket (default: `public.cr.seqera.io/wave/s5cmd:v2.2.2`). From f74319531526f65256109d6a22111aa99110b7f3 Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:46:04 -0500 Subject: [PATCH 10/12] docs: fix blobCache default values to match source code status.delay: 5s -> 2s, status.duration: 5d -> 1h, timeout: 5m -> 10m Source: BlobCacheConfig.groovy lines 43, 54, 57 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 469e925bc..5e736d7c0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -435,10 +435,10 @@ Configure how Wave caches container blobs to improve client performance and opti Options include: `aws-presigned-url` and `cloudflare-waf-token`. `wave.blobCache.status.delay` *(optional)* -: Sets the time delay in checking the status of the transfer of the blob binary from the repository to the cache (default: `5s`). +: Sets the time delay in checking the status of the transfer of the blob binary from the repository to the cache (default: `2s`). `wave.blobCache.status.duration` *(optional)* -: Sets the time for which Wave will store the blob binary in cache (default: `5d`). +: Sets the duration for which blob transfer status records are retained in cache (default: `1h`). `wave.blobCache.storage.accessKey` *(optional)* : Specifies the access key (part of credentials) to access the resources of the service used for caching. @@ -457,7 +457,7 @@ Configure how Wave caches container blobs to improve client performance and opti : Specifies the secret key (part of credentials) to access the resources of the service used for caching. `wave.blobCache.timeout` *(optional)* -: Sets the timeout for blob binary transfer, after which Wave will throw a `TransferTimeoutException` exception (default: `5m`). +: Sets the timeout for blob binary transfer, after which Wave will throw a `TransferTimeoutException` exception (default: `10m`). ## Email configuration From ad9ce34543d37fc2d719dd631f715b12b203e15b Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:46:23 -0500 Subject: [PATCH 11/12] docs: mark blobCache storage accessKey/secretKey as required These credentials are unconditionally passed to AwsBasicCredentials.create() in S3ClientFactory, causing NPE if null. IAM-based auth is not yet supported for blob cache. Ref: FD-7221 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configuration.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 5e736d7c0..3d4e105e7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -440,7 +440,7 @@ Configure how Wave caches container blobs to improve client performance and opti `wave.blobCache.status.duration` *(optional)* : Sets the duration for which blob transfer status records are retained in cache (default: `1h`). -`wave.blobCache.storage.accessKey` *(optional)* +`wave.blobCache.storage.accessKey` *(required)* : Specifies the access key (part of credentials) to access the resources of the service used for caching. `wave.blobCache.storage.bucket` *(required)* @@ -453,9 +453,13 @@ Configure how Wave caches container blobs to improve client performance and opti `wave.blobCache.storage.region` *(required)* : Sets the AWS region where the bucket is created. -`wave.blobCache.storage.secretKey` *(optional)* +`wave.blobCache.storage.secretKey` *(required)* : Specifies the secret key (part of credentials) to access the resources of the service used for caching. +:::note +Static credentials (`accessKey` and `secretKey`) are currently required for blob cache storage access. IAM-based authentication (such as EKS Pod Identity or IRSA) is not yet supported for the blob cache feature. This differs from the S3 build cache, which does support IAM-based authentication. +::: + `wave.blobCache.timeout` *(optional)* : Sets the timeout for blob binary transfer, after which Wave will throw a `TransferTimeoutException` exception (default: `10m`). From 43c8b06c8c7065aac3d5e85db8c80319f02ca34f Mon Sep 17 00:00:00 2001 From: Rob Syme Date: Fri, 6 Feb 2026 16:46:43 -0500 Subject: [PATCH 12/12] docs: fix build cache config from nested object to flat string wave.build.cache is bound as a simple String in BuildConfig.groovy, not a nested object with enabled/repository sub-properties. Co-Authored-By: Claude Opus 4.6 Signed-off-by: Rob Syme --- docs/configure-wave.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/configure-wave.md b/docs/configure-wave.md index 5e0f5e95b..1cd6c71bd 100644 --- a/docs/configure-wave.md +++ b/docs/configure-wave.md @@ -157,9 +157,7 @@ Configure ECR cache repository in your Wave configuration: wave: build: enabled: true - cache: - enabled: true - repository: "123456789012.dkr.ecr.us-east-1.amazonaws.com/wave-cache" + cache: "123456789012.dkr.ecr.us-east-1.amazonaws.com/wave-cache" ``` #### IAM permissions @@ -235,9 +233,8 @@ Using ECR as a cache repository provides: #### Configuration Options -| Setting | Description | Example | -| ------------------ | -------------------- | --------------------------------------------------------- | -| `cache.enabled` | Enable build caching | `true` | -| `cache.repository` | ECR repository URL | `123456789012.dkr.ecr.us-east-1.amazonaws.com/wave-cache` | +| Setting | Description | Example | +| -------------------------- | --------------------------------- | --------------------------------------------------------- | +| `wave.build.cache` | Cache repository URL or S3 path | `123456789012.dkr.ecr.us-east-1.amazonaws.com/wave-cache` | **Note:** ECR cache requires Wave build service to be enabled and is only available in AWS deployments with proper ECR access configured.