Merge pull request #4 from envoyproxy/master

sync from master.

.azure-pipelines/pipelines.yml

@@ -160,6 +160,24 @@ jobs:
           artifactName: docker
         condition: always()
 
+  - job: examples
+    dependsOn: ["docker"]
+    displayName: "Verify examples run as documented"
+    pool:
+      vmImage: "ubuntu-18.04"
+    steps:
+      - task: DownloadBuildArtifacts@0
+        inputs:
+          buildType: current
+          artifactName: "docker"
+          itemPattern: "docker/envoy-docker-images.tar.xz"
+          downloadType: single
+          targetPath: $(Build.StagingDirectory)
+      - bash: ./ci/do_ci.sh verify_examples
+        env:
+          ENVOY_DOCKER_BUILD_DIR: $(Build.StagingDirectory)
+          NO_BUILD_SETUP: 1
+
   - job: macOS
     dependsOn: ["format"]
     timeoutInMinutes: 360

.bazelrc

@@ -129,6 +129,7 @@ build:coverage --action_env=GCOV=llvm-profdata
 build:coverage --copt=-DNDEBUG
 # 1.5x original timeout + 300s for trace merger in all categories
 build:coverage --test_timeout=390,750,1500,5700
+build:coverage --define=dynamic_link_tests=true
 build:coverage --define=ENVOY_CONFIG_COVERAGE=1
 build:coverage --cxxopt="-DENVOY_CONFIG_COVERAGE=1"
 build:coverage --coverage_support=@envoy//bazel/coverage:coverage_support

DEPENDENCY_POLICY.md

