Merge pull request #1488 from DirectXMan12/feature/envtest-setup-tool

✨ EnvTest Binaries Setup Tool

Makefile

@@ -56,9 +56,13 @@ help:  ## Display this help
 ## --------------------------------------
 
 .PHONY: test
-test: ## Run the script check-everything.sh which will check all.
+test: test-tools ## Run the script check-everything.sh which will check all.
 	TRACE=1 ./hack/check-everything.sh
 
+.PHONY: test-tools
+test-tools: ## tests the tools codebase (setup-envtest)
+	cd tools/setup-envtest && go test ./...
+
 ## --------------------------------------
 ## Binaries
 ## --------------------------------------
@@ -76,10 +80,17 @@ $(CONTROLLER_GEN): $(TOOLS_DIR)/go.mod # Build controller-gen from tools folder.
 ## Linting
 ## --------------------------------------
 
-.PHONY: lint
-lint: $(GOLANGCI_LINT) ## Lint codebase.
+.PHONY: lint-libs
+lint-libs: $(GOLANGCI_LINT) ## Lint library codebase.
 	$(GOLANGCI_LINT) run -v
 
+.PHONY: lint-tools
+lint-tools: $(GOLANGCI_LINT) ## Lint tools codebase.
+	cd tools/setup-envtest && $(GOLANGCI_LINT) run -v
+
+.PHONY: lint
+lint: lint-libs lint-tools
+
 ## --------------------------------------
 ## Generate
 ## --------------------------------------

hack/check-everything.sh

@@ -20,16 +20,27 @@ set -o pipefail
 
 hack_dir=$(dirname ${BASH_SOURCE})
 source ${hack_dir}/common.sh
-source ${hack_dir}/setup-envtest.sh
 
 tmp_root=/tmp
 kb_root_dir=$tmp_root/kubebuilder
 
 ENVTEST_K8S_VERSION=${ENVTEST_K8S_VERSION:-"1.19.2"}
 
-fetch_envtest_tools "$kb_root_dir"
-fetch_envtest_tools "${hack_dir}/../pkg/internal/testing/integration/assets"
-setup_envtest_env "$kb_root_dir"
+# set up envtest tools if necessary
+
+header_text "installing envtest tools@${ENVTEST_K8S_VERSION} with setup-envtest if necessary"
+tmp_bin=/tmp/cr-tests-bin
+(
+    # don't presume to install for the user
+    cd ${hack_dir}/../tools/setup-envtest
+    GOBIN=${tmp_bin} go install .
+)
+source <(${tmp_bin}/setup-envtest use --use-env -p env ${ENVTEST_K8S_VERSION})
+
+# link the assets into integration
+for tool in kube-apiserver etcd kubectl; do
+    ln -f -s "${KUBEBUILDER_ASSETS:?unable find envtest assets}/${tool}" "${hack_dir}/../pkg/internal/testing/integration/assets/bin/${tool}"
+done
 
 ${hack_dir}/verify.sh
 ${hack_dir}/test-all.sh

tools/setup-envtest/README.md

