Setting up your repo

In order to use the Kubernetes Engine API C++ client library from your own code, you'll need to configure your build system to discover and compile the Cloud C++ client libraries. In some cases your build system or package manager may need to download the libraries too. The Cloud C++ client libraries natively support Bazel and CMake as build systems. We've created a minimal, "Hello World", quickstart that includes detailed instructions on how to compile the library for use in your application. You can fetch the source from GitHub as normal:

git clone https://github.com/googleapis/google-cloud-cpp.git

cd google-cloud-cpp/google/cloud/container/quickstart

Example: Quickstart

The following shows the code that you'll run in the google/cloud/container/quickstart/ directory, which should give you a taste of the Kubernetes Engine API C++ client library API.

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
 
#include "google/cloud/container/cluster_manager_client.h"
#include <iostream>
 
int main(int argc, char* argv[]) try {
  if (argc != 3) {
    std::cerr << "Usage: " << argv[0] << " project-id location-id\n";
    return 1;
  }
 
  namespace container = ::google::cloud::container;
  auto client = container::ClusterManagerClient(
      container::MakeClusterManagerConnection());
 
  auto const location =
      std::string{"projects/"} + argv[1] + "/locations/" + argv[2];
  auto response = client.ListClusters(location);
  if (!response) throw std::move(response).status();
  for (auto const& c : response->clusters()) {
    std::cout << c.DebugString() << "\n";
  }
 
  return 0;
} catch (google::cloud::Status const& status) {
  std::cerr << "google::cloud::Status thrown: " << status << "\n";
  return 1;
}

Environment Variables

GOOGLE_CLOUD_CPP_CLUSTER_MANAGER_ENDPOINT=... overrides the EndpointOption (which defaults to "container.googleapis.com") used by MakeClusterManagerConnection().
GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc turns on tracing for most gRPC calls. The library injects an additional Stub decorator that prints each gRPC request and response. Unless you have configured your own logging backend, you should also set GOOGLE_CLOUD_CPP_ENABLE_CLOG to produce any output on the program's console.
GOOGLE_CLOUD_CPP_ENABLE_TRACING=rpc-streams turns on tracing for streaming gRPC calls. This can produce a lot of output, so use with caution!
GOOGLE_CLOUD_CPP_TRACING_OPTIONS=... modifies the behavior of gRPC tracing, including whether messages will be output on multiple lines, or whether string/bytes fields will be truncated.
GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes turns on logging in the library. Basically the library always "logs" but the logging infrastructure has no backend to actually print anything until the application sets a backend or it sets this environment variable.

Error Handling

This library never throws exceptions to signal error, but you can use exceptions to detect errors in the returned objects. In general, the library returns a StatusOr<T> if an error is possible. This is an "outcome" type, when the operation is successful a StatusOr<T> converts to true in boolean context (and its .ok() member function returns true), the application can then use operator-> or operator* to access the T value. When the operation fails a StatusOr<T> converts to false (and .ok() returns false). It is undefined behavior to use the value in this case.

If you prefer to use exceptions on error, you can use the .value() accessor. It will return the T value or throw on error.

For operations that do not return a value the library simply returns google::cloud::Status.

Override the default endpoint

In some cases, you may need to override the default endpoint used by the client library. Use the google::cloud::EndpointOption when initializing the client library to change this default.

For example, this will override the default endpoint for ClusterManagerClient:

  // This configuration is common with Private Google Access:
  //     https://cloud.google.com/vpc/docs/private-google-access
  auto options = google::cloud::Options{}.set<google::cloud::EndpointOption>(
      "private.googleapis.com");
  auto client = google::cloud::container::ClusterManagerClient(
      google::cloud::container::MakeClusterManagerConnection(options));

Override the authentication configuration

Some applications cannot use the default authentication mechanism (known as Application Default Credentials). You can override this default using google::cloud::UnifiedCredentialsOption. The following example shows how to explicitly load a service account key file.

  [](std::string const& keyfile) {
    auto is = std::ifstream(keyfile);
    is.exceptions(std::ios::badbit);  // Minimal error handling in examples
    auto contents = std::string(std::istreambuf_iterator<char>(is.rdbuf()), {});
    auto options =
        google::cloud::Options{}.set<google::cloud::UnifiedCredentialsOption>(
            google::cloud::MakeServiceAccountCredentials(contents));
    return google::cloud::container::ClusterManagerClient(
        google::cloud::container::MakeClusterManagerConnection(options));
  }

Keep in mind that we chose this as an example because it is relatively easy to understand. Consult the Best practices for managing service account keys guide for more details.

See also: Authentication Components - for more information on the factory functions to create google::cloud::Credentials objects.

Retry, Backoff, and Idempotency Policies.

The library automatically retries requests that fail with transient errors, and uses exponential backoff to backoff between retries. Application developers can override the default policies.