@@ -0,0 +1,103 @@
+# Envoy External Dependency Policy
+
+Envoy has an evolving policy on external dependencies, tracked at
+https://github.com/envoyproxy/envoy/issues/10471. This will become stricter over time, below we
+detail the policy as it currently applies.
+
+## External dependencies dashboard
+
+The list of external dependencies in Envoy with their current version is available at
+https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/external_deps
+
+## Declaring external dependencies
+
+In general, all external dependencies for the Envoy proxy binary build and test should be declared
+in either [bazel/repository_locations.bzl](bazel/repository_locations.bzl) or
+[api/bazel/repository_locations.bzl](api/bazel/repository_locations.bzl), unless listed under
+[policy exceptions](#policy-exceptions).
+
+An example entry for the `nghttp2` dependency is:
+
+```python
+com_github_nghttp2_nghttp2 = dict(
+    project_name = "Nghttp2",
+    project_url = "https://nghttp2.org",
+    version = "1.41.0",
+    sha256 = "eacc6f0f8543583ecd659faf0a3f906ed03826f1d4157b536b4b385fe47c5bb8",
+    strip_prefix = "nghttp2-{version}",
+    urls = ["https://github.com/nghttp2/nghttp2/releases/download/v{version}/nghttp2-{version}.tar.gz"],
+    use_category = ["dataplane"],
+    cpe = "cpe:2.3:a:nghttp2:nghttp2:*",
+),
+```
+
+Dependency declarations must:
+
+* Provide a meaningful project name and URL.
+* State the version in the `version` field. String interpolation should be used in `strip_prefix`
+  and `urls` to reference the version. If you need to reference version `X.Y.Z` as `X_Y_Z`, this
+  may appear in a string as `{underscore_version}`, similarly for `X-Y-Z` you can use
+  `{dash_version}`.
+* Versions should prefer release versions over master branch GitHub SHA tarballs. A comment is
+  necessary if the latter is used. This comment should contain the reason that a non-release
+  version is being used and the YYYY-MM-DD when the last update was performed.
+* Provide accurate entries for `use_category`. Please think carefully about whether there are data
+  or control plane implications of the dependency.
+* CPEs are compulsory for all dependencies that are not purely build/test.
+  [CPEs](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) provide metadata that allow us
+  to correlate with related CVEs in dashboards and other tooling, and also provide a machine
+  consumable join key. You can consult the latest [CPE
+  dictionary](https://nvd.nist.gov/products/cpe) to find a CPE for a dependency.`"N/A"` should only
+  be used if no CPE for the project is available in the CPE database. CPEs should be _versionless_
+  with a `:*` suffix, since the version can be computed from `version`.
+
+When build or test code references Python modules, they should be imported via `pip3_import` in
+[bazel/repositories_extra.bzl](bazel/repositories_extra.bzl). Python modules should not be listed in
+`repository_locations.bzl` entries. `requirements.txt` files for Python dependencies must pin to
+exact versions, e.g. `PyYAML==5.3.1` and ideally also include a [SHA256
+checksum](https://davidwalsh.name/hashin).
+
+Pure developer tooling and documentation builds may reference Python via standalone
+`requirements.txt`, following the above policy.
+
+## New external dependencies
+
+* Any new dependency on the Envoy data or control plane that impacts Envoy core (i.e. is not
+  specific to a single non-core extension) must be cleared with the Envoy security team, please file
+  an issue and tag
+  [@envoyproxy/security-team](https://github.com/orgs/envoyproxy/teams/security-team). While policy
+  is still [evolving](robust_to_untrusted_downstream_and_upstream), criteria that will be used in
+  evaluation include:
+  * Does the project have release versions? How often do releases happen?
+  * Does the project have a security vulnerability disclosure process and contact details?
+  * Does the project have effective governance, e.g. multiple maintainers, a governance policy?
+  * Does the project have a code review culture? Are patches reviewed by independent maintainers
+    prior to merge?
+  * Does the project enable mandatory GitHub 2FA for contributors?
+  * Does the project have evidence of high test coverage, fuzzing, static analysis (e.g. CodeQL),
+    etc.?
+
+* Dependencies for extensions that are tagged as `robust_to_untrusted_downstream` or
+  `robust_to_untrusted_downstream_and_upstream` should be sensitive to the same set of concerns
+  as the core data plane.
+
+## Maintaining existing dependencies
+
+We rely on community volunteers to help track the latest versions of dependencies. On a best effort
+basis:
+
+* Core Envoy dependencies will be updated by the Envoy maintainers/security team.
+
+* Extension [CODEOWNERS](CODEOWNERS) should update extension specific dependencies.
+
+Where possible, we prefer the latest release version for external dependencies, rather than master
+branch GitHub SHA tarballs.
+
+## Policy exceptions
+
+The following dependencies are exempt from the policy:
+
+* Any developer-only facing tooling or the documentation build.
+
+* Transitive build time dependencies, e.g. Go projects vendored into
+  [protoc-gen-validate](https://github.com/envoyproxy/protoc-gen-validate).

EXTENSION_POLICY.md

@@ -33,6 +33,8 @@ The following procedure will be used when proposing new extensions for inclusion
   4. Any extension added via this process becomes a full part of the repository. This means that any
   API breaking changes in the core code will be automatically fixed as part of the normal PR process
   by other contributors.
+  5. Any new dependencies added for this extension must comply with
+  [DEPENDENCY_POLICY.md](DEPENDENCY_POLICY.md), please follow the steps detailed there.
 
 ## Removing existing extensions
 
@@ -56,3 +58,54 @@ may be a single individual, but it is always preferred to have multiple reviewer
 In the event that the Extension PR author is a sponsoring maintainer and no other sponsoring maintainer
 is available, another maintainer may be enlisted to perform a minimal review for style and common C++
 anti-patterns. The Extension PR must still be approved by a non-maintainer reviewer.
+
+## Extension stability and security posture
+
+Every extension is expected to be tagged with a `status` and `security_posture` in its
+`envoy_cc_extension` rule.
+
+The `status` is one of:
+* `stable`: The extension is stable and is expected to be production usable. This is the default if
+  no `status` is specified.
+* `alpha`: The extension is functional but has not had substantial production burn time, use only
+  with this caveat.
+* `wip`: The extension is work-in-progress. Functionality is incomplete and it is not intended for
+  production use.
+
+The extension status may be adjusted by the extension [CODEOWNERS](./CODEOWNERS) and/or Envoy
+maintainers based on an assessment of the above criteria. Note that the status of the extension
+reflects the implementation status. It is orthogonal to the API stability, for example, an extension
+with configuration `envoy.foo.v3alpha.Bar` might have a `stable` implementation and
+`envoy.foo.v3.Baz` can have a `wip` implementation.
+
+The `security_posture` is one of:
+* `robust_to_untrusted_downstream`: The extension is hardened against untrusted downstream traffic. It
+   assumes that the upstream is trusted.
+* `robust_to_untrusted_downstream_and_upstream`: The extension is hardened against both untrusted
+   downstream and upstream traffic.
+* `requires_trusted_downstream_and_upstream`: The extension is not hardened and should only be used in deployments
+   where both the downstream and upstream are trusted.
+* `unknown`: This is functionally equivalent to `requires_trusted_downstream_and_upstream`, but acts
+  as a placeholder to allow us to identify extensions that need classifying.
+* `data_plane_agnostic`: Not relevant to data plane threats, e.g. stats sinks.
+
+An assessment of a robust security posture for an extension is subject to the following guidelines:
+
+* Does the extension have fuzz coverage? If it's only receiving fuzzing
+  courtesy of the generic listener/network/HTTP filter fuzzers, does it have a
+  dedicated fuzzer for any parts of the code that would benefit?
+* Does the extension have unbounded internal buffering? Does it participate in
+  flow control via watermarking as needed?
+* Does the extension have at least one deployment with live untrusted traffic
+  for a period of time, N months?
+* Does the extension rely on dependencies that meet our [extension maturity
+  model](https://github.com/envoyproxy/envoy/issues/10471)?
+* Is the extension reasonable to audit by Envoy security team?
+* Is the extension free of obvious scary things, e.g. `memcpy`, does it have gnarly parsing code, etc?
+* Does the extension have active [CODEOWNERS](CODEOWNERS) who are willing to
+  vouch for the robustness of the extension?
+* Is the extension absent a [low coverage
+  exception](https://github.com/envoyproxy/envoy/blob/master/test/per_file_coverage.sh#L5)?
+
+The current stability and security posture of all extensions can be seen
+[here](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/threat_model#core-and-extensions).

GOVERNANCE.md

@@ -150,11 +150,47 @@ If a maintainer is no longer interested or cannot perform the maintainer duties
 should volunteer to be moved to emeritus status. In extreme cases this can also occur by a vote of
 the maintainers per the voting process below.
 
+# xDS API shepherds
+
+The [xDS API shepherds](https://github.com/orgs/envoyproxy/teams/api-shepherds) are responsible for
+approving any PR that modifies the [api/](api/) tree. They ensure that API [style](api/STYLE.md) and
+[versioning](api/API_VERSIONING.md) policies are enforced and that a consistent approach is taken
+towards API evolution.
+
+The xDS API shepherds are also the xDS API maintainers; they work collaboratively with the community
+to drive the xDS API roadmap and review major proposed design changes. The API shepherds are
+intended to be representative of xDS client and control plane developers who are actively working on
+xDS development and evolution.
+
+As with maintainers, an API shepherd should be spending at least 25% of their time working on xDS
+developments and expect to be active in this space in the near future. API shepherds are expected to
+take on API shepherd review load and participate in meetings. They should be active on Slack `#xds`
+and responsive to GitHub issues and PRs on which they are tagged.
+
+The API shepherds are distinct to the [UDPA working
+group](https://github.com/cncf/udpa/blob/master/README.md), which aims to evolve xDS directionally
+towards a universal dataplane API. API shepherds are responsible for the execution of the xDS
+day-to-day and guiding xDS implementation changes. Proposals from UDPA-WG will be aligned with the
+xDS API shepherds to ensure that xDS is heading towards the UDPA goal. xDS API shepherds operate
+under the [envoyproxy](https://github.com/envoyproxy) organization but are expected to keep in mind
+the needs of all xDS clients (currently Envoy and gRPC, but we are aware of other in-house
+implementations) and the goals of UDPA-WG.
+
+If you wish to become an API shepherd and satisfy the above criteria, please contact an existing
+API shepherd. We will factor in PR and review history to determine if the above API shepherd
+requirements are met. We may ask you to shadow an existing API shepherd for a period of time to
+build confidence in consistent application of the API guidelines to PRs.
+
 # Extension addition policy
 
 Adding new [extensions](REPO_LAYOUT.md#sourceextensions-layout) has a dedicated policy. Please
 see [this](./EXTENSION_POLICY.md) document for more information.
 
+# Exernal dependency policy
+
+Adding new external dependencies has a dedicated policy. Please see [this](DEPENDENCY_POLICY.md)
+document for more information.
+
 # Conflict resolution and voting
 
 In general, we prefer that technical issues and maintainer membership are amicably worked out

api/envoy/admin/v3/init_dump.proto

@@ -0,0 +1,32 @@
+syntax = "proto3";
+
+package envoy.admin.v3;
+
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+
+option java_package = "io.envoyproxy.envoy.admin.v3";
+option java_outer_classname = "InitDumpProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: InitDump]
+
+// Dumps of unready targets of envoy init managers. Envoy's admin fills this message with init managers,
+// which provides the information of their unready targets.
+// The :ref:`/init_dump <operations_admin_interface_init_dump>` will dump all unready targets information.
+message UnreadyTargetsDumps {
+  // Message of unready targets information of an init manager.
+  message UnreadyTargetsDump {
+    // Name of the init manager. Example: "init_manager_xxx".
+    string name = 1;
+
+    // Names of unready targets of the init manager. Example: "target_xxx".
+    repeated string target_names = 2;
+  }
+
+  // You can choose specific component to dump unready targets with mask query parameter.
+  // See :ref:`/init_dump?mask={} <operations_admin_interface_init_dump_by_mask>` for more information.
+  // The dumps of unready targets of all init managers.
+  repeated UnreadyTargetsDump unready_targets_dumps = 1;
+}

api/envoy/config/bootstrap/v3/bootstrap.proto

@@ -40,7 +40,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // <config_overview_bootstrap>` for more detail.
 
 // Bootstrap :ref:`configuration overview <config_overview_bootstrap>`.
-// [#next-free-field: 26]
+// [#next-free-field: 27]
 message Bootstrap {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.bootstrap.v2.Bootstrap";
@@ -108,6 +108,40 @@ message Bootstrap {
   // identification purposes (e.g. in generated headers).
   core.v3.Node node = 1;
 
+  // A list of :ref:`Node <envoy_v3_api_msg_config.core.v3.Node>` field names
+  // that will be included in the context parameters of the effective
+  // *UdpaResourceLocator* that is sent in a discovery request when resource
+  // locators are used for LDS/CDS. Any non-string field will have its JSON
+  // encoding set as the context parameter value, with the exception of
+  // metadata, which will be flattened (see example below). The supported field
+  // names are:
+  // - "cluster"
+  // - "id"
+  // - "locality.region"
+  // - "locality.sub_zone"
+  // - "locality.zone"
+  // - "metadata"
+  // - "user_agent_build_version.metadata"
+  // - "user_agent_build_version.version"
+  // - "user_agent_name"
+  // - "user_agent_version"
+  //
+  // The node context parameters act as a base layer dictionary for the context
+  // parameters (i.e. more specific resource specific context parameters will
+  // override). Field names will be prefixed with “udpa.node.” when included in
+  // context parameters.
+  //
+  // For example, if node_context_params is ``["user_agent_name", "metadata"]``,
+  // the implied context parameters might be::
+  //
+  //   node.user_agent_name: "envoy"
+  //   node.metadata.foo: "{\"bar\": \"baz\"}"
+  //   node.metadata.some: "42"
+  //   node.metadata.thing: "\"thing\""
+  //
+  // [#not-implemented-hide:]
+  repeated string node_context_params = 26;
+
   // Statically specified resources.
   StaticResources static_resources = 2;