Repository navigation
docs(cmd): Describe every resource field in help - #534
Open
dragosgheorghioiu wants to merge 1 commit into
Open
dragosgheorghioiu wants to merge 1 commit into
dragosgheorghioiu wants to merge 1 commit into
Conversation
dragosgheorghioiu
force-pushed
the
dragosg/docs/resource-field-help
branch
2 times, most recently
from
October 7, 2026 11:40
599add7 to
f95ab85
Compare
dragosgheorghioiu
force-pushed
the
dragosg/docs/resource-field-help
branch
from
October 7, 2026 12:12
f95ab85 to
9ebcf0e
Compare
jedevc
reviewed
Oct 7, 2026
Most resource fields had no help text, so --help and the fields reference showed bare names such as state or vcpus, and tools that read the field list had nothing to explain a value with. Give each field of the resource structs a help tag, and keep the help and example tags on resource.Field so that help output, the fields reference and tool schemas share one description. Signed-off-by: Dragos Gheorghioiu <dragosg@unikraft.com>
dragosgheorghioiu
force-pushed
the
dragosg/docs/resource-field-help
branch
from
October 8, 2026 06:19
9ebcf0e to
87c2bdd
Compare
jedevc
reviewed
Oct 9, 2026
| Image types.ImageRef `mirror:"instance.image" field:",short" create:"set" edit:"set" flag:"image" help:"Image to deploy." placeholder:"<name>:<tag>" example:"nginx:latest,my-app:v1.2.3"` | ||
| PullPolicy *platform.PullPolicy `field:"pull-policy,invisible,valueless" create:"set" flag:"pull-policy" help:"Image pull policy." placeholder:"policy" example:"always,never,if_not_present"` | ||
| Type_ *platform.InstanceType `mirror:"instance.type" field:"type,long" create:"set" flag:"type" help:"Type of virtual machine to run. \"full\" requires a plan with full VM support." placeholder:"type" example:"micro,full"` | ||
| Image types.ImageRef `mirror:"instance.image" field:",short" create:"set" edit:"set" flag:"image" help:"Image to deploy, as an OCI reference or a full registry URL. Required unless template, branch or checkpoint is given, and cannot be combined with them." placeholder:"<name>:<tag>" example:"nginx:latest,my-app:v1.2.3"` |
Member
There was a problem hiding this comment.
ai suggestion: This help is shared with edit, where "required unless template, branch or checkpoint is given" is wrong - none of those exist on edit. Same for --memory telling edit users about the 128MiB default. Can we keep the create-only clauses out of fields that are edit:"set" too?
$ sed -n '/^Edit flags:/,/^$/p' cmd/unikraft/testdata/TestHelp/instances | grep -A1 -- '--image='
--image=<name>:<tag>
Image to deploy, as an OCI reference or a full registry URL. Required unless template, branch or checkpoint is given, and cannot be combined with them.
(also at internal/cmd/instances.go:118)
| example.com: a dotted name is a custom domain, with a certificate issued automatically unless given as name=example.com,certificate=my-cert. | ||
| [examples: example.com, myapp] | ||
| -v, --volume=[<name>]:<path>[:<options>] ... | ||
| Volume to attach as NAME:/MOUNT[:ro], where the mount path must be absolute. On create, add :size=SIZE to make a new volume with the instance, and leave NAME empty to have one generated. Up to 4 per instance. |
Member
There was a problem hiding this comment.
follow-up: Not this PR's fault, but kingkong doesn't wrap help at the terminal width, so these now run to ~270 columns on an 80-col terminal. Lines over 80 in this golden went from 32 to 141. Maybe worth adding wrapping in kingkong to the size of the terminal?
| Name string `mirror:"instance.name" field:",short" create:"set" flag:"name" short:"n" help:"Instance name." placeholder:"name"` | ||
| UUID string `mirror:"instance.uuid" field:",long"` | ||
| Metro LinkName[Metro] `field:"metro,short" create:"set,required" flag:"metro" help:"Metro to deploy in. Defaults to the profile's default metro." placeholder:"metro" example:"fra,sfo"` | ||
| Name string `mirror:"instance.name" field:",short" create:"set" flag:"name" short:"n" help:"Instance name: a lowercase DNS label of up to 118 characters, unique per metro. Generated from the image name when omitted." placeholder:"name"` |
Member
There was a problem hiding this comment.
nit: Where does 118 come from? The SDK only says "must be unique" and "a random name will be generated", not derived from the image. Not sure about the magic numbers throughout this PR generally.
(also at internal/cmd/instance_templates.go:41, internal/cmd/instance_checkpoints.go:44)
| Tags []string `mirror:"volume.tags" field:",long" create:"set" edit:"set,add,del" flag:"tag" sep:"none" help:"Tags for grouping and filtering: up to 16, each 1 to 256 characters of letters, digits and -+_.:=. Not visible to the guest." placeholder:"tag" example:"env-prod"` | ||
|
|
||
| State types.VolumeState `mirror:"volume.state" field:",short" help:"Lifecycle state: available (not attached), idle (attached to a stopped instance), mounted (in use by a running instance), busy (clone or resize in progress), uninitialized, initializing, error or template."` | ||
| Usage types.MeterUsage[types.SizeMebibytes] `field:"usage,short" help:"Used space (MiB)."` |
Member
There was a problem hiding this comment.
nit: usage renders as a percentage and a bar, not MiB. free already prints its own unit too.
$ grep -n 'usage\|free' internal/cmd/testdata/TestOutput/volumes | head -2
7:usage: 80% ⣿⣿⣿⣿⣿⣿⣿⣿⣀⣀
8:free: 10MiB
(also at internal/cmd/volumes.go:197)
| Persistent bool `mirror:"volume.persistent" field:",long"` | ||
| AccessMode *types.AccessMode `mirror:"volume.access_mode" field:",long" create:"set" flag:"access-mode" help:"Volume access mode." placeholder:"access-mode" example:"rwo,rox,rwx"` | ||
| Metro LinkName[Metro] `field:"metro,short" create:"set,required" flag:"metro" help:"Metro to create in. Defaults to the profile's default metro." placeholder:"metro" example:"fra,sfo"` | ||
| Name string `mirror:"volume.name" field:",short" create:"set" flag:"name" short:"n" help:"Volume name, unique per metro. Generated as vol-XXXX when omitted." placeholder:"name"` |
Member
There was a problem hiding this comment.
nit: SDK says the suffix is 5 characters, so vol-XXXXX? Or just "Generated when omitted" like the other resources, then it can't drift.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Most resource fields had no help text, so
--helpand the fields reference showed bare names such asstateorvcpus, and anything reading the field list, such as a tool schema, had nothing to explain a value with.This gives every field of the resource structs (certificates, images, instances, checkpoints, templates, metros, services, volumes) a
helptag, and keeps thehelpandexampletags onresource.Fieldso that help output, the fields reference and generated schemas share one description.