diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c59d73c0e7222..9b6e47913f07f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -253,15 +253,9 @@ Extension configuration should be located in a directory structure like The code for the extension should be located under the equivalent `source/extensions/area/plugin`, and include an *envoy_cc_extension* with the configuration and tagged with the appropriate security posture, and an -*envoy_cc_library* with the code. More details on how to add a new extension -API can be found [here](api/STYLE.md#adding-an-extension-configuration-to-the-api): +*envoy_cc_library* with the code. -Other changes will likely include - - * Editing [source/extensions/extensions_build_config.bzl](source/extensions/extensions_build_config.bzl) to include the new extensions - * Editing [source/extensions/extensions_metadata.yaml](source/extensions/extensions_metadata.yaml) to include metadata for the new extensions - * Editing [docs/root/api-v3/config/config.rst](docs/root/api-v3/config/config.rst) to add area/area - * Adding `docs/root/api-v3/config/area/area.rst` to add a table of contents for the API docs +More details on how to add a new extension API can be found [here](api/STYLE.md#adding-an-extension-configuration-to-the-api): # Adding contrib extensions diff --git a/OWNERS.md b/OWNERS.md index 74100d89c40be..f4b600c7d29d1 100644 --- a/OWNERS.md +++ b/OWNERS.md @@ -65,6 +65,7 @@ without further review. * Tony Allen ([tonya11en](https://github.com/tonya11en)) (tony@allen.gg) * Dmitri Dolguikh ([dmitri-d](https://github.com/dmitri-d)) (ddolguik@redhat.com) * Yan Avlasov ([yanavlasov](https://github.com/yanavlasov)) (yavlasov@google.com) +* William A Rowe Jr ([wrowe](https://github.com/wrowe)) (wrowe@vmware.com) # Emeritus maintainers diff --git a/api/STYLE.md b/api/STYLE.md index d73e17b773b24..b185be97c9687 100644 --- a/api/STYLE.md +++ b/api/STYLE.md @@ -112,10 +112,9 @@ Extensions must currently be added as v3 APIs following the [package organization](#package-organization) above. To add an extension config to the API, the steps below should be followed: -1. If this is still WiP and subject to breaking changes, use `vNalpha` instead of `vN` in steps - below. Refer to the [Cache filter config](envoy/extensions/filters/http/cache/v3alpha/cache.proto) - as an example of `v3alpha`, and the - [Buffer filter config](envoy/extensions/filters/http/buffer/v3/buffer.proto) as an example of `v3`. +1. If this is still WiP and subject to breaking changes, please tag it + `option (udpa.annotations.file_status).work_in_progress = true;` and + optionally hide it from the docs (`[#not-implemented-hide:]`. 1. Place the v3 extension configuration `.proto` in `api/envoy/extensions`, e.g. `api/envoy/extensions/filters/http/foobar/v3/foobar.proto` together with an initial BUILD file: ```bazel @@ -127,16 +126,26 @@ To add an extension config to the API, the steps below should be followed: deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], ) ``` -1. Add to the v3 extension config proto `import "udpa/annotations/status.proto";` -1. If this is still WiP and subject to breaking changes, set - `option (udpa.annotations.file_status).work_in_progress = true;`. -1. Add to the v3 extension config proto a file level - `option (udpa.annotations.file_status).package_version_status = ACTIVE;`. +1. Update [source/extensions/extensions_metadata.yaml](../source/extensions/extensions_metadata.yaml) + with the category, security posture, and status. The category field will have to match an + annotation of the form `// [#extension-category: your.extension.category]` + in one of the proto files for the docs build to pass. +1. Update + [source/extensions/extensions_build_config.bzl](source/extensions/extensions_build_config.bzl) + to include the new extension. +1. If the extension is not hidden, find or create a docs file with a toctree + and to reference your proto to make sure users can navigate to it from the API docs + (and to not break the docs build). + See the [key-value-store PR](https://github.com/envoyproxy/envoy/pull/17745/files) for an example of adding a new extension point to common. +1. Make sure your proto imports the v3 extension config proto (`import "udpa/annotations/status.proto";`) +1. Make sure your proto is either tracked as a work in progress + (`option (udpa.annotations.file_status).work_in_progress = true;`) + or ready to be used + (`option (udpa.annotations.file_status).package_version_status = ACTIVE;`). This is required to automatically include the config proto in [api/versioning/BUILD](versioning/BUILD). 1. Add a reference to the v3 extension config in (1) in [api/versioning/BUILD](versioning/BUILD) under `active_protos`. 1. Run `./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. + reformat `foobar.proto` as needed and also generate the shadow API protos. 1. `git add api/ generated_api_shadow/` to add any new files to your Git index. ## API annotations diff --git a/api/envoy/config/endpoint/v3/endpoint_components.proto b/api/envoy/config/endpoint/v3/endpoint_components.proto index 0a9aac105e72d..1faf64e20c2c6 100644 --- a/api/envoy/config/endpoint/v3/endpoint_components.proto +++ b/api/envoy/config/endpoint/v3/endpoint_components.proto @@ -9,7 +9,6 @@ import "envoy/config/core/v3/health_check.proto"; import "google/protobuf/wrappers.proto"; -import "udpa/annotations/migrate.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; import "validate/validate.proto"; diff --git a/api/envoy/extensions/common/key_value/v3/config.proto b/api/envoy/extensions/common/key_value/v3/config.proto index 0db9c622cd16c..66a55435437b3 100644 --- a/api/envoy/extensions/common/key_value/v3/config.proto +++ b/api/envoy/extensions/common/key_value/v3/config.proto @@ -4,9 +4,6 @@ package envoy.extensions.common.key_value.v3; import "envoy/config/core/v3/extension.proto"; -import "google/protobuf/any.proto"; -import "google/protobuf/duration.proto"; - import "udpa/annotations/status.proto"; import "validate/validate.proto"; diff --git a/envoy/server/overload/overload_manager.h b/envoy/server/overload/overload_manager.h index 4939897c70792..bfdbb2e260c21 100644 --- a/envoy/server/overload/overload_manager.h +++ b/envoy/server/overload/overload_manager.h @@ -46,7 +46,7 @@ using OverloadActionNames = ConstSingleton; */ class OverloadActionStatsNameValues { public: - // Count of ther number of streams the reset streams action has reset + // Count of the number of streams the reset streams action has reset const std::string ResetStreamsCount = "envoy.overload_actions.reset_high_memory_stream.count"; }; diff --git a/generated_api_shadow/envoy/config/endpoint/v3/endpoint_components.proto b/generated_api_shadow/envoy/config/endpoint/v3/endpoint_components.proto index 0a9aac105e72d..1faf64e20c2c6 100644 --- a/generated_api_shadow/envoy/config/endpoint/v3/endpoint_components.proto +++ b/generated_api_shadow/envoy/config/endpoint/v3/endpoint_components.proto @@ -9,7 +9,6 @@ import "envoy/config/core/v3/health_check.proto"; import "google/protobuf/wrappers.proto"; -import "udpa/annotations/migrate.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; import "validate/validate.proto"; diff --git a/generated_api_shadow/envoy/extensions/common/key_value/v3/config.proto b/generated_api_shadow/envoy/extensions/common/key_value/v3/config.proto index 0db9c622cd16c..66a55435437b3 100644 --- a/generated_api_shadow/envoy/extensions/common/key_value/v3/config.proto +++ b/generated_api_shadow/envoy/extensions/common/key_value/v3/config.proto @@ -4,9 +4,6 @@ package envoy.extensions.common.key_value.v3; import "envoy/config/core/v3/extension.proto"; -import "google/protobuf/any.proto"; -import "google/protobuf/duration.proto"; - import "udpa/annotations/status.proto"; import "validate/validate.proto";