Skip to content
55 changes: 55 additions & 0 deletions docs/install/configure-wave-build.md
Original file line number Diff line number Diff line change
Expand Up @@ -341,3 +341,58 @@ Set up monitoring for build operations:
- **Build timeouts** - Adjust build timeout settings based on workload requirements

For additional configuration options and advanced features, see [Configuring Wave](./configure-wave.md).

## Bottlerocket support

Bottlerocket sets `user.max_user_namespaces=0` by default for security. To use Buildkit with Bottlerocket, enable user namespaces for container builds by setting `user.max_user_namespaces=N` on your host nodes, where `N` is a positive integer, such as `63359`.

You can configure this setting in two ways:

#### Recommended: Node startup configuration

Configure the user namespace setting in your node group's startup script or user data. This approach applies the configuration at boot time and doesn't require privileged containers in your cluster.

#### Alternative: DaemonSet

If you can't control the node configuration directly, use DaemonSet. This approach requires running a privileged container. We recommend you deploy it only on wave-build nodes and use a dedicated namespace for isolation.

Choose a reason for hiding this comment

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

Is there a known scenario where the preferred option won't be available and the DS workaround will be needed?


**Example manifest:**

```yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
labels:
app: sysctl-userns
name: sysctl-userns
spec:
selector:
matchLabels:
app: sysctl-userns
template:
metadata:
labels:
app: sysctl-userns
spec:
containers:
- name: sysctl-userns
image: busybox
command: ["sh", "-euxc", "sysctl -w user.max_user_namespaces=63359 && sleep infinity"]
securityContext:
privileged: true
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: service
operator: In
values: ["wave-build", "wave-build-arm64"]
```

#### Additional resources

For more information about Bottlerocket, see:

- [Bottlerocket FAQs](https://bottlerocket.dev/en/faq/)
- [Amazon Bottlerocket FAQs](https://aws.amazon.com/bottlerocket/faqs/)