-
Notifications
You must be signed in to change notification settings - Fork 763
feat(server,k8s): implement pause/resume with rootfs snapshot support #668
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
fengcone
wants to merge
1
commit into
alibaba:main
Choose a base branch
from
fengcone:feature/public-k8s-pause-resume
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| # Kubernetes Operator | ||
|
|
||
| ## Overview | ||
|
|
||
| Kubernetes operator managing sandbox environments via custom resources. Provides BatchSandbox (O(1) batch delivery), Pool (resource pooling for fast provisioning), and optional task orchestration. Built with controller-runtime (Kubebuilder). | ||
|
|
||
| ## Structure | ||
|
|
||
| ``` | ||
| kubernetes/ | ||
| ├── apis/sandbox/v1alpha1/ # CRD type definitions | ||
| │ ├── batchsandbox_types.go # BatchSandbox spec + status | ||
| │ ├── pool_types.go # Pool spec + status | ||
| │ └── sandboxsnapshot_types.go | ||
| ├── cmd/ | ||
| │ ├── controller/main.go # Controller manager entry point | ||
| │ ├── image-committer/main.go # Image committer binary (runs as commit Job) | ||
| │ └── task-executor/main.go # Task executor binary (runs as sidecar) | ||
| ├── internal/ | ||
| │ ├── controller/ # Reconciliation loops | ||
| │ ├── scheduler/ # Pool allocation logic (bufferMin/Max, poolMax) | ||
| │ └── utils/ # Utility functions | ||
| ├── config/ | ||
| │ ├── crd/bases/ # Generated CRD YAML manifests | ||
| │ ├── rbac/ # ClusterRole, ClusterRoleBinding | ||
| │ ├── manager/ # Controller deployment manifest | ||
| │ └── samples/ # Example CRD instances | ||
| ├── charts/ # Helm charts (opensandbox-controller, opensandbox-server, opensandbox) | ||
| ├── test/e2e/ # End-to-end tests + testdata | ||
| └── Dockerfile # Controller image build | ||
| Dockerfile.image-committer # Image-committer image build | ||
| ``` | ||
|
|
||
| ## Where to Look | ||
|
|
||
| | Task | File | Notes | | ||
| |------|------|-------| | ||
| | Add CRD field | `apis/sandbox/v1alpha1/*_types.go` | Run `make install` to update CRDs | | ||
| | Controller logic | `internal/controller/` | BatchSandbox + Pool reconciliation | | ||
| | Pool allocation | `internal/scheduler/` | Buffer management, sandbox→pool assignment | | ||
| | Task execution | `cmd/task-executor/`, `internal/task-executor/` | Process-based tasks in sandboxes | | ||
| | Helm values | `charts/opensandbox-controller/values.yaml` | Controller + task-executor image refs | | ||
| | RBAC permissions | `config/rbac/` | ClusterRole rules | | ||
| | E2E tests | `test/e2e/` | Ginkgo/Gomega test framework | | ||
|
|
||
| ## Conventions | ||
|
|
||
| - **Framework**: Kubebuilder with `controller-runtime` v0.21. | ||
| - **Go version**: 1.24. Own `go.mod` (`github.com/alibaba/opensandbox/sandbox-k8s`). | ||
| - **Concurrency**: BatchSandbox controller concurrency=32, Pool controller concurrency=1. | ||
| - **CRD version**: `v1alpha1` under group `sandbox.opensandbox.io`. | ||
| - **Helm charts**: Umbrella chart (`opensandbox`) wraps controller + server subcharts. | ||
| - **Logging**: `klog/v2` + `zap`. Log level configurable via `--zap-log-level` flag. | ||
|
|
||
| ## Anti-Patterns | ||
|
|
||
| - `pause`/`resume` lifecycle uses SandboxSnapshot CRD + image-committer Job to snapshot and restore containers. | ||
| - BatchSandbox deletion waits for running tasks to terminate before removing the resource. | ||
| - Task-executor requires `shareProcessNamespace: true` and `SYS_PTRACE` capability in pod spec. | ||
| - Pool template changes do not affect already-allocated sandboxes. | ||
|
|
||
| ## Commands | ||
|
|
||
| ```bash | ||
| make install # install CRDs into cluster | ||
| make deploy CONTROLLER_IMG=... TASK_EXECUTOR_IMG=... # deploy controller | ||
| make docker-build # build controller image | ||
| make docker-build-task-executor # build task-executor image | ||
| make docker-build-image-committer # build image-committer image | ||
| make test # run tests | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| # Copyright 2025 Alibaba Group Holding Ltd. | ||
| # | ||
| # 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. | ||
|
|
||
| # Build stage | ||
| FROM golang:1.24-alpine AS builder | ||
|
|
||
| # Use Aliyun mirror for faster downloads in China | ||
| RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories | ||
|
|
||
| WORKDIR /workspace | ||
|
|
||
| # Copy go mod files | ||
| COPY go.mod go.sum ./ | ||
| RUN GOPROXY=https://goproxy.cn,direct go mod download | ||
|
|
||
| # Copy source code | ||
| COPY cmd/image-committer/ cmd/image-committer/ | ||
|
|
||
| # Build binary | ||
| RUN CGO_ENABLED=0 GOOS=linux go build -o /usr/local/bin/image-committer ./cmd/image-committer/ | ||
|
|
||
| # Runtime stage | ||
| FROM alpine:3.19 | ||
|
|
||
| # Use Aliyun mirror for faster downloads in China | ||
| RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories | ||
|
|
||
| # Install containerd CLI tools | ||
| RUN apk add --no-cache \ | ||
| containerd-ctr \ | ||
| cri-tools \ | ||
| curl \ | ||
| jq \ | ||
| nerdctl | ||
|
|
||
| # Create directories for socket mounts | ||
| RUN mkdir -p /var/run/containerd /run/k8s/containerd | ||
|
|
||
| # Copy the built binary from builder stage | ||
| COPY --from=builder /usr/local/bin/image-committer /usr/local/bin/image-committer | ||
| RUN chmod +x /usr/local/bin/image-committer | ||
|
|
||
| WORKDIR /workspace | ||
|
|
||
| ENTRYPOINT ["/usr/local/bin/image-committer"] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
175 changes: 175 additions & 0 deletions
175
kubernetes/apis/sandbox/v1alpha1/sandboxsnapshot_types.go
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,175 @@ | ||
| // Copyright 2025 Alibaba Group Holding Ltd. | ||
| // | ||
| // 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. | ||
|
|
||
| package v1alpha1 | ||
|
|
||
| import ( | ||
| metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" | ||
| runtime "k8s.io/apimachinery/pkg/runtime" | ||
| ) | ||
|
|
||
| // SnapshotType defines the type of snapshot. | ||
| type SnapshotType string | ||
|
|
||
| const ( | ||
| SnapshotTypeRootfs SnapshotType = "Rootfs" | ||
| ) | ||
|
|
||
| // +kubebuilder:validation:Enum=Pending;Committing;Ready;Failed | ||
| // SandboxSnapshotPhase defines the phase of a snapshot. | ||
| type SandboxSnapshotPhase string | ||
|
|
||
| const ( | ||
| SandboxSnapshotPhasePending SandboxSnapshotPhase = "Pending" | ||
| SandboxSnapshotPhaseCommitting SandboxSnapshotPhase = "Committing" | ||
| SandboxSnapshotPhaseReady SandboxSnapshotPhase = "Ready" | ||
| SandboxSnapshotPhaseFailed SandboxSnapshotPhase = "Failed" | ||
| ) | ||
|
|
||
| // ContainerSnapshot represents a snapshot of a single container. | ||
| type ContainerSnapshot struct { | ||
| // ContainerName is the name of the container. | ||
| ContainerName string `json:"containerName"` | ||
| // ImageURI is the target image URI for this container's snapshot. | ||
| ImageURI string `json:"imageUri"` | ||
| // ImageDigest is the digest of the pushed snapshot image. | ||
| // +optional | ||
| ImageDigest string `json:"imageDigest,omitempty"` | ||
| } | ||
|
|
||
| // SandboxSnapshotSpec defines the desired state of SandboxSnapshot. | ||
| type SandboxSnapshotSpec struct { | ||
| // SandboxID is the stable public identifier for the sandbox. | ||
| SandboxID string `json:"sandboxId"` | ||
|
|
||
| // SnapshotType indicates the type of snapshot (default: Rootfs). | ||
| // +optional | ||
| // +kubebuilder:validation:Optional | ||
| // +kubebuilder:default=Rootfs | ||
| SnapshotType SnapshotType `json:"snapshotType,omitempty"` | ||
|
|
||
| // SourceBatchSandboxName is the name of the source BatchSandbox. | ||
| SourceBatchSandboxName string `json:"sourceBatchSandboxName"` | ||
|
|
||
| // SourcePodName is the name of the source Pod. | ||
| // +optional | ||
| // +kubebuilder:validation:Optional | ||
| SourcePodName string `json:"sourcePodName,omitempty"` | ||
|
|
||
| // SourceNodeName is the node where the source Pod runs. | ||
| // +optional | ||
| // +kubebuilder:validation:Optional | ||
| SourceNodeName string `json:"sourceNodeName,omitempty"` | ||
|
|
||
| // SnapshotPushSecret is the Secret name for pushing to registry. | ||
| // +optional | ||
| SnapshotPushSecret string `json:"snapshotPushSecret,omitempty"` | ||
|
|
||
| // ResumeImagePullSecret is the Secret name for pulling snapshot during resume. | ||
| // +optional | ||
| ResumeImagePullSecret string `json:"resumeImagePullSecret,omitempty"` | ||
|
|
||
| // ResumeTemplate contains enough information to reconstruct BatchSandbox. | ||
| // +optional | ||
| // +kubebuilder:pruning:PreserveUnknownFields | ||
| // +kubebuilder:validation:Schemaless | ||
| ResumeTemplate *runtime.RawExtension `json:"resumeTemplate,omitempty"` | ||
|
|
||
| // SnapshotRegistry is the OCI registry for snapshot images. | ||
| // +optional | ||
| // +kubebuilder:validation:Optional | ||
| SnapshotRegistry string `json:"snapshotRegistry,omitempty"` | ||
|
|
||
| // ContainerSnapshots holds per-container snapshot information. | ||
| // The controller fills this during resolution. | ||
| // +optional | ||
| // +kubebuilder:validation:Optional | ||
| ContainerSnapshots []ContainerSnapshot `json:"containerSnapshots,omitempty"` | ||
|
|
||
| // PausedAt is the timestamp when pause was initiated. | ||
| PausedAt metav1.Time `json:"pausedAt"` | ||
|
|
||
| // PauseVersion is incremented by the server to request a pause. | ||
| // Controller ACKs by setting status.pauseVersion to match when entering Committing phase. | ||
| PauseVersion int `json:"pauseVersion"` | ||
|
|
||
| // ResumeVersion is incremented by the server to request a resume. | ||
| // Controller ACKs by setting status.resumeVersion to match when starting resume. | ||
| ResumeVersion int `json:"resumeVersion"` | ||
| } | ||
|
|
||
| // SnapshotRecord represents a single pause or resume event in the snapshot history. | ||
| type SnapshotRecord struct { | ||
| // Action is "Pause" or "Resume". | ||
| Action string `json:"action"` | ||
| // Version is the pauseVersion or resumeVersion that triggered this action. | ||
| Version int `json:"version"` | ||
| // Timestamp is when this record was created. | ||
| Timestamp metav1.Time `json:"timestamp"` | ||
| // Message is a human-readable description of the event. | ||
| Message string `json:"message"` | ||
| } | ||
|
|
||
| // SandboxSnapshotStatus defines the observed state of SandboxSnapshot. | ||
| type SandboxSnapshotStatus struct { | ||
| // Phase indicates the current phase of the snapshot. | ||
| Phase SandboxSnapshotPhase `json:"phase,omitempty"` | ||
|
|
||
| // Message provides human-readable status information. | ||
| Message string `json:"message,omitempty"` | ||
|
|
||
| // ReadyAt is the timestamp when the snapshot became Ready. | ||
| ReadyAt *metav1.Time `json:"readyAt,omitempty"` | ||
|
|
||
| // ContainerSnapshots holds per-container snapshot results (filled by controller after push). | ||
| // +optional | ||
| ContainerSnapshots []ContainerSnapshot `json:"containerSnapshots,omitempty"` | ||
|
|
||
| // PauseVersion is ACKed by the controller when entering Committing phase. | ||
| PauseVersion int `json:"pauseVersion"` | ||
|
|
||
| // ResumeVersion is ACKed by the controller when starting resume. | ||
| ResumeVersion int `json:"resumeVersion"` | ||
|
|
||
| // History records each pause/resume cycle. | ||
| // +optional | ||
| History []SnapshotRecord `json:"history,omitempty"` | ||
| } | ||
|
|
||
| // +genclient | ||
| // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object | ||
| // +kubebuilder:object:root=true | ||
| // +kubebuilder:subresource:status | ||
| // +kubebuilder:resource:shortName=sbxsnap | ||
| // +kubebuilder:printcolumn:name="PHASE",type="string",JSONPath=".status.phase" | ||
| // +kubebuilder:printcolumn:name="SANDBOX_ID",type="string",JSONPath=".spec.sandboxId" | ||
| // +kubebuilder:printcolumn:name="AGE",type="date",JSONPath=".metadata.creationTimestamp" | ||
| type SandboxSnapshot struct { | ||
| metav1.TypeMeta `json:",inline"` | ||
| metav1.ObjectMeta `json:"metadata,omitempty"` | ||
|
|
||
| Spec SandboxSnapshotSpec `json:"spec,omitempty"` | ||
| Status SandboxSnapshotStatus `json:"status,omitempty"` | ||
| } | ||
|
|
||
| // +kubebuilder:object:root=true | ||
| type SandboxSnapshotList struct { | ||
| metav1.TypeMeta `json:",inline"` | ||
| metav1.ListMeta `json:"metadata,omitempty"` | ||
| Items []SandboxSnapshot `json:"items"` | ||
| } | ||
|
|
||
| func init() { | ||
| SchemeBuilder.Register(&SandboxSnapshot{}, &SandboxSnapshotList{}) | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The
PausePolicystruct usessnapshotPushSecret/resumeImagePullSecretJSON keys, but the server request schema and generated CRD usesnapshotPushSecretName/resumeImagePullSecretName. This mismatch causes secret fields to be dropped when decodingBatchSandboxinto typed Go structs, so pause/resume flows lose registry credentials (commit jobs cannot push to private registries and resumed sandboxes can miss image pull secrets).Useful? React with 👍 / 👎.