|
| 1 | +# Envtest Binaries Manager |
| 2 | + |
| 3 | +This is a small tool that manages binaries for envtest. It can be used to |
| 4 | +download new binaries, list currently installed and available ones, and |
| 5 | +clean up versions. |
| 6 | + |
| 7 | +To use it, just go-install it on 1.16+ (it's a separate, self-contained |
| 8 | +module): |
| 9 | + |
| 10 | +```shell |
| 11 | +go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest |
| 12 | +``` |
| 13 | + |
| 14 | +For full documentation, run it with the `--help` flag, but here are some |
| 15 | +examples: |
| 16 | + |
| 17 | +```shell |
| 18 | +# download the latest envtest, and print out info about it |
| 19 | +setup-envtest use |
| 20 | + |
| 21 | +# download the latest 1.19 envtest, and print out the path |
| 22 | +setup-envtest use -p path 1.19.x! |
| 23 | + |
| 24 | +# switch to the most recent 1.21 envtest on disk |
| 25 | +source <(setup-envtest use -i -p env 1.21.x) |
| 26 | + |
| 27 | +# list all available local versions for darwin/amd64 |
| 28 | +setup-envtest list -i --os darwin --arch amd64 |
| 29 | + |
| 30 | +# remove all versions older than 1.16 from disk |
| 31 | +setup-envtest cleanup <1.16 |
| 32 | + |
| 33 | +# use the value from $KUBEBUILDER_ASSETS if set, otherwise follow the normal |
| 34 | +# logic for 'use' |
| 35 | +setup-envtest --use-env |
| 36 | + |
| 37 | +# use the value from $KUBEBUILDER_ASSETS if set, otherwise use the latest |
| 38 | +# installed version |
| 39 | +setup-envtest use -i --use-env |
| 40 | + |
| 41 | +# sideload a pre-downloaded tarball as Kubernetes 1.16.2 into our store |
| 42 | +setup-envtest sideload 1.16.2 < downloaded-envtest.tar.gz |
| 43 | +``` |
| 44 | + |
| 45 | +## Where does it put all those binaries? |
| 46 | + |
| 47 | +By default, binaries are stored in a subdirectory of an OS-specific data |
| 48 | +directory, as per the OS's conventions. |
| 49 | + |
| 50 | +On Linux, this is `$XDG_DATA_HOME`; on Windows, `%LocalAppData`; and on |
| 51 | +OSX, `~/Library/Application Support`. |
| 52 | + |
| 53 | +There's an overall folder that holds all files, and inside that is |
| 54 | +a folder for each version/platform pair. The exact directory structure is |
| 55 | +not guarnateed, except that the leaf directory will contain the names |
| 56 | +expected by envtest. You should always use `setup-envtest fetch` or |
| 57 | +`setup-envtest switch` (generally with the `-p path` or `-p env` flags) to |
| 58 | +get the directory that you should use. |
| 59 | + |
| 60 | +## Why do I have to do that `source <(blah blah blah)` thing |
| 61 | + |
| 62 | +This is a normal binary, not a shell script, so we can't set the parent |
| 63 | +process's environment variables. If you use this by hand a lot and want |
| 64 | +to save the typing, you could put something like the following in your |
| 65 | +`~/.zshrc` (or similar for bash/fish/whatever, modified to those): |
| 66 | + |
| 67 | +```shell |
| 68 | +setup-envtest() { |
| 69 | + if (($@[(Ie)use])); then |
| 70 | + source <($GOPATH/bin/setup-envtest "$@" -p env) |
| 71 | + else |
| 72 | + $GOPATH/bin/setup-envtest "$@" |
| 73 | + fi |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +## What if I don't want to talk to the internet? |
| 78 | + |
| 79 | +There are a few options. |
| 80 | + |
| 81 | +First, you'll probably want to set the `-i/--installed` flag. If you want |
| 82 | +to avoid forgetting to set this flag, set the `ENVTEST_INSTALLED_ONLY` |
| 83 | +env variable, which will switch that flag on by default. |
| 84 | + |
| 85 | +Then, you have a few options for managing your binaries: |
| 86 | + |
| 87 | +- If you don't *really* want to manage with this tool, or you want to |
| 88 | + respect the $KUBEBUILDER_ASSETS variable if it's set to something |
| 89 | + outside the store, use the `use --use-env -i` command. |
| 90 | + |
| 91 | + `--use-env` makes the command unconditionally use the value of |
| 92 | + KUBEBUILDER_ASSETS as long as it contains the required binaries, and |
| 93 | + `-i` indicates that we only ever want to work with installed binaries |
| 94 | + (no reaching out the the remote GCS storage). |
| 95 | + |
| 96 | + As noted about, you can use `ENVTEST_INSTALLED_ONLY=true` to switch `-i` |
| 97 | + on by default, and you can use `ENVTEST_USE_ENV=true` to switch |
| 98 | + `--use-env` on by default. |
| 99 | + |
| 100 | +- If you want to use this tool, but download your gziped tarballs |
| 101 | + separately, you can use the `sideload` command. You'll need to use the |
| 102 | + `-k/--version` flag to indicate which version you're sideloading. |
| 103 | + |
| 104 | + After that, it'll be as if you'd installed the binaries with `use`. |
| 105 | + |
| 106 | +- If you want to talk to some internal source, you can use the |
| 107 | + `--remote-bucket` and `--remote-server` options. The former sets which |
| 108 | + GCS bucket to download from, and the latter sets the host to talk to as |
| 109 | + if it were a GCS endpoint. Theoretically, you could use the latter |
| 110 | + version to run an internal "mirror" -- the tool expects |
| 111 | + |
| 112 | + - `HOST/storage/v1/b/BUCKET/o` to return JSON like |
| 113 | + |
| 114 | + ```json |
| 115 | + {"items": [ |
| 116 | + {"name": "kubebuilder-tools-X.Y.Z-os-arch.tar.gz", "md5Hash": "<base-64-encoded-md5-hash>"}, |
| 117 | + {"name": "kubebuilder-tools-X.Y.Z-os-arch.tar.gz", "md5Hash": "<base-64-encoded-md5-hash>"}, |
| 118 | + ]} |
| 119 | + ``` |
| 120 | + |
| 121 | + - `HOST/storage/v1/b/BUCKET/o/TARBALL_NAME` to return JSON like |
| 122 | + `{"name": "kubebuilder-tools-X.Y.Z-os-arch.tar.gz", "md5Hash": "<base-64-encoded-md5-hash>"}` |
| 123 | + |
| 124 | + - `HOST/storage/v1/b/BUCKET/o/TARBALL_NAME?alt=media` to return the |
| 125 | + actual file contents |
0 commit comments