Google Cloud Platform C++ Client Libraries: Client Configuration

The Google Cloud C++ Client Libraries allow you to configure client behavior via the google::cloud::Options class passed to the client constructor or the connection factory functions.

1. Common Configuration Options

The google::cloud::Options class is a type-safe map where you set specific option structs.

Option Struct	Description
google::cloud::EndpointOption	The address of the API remote host. Used for Regional Endpoints.
google::cloud::UserProjectOption	Quota project to use for the request.
google::cloud::AuthorityOption	Sets the :authority pseudo-header (useful for testing/emulators).
google::cloud::UnifiedCredentialsOption	Explicit credentials object (overrides default discovery).
google::cloud::TracingComponentsOption	Controls client-side logging/tracing.

2. Customizing the API Endpoint

You can modify the API endpoint to connect to a specific Google Cloud region or to a private endpoint.

Connecting to a Regional Endpoint

namespace pubsub = ::google::cloud::pubsub;
using ::google::cloud::Options;
[](https://github.com/googleapis/google-cloud-cpp/blob/main/std::string const& project_id, std::string const& topic_id) {
  // This service supports specifying a regional or locational endpoint prefix
  // when creating the SubscriptionAdminConnection.
  // For example, to connect to "europe-central2-pubsub.googleapis.com":
  auto pub = pubsub::Publisher(pubsub::MakePublisherConnection(
      "europe-central2", pubsub::Topic(project_id, topic_id)));

  // This configuration is common with Private Google Access:
  //     https://cloud.google.com/vpc/docs/private-google-access
  auto vpc_pub = pubsub::Publisher(pubsub::MakePublisherConnection(
      pubsub::Topic(project_id, topic_id),
      Options{}.set<google::cloud::EndpointOption>(
          "private.googleapis.com")));
}

3. Configuring a Proxy

Proxy with gRPC

The C++ gRPC layer respects standard environment variables. You generally do not configure this in C++ code.

Set the following environment variables in your shell or Docker container:

export http_proxy="http://proxy.example.com:3128"
export https_proxy="http://proxy.example.com:3128"

Handling Self-Signed Certificates: If your proxy uses a self-signed certificate, use the standard gRPC environment variable:

export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="/path/to/roots.pem"

Proxy with REST

If using a library that supports REST (like google-cloud-storage), it primarily relies on libcurl, which also respects the standard http_proxy and https_proxy environment variables.

4. Configuring Retries and Timeouts

In C++, retry policies are configured via Options or passed specifically to the connection factory.

Configuring Retry Policies

You can set the RetryPolicyOption and BackoffPolicyOption.

auto options =
    google::cloud::Options{}
        .set<google::cloud::secretmanager_v1::
                 SecretManagerServiceConnectionIdempotencyPolicyOption>(
            CustomIdempotencyPolicy().clone())
        .set<google::cloud::secretmanager_v1::
                 SecretManagerServiceRetryPolicyOption>(
            google::cloud::secretmanager_v1::
                SecretManagerServiceLimitedErrorCountRetryPolicy(3)
                    .clone())
        .set<google::cloud::secretmanager_v1::
                 SecretManagerServiceBackoffPolicyOption>(
            google::cloud::ExponentialBackoffPolicy(
                /*initial_delay=*/std::chrono::milliseconds(200),
                /*maximum_delay=*/std::chrono::seconds(45),
                /*scaling=*/2.0)
                .clone());
auto connection =
    google::cloud::secretmanager_v1::MakeSecretManagerServiceConnection(
        options);

// c1 and c2 share the same retry policies
auto c1 =
    google::cloud::secretmanager_v1::SecretManagerServiceClient(connection);
auto c2 =
    google::cloud::secretmanager_v1::SecretManagerServiceClient(connection);

// You can override any of the policies in a new client. This new client
// will share the policies from c1 (or c2) *except* for the retry policy.
auto c3 = google::cloud::secretmanager_v1::SecretManagerServiceClient(
    connection, google::cloud::Options{}
                    .set<google::cloud::secretmanager_v1::
                             SecretManagerServiceRetryPolicyOption>(
                        google::cloud::secretmanager_v1::
                            SecretManagerServiceLimitedTimeRetryPolicy(
                                std::chrono::minutes(5))
                                .clone()));

// You can also override the policies in a single call:
// c3.SomeRpc(..., google::cloud::Options{}
//     .set<google::cloud::secretmanager_v1::SecretManagerServiceRetryPolicyOption>(
//       google::cloud::secretmanager_v1::SecretManagerServiceLimitedErrorCountRetryPolicy(10).clone()));

Configuring Timeouts

There isn't a single "timeout" integer. Instead, you can configure the Idempotency Policy (to determine which RPCs are safe to retry) or use google::cloud::Options to set specific RPC timeouts if the library exposes a specific option, though usually, the RetryPolicy (Total Timeout) governs the duration of the call.

For per-call context (like deadlines), you can sometimes use grpc::ClientContext if dropping down to the raw stub level, but idiomatic Google Cloud C++ usage prefers the Policy approach.