Add crictl [create,runp,run,pull] jsonschema subcommands

The `jsonschema` / `js` subcommands will print the pod and/or container config JSON schemas for end users to understand where the data is coming from. Signed-off-by: Sascha Grunert <[email protected]>
kubernetes-sigs · Jun 11, 2024 · 63e11d5 · 63e11d5
1 parent fa6c0a3
commit 63e11d5
Show file tree

Hide file tree

Showing 47 changed files with 6,222 additions and 6 deletions.
diff --git a/cmd/crictl/container.go b/cmd/crictl/container.go
@@ -139,6 +139,44 @@ var runPullFlags = []cli.Flag{
 	},
 }
 
+var subcommands = []*cli.Command{{
+	Name:    "jsonschema",
+	Aliases: []string{"js"},
+	Usage:   "Display the JSON schema for the pod or container config",
+	Flags: []cli.Flag{
+		&cli.BoolFlag{
+			Name:    "pod",
+			Aliases: []string{"p"},
+			Usage:   "Print the pod JSON schema, which will be generated from the PodSandboxConfig of the CRI API",
+		},
+		&cli.BoolFlag{
+			Name:    "container",
+			Aliases: []string{"c"},
+			Usage:   "Print the container JSON schema, which will be generated from the ContainerConfig of the CRI API",
+		},
+	},
+	UseShortOptionHandling: true,
+	Action: func(c *cli.Context) error {
+		if !c.IsSet("pod") && !c.IsSet("container") {
+			return cli.ShowSubcommandHelp(c)
+		}
+
+		if c.IsSet("pod") {
+			if err := printJSONSchema(&pb.PodSandboxConfig{}); err != nil {
+				return fmt.Errorf("print pod sandbox config JSON schema: %w", err)
+			}
+		}
+
+		if c.IsSet("container") {
+			if err := printJSONSchema(&pb.ContainerConfig{}); err != nil {
+				return fmt.Errorf("print container config JSON schema: %w", err)
+			}
+		}
+
+		return nil
+	},
+}}
+
 var createContainerCommand = &cli.Command{
 	Name:      "create",
 	Usage:     "Create a new container",
@@ -148,7 +186,7 @@ var createContainerCommand = &cli.Command{
 		Aliases: []string{"T"},
 		Usage:   "Seconds to wait for a container create request to complete before cancelling the request",
 	}),
