proto-public

The github.com/hashicorp/consul/proto-public module holds every protobuf schema that the agent exposes externally — to Consul Dataplane, the v2 resource clients, dataplane consumers, and third-party tooling. The internal protos (proto/private/) are not in this module; they're version-locked with the server.

Sub-packages

Package	What it defines
pbacl	ACL gRPC service (login, token issuance) consumed by dataplane
pbconnectca	Connect CA gRPC: Sign(CSR) → Cert, WatchRoots(stream)
pbdataplane	Dataplane bootstrap and config gRPC: GetEnvoyBootstrapParams, GetSupportedDataplaneFeatures
pbdns	DNS-over-gRPC service used by dataplane to avoid binding UDP
pbmulticluster	V2 multicluster (peering successor) resource types
pbresource	Generic resource service: Read, Write, WriteStatus, List, Delete, Watch over typed resources
pbserverdiscovery	Server discovery service: WatchServers long-lived stream emitting authoritative server set

Tooling

• Schemas are compiled with buf (pinned to v1.56.0 in the Makefile).
• buf.yaml and buf.gen.yaml at the module root configure the generators.
• Generated .pb.go files are checked in; regenerate with make proto.
• annotations/ carries custom protobuf annotations (e.g., resource type marker) that other packages reference.

Conventions

• Every public service has both a streaming and a unary variant where it makes sense (Watch + Read, Watch + List).
• Resource types follow the <group>.<version>.<kind> triple convention used by the v2 resource framework. pbresource.Type is the canonical representation.
• IDs are scoped by Tenancy (partition, namespace, peer-name in CE; partition is default).
• Status messages on resources hold reconciliation state set by controllers, never by clients.

Stability promise

The schemas in this module are versioned with the Consul minor release. New fields use new field numbers; renames are forbidden. The dataplane and any downstream tooling rely on this contract.

Server-side handlers

Implementations of these services live in the root module under agent/grpc-external/services/:

Service	Implementation
pbacl	agent/grpc-external/services/acl/
pbconnectca	agent/grpc-external/services/connectca/
pbdataplane	agent/grpc-external/services/dataplane/
pbdns	agent/grpc-external/services/dns/
pbresource	internal/resource/ + plumbing in agent/grpc-external/services/resource/
pbserverdiscovery	agent/grpc-external/services/serverdiscovery/

Entry points for modification

• Add a field to an existing service: edit the .proto, make proto, and update the corresponding handler in agent/grpc-external/services/.
• Add a new public service: create pbnewthing/ with .proto files, regenerate, implement the server in agent/grpc-external/services/newthing/, and register it in agent/consul/server_grpc.go.
• Move a v2 resource type into a new group: add the <group> directory under proto-public/, define the proto, register with internal/resource/.