Merge remote-tracking branch 'upstream' into AddNetworkPolicy

Author: vicentefb

Makefile

@@ -1,5 +1,5 @@
 .PHONY: all
-all: fix-go-generate build lint-go test-unit
+all: fix-go-generate build lint-go test-unit toc-verify
 
 .PHONY: fix-go-generate
 fix-go-generate:
@@ -32,3 +32,18 @@ test-e2e:
 .PHONY: lint-go
 lint-go:
 	./dev/tools/lint-go
+
+# Example usage: make release TAG=v0.1.0
+.PHONY: release
+release:
+	go mod tidy
+	go generate ./...
+	./dev/tools/release --tag=${TAG}
+
+.PHONY: toc-update
+toc-update:
+	./dev/tools/update-toc
+
+.PHONY: toc-verify
+toc-verify:
+	./dev/tools/verify-toc

README.md

@@ -4,6 +4,63 @@
 
 This project is developing a `Sandbox` Custom Resource Definition (CRD) and controller for Kubernetes, under the umbrella of [SIG Apps](https://github.com/kubernetes/community/tree/master/sig-apps). The goal is to provide a declarative, standardized API for managing workloads that require the characteristics of a long-running, stateful, singleton container with a stable identity, much like a lightweight, single-container VM experience built on Kubernetes primitives.
 
+## Overview
+
+### Core: Sandbox
+
+The `Sandbox` CRD is the core of agent-sandbox. It provides a declarative API for managing a single, stateful pod with a stable identity and persistent storage. This is useful for workloads that don't fit well into the stateless, replicated model of Deployments or the numbered, stable model of StatefulSets.
+
+Key features of the `Sandbox` CRD include:
+
+*   **Stable Identity:** Each Sandbox has a stable hostname and network identity.
+*   **Persistent Storage:** Sandboxes can be configured with persistent storage that survives restarts.
+*   **Lifecycle Management:** The Sandbox controller manages the lifecycle of the pod, including creation, scheduled deletion, pausing and resuming.
+
+### Extensions
+
+The `extensions` module provides additional CRDs and controllers that build on the core `Sandbox` API to provide more advanced features.
+
+*   `SandboxTemplate`: Provides a way to define reusable templates for creating Sandboxes, making it easier to manage large numbers of similar Sandboxes.
+*   `SandboxClaim`: Allows users to create Sandboxes from a template, abstracting away the details of the underlying Sandbox configuration.
+*   `SandboxWarmPool`: Manages a pool of pre-warmed Sandbox Pods that can be quickly allocated to users, reducing the time it takes to get a new Sandbox up and running.
+
+## Installation
+
+You can install the agent-sandbox controller and its CRDs with the following command.
+
+```sh
+# Replace "vX.Y.Z" with a specific version tag (e.g., "v0.1.0") from
+# https://github.com/kubernetes-sigs/agent-sandbox/releases
+export VERSION="vX.Y.Z"
+
+# To install only the core components:
+kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml
+
+# To install the extensions components:
+kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml
+```
+
+## Getting Started
+
+Once you have installed the controller, you can create a simple Sandbox by applying the following YAML to your cluster:
+
+```yaml
+apiVersion: agents.x-k8s.io/v1alpha1
+kind: Sandbox
+metadata:
+  name: my-sandbox
+spec:
+  template:
+    spec:
+      containers:
+      - name: my-container
+        image: <IMAGE>
+```
+
+This will create a new Sandbox named `my-sandbox` running the image you specify. You can then access the Sandbox using its stable hostname, `my-sandbox`.
+
+For more complex examples, including how to use the extensions, please see the [examples/](examples/) and [extensions/examples/](extensions/examples/) directories.
+
 ## Motivation
 
 Kubernetes excels at managing stateless, replicated applications (Deployments) and stable, numbered sets of stateful pods (StatefulSets). However, there's a growing need for an abstraction to handle use cases such as:

clients/python/agentic-sandbox-client/.gitignore

@@ -0,0 +1,14 @@
+build/
+venv/
+
+__pycache__/
+*.pyc
+.env
+.DS_Store
+.idea/
+.vscode/
+logs/
+*.log
+
+agentic_sandbox.egg-info/
+dist/

clients/python/agentic-sandbox-client/README.md

@@ -0,0 +1,92 @@
+# Agentic Sandbox Client Python
+
+This Python client provides a simple, high-level interface for creating and interacting with sandboxes managed by the Agent Sandbox controller. It's designed to be used as a context manager, ensuring that sandbox resources are properly created and cleaned up.
+
+## Usage
+
+### Prerequisites
+
+- A running Kubernetes cluster (e.g., `kind`).
+- The Agent Sandbox controller must be deployed with the extensions feature enabled.
+- A `SandboxTemplate` resource must be created in the cluster.
+- The `kubectl` command-line tool must be installed and configured to connect to your cluster.
+
+### Installation
+
+1.  **Create a virtual environment:**
+    ```bash
+    python3 -m venv .venv
+    ```
+2.  **Activate the virtual environment:**
+    ```bash
+    source .venv/bin/activate
+    ```
+3. **Option 1: Install from source via git:**
+    ```bash
+    # Replace "main" with a specific version tag (e.g., "v0.1.0") from 
+    # https://github.com/kubernetes-sigs/agent-sandbox/releases to pin a version tag.
+    export VERSION="main"
+
+    pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${VERSION}#subdirectory=clients/python/agentic-sandbox-client"
+    ```
+4. **Option 2: Install from source in editable mode:**
+    ```bash
+    git clone https://github.com/kubernetes-sigs/agent-sandbox.git
+    cd agent-sandbox/clients/agentic-sandbox-client-python
+    cd ~/path_to_venv
+    pip install -e .
+    ```
+
+### Example:
+
+```python
+from agentic_sandbox import SandboxClient
+
+with SandboxClient(template_name="sandbox-python-template", namespace="default") as sandbox:
+    result = sandbox.run("echo 'Hello, World!'")
+    print(result.stdout)
+```
+
+## How It Works
+
+The `SandboxClient` client automates the entire lifecycle of a temporary sandbox environment:
+
+1.  **Initialization (`with SandboxClient(...)`):** The client is initialized with the name of the `SandboxTemplate` you want to use and the namespace where the resources should be created:
+
+    -   **`template_name` (str):** The name of the `SandboxTemplate` resource to use for creating the sandbox.
+    -   **`namespace` (str, optional):** The Kubernetes namespace to create the `SandboxClaim` in. Defaults to "default". 
+    -   When you create a `SandboxClient` instance within a `with` block, it initiates the process of creating a sandbox.
+2.  **Claim Creation:** It creates a `SandboxClaim` Kubernetes resource. This claim tells the agent-sandbox controller to provision a new sandbox using a predefined `SandboxTemplate`.
+3.  **Waiting for Readiness:** The client watches the Kubernetes API for the corresponding `Sandbox` resource to be created and become "Ready". This indicates that the pod is running and the server inside is active.
+4.  **Port Forwarding:** Once the sandbox pod is ready, the client automatically starts a `kubectl port-forward` process in the background. This creates a secure tunnel from your local machine to the sandbox pod, allowing you to communicate with the server running inside.
+5.  **Interaction:** The `SandboxClient` object provides three main methods to interact with the running sandbox:
+    *   `run(command)`: Executes a shell command inside the sandbox.
+    *   `write(path, content)`: Uploads a file to the sandbox.
+    *   `read(path)`: Downloads a file from the sandbox.
+6.  **Cleanup (`__exit__`):** When the `with` block is exited (either normally or due to an error), the client automatically cleans up all resources. It terminates the `kubectl port-forward` process and deletes the `SandboxClaim`, which in turn causes the controller to delete the `Sandbox` pod.
+
+
+## How to Test the Client
+
+A test script, `test_client.py`, is included to verify the client's functionality.
+You should see output indicating that the tests for command execution and file operations have passed.
+
+## Packaging and Installation
+
+This client is configured as a standard Python package using `pyproject.toml`.
+
+### Prerequisites
+
+-   Python 3.7+
+-   `pip`
+-   `build` (install with `pip install build`)
+
+### Building the Package
+
+To build the package from the source, navigate to the `agentic-sandbox-client` directory and run the following command:
+
+```bash
+python -m build
+```
+
+This will create a `dist` directory containing the packaged distributables: a `.whl` (wheel) file and a `.tar.gz` (source archive).

clients/python/agentic-sandbox-client/agentic_sandbox/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .sandbox_client import SandboxClient