aws: update credential provider proto and support credential file reload

api/envoy/extensions/common/aws/v3/BUILD

@@ -5,5 +5,8 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
 licenses(["notice"])  # Apache 2
 
 api_proto_package(
-    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+    deps = [
+        "//envoy/config/core/v3:pkg",
+        "@com_github_cncf_xds//udpa/annotations:pkg",
+    ],
 )

api/envoy/extensions/common/aws/v3/credential_provider.proto

@@ -2,6 +2,8 @@ syntax = "proto3";
 
 package envoy.extensions.common.aws.v3;
 
+import "envoy/config/core/v3/base.proto";
+
 import "udpa/annotations/sensitive.proto";
 import "udpa/annotations/status.proto";
 import "validate/validate.proto";
@@ -14,18 +16,26 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: AWS common configuration]
 
-// Configuration for AWS credential provider. Normally, this is optional and the credentials are
+// Configuration for AWS credential provider. This is optional and the credentials are normally
 // retrieved from the environment or AWS configuration files by following the default credential
-// provider chain. This is to support cases where the credentials need to be explicitly provided
-// by the control plane.
+// provider chain. However, this configuration can be used to override the default behavior.
 message AwsCredentialProvider {
   // The option to use `AssumeRoleWithWebIdentity <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`_.
-  // If inline_credential is set, this is ignored.
-  AssumeRoleWithWebIdentityCredentialProvider assume_role_with_web_identity = 1;
+  AssumeRoleWithWebIdentityCredentialProvider assume_role_with_web_identity_provider = 1;
 
-  // The option to use an inline credential.
-  // If this is set, it takes precedence over assume_role_with_web_identity.
+  // The option to use an inline credential. If inline credential is provided, no chain will be created and only the inline credential will be used.
   InlineCredentialProvider inline_credential = 2;
+
+  // The option to specify parameters for credential retrieval from an envoy data source, such as a file in AWS credential format.
+  CredentialsFileCredentialProvider credentials_file_provider = 3;
+
+  // Create a custom credential provider chain instead of the default credential provider chain.
+  // If set to TRUE, the credential provider chain that is created contains only those set in this credential provider message.
+  // If set to FALSE, the settings provided here will act as modifiers to the default credential provider chain.
+  // Defaults to FALSE.
+  //
+  // This has no effect if inline_credential is provided.
+  bool custom_credential_provider_chain = 4;
 }
 
 // Configuration to use an inline AWS credential. This is an equivalent to setting the well-known
@@ -43,12 +53,27 @@ message InlineCredentialProvider {
 }
 
 // Configuration to use `AssumeRoleWithWebIdentity <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`_
-// to get AWS credentials.
+// to retrieve AWS credentials.
 message AssumeRoleWithWebIdentityCredentialProvider {
+  // Data source for a web identity token that is provided by the identity provider to assume the role.
+  // When using this data source, even if a ``watched_directory`` is provided, the token file will only be re-read when the credentials
+  // returned from AssumeRoleWithWebIdentity expire.
+  config.core.v3.DataSource web_identity_token_data_source = 1
+      [(udpa.annotations.sensitive) = true];
+
   // The ARN of the role to assume.
-  string role_arn = 1 [(validate.rules).string = {min_len: 1}];
+  string role_arn = 2 [(validate.rules).string = {min_len: 1}];
 
-  // The web identity token that is provided by the identity provider to assume the role.
-  string web_identity_token = 2
-      [(validate.rules).string = {min_len: 1}, (udpa.annotations.sensitive) = true];
+  // Optional role session name to use in AssumeRoleWithWebIdentity API call.
+  string role_session_name = 3;
+}
+
+message CredentialsFileCredentialProvider {
+  // Data source from which to retrieve AWS credentials
+  // When using this data source, if a ``watched_directory`` is provided, the credential file will be re-read when a file move is detected.
+  // See :ref:`watched_directory <envoy_v3_api_msg_config.core.v3.DataSource>` for more information about the ``watched_directory`` field.
+  config.core.v3.DataSource credentials_data_source = 1 [(udpa.annotations.sensitive) = true];
+
+  // The profile within the credentials_file data source. If not provided, the default profile will be used.
+  string profile = 2;
 }

changelogs/current.yaml

@@ -209,7 +209,8 @@ new_features:
   change: |
     Added an optional field :ref:`credential_provider
     <envoy_v3_api_field_extensions.filters.http.aws_request_signing.v3.AwsRequestSigning.credential_provider>`
