Add migration guide for v1.3.0 docker

website/blog/releases/v1.3.0.md

@@ -90,7 +90,22 @@ Spice.ai adopts the latest minus one DataFusion release for quality assurance an
 
 ## Breaking Changes
 
-No breaking changes.
+The container image now always runs as a non-root user (UID/GID 65534) with minimal dependencies, resulting in a smaller, more secure image. Standard Linux tools, including `bash`, are no longer included.
+
+**Kubernetes Deployments**:
+
+- Use of the v1.3.0+ Helm chart is required, which includes a `securityContext` ensuring the sandbox user has required file access.
+
+- For deployments using a lower version than the v1.3.0 Helm chart, add the following `securityContext` to the pod specification:
+
+```yaml
+securityContext:
+  runAsUser: 65534
+  runAsGroup: 65534
+  fsGroup: 65534
+```
+
+See the [Docker Sandbox Guide](https://spiceai.org/docs/deployment/docker/sandbox) for details on how to update custom Docker images to restore the previous behavior.
 
 ## Cookbook Updates
 

website/docs/deployment/docker/sandbox.md

@@ -0,0 +1,83 @@
+---
+title: 'Docker Sandbox Guide - v1.3.0'
+description: 'Migrating to v1.3.0'
+sidebar_label: 'Sandbox Guide - v1.3.0'
+sidebar_position: 1
+tags:
+  - deployment
+  - docker
+  - sandbox
+---
+
+## v1.3.0 Docker Sandbox
+
+In the v1.3.0 release, the Docker image changed the sandbox from a script that ran at startup, to being baked into the Docker image itself. Prior to this, the Docker image would start up as a root user, and then set up a sandbox user with restricted permissions before starting the Spice runtime in that restricted context.
+
+Additionally, the Docker image includes no standard Linux tools like `bash`.
+
+Starting with v1.3.0, the sandboxing logic is baked directly into the final Docker image, and the Docker image starts up as the sandbox user.
+
+For most users, this change will be transparent. However, there are a few cases where an action is required to update.
+
+### Building a custom Docker image based on v1.3.0
+
+Building a custom Docker image based on v1.3.0 that installs additional dependencies will require using the `debian:bookworm-slim` base image and copying the `spiced` binary from the `spiceai/spiceai` image into the custom image. This approach can also be used to restore the previous behavior of including standard Linux tools like `bash`.
+
+```dockerfile
+FROM debian:bookworm-slim
+
+# Copy the spiced binary from the spiceai/spiceai image into the custom image.
+COPY --from=spiceai/spiceai:v1.3.0 /usr/local/bin/spiced /usr/local/bin/spiced
+
+# Install any additional dependencies needed for the image.
+RUN apt update && apt install -y --no-install-recommends <your-dependencies>
+
+# Any other customizations needed for the image.
+
+WORKDIR /app
+
+ENTRYPOINT ["/usr/local/bin/spiced"]
+```
+
+This will restore the previous behavior of starting as the root user and including standard Linux tools, like `bash`.
+
+#### Running as a non-root user
+
+Spice recommends that custom Docker images based on Spice run as a non-root user. i.e.
+
+```dockerfile
+RUN addgroup -g 1001 -S sandboxgroup && adduser -u 1001 -S -G sandboxgroup sandbox
+USER sandbox
+```
+
+This may require additional configuration of mounted volumes to ensure that the sandbox user has access to the necessary files. i.e. in Kubernetes, this requires adding a `securityContext` to the pod spec.
+
+```yaml
+securityContext:
+  runAsUser: 1001
+  runAsGroup: 1001
+  # Tells Kubernetes to set the group of the files in the volume to sandboxgroup, 
+  # which allows the sandbox user to access the files.
+  fsGroup: 1001
+```
+
+:::note
+
+The `fsGroup` directive does not work for all Kubernetes storage types. For example, it does not work for `hostPath` volumes. In this case, an init container can be used to set the group of the files in the volume.
+
+:::
+
+### Custom Kubernetes deployments
+
+Kubernetes deployments that do not use the v1.3.0 Helm chart will need to add the following `securityContext` to their pod spec:
+
+```yaml
+securityContext:
+  runAsUser: 65534
+  runAsGroup: 65534
+  fsGroup: 65534
+```
+
+### Debugging sandbox container
+
+To debug issues with the sandbox container, see the [Debugging Sandbox Container](/docs/troubleshooting/index.md#debugging-sandbox-container) section of the troubleshooting guide.

website/docs/deployment/index.md

@@ -20,5 +20,5 @@ Learn how to deploy Spice.ai in your environment.
 ## Deployment Guides
 
 - [Kubernetes (Helm)](kubernetes/index.md)
-- [Docker](docker.md)
+- [Docker](docker/index.md)
 - [Spice Cloud](cloud/index.md)

website/docs/troubleshooting/index.md

@@ -171,3 +171,42 @@ explain select * from taxi_trips
 |               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 +---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 ```
+
+## Debugging Sandbox Container
+
+The Spice sandbox container is a minimal container that doesn't include standard Linux tools like `bash`. This can make it difficult to debug issues in the container itself.
+
+### SQL REPL
+
+It's possible to run the SQL REPL from the container to debug SQL queries:
+
+```console
+docker exec -it <container_id> spiced --repl
+```
+
+Or from `kubectl`:
+
+```console
+kubectl exec -it <pod_name> -- spiced --repl
+```
+
+### Debugging with a shell
+
+To debug issues using a shell, mount a volume that has a statically compiled `busybox` binary, and exec into the container using the `busybox sh` command. Here is an example in Docker:
+
+```bash
+# Create a volume for the busybox binary
+docker volume create busybox
+
+# Copy the busybox binary to the volume
+docker run --rm -v busybox:/data busybox:stable-musl sh -c "mkdir -p /data && cp /bin/busybox /data/busybox"
+
+# Run the Spice.ai container with the busybox binary mounted, ensure that any other volumes are mounted as well (i.e. for spicepod)
+docker run -v busybox:/busy -v <path_to_spicepod>:/app/spicepod -d --name spiceai-debug spiceai/spiceai:1.3.0
+
+# Exec into the container
+docker exec -it spiceai-debug /busy/busybox sh
+
+# At this point, a shell with standard Linux tools is available via the busybox binary. 
+# However, commands must be prefixed with `/busy/busybox`, for example: `/busy/busybox ls -l /app`.
+```