Secret discovery service (SDS)

The most important benefit of SDS is to simplify the certificate management. Without this feature, in k8s deployment, certificates must be created as secrets and mounted into the proxy containers. If certificates are expired, the secrets need to be updated and the proxy containers need to be re-deployed. With SDS, a central SDS server will push certificates to all Envoy instances. If certificates are expired, the server just pushes new certificates to Envoy instances, Envoy will use the new ones right away without re-deployment.

If a listener server certificate needs to be fetched by SDS remotely, it will NOT be marked as active, its port will not be opened before the certificates are fetched. If Envoy fails to fetch the certificates due to connection failures, or bad response data, the listener will be marked as active, and the port will be open, but the connection to the port will be reset.

Upstream clusters are handled in a similar way, if a cluster client certificate needs to be fetched by SDS remotely, it will NOT be marked as active and it will not be used before the certificates are fetched. If Envoy fails to fetch the certificates due to connection failures, or bad response data, the cluster will be marked as active, it can be used to handle the requests, but the requests routed to that cluster will be rejected.

If a static cluster is using SDS, and it needs to define a SDS cluster (unless Google gRPC is used which doens’t need a cluster), the SDS cluster has to be defined before the static clusters using it.

A SDS server needs to implement the gRPC service SecretDiscoveryService. It follows the same protocol as other

SdsSecretConfig is used to specify the secret. Its field name is a required field. If its sds_config field is empty, the name field specifies the secret in the bootstrap static_resource . Otherwise, it specifies the SDS server as ConfigSource. Only gRPC is supported for the SDS service so its api_config_source must specify a grpc_service.

SdsSecretConfig is used in two fields in . The first field is tls_certificate_sds_secret_configs to use SDS to get TlsCertificate. The second field is validation_context_sds_secret_config to use SDS to get .

This example show how to configure secrets in the static_resource:

This example shows how to configure secrets fetched from remote SDS servers:

  - name: sds_server_mtls
    http2_protocol_options: {}
    hosts:
      socket_address:
        address: 127.0.0.1
        port_value: 8234
    tls_context:
      common_tls_context:
      - tls_certificate:
        certificate_chain:
          filename: certs/sds_cert.pem
        private_key:
          filename: certs/sds_key.pem
    http2_protocol_options: {}
    hosts:
      - pipe:
  - name: example_cluster
    connect_timeout: 0.25s
    hosts:
    - name: local_service_tls
      ...
      tls_context:
        common_tls_context:
          tls_certificate_sds_secret_configs:
          - name: client_cert
            sds_config:
              api_config_source:
                api_type: GRPC
                grpc_services:
                  google_grpc:
                    target_uri: unix:/tmp/uds_path
  ....
    tls_context:
      common_tls_context:
        tls_certificate_sds_secret_configs:
        - name: server_cert
          sds_config:
            api_config_source:
              api_type: GRPC
              grpc_services:
                envoy_grpc:
                  cluster_name: sds_server_mtls
        validation_context_sds_secret_config:
          name: validation_context
          sds_config:
            api_config_source:
              api_type: GRPC
              grpc_services:
                envoy_grpc:

For illustration, above example uses three methods to access the SDS server. A gRPC SDS server can be reached by Unix Domain Socket path /tmp/uds_path and 127.0.0.1:8234 by mTLS. It provides three secrets, client_cert, server_cert and validation_context. In the config, cluster example_cluster certificate client_cert is configured to use Google gRPC with UDS to talk to the SDS server. The Listener needs to fetch server_cert and validation_context from the SDS server. The server_cert is using Envoy gRPC with cluster sds_server_mtls configured with client certificate to use mTLS to talk to SDS server. The validate_context is using Envoy gRPC with cluster sds_server_uds configured with UDS path to talk to the SDS server.

SSL socket factory outputs following SDS related statistics. They are all counter type.

For downstream listeners, they are in the listener..server_ssl_socket_factory. namespace.