tooling: Add buf bazel dependency and tests to evaluate it (#17515)

Follow-up to #17375 where it was agreed that protolock is not actively maintained enough to depend on. This PR "migrates" the tests from that PR to use buf instead, and also cleans some of the code per a few of the review comments. Still a few outstanding points:

- buf build on the envoy/api folder requires several protobuf dependencies such as udpa to be available to buf to consume. Suggested solution by buf is to point buf's config to necessary BSR modules that the buf team is hosting.
  - These lines are commented out in this PR as I had some trouble automating it for the tests, and it is not necessary for the tests to pass
  - May introduce issues if buf is not pointing to the same version of modules that bazel builds for envoy. May need to introduce some way to couple them, or (ideally) find a way to run the breaking change detector without building the dependencies
- Currently bazel is using a binary release of buf (for linux). Goal is to move to building it from source in the near future
- It may be in our interest to expand the list of API-breaking-change rules (buf provides an extensive list of rules we could adopt)

Risk Level: Low

Testing: Tests that evaluate buf against "allowed" and "breaking" protobuf API changes. Currently 4 tests are skipped - 3 of them are PGV-related (we need to communicate our desired PGV rules to the buf team so they may add them in the near future). The 4th is a test I had originally written to evaluate protolock but may not apply to buf ("forcing" a breaking change) - refer to comments

Docs Changes:
Release Notes:
Platform Specific Features: buf binary imported by bazel is linux-only. Hopefully the ["manual"] tags attribute prevents any issues for non-linux users

Signed-off-by: Yaseen Alkhafaji <yaseena@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ c74cebb3cc7dfb26488f7cac8eb9258cf9a7588e

bazel/repositories.bzl

@@ -47,6 +47,11 @@ def api_dependencies():
         name = "opentelemetry_proto",
         build_file_content = OPENTELEMETRY_LOGS_BUILD_CONTENT,
     )
+    external_http_archive(
+        name = "com_github_bufbuild_buf",
+        build_file_content = BUF_BUILD_CONTENT,
+        tags = ["manual"],
+    )
 
 PROMETHEUSMETRICS_BUILD_CONTENT = """
 load("@envoy_api//bazel:api_build_system.bzl", "api_cc_py_proto_library")
@@ -150,3 +155,17 @@ go_proto_library(
     visibility = ["//visibility:public"],
 )
 """
+
+BUF_BUILD_CONTENT = """
+package(
+    default_visibility = ["//visibility:public"],
+)
+
+filegroup(
+    name = "buf",
+    srcs = [
+        "@com_github_bufbuild_buf//:bin/buf",
+    ],
+    tags = ["manual"], # buf is downloaded as a linux binary; tagged manual to prevent build for non-linux users
+)
+"""

bazel/repository_locations.bzl

@@ -118,4 +118,16 @@ REPOSITORY_LOCATIONS_SPEC = dict(
         urls = ["https://github.com/open-telemetry/opentelemetry-proto/archive/v{version}.tar.gz"],
         use_category = ["api"],
     ),
+    com_github_bufbuild_buf = dict(
+        project_name = "buf",
+        project_desc = "A new way of working with Protocol Buffers.",  # Used for breaking change detection in API protobufs
+        project_url = "https://buf.build",
+        version = "0.48.2",
+        sha256 = "ee0ea6c4a7bbb016d79b056905c0a1f018e7c5e47b37038c993a77b1bc732c0d",
+        strip_prefix = "buf",
+        urls = ["https://github.com/bufbuild/buf/releases/download/v{version}/buf-Linux-x86_64.tar.gz"],
+        release_date = "2021-07-30",
+        use_category = ["api"],
+        tags = ["manual"],
+    ),
 )