New to Akka? Start with the Akka SDK.
Google Common
The google-common module provides central configuration for Google connectors in Alpakka as well as basic support for interfacing with Google APIs.
Artifacts
The Akka dependencies are available from Akka’s secure library repository. To access them you need to use a secure, tokenized URL as specified at https://account.akka.io/token.
Additionally, add the dependencies as below.
- sbt
val AkkaVersion = "2.11.0" libraryDependencies ++= Seq( "com.lightbend.akka" %% "akka-stream-alpakka-google-common" % "11.0.1", "com.typesafe.akka" %% "akka-stream" % AkkaVersion )- Maven
<properties> <akka.version>2.11.0</akka.version> <scala.binary.version>2.13</scala.binary.version> </properties> <dependencies> <dependency> <groupId>com.lightbend.akka</groupId> <artifactId>akka-stream-alpakka-google-common_${scala.binary.version}</artifactId> <version>11.0.1</version> </dependency> <dependency> <groupId>com.typesafe.akka</groupId> <artifactId>akka-stream_${scala.binary.version}</artifactId> <version>${akka.version}</version> </dependency> </dependencies>- Gradle
def versions = [ AkkaVersion: "2.11.0", ScalaBinary: "2.13" ] dependencies { implementation "com.lightbend.akka:akka-stream-alpakka-google-common_${versions.ScalaBinary}:11.0.1" implementation "com.typesafe.akka:akka-stream_${versions.ScalaBinary}:${versions.AkkaVersion}" }
The table below shows direct dependencies of this module and the second tab shows all libraries it depends on transitively.
- Direct dependencies
Organization Artifact Version com.github.jwt-scala jwt-json-common_2.13 11.0.3 com.google.auth google-auth-library-credentials 1.56.0 com.typesafe.akka akka-http-spray-json_2.13 10.8.0 com.typesafe.akka akka-http_2.13 10.8.0 com.typesafe.akka akka-stream_2.13 2.11.0 org.scala-lang scala-library 2.13.18 - Dependency tree
com.github.jwt-scala jwt-json-common_2.13 11.0.3 Apache-2.0 com.github.jwt-scala jwt-core_2.13 11.0.3 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 com.google.auth google-auth-library-credentials 1.56.0 BSD New license org.jspecify jspecify 1.0.0 The Apache License, Version 2.0 com.typesafe.akka akka-http-spray-json_2.13 10.8.0 BUSL-1.1 com.typesafe.akka akka-http_2.13 10.8.0 BUSL-1.1 com.typesafe.akka akka-http-core_2.13 10.8.0 BUSL-1.1 com.typesafe.akka akka-parsing_2.13 10.8.0 BUSL-1.1 org.scala-lang scala-library 2.13.18 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 com.typesafe.akka akka-pki_2.13 2.11.0 BUSL-1.1 com.hierynomus asn-one 0.6.0 The Apache License, Version 2.0 com.typesafe.akka akka-actor_2.13 2.11.0 BUSL-1.1 com.typesafe config 1.4.10 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 org.slf4j slf4j-api 2.0.20 MIT org.scala-lang scala-library 2.13.18 Apache-2.0 io.spray spray-json_2.13 1.3.6 Apache 2 org.scala-lang scala-library 2.13.18 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 com.typesafe.akka akka-http_2.13 10.8.0 BUSL-1.1 com.typesafe.akka akka-http-core_2.13 10.8.0 BUSL-1.1 com.typesafe.akka akka-parsing_2.13 10.8.0 BUSL-1.1 org.scala-lang scala-library 2.13.18 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 com.typesafe.akka akka-pki_2.13 2.11.0 BUSL-1.1 com.hierynomus asn-one 0.6.0 The Apache License, Version 2.0 com.typesafe.akka akka-actor_2.13 2.11.0 BUSL-1.1 com.typesafe config 1.4.10 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 org.slf4j slf4j-api 2.0.20 MIT org.scala-lang scala-library 2.13.18 Apache-2.0 com.typesafe.akka akka-stream_2.13 2.11.0 BUSL-1.1 com.typesafe.akka akka-actor_2.13 2.11.0 BUSL-1.1 com.typesafe config 1.4.10 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0 com.typesafe.akka akka-protobuf-v3_2.13 2.11.0 BUSL-1.1 org.reactivestreams reactive-streams 1.0.4 MIT-0 org.scala-lang scala-library 2.13.18 Apache-2.0 org.scala-lang scala-library 2.13.18 Apache-2.0
Configuration
Shared settings for all Google connectors are read by default from the alpakka.google configuration section in your application.conf. The available options and their default values are documented in the reference.conf. If you use a non-standard configuration path or need multiple different configurations please refer to the sections below.
sourcealpakka.google {
# The project ID.
# If unset, Alpakka will first attempt to read the project-id from the credentials provider. If that doesn't provide
# a project-id, then default-project-id will be used.
project-id = ""
# The default project id to use if not explicitly specified through project-id, or implicitly provided by a
# credentials provider. Don't override.
default-project-id = ""
default-project-id = ${?GOOGLE_CLOUD_PROJECT}
default-project-id = ${?GCP_PROJECT}
credentials {
# Used to build a list of default scopes from each of the modules, don't override
default-scopes = ${?alpakka.google.credentials.default-scopes} []
# Override to specify custom scopes
scopes = ${alpakka.google.credentials.default-scopes}
# Options: application-default, service-account, compute-engine, user-access, none
# application-default first tries service-account then compute-engine. If neither is available it logs a
# warning and falls back to none, which means that requests are sent without valid credentials and are
# rejected by Google APIs. Set this explicitly if that fallback is not wanted.
provider = application-default
application-default {
# Resolves a path to the well-known credentials file
# See https://github.com/googleapis/google-auth-library-java/blob/master/oauth2_http/java/com/google/auth/oauth2/DefaultCredentialsProvider.java#L237
path = ${user.home}/.config
path = ${?APPDATA} # Windows-only
path = ${alpakka.google.credentials.application-default.path}/gcloud
path = ${?CLOUDSDK_CONFIG}
path = ${alpakka.google.credentials.application-default.path}/application_default_credentials.json
path = ${?GOOGLE_APPLICATION_CREDENTIALS}
}
service-account {
# Config values have first priority, otherwise look for credentials file
project-id = ""
client-email = ""
private-key = ""
# Resolves a path to the well-known credentials file
# See https://github.com/googleapis/google-auth-library-java/blob/master/oauth2_http/java/com/google/auth/oauth2/DefaultCredentialsProvider.java#L237
path = ${user.home}/.config
path = ${?APPDATA} # Windows-only
path = ${alpakka.google.credentials.service-account.path}/gcloud
path = ${?CLOUDSDK_CONFIG}
path = ${alpakka.google.credentials.service-account.path}/application_default_credentials.json
path = ${?GOOGLE_APPLICATION_CREDENTIALS}
# Always required regardless of where credentials are read from
scopes = ${alpakka.google.credentials.scopes}
}
# Timeout for blocking call during settings initialization to compute engine metadata server.
# Exceeding it is treated as a failure to obtain compute engine credentials, and usually means that the
# metadata server is not reachable rather than that the credentials are wrong.
compute-engine.timeout = 3s
user-access {
project-id = ""
client-id = ""
client-secret = ""
refresh-token = ""
# Resolves a path to the well-known credentials file
# See https://github.com/googleapis/google-auth-library-java/blob/master/oauth2_http/java/com/google/auth/oauth2/DefaultCredentialsProvider.java#L237
path = ${user.home}/.config
path = ${?APPDATA} # Windows-only
path = ${alpakka.google.credentials.user-access.path}/gcloud
path = ${?CLOUDSDK_CONFIG}
path = ${alpakka.google.credentials.user-access.path}/application_default_credentials.json
path = ${?GOOGLE_APPLICATION_CREDENTIALS}
}
none {
project-id = "<no-project-id>"
token = "<no-token>"
}
}
# Standard query parameters for all Google APIs sent with every request
user-ip = ""
quota-user = ""
pretty-print = false
# The minimum size of a chunk, must be a multiple of 256 KiB. See https://github.com/googleapis/java-core/issues/86
upload-chunk-size = 15 MiB
# The retry settings for requests to Google APIs
# Defaults from https://github.com/googleapis/python-api-core/blob/master/google/api_core/retry.py#L72
retry-settings {
max-retries = 6
min-backoff = 1 second
max-backoff = 1 minute
random-factor = 0.2
}
# An address of a proxy that will be used for all connections using HTTP CONNECT tunnel.
# forward-proxy {
# scheme = "https"
# host = "proxy"
# port = 8080
# credentials {
# username = "username"
# password = "password"
# }
# trust-pem = "/path/to/file.pem"
# }
}
Credentials
The alpakka.google.credentials.provider setting selects where credentials come from:
provider |
Credentials |
|---|---|
application-default (default) |
Tries service-account, then compute-engine |
service-account |
A service account key, from your configuration file or a credentials file |
compute-engine |
The service account of the Compute Engine instance, read from the metadata server |
user-access |
A user refresh token, from your configuration file or a credentials file |
none |
No credentials; requests are sent unauthenticated |
With the default application-default provider, credentials will be loaded automatically:
- From the file path specified by the
GOOGLE_APPLICATION_CREDENTIALSenvironment variable or another “well-known” location; or - When running in a Compute Engine instance, from the metadata server at
metadata.google.internal.
Credentials can also be specified manually in your configuration file.
If neither source yields credentials, application-default does not fail: it logs a warning and falls back to the none provider. Requests are then sent without valid credentials and are rejected by Google APIs, typically with 401 Unauthorized or 403 Forbidden, which looks like a permissions problem rather than a configuration problem. Set provider explicitly if this fallback is not what you want.
Reading credentials from the Compute Engine metadata server blocks during settings initialization for at most alpakka.google.credentials.compute-engine.timeout. A timeout means the metadata server could not be reached — because the application is not running on Google Cloud, or because the request was intercepted or blocked by a proxy or service mesh — and leads to the same fallback. The warning names both the service account and the Compute Engine failure, so check it before investigating IAM.
Accessing settings
GoogleSettingsGoogleSettings provides methods to retrieve settings from your configuration and GoogleAttributesGoogleAttributes to access the settings attached to a stream. Additionally, if there is an implicit ActorSystemActorSystem in scope, then so will be an implicit instance of the default GoogleSettingsGoogleSettings.
- Scala
-
source
val defaultSettings = GoogleSettings() val customSettings = GoogleSettings("my-app.custom-google-config") Source.fromMaterializer { (mat, attr) => val settings: GoogleSettings = GoogleAttributes.resolveSettings(mat, attr) Source.empty } - Java
-
source
GoogleSettings defaultSettings = GoogleSettings.create(system); GoogleSettings customSettings = GoogleSettings.create("my-app.custom-google-config", system); Source.fromMaterializer( (mat, attr) -> { GoogleSettings settings = GoogleAttributes.resolveSettings(mat, attr); return Source.empty(); });
Apply custom settings to a part of the stream
In certain situations it may be desirable to modify the GoogleSettingsGoogleSettings applied to a part of the stream, for example to use different credentials or change the RetrySettingsRetrySettings. This is accomplished by adding GoogleAttributesGoogleAttributes to your stream.
- Scala
-
source
stream.addAttributes(GoogleAttributes.settingsPath("my-app.custom-google-config")) val defaultSettings = GoogleSettings() val customSettings = defaultSettings.withProjectId("my-other-project") stream.addAttributes(GoogleAttributes.settings(customSettings)) - Java
-
source
stream.addAttributes(GoogleAttributes.settingsPath("my-app.custom-google-config")); GoogleSettings defaultSettings = GoogleSettings.create(system); GoogleSettings customSettings = defaultSettings.withProjectId("my-other-project"); stream.addAttributes(GoogleAttributes.settings(customSettings));
Interop with Google Java client libraries
Instances of the CredentialsCredentials class can be converted via the toGoogle() method to Credentials compatible with Google Java client libraries.
Accessing other Google APIs
The GoogleGoogle object class provides methods for interfacing with Google APIs. You can use it to access APIs that are not currently supported by Alpakka and build new connectors.