feat(kit): admit Kit v3 descriptors against archie's capability support
Decodes published descriptors from the manifest annotation, composes one workload with its mixins through the Kit spec package, and applies the runtime's support table: unsupported required capabilities refuse the launch, optional ones are skipped and recorded, and forge or passthrough credentials are refused. A composition must carry a headless prompt verb.
This commit is contained in:
4 files changed
+416
-1
No files matched your search
@@ -17,12 +17,13 @@ require (
|
||||
github.com/containerd/errdefs v1.0.0 // indirect
|
||||
github.com/containerd/errdefs/pkg v0.3.0 // indirect
|
||||
github.com/containerd/log v0.2.0 // indirect
|
||||
github.com/containerd/platforms v0.2.1 // indirect
|
||||
github.com/containerd/platforms v1.0.0-rc.5 // indirect
|
||||
github.com/cpuguy83/dockercfg v0.3.2 // indirect
|
||||
github.com/davidmz/go-pageant v1.0.2 // indirect
|
||||
github.com/distribution/reference v0.6.0 // indirect
|
||||
github.com/docker/go-connections v0.8.1 // indirect
|
||||
github.com/docker/go-units v0.5.0 // indirect
|
||||
github.com/docker/sandbox-kit-spec/v3 v3.0.0-m.6 // indirect
|
||||
github.com/dustin/go-humanize v1.1.0 // indirect
|
||||
github.com/ebitengine/purego v0.11.1 // indirect
|
||||
github.com/emirpasic/gods v1.18.1 // indirect
|
||||
|
||||
@@ -107,6 +107,8 @@ github.com/containerd/log v0.2.0 h1:BewD/umNgVnoczglOpX8eRMyEy5t5iPlu5AIpnWDONc=
|
||||
github.com/containerd/log v0.2.0/go.mod h1:/M7L7CXKcPTfNC74XzaK+5H5KbO5+4lJVpuVI6vRLoM=
|
||||
github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
|
||||
github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
|
||||
github.com/containerd/platforms v1.0.0-rc.5 h1:vXd569rDrz8LeMXzAnBsy6LADV5YtsD8oyaRarxdmSU=
|
||||
github.com/containerd/platforms v1.0.0-rc.5/go.mod h1:lKlMXyLybmBedS/JJm11uDofzI8L2v0J2ZbYvNsbq1A=
|
||||
github.com/containerd/typeurl/v2 v2.2.0/go.mod h1:8XOOxnyatxSWuG8OfsZXVnAF4iZfedjS/8UHSPJnX4g=
|
||||
github.com/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBqoWM=
|
||||
github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
|
||||
@@ -130,6 +132,8 @@ github.com/docker/go-connections v0.8.1 h1:JibmG5hULs5qXSr/cp/w3Pw5fZuStt4MOHMUE
|
||||
github.com/docker/go-connections v0.8.1/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q=
|
||||
github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
|
||||
github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
|
||||
github.com/docker/sandbox-kit-spec/v3 v3.0.0-m.6 h1:co7vn6GgImYEGO/KPlhPRJT9i5EPWgOKcB9q7bNJlFQ=
|
||||
github.com/docker/sandbox-kit-spec/v3 v3.0.0-m.6/go.mod h1:MrWO4PN3/VYC5xF8eyI8U82Nv/agTHcN4IUzheqA90c=
|
||||
github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg=
|
||||
github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI=
|
||||
github.com/ebitengine/purego v0.11.1 h1:2zpWRSQNVKN4eKsKO9eM1ILDgWfYMY9GwqRmK6XeQ/0=
|
||||
|
||||
@@ -0,0 +1,173 @@
|
||||
// Package kit decides whether archie can run a harness packaged as Kit v3
|
||||
// images, and what it runs with. Descriptor grammar, validation and
|
||||
// composition belong to the Kit spec package; this package owns only the
|
||||
// runtime's half of the contract: which capability types archie implements,
|
||||
// and the refusals that keep the host's guarantees intact.
|
||||
package kit
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/docker/sandbox-kit-spec/v3/spec"
|
||||
)
|
||||
|
||||
const (
|
||||
typeCredential = "com.docker.sandbox/credential@1"
|
||||
typeAgentSessions = "com.docker.sandbox/agent-sessions@1"
|
||||
|
||||
// contextPath is where the composed agent-context body is staged.
|
||||
contextPath = "/usr/share/archie/agent-context.md"
|
||||
)
|
||||
|
||||
// supported is every capability type archie provides. Anything else is
|
||||
// refused when required and skipped when optional: approximating a type
|
||||
// archie does not implement would grant a Kit something nobody reviewed.
|
||||
var supported = map[string]bool{
|
||||
typeCredential: true,
|
||||
"com.docker.sandbox/network-policy@1": true,
|
||||
"com.docker.sandbox/volume@1": true,
|
||||
"com.docker.sandbox/lifecycle@1": true,
|
||||
typeAgentSessions: true,
|
||||
"com.docker.sandbox/agent-skills@1": true,
|
||||
"com.docker.sandbox/agent-context@1": true,
|
||||
"com.docker.sandbox/resources@1": true,
|
||||
}
|
||||
|
||||
// forgeServices are credential services a harness never receives: the model
|
||||
// never runs git, so it never holds a credential that could push.
|
||||
var forgeServices = map[string]bool{
|
||||
"github": true,
|
||||
"gitlab": true,
|
||||
"gitea": true,
|
||||
"forgejo": true,
|
||||
"bitbucket": true,
|
||||
}
|
||||
|
||||
// Skip is an optional capability archie does not provide, recorded so the
|
||||
// step that ran without it can say so.
|
||||
type Skip struct {
|
||||
Type string
|
||||
Reason string
|
||||
}
|
||||
|
||||
// Refusal is a required capability archie will not provide.
|
||||
type Refusal struct {
|
||||
Type string
|
||||
Reason string
|
||||
}
|
||||
|
||||
// RefusedError carries every refusal, so an operator fixes a Kit in one pass.
|
||||
type RefusedError struct {
|
||||
Refusals []Refusal
|
||||
}
|
||||
|
||||
func (e *RefusedError) Error() string {
|
||||
parts := make([]string, len(e.Refusals))
|
||||
for i, r := range e.Refusals {
|
||||
parts[i] = r.Type + ": " + r.Reason
|
||||
}
|
||||
return "kit refused: " + strings.Join(parts, "; ")
|
||||
}
|
||||
|
||||
// Plan is what archie launches: the composed descriptor, the capabilities
|
||||
// it provides, and what it skipped.
|
||||
type Plan struct {
|
||||
Descriptor *spec.Descriptor
|
||||
Capabilities []spec.Capability
|
||||
Skipped []Skip
|
||||
Sessions *spec.AgentSessions
|
||||
ContextSources []spec.ContextSource
|
||||
}
|
||||
|
||||
// DecodePublished reads the descriptor from an image's manifest annotations
|
||||
// and holds it to the published form: strict decoding, full validation, and
|
||||
// no unexpanded build-phase args.
|
||||
func DecodePublished(annotations map[string]string) (*spec.Descriptor, error) {
|
||||
raw, ok := annotations[spec.AnnotationDescriptor]
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("image is not a kit: no %s annotation", spec.AnnotationDescriptor)
|
||||
}
|
||||
d, err := spec.Decode([]byte(raw))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if _, err := spec.ValidatePublished([]byte(raw), d); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return d, nil
|
||||
}
|
||||
|
||||
// Admit applies archie's capability support to one descriptor. Every
|
||||
// required capability archie will not provide is collected into a
|
||||
// RefusedError; optional ones are skipped.
|
||||
func Admit(d *spec.Descriptor) (*Plan, error) {
|
||||
plan := &Plan{Descriptor: d}
|
||||
var refusals []Refusal
|
||||
for _, c := range d.Capabilities {
|
||||
reason, err := refusalReason(c)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
switch {
|
||||
case reason == "":
|
||||
plan.Capabilities = append(plan.Capabilities, c)
|
||||
case c.Optional:
|
||||
plan.Skipped = append(plan.Skipped, Skip{Type: c.Type, Reason: reason})
|
||||
default:
|
||||
refusals = append(refusals, Refusal{Type: c.Type, Reason: reason})
|
||||
}
|
||||
}
|
||||
if len(refusals) > 0 {
|
||||
return nil, &RefusedError{Refusals: refusals}
|
||||
}
|
||||
return plan, nil
|
||||
}
|
||||
|
||||
// Compose merges one workload Kit and its mixins, in the order given, and
|
||||
// admits the result. archie drives a harness headlessly, so the composition
|
||||
// must carry an agent-sessions prompt verb.
|
||||
func Compose(contributions []spec.Contribution) (*Plan, error) {
|
||||
merged, err := spec.Merge(contributions, spec.MergeOptions{ContextPath: contextPath})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if merged.Descriptor.Kind != spec.KindWorkload {
|
||||
return nil, errors.New("kit composition has no workload: a harness needs exactly one base kit")
|
||||
}
|
||||
plan, err := Admit(merged.Descriptor)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
sessions, err := spec.AgentSessionsOf(plan.Capabilities)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if sessions == nil || len(sessions.Prompt) == 0 {
|
||||
return nil, fmt.Errorf("kit composition declares no %s prompt verb: archie cannot run it headlessly", typeAgentSessions)
|
||||
}
|
||||
plan.Sessions = sessions
|
||||
plan.ContextSources = merged.ContextSources
|
||||
return plan, nil
|
||||
}
|
||||
|
||||
func refusalReason(c spec.Capability) (string, error) {
|
||||
if !supported[c.Type] {
|
||||
return "not provided by archie", nil
|
||||
}
|
||||
if c.Type != typeCredential {
|
||||
return "", nil
|
||||
}
|
||||
var cred spec.Credential
|
||||
if err := spec.DecodeCapabilityConfig(c, &cred); err != nil {
|
||||
return "", err
|
||||
}
|
||||
if forgeServices[cred.Service] {
|
||||
return fmt.Sprintf("service %q is a forge credential; harnesses never hold one", cred.Service), nil
|
||||
}
|
||||
if cred.OAuth != nil && cred.OAuth.Passthrough {
|
||||
return fmt.Sprintf("service %q asks for OAuth passthrough; real tokens never enter the container", cred.Service), nil
|
||||
}
|
||||
return "", nil
|
||||
}
|
||||
@@ -0,0 +1,237 @@
|
||||
package kit
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"slices"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/docker/sandbox-kit-spec/v3/spec"
|
||||
)
|
||||
|
||||
const sessions = `
|
||||
- type: com.docker.sandbox/agent-sessions@1
|
||||
config:
|
||||
prompt: [-p, "{{.Prompt}}"]
|
||||
resume: [--resume, "{{.SessionID}}"]`
|
||||
|
||||
func descriptor(t *testing.T, kind, capabilities string) *spec.Descriptor {
|
||||
t.Helper()
|
||||
d, err := spec.Decode([]byte("schemaVersion: \"3\"\nkind: " + kind + "\ncapabilities:" + capabilities + "\n"))
|
||||
if err != nil {
|
||||
t.Fatalf("fixture does not decode: %v", err)
|
||||
}
|
||||
return d
|
||||
}
|
||||
|
||||
func refusedTypes(t *testing.T, err error) []string {
|
||||
t.Helper()
|
||||
var refused *RefusedError
|
||||
if !errors.As(err, &refused) {
|
||||
t.Fatalf("want *RefusedError, got %v", err)
|
||||
}
|
||||
var types []string
|
||||
for _, r := range refused.Refusals {
|
||||
types = append(types, r.Type)
|
||||
}
|
||||
return types
|
||||
}
|
||||
|
||||
func TestAdmit(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
capabilities string
|
||||
wantRefused []string
|
||||
wantSkipped []string
|
||||
wantAdmitted int
|
||||
}{
|
||||
{
|
||||
name: "every supported type is admitted",
|
||||
capabilities: sessions + `
|
||||
- type: com.docker.sandbox/network-policy@1
|
||||
config: {runtime: {allow: [api.example.com:443]}}
|
||||
- type: com.docker.sandbox/credential@1
|
||||
config:
|
||||
service: example
|
||||
phase: runtime
|
||||
apiKey: {name: EXAMPLE_KEY, proxyManaged: true, inject: [{domain: api.example.com, header: Authorization, format: "Bearer %s"}]}
|
||||
- type: com.docker.sandbox/volume@1
|
||||
config: {path: /home/agent/.state, size: 1g}
|
||||
- type: com.docker.sandbox/lifecycle@1
|
||||
config: {startup: [{command: [true]}]}
|
||||
- type: com.docker.sandbox/agent-skills@1
|
||||
config: {path: /home/agent/.skills}
|
||||
- type: com.docker.sandbox/agent-context@1
|
||||
config: {content: be terse}
|
||||
- type: com.docker.sandbox/resources@1
|
||||
config: {memory: 2g}`,
|
||||
wantAdmitted: 8,
|
||||
},
|
||||
{
|
||||
name: "a required unsupported type refuses the launch",
|
||||
capabilities: sessions + "\n - type: com.docker.sandbox/privileged@1",
|
||||
wantRefused: []string{"com.docker.sandbox/privileged@1"},
|
||||
},
|
||||
{
|
||||
name: "an optional unsupported type is skipped and recorded",
|
||||
capabilities: sessions + `
|
||||
- type: com.docker.sandbox/port@1
|
||||
optional: true
|
||||
config: {port: 8080}`,
|
||||
wantSkipped: []string{"com.docker.sandbox/port@1"},
|
||||
wantAdmitted: 1,
|
||||
},
|
||||
{
|
||||
name: "network-policy@2 is refused",
|
||||
capabilities: sessions + `
|
||||
- type: com.docker.sandbox/network-policy@2
|
||||
config: {runtime: {allow: [api.example.com]}}`,
|
||||
wantRefused: []string{"com.docker.sandbox/network-policy@2"},
|
||||
},
|
||||
{
|
||||
name: "a host-specific type archie does not know is refused",
|
||||
capabilities: sessions + `
|
||||
- type: example.com/gpu-broker@1
|
||||
config: {pool: a}`,
|
||||
wantRefused: []string{"example.com/gpu-broker@1"},
|
||||
},
|
||||
{
|
||||
name: "a credential with passthrough is refused",
|
||||
capabilities: sessions + `
|
||||
- type: com.docker.sandbox/network-policy@1
|
||||
config: {runtime: {allow: [api.example.com]}}
|
||||
- type: com.docker.sandbox/credential@1
|
||||
config:
|
||||
service: example
|
||||
phase: runtime
|
||||
oauth: {tokenEndpoint: {host: api.example.com}, passthrough: true}`,
|
||||
wantRefused: []string{"com.docker.sandbox/credential@1"},
|
||||
},
|
||||
{
|
||||
name: "an optional forge credential is skipped, never bound",
|
||||
capabilities: sessions + `
|
||||
- type: com.docker.sandbox/network-policy@1
|
||||
config: {runtime: {allow: [api.github.com]}}
|
||||
- type: com.docker.sandbox/credential@1
|
||||
optional: true
|
||||
config:
|
||||
service: github
|
||||
phase: runtime
|
||||
apiKey: {name: GH_TOKEN, proxyManaged: true, inject: [{domain: api.github.com, header: Authorization, format: "Bearer %s"}]}`,
|
||||
wantSkipped: []string{"com.docker.sandbox/credential@1"},
|
||||
wantAdmitted: 2,
|
||||
},
|
||||
{
|
||||
name: "every refusal is reported, not only the first",
|
||||
capabilities: sessions + `
|
||||
- type: com.docker.sandbox/privileged@1
|
||||
- type: com.docker.sandbox/long-running@1`,
|
||||
wantRefused: []string{"com.docker.sandbox/privileged@1", "com.docker.sandbox/long-running@1"},
|
||||
},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
plan, err := Admit(descriptor(t, spec.KindWorkload, tt.capabilities))
|
||||
if tt.wantRefused != nil {
|
||||
if got := refusedTypes(t, err); !slices.Equal(got, tt.wantRefused) {
|
||||
t.Fatalf("refused %v, want %v", got, tt.wantRefused)
|
||||
}
|
||||
return
|
||||
}
|
||||
if err != nil {
|
||||
t.Fatalf("Admit: %v", err)
|
||||
}
|
||||
var skipped []string
|
||||
for _, s := range plan.Skipped {
|
||||
skipped = append(skipped, s.Type)
|
||||
}
|
||||
if !slices.Equal(skipped, tt.wantSkipped) {
|
||||
t.Fatalf("skipped %v, want %v", skipped, tt.wantSkipped)
|
||||
}
|
||||
if len(plan.Capabilities) != tt.wantAdmitted {
|
||||
t.Fatalf("admitted %d capabilities, want %d", len(plan.Capabilities), tt.wantAdmitted)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestRefusalNamesTheCapability(t *testing.T) {
|
||||
_, err := Admit(descriptor(t, spec.KindWorkload, sessions+"\n - type: com.docker.sandbox/usb-device@1\n config: {class: hid}"))
|
||||
if err == nil || !strings.Contains(err.Error(), "com.docker.sandbox/usb-device@1") {
|
||||
t.Fatalf("error %v does not name the refused capability", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCompose(t *testing.T) {
|
||||
workload := spec.Contribution{Reference: "workload", Descriptor: descriptor(t, spec.KindWorkload, sessions)}
|
||||
mixin := spec.Contribution{Reference: "mixin", Descriptor: descriptor(t, spec.KindMixin, `
|
||||
- type: com.docker.sandbox/network-policy@1
|
||||
config: {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"}]}`)}
|
||||
bareWorkload := spec.Contribution{Reference: "bare", Descriptor: descriptor(t, spec.KindWorkload, `
|
||||
- type: com.docker.sandbox/resources@1
|
||||
config: {memory: 1g}`)}
|
||||
|
||||
t.Run("a workload and its mixins compose into one plan", func(t *testing.T) {
|
||||
plan, err := Compose([]spec.Contribution{workload, mixin})
|
||||
if err != nil {
|
||||
t.Fatalf("Compose: %v", err)
|
||||
}
|
||||
if !spec.HasCapability(plan.Capabilities, typeCredential) {
|
||||
t.Fatal("the mixin's credential did not reach the plan")
|
||||
}
|
||||
if plan.Sessions == nil || len(plan.Sessions.Prompt) == 0 {
|
||||
t.Fatal("the plan carries no headless prompt verb")
|
||||
}
|
||||
})
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
contributions []spec.Contribution
|
||||
want string
|
||||
}{
|
||||
{"no workload", []spec.Contribution{mixin}, "no workload"},
|
||||
{"no headless prompt verb", []spec.Contribution{bareWorkload}, "agent-sessions"},
|
||||
{"two workloads", []spec.Contribution{workload, bareWorkload}, "workload"},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name+" is refused", func(t *testing.T) {
|
||||
_, err := Compose(tt.contributions)
|
||||
if err == nil || !strings.Contains(err.Error(), tt.want) {
|
||||
t.Fatalf("error %v, want one mentioning %q", err, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestDecodePublished(t *testing.T) {
|
||||
published := "schemaVersion: \"3\"\nkind: workload\ncapabilities:" + sessions + "\n"
|
||||
tests := []struct {
|
||||
name string
|
||||
annotations map[string]string
|
||||
wantErr string
|
||||
}{
|
||||
{"a published descriptor decodes", map[string]string{spec.AnnotationDescriptor: published}, ""},
|
||||
{"an image without the annotation is not a kit", map[string]string{"org.opencontainers.image.title": "x"}, "not a kit"},
|
||||
{"an unknown field is an error", map[string]string{spec.AnnotationDescriptor: published + "surprise: true\n"}, "surprise"},
|
||||
{"an unexpanded build arg is not a published form", map[string]string{spec.AnnotationDescriptor: "schemaVersion: \"3\"\nkind: workload\nversion: \"${{ kit.args.version }}\"\n"}, "version"},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
d, err := DecodePublished(tt.annotations)
|
||||
if tt.wantErr == "" {
|
||||
if err != nil || d == nil {
|
||||
t.Fatalf("DecodePublished: %v", err)
|
||||
}
|
||||
return
|
||||
}
|
||||
if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
|
||||
t.Fatalf("error %v, want one mentioning %q", err, tt.wantErr)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user