From 1bd009c28366856b0d48b0918ebb57c16b4cb495 Mon Sep 17 00:00:00 2001 From: munishchouhan Date: Fri, 27 Mar 2026 20:10:26 +0100 Subject: [PATCH 1/2] added missing configuration.md Signed-off-by: munishchouhan --- docs/configuration.md | 104 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 8113ced5a..5f4b0b3e6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -30,6 +30,10 @@ Configure general Wave application settings, such as application name, port, ano : Enables anonymous access to the Wave server (default: `false`). : Modify this option based on your security requirements. +`wave.denyHosts` *(optional)* +: A list of hostname patterns to deny. Requests targeting these hosts are rejected. + Example patterns: `ngrok.app`, `ngrok-free.app`, `//localhost`. + `wave.denyPaths` *(optional)* : Filter out API calls for specific artifacts, like manifests, that don't exist. @@ -338,8 +342,25 @@ Configure Kubernetes-specific settings for Wave, where build and scan processes `wave.build.k8s.namespace` *(required)* : Sets the Kubernetes namespace where Wave will run its build pods. +`wave.build.k8s.dns.policy` *(optional)* +: Sets the DNS policy for Wave build Kubernetes pods (e.g., `None`, `Default`, `ClusterFirst`). + When set to `None`, you must also configure `wave.build.k8s.dns.servers`. + +`wave.build.k8s.dns.servers` *(optional)* +: A list of custom DNS server IP addresses for Wave build pods. Used when `wave.build.k8s.dns.policy` is set to `None`. + Example: `['1.1.1.1', '8.8.8.8']`. + `wave.build.k8s.node-selector` *(optional)* -: Sets the node selector for Wave build Kubernetes pods. Value must be a map entry in `key=value` format (e.g., `service=wave-build`). +: Sets the node selector for Wave build Kubernetes pods. Value is a map where keys are platform identifiers + and values are Kubernetes node label selectors in `label=value` format. + Supported platform keys: `linux/amd64`, `linux/arm64`, `noarch`. + Example: + ```yaml + wave.build.k8s.nodeSelector: + linux/amd64: 'seqera.io/wave-build-amd64=true' + linux/arm64: 'seqera.io/wave-build-arm64=true' + noarch: 'seqera.io/wave-build=true' + ``` `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. @@ -376,6 +397,9 @@ Configure how Wave's vulnerability scanning process uses a [Trivy Docker image]( : Sets the [severity levels](https://aquasecurity.github.io/trivy/v0.22.0/vulnerability/examples/filter/) to report in vulnerability scanning. : Options include: `MEDIUM`,`HIGH`, and `CRITICAL`. +`wave.scan.status.duration` *(optional)* +: Sets the duration for which scan status records are retained (default: `5d`). + ### Kubernetes Wave scan process Configure Wave scanning process resource requirements for Kubernetes deployments with the following options: @@ -388,6 +412,35 @@ Configure Wave scanning process resource requirements for Kubernetes deployments : Sets the [memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave scan processes. For example, set to `3Gi` (3 Gigabytes) or `2000Mi` (2000 Megabytes). +## Container mirror process + +Configure Kubernetes resource requirements for Wave's container mirroring operations with the following options: + +`wave.mirror.k8s.resources.requests.cpu` *(optional)* +: Sets the CPU resources requested for mirror Kubernetes pods. + +`wave.mirror.k8s.resources.requests.memory` *(optional)* +: Sets the memory resources requested for mirror Kubernetes pods. + +`wave.mirror.k8s.resources.limits.cpu` *(optional)* +: Sets the CPU resource limit for mirror Kubernetes pods. + +`wave.mirror.k8s.resources.limits.memory` *(optional)* +: Sets the memory resource limit for mirror Kubernetes pods. + +## Proxy cache + +Configure Wave's in-memory proxy cache for registry responses with the following options: + +`wave.proxy-cache.enabled` *(optional)* +: Enables the proxy cache (default: `false`). + +`wave.proxy-cache.duration` *(optional)* +: Sets the cache entry expiration duration (default: `120s`). + +`wave.proxy-cache.max-size` *(optional)* +: Sets the maximum number of entries in the proxy cache (default: `10000`). + ## Security ### Client IP address resolution @@ -418,6 +471,9 @@ Configure how Wave controls rate limits for anonymous and authenticated user acc `rate-limit.pull.authenticated` *(required)* : Sets the rate limit for pull requests from authenticated users (default: `100/1m`). +`rate-limit.timeout-errors.max-rate` *(optional)* +: Sets the maximum rate of timeout errors before Wave begins rejecting requests (default: `10/1m`). + ## Database and cache Wave uses external database and caching services to store application data and improve performance. @@ -557,3 +613,49 @@ Configure user credentials for accessing authenticated Wave APIs and services wi : Sets a list of credentials to access authenticated Wave APIs like metrics APIs. Format of the credential list: `- :` +## License server + +Configure the connection to the Seqera license management server: + +`license.server.url` *(optional)* +: Specifies the URL of the Seqera license management server. + Required when license validation is enabled. + Example: `https://licenses.seqera.io`. + +## Advanced + +These settings control internal operational behavior. The defaults are suitable for most deployments, but may need tuning at scale. + +### Job manager + +`wave.job-manager.poll-interval` *(optional)* +: Sets the polling interval for checking job status (default: `1s`). + +`wave.job-manager.scheduler-interval` *(optional)* +: Sets the interval for the job scheduler to process queued jobs (default: `1s`). + +### Message stream + +`wave.message-stream.claim-timeout` *(optional)* +: Sets the timeout for claiming messages from the Redis stream (default: `5s`). + +`wave.message-stream.consume-warn-timeout` *(optional)* +: Sets the threshold duration after which a slow message consumer triggers a warning (default: `4s`). + +### Thread monitor + +`wave.thread-monitor.dump-file` *(optional)* +: Sets the file path where thread dumps are written when the thread count exceeds the threshold. + Example: `/efs/wave/dump/threads-dump.txt`. + +`wave.thread-monitor.dump-threshold` *(optional)* +: Sets the thread count threshold that triggers a thread dump (default: `200`). + +`wave.thread-monitor.interval` *(optional)* +: Sets the interval for the thread monitor check (default: `5m`). + +### Trace + +`wave.trace.slow-endpoint.duration` *(optional)* +: Sets the threshold duration for logging slow HTTP endpoints (default: `1m`). + From 88c58bb4aef00e989023a7858dd0a41ee4ae0a4a Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Thu, 16 Apr 2026 17:11:57 +1200 Subject: [PATCH 2/2] Update formatting and style --- docs/configuration.md | 382 +++++++++++++++++------------------------ docs/configure-wave.md | 99 +++++++++++ 2 files changed, 253 insertions(+), 228 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 5f4b0b3e6..2926e7691 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -23,26 +23,26 @@ You can configure Wave using either the `config.yml` file or environment variabl Configure general Wave application settings, such as application name, port, anonymous access permissions, and platform URLs with the following options: `tower.endpoint.url` *(optional)* -: Specifies the URL pointing to the Seqera platform API service (default: [`https://api.cloud.seqera.io`](https://api.cloud.seqera.io)). +: URL of the Seqera platform API service (default: [`https://api.cloud.seqera.io`](https://api.cloud.seqera.io)). Can be set using the `${TOWER_ENDPOINT_URL}` environment variable. `wave.allowAnonymous` *(required)* -: Enables anonymous access to the Wave server (default: `false`). -: Modify this option based on your security requirements. +: When `true`, anonymous users can access the Wave server (default: `false`). + Modify this option based on your security requirements. `wave.denyHosts` *(optional)* -: A list of hostname patterns to deny. Requests targeting these hosts are rejected. +: Hostname patterns to deny. Requests targeting these hosts are rejected. Example patterns: `ngrok.app`, `ngrok-free.app`, `//localhost`. `wave.denyPaths` *(optional)* -: Filter out API calls for specific artifacts, like manifests, that don't exist. +: API path patterns to filter out. Requests for matching artifacts, such as non-existent manifests, are rejected. `wave.server.url` *(required)* -: Specifies the URL for the Wave server. +: URL of the Wave server. Can be set using the `${WAVE_SERVER_URL}` environment variable. `wave.tokens.cache.duration` *(optional)* -: Sets the duration for cached tokens generated by Wave (default: `36h`). +: Cache duration for tokens generated by Wave (default: `36h`). ## Container registry @@ -59,32 +59,32 @@ These configurations enable Wave authentication for repositories used to push or Configure container registry authentication with the following options: `wave.registries..password` *(optional)* -: Specifies the AWS ECR password for authentication. +: AWS ECR password for authentication. For example: `195996028523.dkr.ecr.eu-west-1.amazonaws.com`. Can be set using the `${AWS_SECRET_ACCESS_KEY}` environment variable. `wave.registries..username` *(optional)* -: Specifies the AWS ECR (Elastic Container Registry) username for authentication. +: AWS ECR (Elastic Container Registry) username for authentication. For example, `195996028523.dkr.ecr.eu-west-1.amazonaws.com`. Can be set using the `${AWS_ACCESS_KEY_ID}` environment variable. `wave.registries.default` *(optional)* -: Sets the default container registry for Wave (default: `docker.io`). +: Default container registry for Wave (default: `docker.io`). `wave.registries.docker.io.password` *(optional)* -: Specifies the Docker Hub password or PAT (Personal Access Token) for authentication. +: Docker Hub password or PAT (Personal Access Token) for authentication. Can be set using the `${DOCKER_PAT}` environment variable. `wave.registries.docker.io.username` *(optional)* -: Specifies the Docker Hub username for authentication. +: Docker Hub username for authentication. Can be set using the `${DOCKER_USER}` environment variable. `wave.registries.quay.io.password` *(optional)* -: Specifies the Quay.io password or PAT for authentication. +: Quay.io password or PAT for authentication. Can be set using the `${QUAY_PAT}` environment variable. `wave.registries.quay.io.username` *(optional)* -: Specifies the Quay.io username for authentication. +: Quay.io username for authentication. Can be set using the `${QUAY_USER}` environment variable. ## AWS cross-account role chaining @@ -100,18 +100,22 @@ This enables a two-hop role chaining pattern: Configure jump role chaining with the following options: `wave.aws.jump-role-arn` *(optional)* -: Specifies the ARN of the intermediate IAM role that Wave assumes before assuming the target role from the Seqera Platform. +: ARN of the intermediate IAM role that Wave assumes before assuming the target role from the Seqera Platform. Can be set using the `WAVE_AWS_JUMP_ROLE_ARN` environment variable. - Example: `arn:aws:iam::123456789012:role/wave-jump-role` + For example, `arn:aws:iam::123456789012:role/wave-jump-role`. `wave.aws.jump-external-id` *(optional)* -: Specifies the external ID used when assuming the jump role, for confused deputy protection. +: External ID used when assuming the jump role, for confused deputy protection. Can be set using the `WAVE_AWS_JUMP_EXTERNAL_ID` environment variable. +
+ :::note When the jump role is not configured, Wave assumes target roles directly using its default credentials (the previous behavior). The jump role is only used for role-based ECR authentication, not for static AWS credential flows. ::: +
+ ### STS retry configuration Configure retry behavior for AWS STS AssumeRole calls: @@ -146,65 +150,70 @@ Configure caching for jump role temporary credentials to avoid redundant STS cal Configure the HTTP client with the following options: `wave.httpclient.connectTimeout` *(optional)* -: Sets the connection timeout for the HTTP client (default: `20s`). +: Connection timeout for the HTTP client (default: `20s`). `wave.httpclient.retry.attempts` *(optional)* -: Sets the number of HTTP client retry attempts (default: `5`). +: Number of HTTP client retry attempts (default: `5`). `wave.httpclient.retry.delay` *(optional)* -: Sets the delay for HTTP client retries (default: `1s`). +: Delay between HTTP client retries (default: `1s`). `wave.httpclient.retry.jitter` *(optional)* -: Sets the jitter for HTTP client retries (default: `0.25`). +: Jitter factor for HTTP client retries (default: `0.25`). `wave.httpclient.retry.maxDelay` *(optional)* -: Sets the maximum delay for HTTP client retries. +: Maximum delay between HTTP client retries. `wave.httpclient.retry.multiplier` *(optional)* -: Sets the multiplier for HTTP client retries (default: `1.75`). +: Multiplier for HTTP client retries (default: `1.75`). ## Container build process 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: `public.cr.seqera.io/wave/buildkit:v0.25.2-rootless`). +: [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. - Examples: +: Cache repository for images built by Wave. Supports both container registry paths and S3 bucket paths. + For Example: + +
+ - 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`. +: 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` + For 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. +: 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` + For example, `8`. This setting is only used when `wave.build.cache` is configured with an S3 bucket path. `wave.cleanup.strategy` *(optional)* -: Sets the cleanup strategy after the build process. +: Cleanup strategy after the build process. For example, set to `OnSuccess` for cleanup only if a build is successful. `wave.build.compression` *(optional)* -: Sets which type of compression will be applied to cache layers (default: `gzip`). +: Compression type applied to cache layers (default: `gzip`). Options include: `uncompressed`,`estargz`, and `zstd`. `wave.build.force-compression` *(optional)* -: Enables forced compression for each cache layers produced by the build process (default: `false`). +: When `true`, forces compression for each cache layer produced by the build process (default: `false`). `wave.build.oci-mediatypes` *(optional)* -: Enables OCI media types in exported manifests (default: `true`). +: When `true`, includes OCI media types in exported manifests (default: `true`). `wave.build.public-repo` *(optional)* -: Specifies a public repository for container images built by Wave. It is used as the target repository +: Public repository for container images built by Wave. It is used as the target repository when a freeze mode build is requested with packages (Conda/pip) via the v2 API and no custom `buildRepository` is provided in the request. When set, images stored in this repository default to the `imageSuffix` naming strategy. The registry hostname for this repository must be unique (i.e., not shared with `wave.build.repo` or `wave.build.cache-repo`) @@ -212,149 +221,71 @@ Configure how Wave builds container images and manages associated logs for monit When not configured, you must specify a `buildRepository` in the request for freeze mode operations with packages. `wave.build.repo` *(required)* -: Sets the Docker container repository for the container images built by Wave. +: Docker container repository for 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: `public.cr.seqera.io/wave/singularity:v4.2.1-r4`). +: [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`). +: Delay between build status checks (default: `5s`). `wave.build.status.duration` *(optional)* -: Sets the duration for build status checks (default: `1d`). +: Duration for build status checks (default: `1d`). `wave.build.timeout` *(optional)* -: Sets the maximum duration for the build process (default: `5m`). +: Maximum duration for the build process (default: `5m`). `wave.build.trusted-timeout` *(optional)* -: Sets the maximum duration for the build process when you are authenticated and freeze mode is enabled (default: `10m`). +: Maximum duration for the build process when you are authenticated and freeze mode is enabled (default: `10m`). If set to less than `wave.build.timeout`, the longer `wave.build.timeout` value is used. `wave.build.workspace` *(required)* -: 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. +: 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. +:::tip +For S3 cache authentication setup (IAM roles, service accounts, and deployment examples), see [S3 cache authentication](./configure-wave.md#s3-cache-authentication). ::: -#### 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: `wave.build.locks.path` *(required)* -: 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. +: Path where Wave stores 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)). +: Maximum number of bytes read from a log file. If a log file exceeds this limit, it is truncated (default: `100000` (100 KB)). `wave.build.logs.path` *(required)* -: 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. +: Path where Wave stores 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 Configure Kubernetes-specific settings for Wave, where build and scan processes share most configurations except for CPU and memory requirements, with the following options: `wave.build.k8s.labels` *(optional)* -: Sets labels on Wave build Kubernetes pods. +: Labels for Wave build Kubernetes pods. `wave.build.k8s.namespace` *(required)* -: Sets the Kubernetes namespace where Wave will run its build pods. +: Kubernetes namespace where Wave runs build pods. `wave.build.k8s.dns.policy` *(optional)* -: Sets the DNS policy for Wave build Kubernetes pods (e.g., `None`, `Default`, `ClusterFirst`). +: DNS policy for Wave build Kubernetes pods. For example, `None`, `Default`, `ClusterFirst`. When set to `None`, you must also configure `wave.build.k8s.dns.servers`. `wave.build.k8s.dns.servers` *(optional)* -: A list of custom DNS server IP addresses for Wave build pods. Used when `wave.build.k8s.dns.policy` is set to `None`. - Example: `['1.1.1.1', '8.8.8.8']`. +: Custom DNS server IP addresses for Wave build pods. Used when `wave.build.k8s.dns.policy` is set to `None`. + For example, `['1.1.1.1', '8.8.8.8']`. `wave.build.k8s.node-selector` *(optional)* -: Sets the node selector for Wave build Kubernetes pods. Value is a map where keys are platform identifiers +: Node selector for Wave build Kubernetes pods. Value is a map where keys are platform identifiers and values are Kubernetes node label selectors in `label=value` format. Supported platform keys: `linux/amd64`, `linux/arm64`, `noarch`. - Example: + For example: + +
+ ```yaml wave.build.k8s.nodeSelector: linux/amd64: 'seqera.io/wave-build-amd64=true' @@ -362,54 +293,56 @@ Configure Kubernetes-specific settings for Wave, where build and scan processes noarch: 'seqera.io/wave-build=true' ``` +
+ `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. +: [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave build processes. For example, set to `2` (2 CPU cores) or `1500Mi` (1.5 CPU cores). `wave.build.k8s.resources.requests.memory` *(optional)* -: Sets the [memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) to allocate to Wave build processes. +: [Memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave build processes. For example, set to `3Gi` (3 Gigabytes) or `2000Mi` (2000 Megabytes). `wave.build.k8s.service-account` *(optional)* -: Specifies the Kubernetes service account name to be used by Wave build pods. +: Kubernetes service account name for Wave build pods. `wave.build.k8s.storage.claimName` *(optional)* -: Sets the volume claim name for the Wave build Kubernetes pods. +: Volume claim name for Wave build Kubernetes pods. `wave.build.k8s.storage.mountPath` *(optional)* -: Sets the volume mount path on Wave build Kubernetes pods. +: Volume mount path for Wave build Kubernetes pods. ## Container scan process 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: `false`). +: When `true`, activates vulnerability scanning (default: `false`). -`wave.scan.image.name`  *(optional)* -: 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.image.name` *(optional)* +: 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. +: S3 bucket path where Wave stores SBOM reports. For example, `s3://wave-store/scan-reports`. `wave.scan.severity` *(optional)* -: Sets the [severity levels](https://aquasecurity.github.io/trivy/v0.22.0/vulnerability/examples/filter/) to report in vulnerability scanning. +: [Severity levels](https://aquasecurity.github.io/trivy/v0.22.0/vulnerability/examples/filter/) to report in vulnerability scanning. : Options include: `MEDIUM`,`HIGH`, and `CRITICAL`. `wave.scan.status.duration` *(optional)* -: Sets the duration for which scan status records are retained (default: `5d`). +: Duration for which scan status records are retained (default: `5d`). ### Kubernetes Wave scan process Configure Wave scanning process resource requirements for Kubernetes deployments with the following options: `wave.scan.k8s.resources.requests.cpu` *(optional)* -: Sets the amount of [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave scan processes. +: [CPU resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave scan processes. For example, set to `2` (2 CPU cores) or `1500Mi` (1.5 CPU cores). `wave.scan.k8s.resources.requests.memory` *(optional)* -: Sets the [memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave scan processes. +: [Memory resources](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) allocated to Wave scan processes. For example, set to `3Gi` (3 Gigabytes) or `2000Mi` (2000 Megabytes). ## Container mirror process @@ -417,62 +350,48 @@ Configure Wave scanning process resource requirements for Kubernetes deployments Configure Kubernetes resource requirements for Wave's container mirroring operations with the following options: `wave.mirror.k8s.resources.requests.cpu` *(optional)* -: Sets the CPU resources requested for mirror Kubernetes pods. +: CPU resources requested for mirror Kubernetes pods. `wave.mirror.k8s.resources.requests.memory` *(optional)* -: Sets the memory resources requested for mirror Kubernetes pods. +: Memory resources requested for mirror Kubernetes pods. `wave.mirror.k8s.resources.limits.cpu` *(optional)* -: Sets the CPU resource limit for mirror Kubernetes pods. +: CPU resource limit for mirror Kubernetes pods. `wave.mirror.k8s.resources.limits.memory` *(optional)* -: Sets the memory resource limit for mirror Kubernetes pods. +: Memory resource limit for mirror Kubernetes pods. ## Proxy cache Configure Wave's in-memory proxy cache for registry responses with the following options: `wave.proxy-cache.enabled` *(optional)* -: Enables the proxy cache (default: `false`). +: When `true`, activates the proxy cache (default: `false`). `wave.proxy-cache.duration` *(optional)* -: Sets the cache entry expiration duration (default: `120s`). +: Cache entry expiration duration (default: `120s`). `wave.proxy-cache.max-size` *(optional)* -: Sets the maximum number of entries in the proxy cache (default: `10000`). - -## Security - -### Client IP address resolution - -Wave uses client IP addresses for rate limiting. By default, Wave uses socket addresses (secure). - -For AWS ALB deployments, enable the `alb` profile: - -```bash -export MICRONAUT_ENVIRONMENTS=alb -``` - -This trusts X-Forwarded-For headers from ALB for correct client IP resolution. +: Maximum number of entries in the proxy cache (default: `10000`). ## Rate limits 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: `10/1h`). +: 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: `10/1m`). +: Rate limit for build requests from authenticated users (default: `10/1m`). `rate-limit.pull.anonymous` *(required)* -: Sets the rate limit for pull requests from anonymous users (default: `100/1h`). +: Rate limit for pull requests from anonymous users (default: `100/1h`). `rate-limit.pull.authenticated` *(required)* -: Sets the rate limit for pull requests from authenticated users (default: `100/1m`). +: Rate limit for pull requests from authenticated users (default: `100/1m`). `rate-limit.timeout-errors.max-rate` *(optional)* -: Sets the maximum rate of timeout errors before Wave begins rejecting requests (default: `10/1m`). +: Maximum rate of timeout errors before Wave begins rejecting requests (default: `10/1m`). ## Database and cache @@ -483,26 +402,26 @@ Wave uses external database and caching services to store application data and i Configure Redis with the following options: `redis.client.timeout` *(optional)* -: Sets the timeout duration (in milliseconds) for Redis client operations (default: `5000` (5 seconds)). +: Timeout duration (in milliseconds) for Redis client operations (default: `5000` (5 seconds)). `redis.password` *(optional)* -: Specifies the password used to authenticate with the Redis server. +: Password used to authenticate with the Redis server. Can be set using the `${REDIS_PASSWORD}` environment variable. `redis.pool.enabled` *(optional)* -: Enables the Redis pool (default: `true`). +: When `true`, activates the Redis connection pool (default: `true`). `redis.pool.maxIdle` *(optional)* -: Sets the maximum number of idle connections to maintain in the Redis connection pool (default: `10`). +: Maximum number of idle connections in the Redis connection pool (default: `10`). `redis.pool.maxTotal` *(optional)* -: Sets the maximum number of connections that can be maintained in the Redis connection pool (default: `50`). +: Maximum number of connections in the Redis connection pool (default: `50`). `redis.pool.minIdle` *(optional)* -: Sets the minimum number of idle connections to maintain in the Redis connection pool (default: `0`). +: Minimum number of idle connections in the Redis connection pool (default: `0`). `redis.uri` *(required)* -: Specifies the URI for connecting to Redis (default format: `redis://${REDIS_HOST:redis}:${REDIS_PORT:6379}`). +: URI for connecting to Redis (default format: `redis://${REDIS_HOST:redis}:${REDIS_PORT:6379}`). Can be set using the `${REDIS_URI}` environment variable. ### PostgreSQL @@ -510,92 +429,96 @@ Configure Redis with the following options: Configure PostgreSQL with the following options: `wave.db.password` *(required)* -: Specifies the password for the PostgreSQL database user. +: Password for the PostgreSQL database user. Can be set using the `${WAVE_DB_PASSWORD}` environment variable. `wave.db.uri` *(required)* -: Specifies the JDBC connection string for the PostgreSQL database. +: JDBC connection string for the PostgreSQL database. For example, `jdbc:postgresql://localhost:5432/wave`. Can be set using the `${WAVE_DB_URI}` environment variable. `wave.db.user` *(required)* -: Specifies the username for authenticating with the PostgreSQL database. +: Username for authenticating with the PostgreSQL database. Can be set using the `${WAVE_DB_USER}` environment variable. ## Blob cache Configure how Wave caches container blobs to improve client performance and optionally delegates transfer tasks to Kubernetes pods for scalability with the following options: -`wave.blobCache.baseUrl` *(optional)* -: Specifies the URL, which will override the base URL (part of URL before the blob path) of blobs sent to the end client. +`wave.blobCache.baseUrl` *(optional)* +: URL that overrides the base URL (the part before the blob path) of blobs sent to the client. `wave.blobCache.cloudflare.lifetime` *(optional)* -: Sets the validity of the Cloudflare WAF token. +: Validity duration of the Cloudflare WAF token. `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. +: [Cloudflare secret](https://developers.cloudflare.com/waf/custom-rules/use-cases/configure-token-authentication/) used to create the WAF token. `wave.blobCache.url-signature-duration` *(optional)* -: Sets the validity of the AWS S3 URL signature (default: `30m`). +: Validity duration of the AWS S3 URL signature (default: `30m`). `wave.blobCache.enabled` *(optional)* -: Enables the blob cache (default: `false`). +: When `true`, activates the blob cache (default: `false`). `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. +: [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.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. +: [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. +: 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. +: 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`). +: Container image that supplies the [s5cmd tool](https://github.com/peak/s5cmd) for uploading blob binaries to the S3 bucket (default: `public.cr.seqera.io/wave/s5cmd:v2.2.2`). -`wave.blobCache.signing-strategy` *(optional)* -: Sets the URL signing strategy for different services. +`wave.blobCache.signing-strategy` *(optional)* +: URL signing strategy for different services. Currently supports AWS S3 and Cloudflare service. 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: `2s`). +: Delay between status checks for blob binary transfers from the repository to the cache (default: `2s`). `wave.blobCache.status.duration` *(optional)* -: Sets the duration for which blob transfer status records are retained in cache (default: `1h`). +: Duration for which blob transfer status records are retained in cache (default: `1h`). `wave.blobCache.storage.accessKey` *(required)* -: Specifies the access key (part of credentials) to access the resources of the service used for caching. +: Access key credential for the caching service. `wave.blobCache.storage.bucket` *(required)* -: Sets the name of Cloudflare or S3 bucket. +: Name of the Cloudflare or S3 bucket. For example, `s3://wave-blob-cache`. `wave.blobCache.storage.endpoint` *(optional)* -: Specifies the URL for the storage location for the download or upload of blob binaries. +: Storage endpoint URL for blob binary downloads and uploads. `wave.blobCache.storage.region` *(required)* -: Sets the AWS region where the bucket is created. +: AWS region of the bucket. `wave.blobCache.storage.secretKey` *(required)* -: Specifies the secret key (part of credentials) to access the resources of the service used for caching. +: Secret key credential for the caching service. + +
:::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`). +
+ +`wave.blobCache.timeout` *(optional)* +: Timeout for blob binary transfers. Transfers exceeding this duration fail (default: `10m`). ## Email configuration Configure how Wave sends email notifications on behalf of the service with the following options: `mail.from` *(required)* -: Specifies the sender's email address for Wave notifications. +: Sender email address for Wave notifications. Can be set using the `${MAIL_FROM}` environment variable. ## Metrics @@ -603,14 +526,14 @@ Configure how Wave sends email notifications on behalf of the service with the f Configure how Wave Metrics service provides data about container builds and pulls per organization and date with the following options: `wave.metrics.enabled` *(optional)* -: Enables Wave metrics (default: `false`). +: When `true`, activates Wave metrics (default: `false`). ## Accounts Configure user credentials for accessing authenticated Wave APIs and services with the following options: `wave.accounts` *(required)* -: Sets a list of credentials to access authenticated Wave APIs like metrics APIs. +: List of credentials for accessing authenticated Wave APIs such as the metrics API. Format of the credential list: `- :` ## License server @@ -618,44 +541,47 @@ Configure user credentials for accessing authenticated Wave APIs and services wi Configure the connection to the Seqera license management server: `license.server.url` *(optional)* -: Specifies the URL of the Seqera license management server. +: URL of the Seqera license management server. Required when license validation is enabled. - Example: `https://licenses.seqera.io`. + For example, `https://licenses.seqera.io`. -## Advanced +## Job manager -These settings control internal operational behavior. The defaults are suitable for most deployments, but may need tuning at scale. - -### Job manager +Configure polling and scheduling intervals for Wave's asynchronous job processing. `wave.job-manager.poll-interval` *(optional)* -: Sets the polling interval for checking job status (default: `1s`). +: Polling interval for checking job status (default: `1s`). `wave.job-manager.scheduler-interval` *(optional)* -: Sets the interval for the job scheduler to process queued jobs (default: `1s`). +: Interval for the job scheduler to process queued jobs (default: `1s`). + +## Message stream -### Message stream +Configure how Wave consumes messages from the Redis stream used for internal event processing. `wave.message-stream.claim-timeout` *(optional)* -: Sets the timeout for claiming messages from the Redis stream (default: `5s`). +: Timeout for claiming messages from the Redis stream (default: `5s`). `wave.message-stream.consume-warn-timeout` *(optional)* -: Sets the threshold duration after which a slow message consumer triggers a warning (default: `4s`). +: Threshold duration after which a slow message consumer triggers a warning (default: `4s`). + +## Thread monitor -### Thread monitor +Configure thread monitoring to detect and diagnose thread exhaustion issues. When enabled, Wave writes a thread dump to disk if the active thread count exceeds the configured threshold. `wave.thread-monitor.dump-file` *(optional)* -: Sets the file path where thread dumps are written when the thread count exceeds the threshold. - Example: `/efs/wave/dump/threads-dump.txt`. +: File path where thread dumps are written when the thread count exceeds the threshold. + For example, `/efs/wave/dump/threads-dump.txt`. `wave.thread-monitor.dump-threshold` *(optional)* -: Sets the thread count threshold that triggers a thread dump (default: `200`). +: Thread count threshold that triggers a thread dump (default: `200`). `wave.thread-monitor.interval` *(optional)* -: Sets the interval for the thread monitor check (default: `5m`). +: Interval for the thread monitor check (default: `5m`). -### Trace +## Trace -`wave.trace.slow-endpoint.duration` *(optional)* -: Sets the threshold duration for logging slow HTTP endpoints (default: `1m`). +Configure slow endpoint logging to identify HTTP endpoints that exceed expected response times. +`wave.trace.slow-endpoint.duration` *(optional)* +: Threshold duration for logging slow HTTP endpoints (default: `1m`). diff --git a/docs/configure-wave.md b/docs/configure-wave.md index d0b93e312..c0daba8fa 100644 --- a/docs/configure-wave.md +++ b/docs/configure-wave.md @@ -211,3 +211,102 @@ Using ECR as a cache repository provides: | `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. + +## 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. + +For the related configuration options (`wave.build.cache`, `wave.build.cache-bucket-region`, `wave.build.cache-bucket-upload-parallelism`), see [Container build process](./configuration.md#container-build-process). + +### 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 +``` + +## Client IP address resolution + +Wave uses client IP addresses for rate limiting. By default, Wave uses socket addresses (secure). + +For AWS ALB deployments, enable the `alb` profile: + +```bash +export MICRONAUT_ENVIRONMENTS=alb +``` + +This trusts X-Forwarded-For headers from ALB for correct client IP resolution.