@@ -0,0 +1,125 @@
+# Envtest Binaries Manager
+
+This is a small tool that manages binaries for envtest. It can be used to
+download new binaries, list currently installed and available ones, and
+clean up versions.
+
+To use it, just go-install it on 1.16+ (it's a separate, self-contained
+module):
+
+```shell
+go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest
+```
+
+For full documentation, run it with the `--help` flag, but here are some
+examples:
+
+```shell
+# download the latest envtest, and print out info about it
+setup-envtest use
+
+# download the latest 1.19 envtest, and print out the path
+setup-envtest use -p path 1.19.x!
+
+# switch to the most recent 1.21 envtest on disk
+source <(setup-envtest use -i -p env 1.21.x)
+
+# list all available local versions for darwin/amd64
+setup-envtest list -i --os darwin --arch amd64
+
+# remove all versions older than 1.16 from disk
+setup-envtest cleanup <1.16
+
+# use the value from $KUBEBUILDER_ASSETS if set, otherwise follow the normal
+# logic for 'use'
+setup-envtest --use-env
+
+# use the value from $KUBEBUILDER_ASSETS if set, otherwise use the latest
+# installed version
+setup-envtest use -i --use-env
+
+# sideload a pre-downloaded tarball as Kubernetes 1.16.2 into our store
+setup-envtest sideload 1.16.2 < downloaded-envtest.tar.gz
+```
+
+## Where does it put all those binaries?
+
+By default, binaries are stored in a subdirectory of an OS-specific data
+directory, as per the OS's conventions. 
+
+On Linux, this is `$XDG_DATA_HOME`; on Windows, `%LocalAppData`; and on
+OSX, `~/Library/Application Support`.
+
+There's an overall folder that holds all files, and inside that is
+a folder for each version/platform pair.  The exact directory structure is
+not guarnateed, except that the leaf directory will contain the names
+expected by envtest.  You should always use `setup-envtest fetch` or
+`setup-envtest switch` (generally with the `-p path` or `-p env` flags) to
+get the directory that you should use.
+
+## Why do I have to do that `source <(blah blah blah)` thing
+
+This is a normal binary, not a shell script, so we can't set the parent
+process's environment variables.  If you use this by hand a lot and want
+to save the typing, you could put something like the following in your
+`~/.zshrc` (or similar for bash/fish/whatever, modified to those):
+
+```shell
+setup-envtest() {
+    if (($@[(Ie)use])); then
+        source <($GOPATH/bin/setup-envtest "$@" -p env)
+    else
+        $GOPATH/bin/setup-envtest "$@"
+    fi
+}
+```
+
+## What if I don't want to talk to the internet?
+
+There are a few options.
+
+First, you'll probably want to set the `-i/--installed` flag. If you want
+to avoid forgetting to set this flag, set  the `ENVTEST_INSTALLED_ONLY`
+env variable, which will switch that flag on by default.
+
+Then, you have a few options for managing your binaries:
+
+- If you don't *really* want to manage with this tool, or you want to
+  respect the $KUBEBUILDER_ASSETS variable if it's set to something
+  outside the store, use the `use --use-env -i` command.
+
+  `--use-env` makes the command unconditionally use the value of
+  KUBEBUILDER_ASSETS as long as it contains the required binaries, and
+  `-i` indicates that we only ever want to work with installed binaries
+  (no reaching out the the remote GCS storage).
+
+  As noted about, you can use `ENVTEST_INSTALLED_ONLY=true` to switch `-i`
+  on by default, and you can use `ENVTEST_USE_ENV=true` to switch
+  `--use-env` on by default.
+
+- If you want to use this tool, but download your gziped tarballs
+  separately, you can use the `sideload` command.  You'll need to use the
+  `-k/--version` flag to indicate which version you're sideloading.
+
+  After that, it'll be as if you'd installed the binaries with `use`.
+
+- If you want to talk to some internal source, you can use the
+  `--remote-bucket` and `--remote-server` options.  The former sets which
+  GCS bucket to download from, and the latter sets the host to talk to as
+  if it were a GCS endpoint. Theoretically, you could use the latter
+  version to run an internal "mirror" -- the tool expects
+
+  - `HOST/storage/v1/b/BUCKET/o` to return JSON like
+
+    ```json
+    {"items": [
+        {"name": "kubebuilder-tools-X.Y.Z-os-arch.tar.gz", "md5Hash": "<base-64-encoded-md5-hash>"},
+        {"name": "kubebuilder-tools-X.Y.Z-os-arch.tar.gz", "md5Hash": "<base-64-encoded-md5-hash>"},
+    ]}
+    ```
+
+  - `HOST/storage/v1/b/BUCKET/o/TARBALL_NAME` to return JSON like
+    `{"name": "kubebuilder-tools-X.Y.Z-os-arch.tar.gz", "md5Hash": "<base-64-encoded-md5-hash>"}`
+
+  - `HOST/storage/v1/b/BUCKET/o/TARBALL_NAME?alt=media` to return the
+    actual file contents