From b93e1d0b4a2ee235de035d6f03fdec606ab8dd19 Mon Sep 17 00:00:00 2001 From: Jason Hall Date: Tue, 28 Sep 2021 13:24:16 -0400 Subject: [PATCH 1/2] Add 'ko build' as a preferred alias for 'ko publish' --- README.md | 18 ++++---- doc/ko.md | 2 +- doc/ko_build.md | 66 +++++++++++++++++++++++++++ doc/ko_run.md | 2 +- integration_test.sh | 14 +++--- pkg/build/gobuild.go | 4 +- pkg/commands/{publish.go => build.go} | 27 +++++------ pkg/commands/commands.go | 2 +- pkg/commands/run.go | 2 +- 9 files changed, 102 insertions(+), 35 deletions(-) create mode 100644 doc/ko_build.md rename pkg/commands/{publish.go => build.go} (76%) diff --git a/README.md b/README.md index 63592e08b9..30b738b52a 100644 --- a/README.md +++ b/README.md @@ -69,29 +69,29 @@ e.g.: # Build an Image -`ko publish ./cmd/app` builds and pushes a container image, and prints the +`ko build ./cmd/app` builds and pushes a container image, and prints the resulting image digest to stdout. ``` -ko publish ./cmd/app +ko build ./cmd/app ... gcr.io/my-project/app-099ba5bcefdead87f92606265fb99ac0@sha256:6e398316742b7aa4a93161dce4a23bc5c545700b862b43347b941000b112ec3e ``` -Because the output of `ko publish` is an image reference, you can easily pass it +Because the output of `ko build` is an image reference, you can easily pass it to other tools that expect to take an image reference: To run the container: ``` -docker run -p 8080:8080 $(ko publish ./cmd/app) +docker run -p 8080:8080 $(ko build ./cmd/app) ``` Or, for example, to deploy it to other services like [Cloud Run](https://cloud.google.com/run): ``` -gcloud run deploy --image=$(ko publish ./cmd/app) +gcloud run deploy --image=$(ko build ./cmd/app) ``` ## Configuration @@ -168,7 +168,7 @@ templating support is currently limited to environment variables only. workaround certain registry limitations and user preferences: Given `KO_DOCKER_REPO=registry.example.com/repo`, by default, -`ko publish ./cmd/app` will produce an image named like +`ko build ./cmd/app` will produce an image named like `registry.example.com/repo/app-`, which includes the MD5 hash of the full import path, to avoid collisions. @@ -311,7 +311,7 @@ With this small change, running `ko resolve -f deployment.yaml` will instruct `ko` to: 1. scan the YAML file(s) for values with the `ko://` prefix, -2. for each unique `ko://`-prefixed string, execute `ko publish ` to +2. for each unique `ko://`-prefixed string, execute `ko build ` to build and push an image, 3. replace `ko://`-prefixed string(s) in the input YAML with the fully-specified image reference of the built image(s), for example: @@ -375,7 +375,7 @@ this flag directly; however, you can use the `GOFLAGS` environment variable instead: ```sh -GOFLAGS="-ldflags=-X=main.version=1.2.3" ko publish . +GOFLAGS="-ldflags=-X=main.version=1.2.3" ko build . ``` ## How can I set multiple `ldflags`? @@ -421,7 +421,7 @@ You can try out building a Windows container image by [setting the base image](# For example, to build a Windows container image for `ko`, from within this repo: ``` -KO_DEFAULTBASEIMAGE=mcr.microsoft.com/windows/nanoserver:1809 ko publish ./ --platform=windows/amd64 +KO_DEFAULTBASEIMAGE=mcr.microsoft.com/windows/nanoserver:1809 ko build ./ --platform=windows/amd64 ``` ### Known issues 🐛 diff --git a/doc/ko.md b/doc/ko.md index 8e66263c4e..c835801fb2 100644 --- a/doc/ko.md +++ b/doc/ko.md @@ -15,12 +15,12 @@ ko [flags] ### SEE ALSO * [ko apply](ko_apply.md) - Apply the input files with image references resolved to built/pushed image digests. +* [ko build](ko_build.md) - Build and publish container images from the given importpaths. * [ko completion](ko_completion.md) - Output shell completion code (default Bash) * [ko create](ko_create.md) - Create the input files with image references resolved to built/pushed image digests. * [ko delete](ko_delete.md) - See "kubectl help delete" for detailed usage. * [ko deps](ko_deps.md) - Print Go module dependency information about the ko-built binary in the image * [ko login](ko_login.md) - Log in to a registry -* [ko publish](ko_publish.md) - Build and publish container images from the given importpaths. * [ko resolve](ko_resolve.md) - Print the input files with image references resolved to built/pushed image digests. * [ko run](ko_run.md) - A variant of `kubectl run` that containerizes IMPORTPATH first. * [ko version](ko_version.md) - Print ko version. diff --git a/doc/ko_build.md b/doc/ko_build.md new file mode 100644 index 0000000000..1216fcdf8f --- /dev/null +++ b/doc/ko_build.md @@ -0,0 +1,66 @@ +## ko build + +Build and publish container images from the given importpaths. + +### Synopsis + +This sub-command builds the provided import paths into Go binaries, containerizes them, and publishes them. + +``` +ko build IMPORTPATH... [flags] +``` + +### Examples + +``` + + # Build and publish import path references to a Docker + # Registry as: + # ${KO_DOCKER_REPO}/- + # When KO_DOCKER_REPO is ko.local, it is the same as if + # --local and --preserve-import-paths were passed. + ko build github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah + + # Build and publish a relative import path as: + # ${KO_DOCKER_REPO}/- + # When KO_DOCKER_REPO is ko.local, it is the same as if + # --local and --preserve-import-paths were passed. + ko build ./cmd/blah + + # Build and publish a relative import path as: + # ${KO_DOCKER_REPO}/ + # When KO_DOCKER_REPO is ko.local, it is the same as if + # --local was passed. + ko build --preserve-import-paths ./cmd/blah + + # Build and publish import path references to a Docker + # daemon as: + # ko.local/ + # This always preserves import paths. + ko build --local github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah +``` + +### Options + +``` + --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags). + -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags). + --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container. + -h, --help help for build + --image-label strings Which labels (key=value) to add to the image. + --insecure-registry Whether to skip TLS verification on the registry + -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS) + -L, --local Load into images to local docker daemon. + --oci-layout-path string Path to save the OCI image layout of the built images + --platform string Which platform to use when pulling a multi-platform base. Format: all | [/[/]][,platform]* + -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO. + --push Push images to KO_DOCKER_REPO (default true) + --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated. + -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest]) + --tarball string File to save images tarballs +``` + +### SEE ALSO + +* [ko](ko.md) - Rapidly iterate with Go, Containers, and Kubernetes. + diff --git a/doc/ko_run.md b/doc/ko_run.md index ed3a3111ea..0cde6d7e19 100644 --- a/doc/ko_run.md +++ b/doc/ko_run.md @@ -4,7 +4,7 @@ A variant of `kubectl run` that containerizes IMPORTPATH first. ### Synopsis -This sub-command combines "ko publish" and "kubectl run" to support containerizing and running Go binaries on Kubernetes in a single command. +This sub-command combines "ko build" and "kubectl run" to support containerizing and running Go binaries on Kubernetes in a single command. ``` ko run IMPORTPATH [flags] diff --git a/integration_test.sh b/integration_test.sh index fe630d96fa..7e0c7853e3 100755 --- a/integration_test.sh +++ b/integration_test.sh @@ -36,7 +36,7 @@ echo "Beginning scenarios." FILTER="[^ ]local[^ ]*" echo "1. GOPATH mode should always create an image that outputs 'Hello World'" -RESULT="$(GO111MODULE=off ./ko publish --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" +RESULT="$(GO111MODULE=off ./ko build --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" if [[ "$RESULT" != *"Hello World"** ]]; then echo "Test FAILED. Saw $RESULT" && exit 1 else @@ -46,7 +46,7 @@ fi echo "2. Go module auto mode should create an image that outputs 'Hello World' when run outside the module." pushd .. || exit 1 -RESULT="$(GO111MODULE=auto GOFLAGS="-mod=vendor" ./ko/ko publish --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" +RESULT="$(GO111MODULE=auto GOFLAGS="-mod=vendor" ./ko/ko build --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" if [[ "$RESULT" != *"Hello World"* ]]; then echo "Test FAILED. Saw $RESULT" && exit 1 else @@ -57,7 +57,7 @@ popd || exit 1 echo "3. Auto inside the module with vendoring should output TEST" -RESULT="$(GO111MODULE=auto GOFLAGS="-mod=vendor" ./ko publish --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" +RESULT="$(GO111MODULE=auto GOFLAGS="-mod=vendor" ./ko build --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" if [[ "$RESULT" != *"TEST"* ]]; then echo "Test FAILED. Saw $RESULT" && exit 1 else @@ -65,7 +65,7 @@ else fi echo "4. Auto inside the module without vendoring should output TEST" -RESULT="$(GO111MODULE=auto GOFLAGS="" ./ko publish --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" +RESULT="$(GO111MODULE=auto GOFLAGS="" ./ko build --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" if [[ "$RESULT" != *"TEST"* ]]; then echo "Test FAILED. Saw $RESULT" && exit 1 else @@ -73,7 +73,7 @@ else fi echo "5. On inside the module with vendor should output TEST." -RESULT="$(GO111MODULE=on GOFLAGS="-mod=vendor" ./ko publish --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" +RESULT="$(GO111MODULE=on GOFLAGS="-mod=vendor" ./ko build --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" if [[ "$RESULT" != *"TEST"* ]]; then echo "Test FAILED. Saw $RESULT" && exit 1 else @@ -81,7 +81,7 @@ else fi echo "6. On inside the module without vendor should output TEST" -RESULT="$(GO111MODULE=on GOFLAGS="" ./ko publish --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" +RESULT="$(GO111MODULE=on GOFLAGS="" ./ko build --local github.com/go-training/helloworld | grep "$FILTER" | xargs -I% docker run %)" if [[ "$RESULT" != *"TEST"* ]]; then echo "Test FAILED. Saw $RESULT" && exit 1 else @@ -90,7 +90,7 @@ fi echo "7. On outside the module should fail." pushd .. || exit 1 -GO111MODULE=on ./ko/ko publish --local github.com/go-training/helloworld && exit 1 +GO111MODULE=on ./ko/ko build --local github.com/go-training/helloworld && exit 1 popd || exit 1 popd || exit 1 diff --git a/pkg/build/gobuild.go b/pkg/build/gobuild.go index c62d08d0cb..cff0a712f2 100644 --- a/pkg/build/gobuild.go +++ b/pkg/build/gobuild.go @@ -738,7 +738,7 @@ func (g *gobuild) buildOne(ctx context.Context, refStr string, base v1.Image, pl Layer: dataLayer, History: v1.History{ Author: "ko", - CreatedBy: "ko publish " + ref.String(), + CreatedBy: "ko build " + ref.String(), Comment: "kodata contents, at $KO_DATA_PATH", }, }) @@ -765,7 +765,7 @@ func (g *gobuild) buildOne(ctx context.Context, refStr string, base v1.Image, pl Layer: binaryLayer, History: v1.History{ Author: "ko", - CreatedBy: "ko publish " + ref.String(), + CreatedBy: "ko build " + ref.String(), Comment: "go build output, at " + appPath, }, }) diff --git a/pkg/commands/publish.go b/pkg/commands/build.go similarity index 76% rename from pkg/commands/publish.go rename to pkg/commands/build.go index a784f3ca88..06a2b36893 100644 --- a/pkg/commands/publish.go +++ b/pkg/commands/build.go @@ -21,40 +21,41 @@ import ( "github.com/spf13/cobra" ) -// addPublish augments our CLI surface with publish. -func addPublish(topLevel *cobra.Command) { +// addBuild augments our CLI surface with build. +func addBuild(topLevel *cobra.Command) { po := &options.PublishOptions{} bo := &options.BuildOptions{} - publish := &cobra.Command{ - Use: "publish IMPORTPATH...", - Short: "Build and publish container images from the given importpaths.", - Long: `This sub-command builds the provided import paths into Go binaries, containerizes them, and publishes them.`, + build := &cobra.Command{ + Use: "build IMPORTPATH...", + Short: "Build and publish container images from the given importpaths.", + Long: `This sub-command builds the provided import paths into Go binaries, containerizes them, and publishes them.`, + Aliases: []string{"publish"}, Example: ` # Build and publish import path references to a Docker # Registry as: # ${KO_DOCKER_REPO}/- # When KO_DOCKER_REPO is ko.local, it is the same as if # --local and --preserve-import-paths were passed. - ko publish github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah + ko build github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah # Build and publish a relative import path as: # ${KO_DOCKER_REPO}/- # When KO_DOCKER_REPO is ko.local, it is the same as if # --local and --preserve-import-paths were passed. - ko publish ./cmd/blah + ko build ./cmd/blah # Build and publish a relative import path as: # ${KO_DOCKER_REPO}/ # When KO_DOCKER_REPO is ko.local, it is the same as if # --local was passed. - ko publish --preserve-import-paths ./cmd/blah + ko build --preserve-import-paths ./cmd/blah # Build and publish import path references to a Docker # daemon as: # ko.local/ # This always preserves import paths. - ko publish --local github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah`, + ko build --local github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah`, Args: cobra.MinimumNArgs(1), RunE: func(_ *cobra.Command, args []string) error { ctx := createCancellableContext() @@ -78,7 +79,7 @@ func addPublish(topLevel *cobra.Command) { return nil }, } - options.AddPublishArg(publish, po) - options.AddBuildOptions(publish, bo) - topLevel.AddCommand(publish) + options.AddPublishArg(build, po) + options.AddBuildOptions(build, bo) + topLevel.AddCommand(build) } diff --git a/pkg/commands/commands.go b/pkg/commands/commands.go index 31faf860c8..980a6ac0a0 100644 --- a/pkg/commands/commands.go +++ b/pkg/commands/commands.go @@ -29,7 +29,7 @@ func AddKubeCommands(topLevel *cobra.Command) { addCreate(topLevel) addApply(topLevel) addResolve(topLevel) - addPublish(topLevel) + addBuild(topLevel) addRun(topLevel) addDeps(topLevel) addCompletion(topLevel) diff --git a/pkg/commands/run.go b/pkg/commands/run.go index d861e294bc..b863cfc4f3 100644 --- a/pkg/commands/run.go +++ b/pkg/commands/run.go @@ -35,7 +35,7 @@ func addRun(topLevel *cobra.Command) { run := &cobra.Command{ Use: "run IMPORTPATH", Short: "A variant of `kubectl run` that containerizes IMPORTPATH first.", - Long: `This sub-command combines "ko publish" and "kubectl run" to support containerizing and running Go binaries on Kubernetes in a single command.`, + Long: `This sub-command combines "ko build" and "kubectl run" to support containerizing and running Go binaries on Kubernetes in a single command.`, Example: ` # Publish the image and run it on Kubernetes as: # ${KO_DOCKER_REPO}/- From 7249a9eab6ce104a7b9948cbc831b2795510b669 Mon Sep 17 00:00:00 2001 From: Jason Hall Date: Thu, 30 Sep 2021 10:45:45 -0400 Subject: [PATCH 2/2] rm ko_publish.md --- doc/ko_publish.md | 66 ----------------------------------------------- 1 file changed, 66 deletions(-) delete mode 100644 doc/ko_publish.md diff --git a/doc/ko_publish.md b/doc/ko_publish.md deleted file mode 100644 index 6923c7ea14..0000000000 --- a/doc/ko_publish.md +++ /dev/null @@ -1,66 +0,0 @@ -## ko publish - -Build and publish container images from the given importpaths. - -### Synopsis - -This sub-command builds the provided import paths into Go binaries, containerizes them, and publishes them. - -``` -ko publish IMPORTPATH... [flags] -``` - -### Examples - -``` - - # Build and publish import path references to a Docker - # Registry as: - # ${KO_DOCKER_REPO}/- - # When KO_DOCKER_REPO is ko.local, it is the same as if - # --local and --preserve-import-paths were passed. - ko publish github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah - - # Build and publish a relative import path as: - # ${KO_DOCKER_REPO}/- - # When KO_DOCKER_REPO is ko.local, it is the same as if - # --local and --preserve-import-paths were passed. - ko publish ./cmd/blah - - # Build and publish a relative import path as: - # ${KO_DOCKER_REPO}/ - # When KO_DOCKER_REPO is ko.local, it is the same as if - # --local was passed. - ko publish --preserve-import-paths ./cmd/blah - - # Build and publish import path references to a Docker - # daemon as: - # ko.local/ - # This always preserves import paths. - ko publish --local github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah -``` - -### Options - -``` - --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags). - -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags). - --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container. - -h, --help help for publish - --image-label strings Which labels (key=value) to add to the image. - --insecure-registry Whether to skip TLS verification on the registry - -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS) - -L, --local Load into images to local docker daemon. - --oci-layout-path string Path to save the OCI image layout of the built images - --platform string Which platform to use when pulling a multi-platform base. Format: all | [/[/]][,platform]* - -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO. - --push Push images to KO_DOCKER_REPO (default true) - --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated. - -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest]) - --tarball string File to save images tarballs -``` - -### SEE ALSO - -* [ko](ko.md) - Rapidly iterate with Go, Containers, and Kubernetes. -