-    to the AWS request signing filter to explicitly specify a source for AWS credentials.
+    to the AWS request signing filter to explicitly specify a source for AWS credentials. Credential file and AssumeRoleWithWebIdentity
+    behaviour can also be overridden with this field.
 - area: tls
   change: |
     Added support for P-384 and P-521 curves for TLS server certificates.

docs/root/configuration/http/http_filters/_include/aws-request-signing-filter-credential-provider-config.yaml

@@ -0,0 +1,70 @@
+static_resources:
+  listeners:
+  - address:
+      socket_address:
+        address: 0.0.0.0
+        port_value: 10000
+    filter_chains:
+    - filters:
+      - name: envoy.filters.network.http_connection_manager
+        typed_config:
+          '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+          stat_prefix: ingress_http
+          http_filters:
+          - name: envoy.filters.http.router
+            typed_config:
+              '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - domains:
+              - '*'
+              name: local_service
+              routes:
+              - match: {prefix: "/"}
+                route: {cluster: default_service}
+  clusters:
+  - name: default_service
+    load_assignment:
+      cluster_name: default_service
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 10001
+    typed_extension_protocol_options:
+      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
+        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
+        upstream_http_protocol_options:
+          auto_sni: true
+          auto_san_validation: true
+        auto_config:
+          http2_protocol_options: {}
+        http_filters:
+        - name: envoy.filters.http.aws_request_signing
+          typed_config:
+            "@type": type.googleapis.com/envoy.extensions.filters.http.aws_request_signing.v3.AwsRequestSigning
+            credential_provider:
+              custom_credential_provider_chain: true
+              credentials_file_provider:
+                credentials_data_source:
+                  filename: /tmp/a
+                  watched_directory:
+                    path: /tmp
+            service_name: vpc-lattice-svcs
+            region: '*'
+            signing_algorithm: AWS_SIGV4A
+            use_unsigned_payload: true
+            match_excluded_headers:
+            - prefix: x-envoy
+            - prefix: x-forwarded
+            - exact: x-amzn-trace-id
+        - name: envoy.filters.http.upstream_codec
+          typed_config:
+            "@type": type.googleapis.com/envoy.extensions.filters.http.upstream_codec.v3.UpstreamCodec
+    transport_socket:
+      name: envoy.transport_sockets.tls
+      typed_config:
+        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext

docs/root/configuration/http/http_filters/_include/aws_credentials.rst

@@ -5,13 +5,24 @@ The filter uses a number of different credentials providers to obtain an AWS acc
 By default, it moves through the credentials providers in the order described below, stopping when one of them returns an access key ID and a
 secret access key (the session token is optional).
 
-1. Environment variables. The environment variables ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY``, and ``AWS_SESSION_TOKEN`` are used.
+1. :ref:`inline_credentials <envoy_v3_api_field_extensions.common.aws.v3.AwsCredentialProvider.inline_credential>` field.
+   If this field is configured, no other credentials providers will be used.
 
-2. The AWS credentials file. The environment variables ``AWS_SHARED_CREDENTIALS_FILE`` and ``AWS_PROFILE`` are respected if they are set, else
+2. :ref:`credential_provider <envoy_v3_api_field_extensions.filters.http.aws_request_signing.v3.AwsRequestSigning.credential_provider>` field.
+   By using this field, the filter allows override of the default environment variables, credential parameters and file locations.
+   Currently this supports both AWS credentials file locations and content, and AssumeRoleWithWebIdentity token files.
+   If the :ref:`credential_provider <envoy_v3_api_field_extensions.filters.http.aws_request_signing.v3.AwsRequestSigning.credential_provider>` field is provided,
+   it can be used either to modify the default credentials provider chain, or when :ref:`custom_credential_provider_chain <envoy_v3_api_field_extensions.common.aws.v3.AwsCredentialProvider.custom_credential_provider_chain>`
+   is set to ``true``, to create a custom credentials provider chain containing only the specified credentials provider settings. Examples of using these fields
+   are provided in :ref:`configuration examples <config_http_filters_aws_request_signing_examples>`.
+
+3. Environment variables. The environment variables ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY``, and ``AWS_SESSION_TOKEN`` are used.
+
+4. The AWS credentials file. The environment variables ``AWS_SHARED_CREDENTIALS_FILE`` and ``AWS_PROFILE`` are respected if they are set, else
    the file ``~/.aws/credentials`` and profile ``default`` are used. The fields ``aws_access_key_id``, ``aws_secret_access_key``, and
    ``aws_session_token`` defined for the profile in the credentials file are used. These credentials are cached for 1 hour.
 