-
+	Subcommands: subcommands,
 	Action: func(c *cli.Context) (err error) {
 		if c.Args().Len() != 3 {
 			return cli.ShowSubcommandHelp(c)
@@ -590,7 +628,7 @@ var runContainerCommand = &cli.Command{
 		Aliases: []string{"t"},
 		Usage:   "Seconds to wait for a container create request before cancelling the request",
 	}),
-
+	Subcommands: subcommands,
 	Action: func(c *cli.Context) (err error) {
 		if c.Args().Len() != 2 {
 			return cli.ShowSubcommandHelp(c)

diff --git a/cmd/crictl/image.go b/cmd/crictl/image.go
@@ -84,6 +84,15 @@ var pullImageCommand = &cli.Command{
 			Usage:   "Annotation to be set on the pulled image",
 		},
 	},
+	Subcommands: []*cli.Command{{
+		Name:      "jsonschema",
+		Aliases:   []string{"js"},
+		Usage:     "Display the JSON schema for the pod-config.json",
+		UsageText: "The schema will be generated from the PodSandboxConfig of the CRI API",
+		Action: func(c *cli.Context) error {
+			return printJSONSchema(&pb.PodSandboxConfig{})
+		},
+	}},
 	ArgsUsage: "NAME[:TAG|@DIGEST]",
 	Action: func(c *cli.Context) error {
 		imageName := c.Args().First()

diff --git a/cmd/crictl/sandbox.go b/cmd/crictl/sandbox.go
@@ -50,6 +50,15 @@ var runPodCommand = &cli.Command{
 	Name:      "runp",
 	Usage:     "Run a new pod",
 	ArgsUsage: "pod-config.[json|yaml]",
+	Subcommands: []*cli.Command{{
+		Name:      "jsonschema",
+		Aliases:   []string{"js"},
+		Usage:     "Display the JSON schema for the pod-config.json",
+		UsageText: "The schema will be generated from the PodSandboxConfig of the CRI API",
+		Action: func(c *cli.Context) error {
+			return printJSONSchema(&pb.PodSandboxConfig{})
+		},
+	}},
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name:    "runtime",

diff --git a/cmd/crictl/util.go b/cmd/crictl/util.go
@@ -33,6 +33,7 @@ import (
 
 	"github.com/golang/protobuf/jsonpb" //nolint:staticcheck
 	"github.com/golang/protobuf/proto"  //nolint:staticcheck
+	"github.com/invopop/jsonschema"
 	utilyaml "k8s.io/apimachinery/pkg/util/yaml"
 	internalapi "k8s.io/cri-api/pkg/apis"
 	pb "k8s.io/cri-api/pkg/apis/runtime/v1"
@@ -170,6 +171,16 @@ func loadContainerConfig(path string) (*pb.ContainerConfig, error) {
 	return &config, nil
 }
 
+func printJSONSchema(typ any) error {
+	schema := jsonschema.Reflect(typ)
+	data, err := json.MarshalIndent(schema, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshal JSON schema: %w", err)
+	}
+	fmt.Println(string(data))
+	return nil
+}
+
 func loadPodSandboxConfig(path string) (*pb.PodSandboxConfig, error) {
 	f, err := openFile(path)
 	if err != nil {

diff --git a/docs/crictl.1 b/docs/crictl.1
@@ -6,6 +6,11 @@
 \fB\fCcrictl\fR has been GA since \fB\fCv1.11.0\fR and is currently under active development. It is hosted at the cri\-tools
 \[la]https://github.com/kubernetes-sigs/cri-tools\[ra] repository. We encourage the CRI developers to report bugs or help extend the coverage by adding more functionalities.
 
+.PP
+The tool expects JSON or YAML encoded files as input and passes them to the
+corresponding container runtime using the CRI API protocol
+\[la]/vendor/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto\[ra]\&.
+
 .SH Install crictl
 .PP
 .RS
@@ -28,7 +33,7 @@ using \fB\fCwget\fR:
 .RS
 
 .nf
-VERSION="v1.26.0" # check latest version in /releases page
+VERSION="v1.30.0" # check latest version in /releases page
 wget https://github.com/kubernetes\-sigs/cri\-tools/releases/download/$VERSION/crictl\-$VERSION\-linux\-amd64.tar.gz
 sudo tar zxvf crictl\-$VERSION\-linux\-amd64.tar.gz \-C /usr/local/bin
 rm \-f crictl\-$VERSION\-linux\-amd64.tar.gz
@@ -43,7 +48,7 @@ using \fB\fCcurl\fR:
 .RS
 
 .nf
-VERSION="v1.26.0" # check latest version in /releases page
+VERSION="v1.30.0" # check latest version in /releases page
 curl \-L https://github.com/kubernetes\-sigs/cri\-tools/releases/download/$VERSION/crictl\-${VERSION}\-linux\-amd64.tar.gz \-\-output crictl\-${VERSION}\-linux\-amd64.tar.gz
 sudo tar zxvf crictl\-$VERSION\-linux\-amd64.tar.gz \-C /usr/local/bin
 rm \-f crictl\-$VERSION\-linux\-amd64.tar.gz

diff --git a/docs/crictl.md b/docs/crictl.md
@@ -4,6 +4,9 @@
 
 `crictl` has been GA since `v1.11.0` and is currently under active development. It is hosted at the [cri-tools](https://github.com/kubernetes-sigs/cri-tools) repository. We encourage the CRI developers to report bugs or help extend the coverage by adding more functionalities.
 
+The tool expects JSON or YAML encoded files as input and passes them to the
+corresponding container runtime using the [CRI API protocol](/vendor/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto).
+
 ## Install crictl
 
 > **NOTE:** The below steps are based on linux-amd64, however you can get downloads for all other platforms (Windows, ARM, etc) in the [releases page](https://github.com/kubernetes-sigs/cri-tools/releases).
@@ -13,7 +16,7 @@
 - using `wget`:
 
 ```sh
-VERSION="v1.26.0" # check latest version in /releases page
+VERSION="v1.30.0" # check latest version in /releases page
 wget https://github.com/kubernetes-sigs/cri-tools/releases/download/$VERSION/crictl-$VERSION-linux-amd64.tar.gz
 sudo tar zxvf crictl-$VERSION-linux-amd64.tar.gz -C /usr/local/bin
 rm -f crictl-$VERSION-linux-amd64.tar.gz
@@ -22,7 +25,7 @@ rm -f crictl-$VERSION-linux-amd64.tar.gz
 - using `curl`:
 
 ```sh
-VERSION="v1.26.0" # check latest version in /releases page
+VERSION="v1.30.0" # check latest version in /releases page
 curl -L https://github.com/kubernetes-sigs/cri-tools/releases/download/$VERSION/crictl-${VERSION}-linux-amd64.tar.gz --output crictl-${VERSION}-linux-amd64.tar.gz
 sudo tar zxvf crictl-$VERSION-linux-amd64.tar.gz -C /usr/local/bin
 rm -f crictl-$VERSION-linux-amd64.tar.gz

diff --git a/go.mod b/go.mod
@@ -10,6 +10,7 @@ require (
 	github.com/docker/go-units v0.5.0
 	github.com/golang/protobuf v1.5.4
 	github.com/google/uuid v1.6.0
+	github.com/invopop/jsonschema v0.12.0
 	github.com/moby/term v0.5.0
 	github.com/onsi/ginkgo/v2 v2.19.0
 	github.com/onsi/gomega v1.33.1
@@ -41,8 +42,10 @@ require (
 require (
 	github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
 	github.com/Microsoft/go-winio v0.6.0 // indirect
+	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/blang/semver/v4 v4.0.0 // indirect
+	github.com/buger/jsonparser v1.1.1 // indirect
 	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.2.0 // indirect
 	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
@@ -61,6 +64,7 @@ require (
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.20.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/liggitt/tabwriter v0.0.0-20181228230101-89fcab3d43de // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mitchellh/go-wordwrap v1.0.1 // indirect
 	github.com/moby/spdystream v0.2.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
@@ -72,6 +76,7 @@ require (
 	github.com/prometheus/procfs v0.12.0 // indirect
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
+	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	github.com/xrash/smetrics v0.0.0-20240312152122-5f08fbb34913 // indirect
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.46.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.44.0 // indirect

diff --git a/go.sum b/go.sum
@@ -7,10 +7,14 @@ github.com/Microsoft/go-winio v0.6.0 h1:slsWYD/zyx7lCXoZVlvQrj0hPTM1HI4+v1sIda2y
 github.com/Microsoft/go-winio v0.6.0/go.mod h1:cTAf44im0RAYeL23bpB+fzCyDH2MJiz2BO69KH/soAE=
 github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio=
 github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
+github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
+github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
 github.com/blang/semver/v4 v4.0.0 h1:1PFHFE6yCCTv8C1TeyNNarDzntLi7wMI5i/pzqYIsAM=
 github.com/blang/semver/v4 v4.0.0/go.mod h1:IbckMUScFkM3pff0VJDNKRiT6TG/YpiHIM2yvyW5YoQ=
+github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs=
+github.com/buger/jsonparser v1.1.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
 github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
 github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
 github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
@@ -75,6 +79,8 @@ github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWm
 github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.20.0 h1:bkypFPDjIYGfCYD5mRBvpqxfYX1YCS1PXdKYWi8FsN0=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.20.0/go.mod h1:P+Lt/0by1T8bfcF3z737NnSbmxQAppXMRziHUxPOC8k=
+github.com/invopop/jsonschema v0.12.0 h1:6ovsNSuvn9wEQVOyc72aycBMVQFKz7cPdMJn10CvzRI=
+github.com/invopop/jsonschema v0.12.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
@@ -140,6 +146,8 @@ github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsT
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/urfave/cli/v2 v2.27.2 h1:6e0H+AkS+zDckwPCUrZkKX38mRaau4nL2uipkJpbkcI=
 github.com/urfave/cli/v2 v2.27.2/go.mod h1:g0+79LmHHATl7DAcHO99smiR/T7uGLw84w8Y42x+4eM=
+github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
+github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
 github.com/xrash/smetrics v0.0.0-20240312152122-5f08fbb34913 h1:+qGGcbkzsfDQNPPe9UDgpxAWQrhbbBXOYJFQDq/dtJw=
 github.com/xrash/smetrics v0.0.0-20240312152122-5f08fbb34913/go.mod h1:4aEEwZQutDLsQv2Deui4iYQ6DWTxR14g6m8Wv88+Xqk=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=

diff --git a/test/e2e/pull_test.go b/test/e2e/pull_test.go
@@ -56,6 +56,10 @@ var _ = t.Describe("pull", func() {
 		t.CrictlExpectSuccess("pull -h", "Pull an image")
 	})
 
+	It("should succeed to generate the JSON schema", func() {
+		t.CrictlExpectSuccess("pull jsonschema", "PodSandboxConfig")
+	})
+
 	It("should fail on not existing image", func() {
 		t.CrictlExpectFailure("pull localhost/wrong", "", "pulling image")
 	})

diff --git a/vendor/github.com/bahlo/generic-list-go/LICENSE b/vendor/github.com/bahlo/generic-list-go/LICENSE
diff --git a/vendor/github.com/bahlo/generic-list-go/README.md b/vendor/github.com/bahlo/generic-list-go/README.md