feat(kit): assemble a Kit container's launch from its plan and image
Assemble turns an admitted Kit composition and the workload image's config into the harness spec (the image's user, never root; the image env plus the workspace, egress and credential sentinels; the launch argv and agent-sessions verbs), lifecycle hooks with their declared users and restricted environments (the image-derived baseline, egress settings, and only the runtime variables each hook declares), the Kit's files, and volume names stable per execution.
This commit is contained in:
1 parent
08d5df9b11
commit
b54aa00a24
2 files changed
+342
No files matched your search
@@ -0,0 +1,185 @@
|
||||
package kit
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"regexp"
|
||||
"slices"
|
||||
"strings"
|
||||
|
||||
"github.com/docker/sandbox-kit-spec/v3/spec"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/egress"
|
||||
)
|
||||
|
||||
const (
|
||||
// DefaultHarnessUser is the Kit agent user: the harness runs as it when
|
||||
// the image names no user, or names root.
|
||||
DefaultHarnessUser = "1000"
|
||||
// WorkspaceDir is where a Kit container mounts the task worktree.
|
||||
WorkspaceDir = "/workspace"
|
||||
|
||||
installHookUser = "0"
|
||||
)
|
||||
|
||||
// hookBaseline is the platform baseline a hook sees besides its declared
|
||||
// variables, taken from the image's environment, never the host's.
|
||||
var hookBaseline = []string{"PATH", "HOME", "HOSTNAME", "TERM"}
|
||||
|
||||
var unsafeVolumeChars = regexp.MustCompile(`[^a-zA-Z0-9_.-]`)
|
||||
|
||||
// ImageConfig is the workload image's runtime contract.
|
||||
type ImageConfig struct {
|
||||
Entrypoint []string
|
||||
Cmd []string
|
||||
Env []string
|
||||
User string
|
||||
}
|
||||
|
||||
// LaunchParams are the run-specific inputs to a Kit container.
|
||||
type LaunchParams struct {
|
||||
// Execution keys the Kit's volumes, so they survive retries of one
|
||||
// WorkflowExecution and are never shared with another.
|
||||
Execution string
|
||||
ProxyToken string
|
||||
CAPath string
|
||||
// Bound lists the credential services the run credential carries.
|
||||
Bound []string
|
||||
}
|
||||
|
||||
// Hook is one lifecycle hook, ready to exec in the container.
|
||||
type Hook struct {
|
||||
Argv []string
|
||||
User string
|
||||
Env []string
|
||||
Background bool
|
||||
}
|
||||
|
||||
// Volume is one volume@1 path backed by a named volume.
|
||||
type Volume struct {
|
||||
Name string
|
||||
Path string
|
||||
}
|
||||
|
||||
// Launch is everything archie needs to run a composed Kit for one run.
|
||||
type Launch struct {
|
||||
Harness agentexec.HarnessSpec
|
||||
Install []Hook
|
||||
Startup []Hook
|
||||
Files []spec.File
|
||||
Volumes []Volume
|
||||
}
|
||||
|
||||
// Assemble derives a Kit container's launch from its admitted plan and the
|
||||
// workload image's config. The harness never runs as root, and no hook sees
|
||||
// a variable it did not declare beyond the image-derived baseline and the
|
||||
// egress settings every sandbox process needs.
|
||||
func Assemble(p *Plan, img ImageConfig, params LaunchParams) (Launch, error) {
|
||||
creds, err := spec.CredentialsOf(p.Capabilities)
|
||||
if err != nil {
|
||||
return Launch{}, err
|
||||
}
|
||||
lifecycle, err := spec.LifecycleOf(p.Capabilities)
|
||||
if err != nil {
|
||||
return Launch{}, err
|
||||
}
|
||||
volumes, err := spec.VolumesOf(p.Capabilities)
|
||||
if err != nil {
|
||||
return Launch{}, err
|
||||
}
|
||||
|
||||
proxyEnv := egress.ProxyEnv(params.ProxyToken, params.CAPath)
|
||||
runtimeVars := map[string]string{"WORKSPACE_DIR": WorkspaceDir}
|
||||
for _, c := range creds {
|
||||
runtimeVars[credentialModeVar(c.Service)] = credentialMode(c, slices.Contains(params.Bound, c.Service))
|
||||
}
|
||||
|
||||
l := Launch{Harness: agentexec.HarnessSpec{
|
||||
User: harnessUser(img.User),
|
||||
Launch: slices.Concat(img.Entrypoint, img.Cmd),
|
||||
Env: slices.Concat(img.Env, []string{"WORKSPACE_DIR=" + WorkspaceDir}, proxyEnv, egress.SentinelEnv(creds)),
|
||||
}}
|
||||
if s := p.Sessions; s != nil {
|
||||
l.Harness.Prompt, l.Harness.Resume, l.Harness.Continue = s.Prompt, s.Resume, s.Continue
|
||||
}
|
||||
|
||||
baseline := slices.Concat(pick(img.Env, hookBaseline), proxyEnv)
|
||||
if lifecycle != nil {
|
||||
for _, h := range lifecycle.Install {
|
||||
l.Install = append(l.Install, Hook{
|
||||
Argv: slices.Clone(h.Command), User: orDefault(h.User, installHookUser),
|
||||
Env: slices.Concat(baseline, declared(h.Env, runtimeVars)),
|
||||
})
|
||||
}
|
||||
for _, h := range lifecycle.Startup {
|
||||
l.Startup = append(l.Startup, Hook{
|
||||
Argv: slices.Clone(h.Command), User: orDefault(h.User, DefaultHarnessUser),
|
||||
Env: slices.Concat(baseline, declared(h.Env, runtimeVars)), Background: h.Background,
|
||||
})
|
||||
}
|
||||
l.Files = lifecycle.Files
|
||||
}
|
||||
for _, v := range volumes {
|
||||
l.Volumes = append(l.Volumes, Volume{Name: volumeName(params.Execution, v.Path), Path: v.Path})
|
||||
}
|
||||
return l, nil
|
||||
}
|
||||
|
||||
func harnessUser(imageUser string) string {
|
||||
name, _, _ := strings.Cut(imageUser, ":")
|
||||
if name == "" || name == "root" || name == "0" {
|
||||
return DefaultHarnessUser
|
||||
}
|
||||
return imageUser
|
||||
}
|
||||
|
||||
func credentialModeVar(service string) string {
|
||||
return "SBX_CRED_" + strings.ToUpper(strings.ReplaceAll(service, "-", "_")) + "_MODE"
|
||||
}
|
||||
|
||||
func credentialMode(c spec.CredentialCapability, bound bool) string {
|
||||
switch {
|
||||
case !bound:
|
||||
return "none"
|
||||
case c.APIKey != nil:
|
||||
return "apikey"
|
||||
default:
|
||||
return "oauth"
|
||||
}
|
||||
}
|
||||
|
||||
// declared resolves a hook's declared variable names against the runtime
|
||||
// variables archie provides; a name archie does not provide stays unset.
|
||||
func declared(names []string, vars map[string]string) []string {
|
||||
var env []string
|
||||
for _, name := range names {
|
||||
if v, ok := vars[name]; ok {
|
||||
env = append(env, name+"="+v)
|
||||
}
|
||||
}
|
||||
return env
|
||||
}
|
||||
|
||||
// pick returns the entries of env whose names are listed.
|
||||
func pick(env, names []string) []string {
|
||||
var out []string
|
||||
for _, e := range env {
|
||||
if name, _, _ := strings.Cut(e, "="); slices.Contains(names, name) {
|
||||
out = append(out, e)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func orDefault(v, fallback string) string {
|
||||
if v == "" {
|
||||
return fallback
|
||||
}
|
||||
return v
|
||||
}
|
||||
|
||||
func volumeName(execution, path string) string {
|
||||
sum := sha256.Sum256([]byte(path))
|
||||
return "archie-kit-" + unsafeVolumeChars.ReplaceAllString(execution, "_") + "-" + hex.EncodeToString(sum[:6])
|
||||
}
|
||||
@@ -0,0 +1,157 @@
|
||||
package kit
|
||||
|
||||
import (
|
||||
"slices"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/docker/sandbox-kit-spec/v3/spec"
|
||||
)
|
||||
|
||||
const launchKit = `
|
||||
- type: com.docker.sandbox/agent-sessions@1
|
||||
config:
|
||||
prompt: [-p, "{{.Prompt}}"]
|
||||
resume: [--resume, "{{.SessionID}}"]
|
||||
- type: com.docker.sandbox/network-policy@1
|
||||
config: {install: {allow: [registry.example.com]}, runtime: {allow: [api.example.com]}}
|
||||
- type: com.docker.sandbox/credential@1
|
||||
config:
|
||||
service: example
|
||||
phase: runtime
|
||||
apiKey: {name: EXAMPLE_KEY, proxyManaged: true, inject: [{domain: api.example.com, header: x-api-key, format: "%s"}]}
|
||||
- type: com.docker.sandbox/volume@1
|
||||
config: {path: /home/agent/.cli/sessions, size: 1g}
|
||||
- type: com.docker.sandbox/volume@1
|
||||
config: {path: /home/agent/.cli/history}
|
||||
- type: com.docker.sandbox/lifecycle@1
|
||||
config:
|
||||
install:
|
||||
- command: echo "$WORKSPACE_DIR" > /etc/seeded
|
||||
env: [WORKSPACE_DIR]
|
||||
startup:
|
||||
- command: [cli, warm-up]
|
||||
env: [SBX_CRED_EXAMPLE_MODE, NOT_A_RUNTIME_VARIABLE]
|
||||
- command: [cli, daemon]
|
||||
user: "0"
|
||||
background: true`
|
||||
|
||||
func plan(t *testing.T) *Plan {
|
||||
t.Helper()
|
||||
p, err := Compose([]spec.Contribution{{Reference: "kit", Descriptor: descriptor(t, spec.KindWorkload, launchKit)}})
|
||||
if err != nil {
|
||||
t.Fatalf("Compose: %v", err)
|
||||
}
|
||||
return p
|
||||
}
|
||||
|
||||
var image = ImageConfig{
|
||||
Entrypoint: []string{"/usr/local/bin/cli"},
|
||||
Cmd: []string{"--no-color"},
|
||||
Env: []string{"PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/home/agent", "IMAGE_ONLY=kept"},
|
||||
User: "agent",
|
||||
}
|
||||
|
||||
var params = LaunchParams{Execution: "exec-42", ProxyToken: "tok", CAPath: "/etc/archie/ca.pem", Bound: []string{"example"}}
|
||||
|
||||
func TestAssembleHarness(t *testing.T) {
|
||||
l, err := Assemble(plan(t), image, params)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
h := l.Harness
|
||||
if !slices.Equal(h.Launch, []string{"/usr/local/bin/cli", "--no-color"}) {
|
||||
t.Errorf("launch %v, want the image entrypoint then cmd", h.Launch)
|
||||
}
|
||||
if !slices.Equal(h.Prompt, []string{"-p", "{{.Prompt}}"}) || !slices.Equal(h.Resume, []string{"--resume", "{{.SessionID}}"}) {
|
||||
t.Errorf("verbs prompt=%v resume=%v, want the Kit's agent-sessions verbs", h.Prompt, h.Resume)
|
||||
}
|
||||
if h.User != "agent" {
|
||||
t.Errorf("user %q, want the image's user", h.User)
|
||||
}
|
||||
for _, want := range []string{
|
||||
"PATH=/usr/local/bin:/usr/bin:/bin", "IMAGE_ONLY=kept",
|
||||
"WORKSPACE_DIR=/workspace",
|
||||
"HTTPS_PROXY=http://archie:tok@archie-egress:3128",
|
||||
"SSL_CERT_FILE=/etc/archie/ca.pem",
|
||||
"EXAMPLE_KEY=archie-proxy-managed",
|
||||
} {
|
||||
if !slices.Contains(h.Env, want) {
|
||||
t.Errorf("harness env lacks %q:\n%s", want, strings.Join(h.Env, "\n"))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestAssembleNeverRunsTheHarnessAsRoot(t *testing.T) {
|
||||
for _, user := range []string{"", "root", "0", "0:0"} {
|
||||
img := image
|
||||
img.User = user
|
||||
l, err := Assemble(plan(t), img, params)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if l.Harness.User != DefaultHarnessUser {
|
||||
t.Errorf("image user %q gave harness user %q, want %q", user, l.Harness.User, DefaultHarnessUser)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestAssembleHooks(t *testing.T) {
|
||||
l, err := Assemble(plan(t), image, params)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if len(l.Install) != 1 || len(l.Startup) != 2 {
|
||||
t.Fatalf("install %d startup %d, want 1 and 2", len(l.Install), len(l.Startup))
|
||||
}
|
||||
install := l.Install[0]
|
||||
if !slices.Equal(install.Argv, []string{"sh", "-c", `echo "$WORKSPACE_DIR" > /etc/seeded`}) {
|
||||
t.Errorf("a string command runs through the shell, as the Kit spec decodes it; got %v", install.Argv)
|
||||
}
|
||||
if install.User != "0" {
|
||||
t.Errorf("install hook user %q, want root by default", install.User)
|
||||
}
|
||||
if !slices.Contains(install.Env, "WORKSPACE_DIR=/workspace") || !slices.Contains(install.Env, "HTTPS_PROXY=http://archie:tok@archie-egress:3128") {
|
||||
t.Errorf("install env %v, want its declared variable and the egress baseline", install.Env)
|
||||
}
|
||||
warm := l.Startup[0]
|
||||
if warm.User != DefaultHarnessUser {
|
||||
t.Errorf("startup hook user %q, want the agent user by default", warm.User)
|
||||
}
|
||||
if !slices.Contains(warm.Env, "SBX_CRED_EXAMPLE_MODE=apikey") {
|
||||
t.Errorf("startup env %v, want the bound credential's mode", warm.Env)
|
||||
}
|
||||
for _, e := range warm.Env {
|
||||
if strings.HasPrefix(e, "NOT_A_RUNTIME_VARIABLE=") || strings.HasPrefix(e, "IMAGE_ONLY=") || strings.HasPrefix(e, "EXAMPLE_KEY=") {
|
||||
t.Errorf("startup env carries %q, which it neither declared nor is baseline", e)
|
||||
}
|
||||
}
|
||||
if daemon := l.Startup[1]; daemon.User != "0" || !daemon.Background {
|
||||
t.Errorf("startup hook %+v, want its declared root user and background flag", daemon)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAssembleVolumesArePerExecution(t *testing.T) {
|
||||
a, err := Assemble(plan(t), image, params)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
again, _ := Assemble(plan(t), image, params)
|
||||
other := params
|
||||
other.Execution = "exec-43"
|
||||
b, _ := Assemble(plan(t), image, other)
|
||||
if len(a.Volumes) != 2 {
|
||||
t.Fatalf("volumes %v, want 2", a.Volumes)
|
||||
}
|
||||
if !slices.Equal(a.Volumes, again.Volumes) {
|
||||
t.Error("volume names are not stable for one execution; a retry would lose its sessions")
|
||||
}
|
||||
if a.Volumes[0].Name == a.Volumes[1].Name {
|
||||
t.Error("two paths share a volume")
|
||||
}
|
||||
for i := range a.Volumes {
|
||||
if a.Volumes[i].Name == b.Volumes[i].Name {
|
||||
t.Errorf("executions share volume %q", a.Volumes[i].Name)
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user