-3. From `AssumeRoleWithWebIdentity <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`_ API call
+5. From `AssumeRoleWithWebIdentity <https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html>`_ API call
    towards AWS Security Token Service using ``WebIdentityToken`` read from a file pointed by ``AWS_WEB_IDENTITY_TOKEN_FILE`` environment
    variable and role arn read from ``AWS_ROLE_ARN`` environment variable. The credentials are extracted from the fields ``AccessKeyId``,
    ``SecretAccessKey``, and ``SessionToken`` are used, and credentials are cached for 1 hour or until they expire (according to the field
@@ -30,7 +41,7 @@ secret access key (the session token is optional).
   If you require the use of SigV4A signing and you are using an alternate partition, such as cn or GovCloud, you can ensure correct generation
   of the STS endpoint by setting the first region in your SigV4A region set to the correct region (such as ``cn-northwest-1`` with no wildcard)
 
-4. Either EC2 instance metadata, ECS task metadata or EKS Pod Identity.
+6. Either EC2 instance metadata, ECS task metadata or EKS Pod Identity.
    For EC2 instance metadata, the fields ``AccessKeyId``, ``SecretAccessKey``, and ``Token`` are used, and credentials are cached for 1 hour.
    For ECS task metadata, the fields ``AccessKeyId``, ``SecretAccessKey``, and ``Token`` are used, and credentials are cached for 1 hour or
    until they expire (according to the field ``Expiration``).
@@ -46,9 +57,6 @@ secret access key (the session token is optional).
    The static internal cluster will still be added even if initially ``envoy.reloadable_features.use_http_client_to_fetch_aws_credentials`` is
    not set so that subsequently if the reloadable feature is set to ``true`` the cluster config is available to fetch the credentials.
 
-Alternatively, each AWS filter (either AWS Request Signing or AWS Lambda) has its own optional configuration to specify the source of the credentials. For example, AWS Request Signing filter
-has :ref:`credential_provider <envoy_v3_api_field_extensions.filters.http.aws_request_signing.v3.AwsRequestSigning.credential_provider>` field.
-
 Statistics
 ----------
 

docs/root/configuration/http/http_filters/aws_request_signing_filter.rst

@@ -59,6 +59,8 @@ the following HTTP header modifications will be made by this extension:
 Example configuration
 ---------------------
 
+.. _config_http_filters_aws_request_signing_examples:
+
 Example filter configuration:
 
 .. literalinclude:: _include/aws-request-signing-filter.yaml
@@ -86,6 +88,16 @@ An example of configuring this filter to use ``AWS_SIGV4A`` signing with a wildc
     :linenos:
     :caption: :download:`aws-request-signing-filter-sigv4a.yaml <_include/aws-request-signing-filter-sigv4a.yaml>`
 
+An example of using the credential provider configuration to modify the default behaviour of the credential provider chain. In this scenario, we use
+the ``custom_credential_provider_chain`` option to disable the default credential provider chain and use specific settings for the credential file
+credentials provider. These settings include a ``watched_directory``, which configures the filter to reload the credentials file when it changes.
+
+.. literalinclude:: _include/aws-request-signing-filter-credential-provider-config.yaml
+    :language: yaml
+    :lines: 46-56
+    :lineno-start: 46
+    :linenos:
+    :caption: :download:`aws-request-signing-filter-credential-provider-config.yaml <_include/aws-request-signing-filter-credential-provider-config.yaml>`
 
 Configuration as an upstream HTTP filter
 ----------------------------------------

source/extensions/common/aws/BUILD

@@ -120,12 +120,14 @@ envoy_cc_library(
         "//envoy/api:api_interface",
         "//source/common/common:logger_lib",
         "//source/common/common:thread_lib",
+        "//source/common/config:datasource_lib",
         "//source/common/http:utility_lib",
         "//source/common/init:target_lib",
         "//source/common/json:json_loader_lib",
         "//source/common/runtime:runtime_features_lib",
         "//source/common/tracing:http_tracer_lib",
         "@com_google_absl//absl/time",
+        "@envoy_api//envoy/config/core/v3:pkg_cc_proto",
         "@envoy_api//envoy/extensions/common/aws/v3:pkg_cc_proto",
     ],
 )
@@ -176,5 +178,6 @@ envoy_cc_library(
         ":region_provider_interface",
         ":utility_lib",
         "//source/common/common:logger_lib",
+        "@envoy_api//envoy/extensions/common/aws/v3:pkg_cc_proto",
     ],
 )