Generally follow guidance at https://cloud.google.com/apis/design/, in particular for proto3 as described at:
A key aspect of our API style is maintaining stability by following the API versioning guidelines. All developers must familiarize themselves with these guidelines, any PR which makes breaking changes to the API will not be merged.
In addition, the following conventions should be followed:
Every proto directory should have a README.md
describing its content. See
for example envoy.service.
The data plane APIs are primarily intended for machine generation and consumption. It is expected that the management server is responsible for mapping higher level configuration concepts to concrete API concepts. Similarly, static configuration fragments may be generated by tools and UIs, etc. The APIs and tools used to generate xDS configuration are beyond the scope of the definitions in this repository.
Use wrapped scalar
types
where there is a real need for the field to have a default value that does not
match the proto3 defaults (0/false/""). This should not be done for fields
where the proto3 defaults make sense. All things being equal, pick appropriate
logic, e.g. enable vs. disable for a bool
field, such that the proto3
defaults work, but only where this doesn't result in API gymnastics.
Use a [#not-implemented-hide:]
protodoc
annotation in comments for fields that lack Envoy
implementation. These indicate that the entity is not implemented in Envoy and the entity
should be hidden from the Envoy documentation.
Always use plural field names for repeated
fields, such as filters
.
Due to the fact that we consider JSON/YAML to be first class inputs, we cannot easily change a a singular field to a repeated field (both due to JSON/YAML array structural differences as well as singular vs. plural field naming). If there is a reasonable expectation that a field may need to be repeated in the future, but we don't need it to be repeated right away, consider making it repeated now but using constraints to enforce a maximum repeated size of 1. E.g.:
repeated OutputSink sinks = 1 [(validate.rules).repeated = {min_items: 1, max_items: 1}];
Always use upper camel case names for message types and enum types without embedded
acronyms, such as HttpRequest
.
Prefer oneof
selections to boolean overloads of fields, for example, prefer:
oneof path_specifier {
string simple_path = 1;
string regex_path = 2;
}
to
string path = 1;
bool path_is_regex = 2;
This is more efficient, extendable and self-describing.
The API includes two types for representing percents. Percent
is
effectively a double value in the range 0.0-100.0. FractionalPercent
is an integral fraction
that can be used to create a truncated percentage also in the range 0.0-100.0. In high performance
paths, FractionalPercent
is preferred as randomness calculations can be performed using integral
modulo and comparison operations only without any floating point conversions. Typically, most
users do not need infinite precision in these paths.
For enum types, if one of the enum values is used for most cases, make it the
first enum value with 0
numeric value. Otherwise, define the first enum
value like TYPE_NAME_UNSPECIFIED = 0
, and treat it as an error. This design
pattern forces developers to explicitly choose the correct enum value for
their use case, and avoid misunderstanding of the default behavior.
Proto fields should be sorted logically, not by field number.
API definitions are layered hierarchically in packages from top-to-bottom as following:
envoy.extensions
contains all definitions for the extensions, the package should match the structure of the source
directory.envoy.service
contains gRPC definitions of supporting services and top-level messages for the services.
e.g. envoy.service.route.v3
contains RDS, envoy.service.listener.v3
contains LDS.envoy.config
contains other definitions for service configuration, bootstrap and some legacy core types.envoy.data
contains data format declaration for data types that Envoy produces.envoy.type
contains common protobuf types such as percent, range and matchers.Extensions should use the regular hierarchy. For example, configuration for network filters belongs
in a package under envoy.extensions.filter.network
.
Extensions must currently be added as v3 APIs following the package organization above. To add an extension config to the API, the steps below should be followed:
vNalpha
instead of vN
in steps
below. Refer to the Cache filter config
as an example of v3alpha
, and the
Buffer filter config as an example of v3
..proto
in api/envoy/extensions
, e.g.
api/envoy/extensions/filter/http/foobar/v3/foobar.proto
together with an initial BUILD file:
load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
licenses(["notice"]) # Apache 2
api_proto_package(
deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
)
import "udpa/annotations/migrate.proto";
and import "udpa/annotations/status.proto";
option (udpa.annotations.file_status).work_in_progress = true;
.option (udpa.annotations.file_status).package_version_status = ACTIVE;
.
This is required to automatically include the config proto in api/versioning/BUILD.active_protos
../tools/proto_format/proto_format.sh fix
. This should regenerate the BUILD
file,
reformat foobar.proto
as needed and also generate the v4alpha extension config (if needed),
together with shadow API protos.git add api/ generated_api_shadow/
to add any new files to your Git index.A number of annotations are used in the Envoy APIs to provide additional API metadata. We describe these annotations below by category.
[deprecated = true]
to denote fields that are deprecated in a major version.
These fields are slated for removal at the next major cycle and follow the
breaking change policy.[envoy.annotations.disallowed_by_default = true]
to denote fields that have
been disallowed by default as per the breaking change policy.[(udpa.annotations.field_migrate).rename = "<new field name>"]
to denote that
the field will be renamed to a given name in the next API major version.[(udpa.annotations.field_migrate).oneof_promotion = "<oneof name>"]
to denote that
the field will be promoted to a given oneof
in the next API major version.[(udpa.annotations.sensitive) = true]
to denote sensitive fields that
should be redacted in output such as logging or configuration dumps.[(udpa.annotations.enum_value_migrate).rename = "new enum value name"]
to denote that
the enum value will be renamed to a given name in the next API major version.option (udpa.annotations.versioning).previous_message_type = "<message type name>";
to denote the previous type name for an upgraded message. You should
never have to write these manually, they are generated by protoxform
.option (envoy.annotations.resource).type = "<resource type name>";
to denote
the resource type for an xDS service definition.option (udpa.annotations.file_migrate).move_to_package = "<package name>";
to denote that in the next major version of the API, the file will be moved to
the given package. This is consumed by protoxform
.option (udpa.annotations.file_status).work_in_progress = true;
to denote a
file that is still work-in-progress and subject to breaking changes.此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。