.. | ||
BUILD | ||
OWNERS | ||
README.md |
Package Groups Used in Kubernetes Visibility Rules
Background
BUILD
rules define dependencies, answering the question:
on what packages does foo depend?
The BUILD
file in this package allows one to define
allowed reverse dependencies, answering the question:
given a package foo, what other specific packages are
allowed to depend on it?
This is done via visibility rules.
Visibility rules discourage unintended, spurious dependencies that blur code boundaries, slow CICD queues and generally inhibit progress.
Facts
-
A package is any directory that contains a
BUILD
file. -
A
package_group
is aBUILD
file rule that defines a named set of packages for use in other rules, e.g., givenpackage_group( name = "database_CONSUMERS", packages = [ "//foo/dbinitializer", "//foo/backend/...", # `backend` and everything below it ], )
one can specify the following visibility rule in any
BUILD
rule:visibility = [ "//build/visible_to:database_CONSUMERS" ],
-
A visibility rule takes a list of package groups as its argument - or one of the pre-defined groups
//visibility:private
or//visibility:public
. -
If no visibility is explicitly defined, a package is private by default.
-
Violations in visibility cause
make bazel-build
to fail, which in turn causes the submit queue to fail - that's the enforcement.
Why define all package groups meant for visibility here (in one file)?
- Ease discovery of appropriate groups for use in a rule.
- Ease reuse (inclusions) of commonly used groups.
- Consistent style:
- easy to read
//build/visible_to:math_library_CONSUMERS
rules, - call out bad dependencies for eventual removal.
- easy to read
- Make it more obvious in code reviews when visibility is being modified.
- One set of
OWNERS
to manage visibility.
The alternative is to use special package literals directly in visibility rules, e.g.
visibility = [
"//foo/dbinitializer:__pkg__",
"//foo/backend:__subpackages__",
],
The difference in style is similar to the difference between
using a named static constant like MAX_NODES
rather than a
literal like 12
. Names are preferable to literals for intent
documentation, search, changing one place rather than n,
associating usage in distant code blocks, etc.
Rule Examples
Nobody outside this package can depend on me.
visibility = ["//visibility:private"],
Since this is the default, there's no reason to use this rule except as a means to override, for some specific target, some broader, whole-package visibility rule.
Anyone can depend on me (eschew this).
visibility = ["//visibility:public"],
Only some servers can depend on me.
Appropriate for, say, backend storage utilities.
visibility = ["//visible_to:server_foo","//visible_to:server_bar"].
Both some client and some server can see me.
Appropriate for shared API definition files and generated code:
visibility = ["//visible_to:client_foo,//visible_to:server_foo"],
Handy commands
Quickly check for visibility violations
bazel build --check_visibility --nobuild \
//cmd/... //pkg/... //plugin/... \
//third_party/... //test/... //vendor/k8s.io/...
Who depends on target q?
To create a seed set for a visibility group, one can ask what packages currently depend on (must currently be able to see) a given Go library target? It's a time consuming query.
q=//pkg/kubectl/cmd:go_default_library
bazel query "rdeps(...,${q})" | \
grep go_default_library | \
sed 's/\(.*\):go_default_library/ "\1",/'
What targets below p are visible to anyone?
A means to look for things one missed when locking down p.
p=//pkg/kubectl/cmd
bazel query "visible(...,${p}/...)"
What packages below p may target q depend on without violating visibility rules?
A means to pinpoint unexpected visibility.
p=//pkg/kubectl
q=//cmd/kubelet:kubelet
bazel query "visible(${q},${p}/...)" | more
What packages does target q need?
q=//cmd/kubectl:kubectl
bazel query "buildfiles(deps($q))" | \
grep -v @bazel_tools | \
grep -v @io_bazel_rules | \
grep -v @io_kubernetes_build | \
grep -v @local_config | \
grep -v @local_jdk | \
grep -v //visible_to: | \
sed 's/:BUILD//' | \
sort | uniq > ~/KUBECTL_BUILD.txt
or try
bazel query --nohost_deps --noimplicit_deps \
"kind('source file', deps($q))" | wc -
How does kubectl depend on pkg/util/parsers?
bazel query "somepath(cmd/kubectl:kubectl, pkg/util/parsers:go_default_library)"