Merge branch 'master' into build-template

Author: munishchouhan

VERSION

@@ -1 +1 @@
-1.28.0
+1.30.0

build.gradle

@@ -32,11 +32,11 @@ dependencies {
     compileOnly 'io.micronaut:micronaut-inject-groovy'
     compileOnly 'io.micronaut:micronaut-http-validation'
     implementation 'jakarta.persistence:jakarta.persistence-api:3.0.0'
-    implementation 'io.seqera:lib-cache-tiered-redis:1.0.0'
+    implementation 'io.seqera:lib-cache-tiered-redis:1.1.0'
     implementation 'io.seqera:lib-lang:1.1.0'
-    implementation 'io.seqera:lib-serde:1.1.0'
-    implementation 'io.seqera:lib-serde-moshi:1.0.0'
-    implementation 'io.seqera:lib-mail:1.3.0'
+    implementation 'io.seqera:lib-serde:1.2.0'
+    implementation 'io.seqera:lib-serde-moshi:1.1.0'
+    implementation 'io.seqera:lib-mail:1.3.1'
     implementation 'io.seqera:lib-pool:1.0.0'
     implementation 'io.seqera:lib-retry:2.0.0'
     implementation 'io.seqera:lib-random:1.0.0'
@@ -101,7 +101,7 @@ dependencies {
     testImplementation 'org.testcontainers:testcontainers'
     testImplementation 'org.testcontainers:postgresql'
     testRuntimeOnly 'com.h2database:h2'
-    testImplementation testFixtures('io.seqera:lib-fixtures-redis:1.0.0')
+    testImplementation testFixtures('io.seqera:lib-fixtures-redis:1.1.0')
 
     // rate limit
     implementation 'com.coveo:spillway:3.0.0'

changelog.txt

@@ -1,4 +1,23 @@
 # Wave changelog
+1.30.0 - 27 Nov 2025
+- Add labels in ConfigSpec (#934) [67ac6c3dc]
+- Use Seqera-hosted buildkit image (#938) [c0c0b6465]
+- Add configurable singularity init container image (#937) [5c0fd3fce]
+- Fix YAML indentation in configure-wave.md (#936) [c09eba7ca]
+- Fix scan and mirror enabled flag bug (#935) [dc23d7bbe]
+- docs: Fix typos in Wave Kubernetes install (#930) [d3478f336]
+
+1.29.1 - 19 Nov 2025
+- Fix scan requirement on createScanStorageOpts [33463ebd2]
+- Add node selectors in scan, mirror and transfer jobs (#905) [47a7c5ac4]
+
+1.29.0 - 13 Nov 2024
+- Add S3 cache support for BuildKit (#927) [8dac665a0]
+- Update buildkit to 0.25.2 (#928) [68a6a2e4a]
+- Add docs for CRAN package support (#925) [482fc1d3c]
+- Fix product name capitalization in documentation (#883) [f03025535]
+- Update local dev config [059b2e4e]
+
 1.28.0 - 4 Nov 2024
 - Add CRAN package support for Wave container builds (#874) [81b4e6681]
 

docs/configuration.md

@@ -110,10 +110,26 @@ 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.13.2-rootless`).
-
-`wave.build.cache` *(required)*
-: Sets the container repository used to cache layers of images built by Wave.
+: Sets the [Buildkit](https://github.com/moby/buildkit) container image used in the Wave build process (default: `moby/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.
+  Examples:
+  - Container registry: `registry.example.com/wave/cache`
+  - S3 bucket: `s3://my-bucket/wave/cache`
+
+`wave.build.cache-bucket-region` *(optional)*
+: Specifies the AWS region for the S3 cache bucket when using an S3 path in `wave.build.cache`.
+  If not specified, Wave uses the `AWS_REGION` or `AWS_DEFAULT_REGION` environment variable.
+  Example: `us-east-1`
+  This setting is only used when `wave.build.cache` is configured with an S3 bucket path.
+
+`wave.build.cache-bucket-upload-parallelism` *(optional)*
+: Controls the number of layers uploaded to S3 in parallel during cache export.
+  Each individual layer is uploaded with 5 threads using the AWS SDK Upload Manager.
+  If not specified, BuildKit uses its default parallelism behavior.
+  Example: `8`
+  This setting is only used when `wave.build.cache` is configured with an S3 bucket path.
 
 `wave.build.cleanup` *(optional)*
 : Sets the cleanup strategy after the build process.
@@ -160,6 +176,91 @@ Configure how Wave builds container images and manages associated logs for monit
 : Sets the path to the directory used by Wave to store artifacts such as Containerfiles, Trivy cache for scan, Buildkit context, and authentication configuration files.
   For example, `/efs/wave/build`.
 
+### S3 cache authentication
+
+When using S3 as the BuildKit cache backend (by configuring `wave.build.cache` with an S3 bucket path), Wave relies on AWS native authentication mechanisms rather than static credentials in configuration files.
+
+#### Kubernetes deployments
+
+S3 cache uses **IAM Roles for Service Accounts (IRSA)** for secure, credential-free authentication.
+
+Configure your Kubernetes ServiceAccount with an IAM role annotation:
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: wave-build-sa
+  namespace: wave-build
+  annotations:
+    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/WaveBuildRole
+```
+
+The IAM role must have permissions to access the S3 cache bucket:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:PutObject",
+        "s3:GetObject",
+        "s3:DeleteObject",
+        "s3:ListBucket",
+        "s3:AbortMultipartUpload",
+        "s3:ListMultipartUploadParts",
+        "s3:ListBucketMultipartUploads"
+      ],
+      "Resource": [
+        "arn:aws:s3:::my-bucket/wave/cache",
+        "arn:aws:s3:::my-bucket/wave/cache/*"
+      ]
+    }
+  ]
+}
+```
+
+Update your Wave deployment to use the annotated ServiceAccount:
+
+```yaml
+spec:
+  template:
+    spec:
+      serviceAccountName: wave-build-sa
+```
+
+#### Docker deployments
+
+For Docker-based builds, use **EC2 Instance Profile** for automatic credential management.
+
+Attach an IAM role to the EC2 instance running Docker with the S3 permissions shown above. BuildKit automatically uses the instance metadata service to obtain temporary credentials.
+
+No additional configuration is required. The AWS SDK in BuildKit automatically discovers and uses the instance profile credentials.
+
+:::note
+For development and testing purposes only, you can provide AWS credentials via environment variables:
+
+```bash
+export AWS_ACCESS_KEY_ID=your_access_key
+export AWS_SECRET_ACCESS_KEY=your_secret_key
+export AWS_REGION=us-east-1
+```
+
+**Warning:** This approach is not recommended for production environments as it requires managing static credentials. Always use EC2 Instance Profile for production Docker deployments.
+:::
+
+#### Configuration example
+
+```yaml
+wave:
+  build:
+    cache: "s3://wave-cache-bucket/buildkit"
+    cache-bucket-region: "us-east-1"  # Optional if AWS_REGION is set
+    cache-bucket-upload-parallelism: 8  # Optional, controls parallel S3 uploads
+```
+
 ### Build process logs
 
 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:

docs/configure-wave.md

@@ -29,18 +29,18 @@ MICRONAUT_ENVIRONMENTS: "postgres,redis,lite,mail"
 
 ```yaml
 mail:
-    from: "[email protected]"
-    smtp:
-        host: "smtp.your-provider.com"
-        port: "587"
-        user: "your-smtp-username"
-        password: "your-smtp-password"
-        auth: true
-        starttls:
-            enable: true
-            required: true
-        ssl:
-            protocols: "TLSv1.2"
+  from: "[email protected]"
+  smtp:
+    host: "smtp.your-provider.com"
+    port: "587"
+    user: "your-smtp-username"
+    password: "your-smtp-password"
+    auth: true
+    starttls:
+      enable: true
+      required: true
+    ssl:
+      protocols: "TLSv1.2"
 ```
 
 #### Configuration Options
@@ -82,7 +82,7 @@ MICRONAUT_ENVIRONMENTS: "postgres,redis,lite,mail,aws-ses"
 
 ```yaml
 mail:
-    from: "[email protected]"
+  from: "[email protected]"
 ```
 
 #### IAM permissions
@@ -135,7 +135,8 @@ Wave can perform security scanning on container builds. This feature requires th
 wave:
   build:
     enabled: true
-    scan: true
+  scan:
+    enabled: true
 ```
 
 ## ECR cache repository
@@ -154,11 +155,11 @@ Configure ECR cache repository in your Wave configuration:
 
 ```yaml
 wave:
-    build:
-        enabled: true
-        cache:
-            enabled: true
-            repository: "123456789012.dkr.ecr.us-east-1.amazonaws.com/wave-cache"
+  build:
+    enabled: true
+    cache:
+      enabled: true
+      repository: "123456789012.dkr.ecr.us-east-1.amazonaws.com/wave-cache"
 ```
 
 #### IAM permissions

docs/install/kubernetes.md

@@ -140,7 +140,7 @@ data:
     # Platform integration (optional)
     tower:
       endpoint:
-        url: "https://your-platform-server.com"
+        url: "https://your-platform-server.com/api"
 
     # Micronaut framework configuration
     micronaut:

docs/wave-lite.md

@@ -10,7 +10,7 @@ Wave Lite enables the use of [Fusion file system](https://docs.seqera.io/fusion)
 ## Installation
 
 - [Docker Compose](./install/docker-compose.md)
-- [Kubernetes](./install/docker-compose.md)
+- [Kubernetes](./install/kubernetes.md)
 
 :::info
 Docker Compose installations only support Wave in Lite mode. Wave's full build capabilities require specific integrations with Kubernetes and AWS EFS Storage, making EKS and AWS a hard dependency for fully-featured deployments. After you have successfully deployed Wave Lite in Kubernetes, see [Configure Wave Build](./install/configure-wave-build.md) to extend your installation to support build capabilities. 

gradle.properties

@@ -17,4 +17,4 @@
 #
 
 micronautVersion=4.9.4
-micronautEnvs=dev,mail,aws-ses
+micronautEnvs=local,mail,aws-ses

src/main/groovy/io/seqera/wave/auth/RegistryLookupCache.groovy

@@ -26,8 +26,8 @@ import groovy.transform.CompileStatic
 import groovy.util.logging.Slf4j
 import io.micronaut.context.annotation.Value
 import io.micronaut.core.annotation.Nullable
+import io.seqera.serde.Encodable
 import io.seqera.serde.moshi.MoshiEncodeStrategy
-import io.seqera.serde.moshi.MoshiSerializable
 import io.seqera.cache.tiered.AbstractTieredCache
 import io.seqera.cache.tiered.L2TieredCache
 import jakarta.inject.Singleton
@@ -75,7 +75,7 @@ class RegistryLookupCache extends AbstractTieredCache<String, RegistryAuth> {
     }
 
     static JsonAdapter.Factory factory() {
-        PolymorphicJsonAdapterFactory.of(MoshiSerializable.class, "@type")
+        PolymorphicJsonAdapterFactory.of(Encodable.class, "@type")
                 .withSubtype(AbstractTieredCache.Entry.class, AbstractTieredCache.Entry.name)
                 .withSubtype(RegistryAuth.class, RegistryAuth.name)
     }

src/main/groovy/io/seqera/wave/configuration/BuildConfig.groovy

@@ -46,12 +46,33 @@ class BuildConfig {
     @Value('${wave.build.singularity-image}')
     String singularityImage
 
+    @Value('${wave.build.singularity-image-init:`public.cr.seqera.io/wave/busybox:latest`}')
+    String singularityImageInit
+
     @Value('${wave.build.repo}')
      String defaultBuildRepository
 
+    @Nullable
     @Value('${wave.build.cache}')
     String defaultCacheRepository
 
+    /**
+     * AWS region for the S3 cache bucket specified in {@link #defaultCacheRepository}.
+     * Only used when {@link #defaultCacheRepository} is an S3 bucket path.
+     */
+    @Nullable
+    @Value('${wave.build.cache-bucket-region}')
+    String cacheBucketRegion
+
+    /**
+     * Number of layers to upload to S3 in parallel during cache export.
+     * Each individual layer is uploaded with 5 threads using the AWS SDK Upload Manager.
+     * Only used when {@link #defaultCacheRepository} is an S3 bucket path.
+     */
+    @Nullable
+    @Value('${wave.build.cache-bucket-upload-parallelism}')
+    Integer cacheBucketUploadParallelism
+
     @Nullable
     @Value('${wave.build.public-repo}')
     String defaultPublicRepository
@@ -138,6 +159,8 @@ class BuildConfig {
                 "singularity-image=${singularityImage}; " +
                 "default-build-repository=${defaultBuildRepository}; " +
                 "default-cache-repository=${defaultCacheRepository}; " +
+                "cache-bucket-region=${cacheBucketRegion}; " +
+                "cache-bucket-upload-parallelism=${cacheBucketUploadParallelism}; " +
                 "default-public-repository=${defaultPublicRepository}; " +
                 "build-workspace=${buildWorkspace}; " +
                 "build-timeout=${defaultTimeout}; " +
@@ -156,6 +179,10 @@ class BuildConfig {
         if( trustedTimeout < defaultTimeout ) {
             log.warn "Trusted build timeout should be longer than default timeout - check configuration setting 'wave.build.trusted-timeout'"
         }
+        // validate at least one cache location is configured
+        if( !defaultCacheRepository ) {
+            log.warn "No cache location configured - 'wave.build.cache' should be set to a container registry or S3 bucket path"
+        }
     }
 
     Duration buildMaxDuration(SubmitContainerTokenRequest request) {
@@ -199,4 +226,26 @@ class BuildConfig {
         final store = BucketTokenizer.from(locksPath)
         return store.scheme ? store.getKey() : null
     }
+
+    /**
+     * Get the AWS region for S3 cache bucket.
+     *
+     * @return The AWS region to use for S3 cache operations, or {@code null} if not configured.
+     *         When {@code null}, BuildKit will use the AWS SDK default region resolution chain
+     *         (environment variables, EC2 instance metadata, etc.)
+     */
+    String getCacheBucketRegion() {
+        return cacheBucketRegion
+    }
+
+    /**
+     * Check if the given path is an S3 bucket path (object storage).
+     * This is used to distinguish between container registry paths and object storage paths.
+     *
+     * @param path The path to check
+     * @return {@code true} if the path starts with {@code s3://}, {@code false} otherwise
+     */
+    static boolean isBucketPath(String path) {
+        return path?.startsWith('s3://')
+    }
 }