1// Copyright 2014 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//      http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15/*
16Package cloud is the root of the packages used to access Google Cloud
17Services. See https://godoc.org/cloud.google.com/go for a full list
18of sub-packages.
19
20
21Client Options
22
23All clients in sub-packages are configurable via client options. These options are
24described here: https://godoc.org/google.golang.org/api/option.
25
26
27Authentication and Authorization
28
29All the clients in sub-packages support authentication via Google Application Default
30Credentials (see https://cloud.google.com/docs/authentication/production), or
31by providing a JSON key file for a Service Account. See the authentication examples
32in this package for details.
33
34
35Timeouts and Cancellation
36
37By default, non-streaming methods, like Create or Get, will have a default deadline applied to the
38context provided at call time, unless a context deadline is already set. Streaming
39methods have no default deadline and will run indefinitely. To set timeouts or
40arrange for cancellation, use contexts. See the examples for details. Transient
41errors will be retried when correctness allows.
42
43To opt out of default deadlines, set the temporary environment variable
44GOOGLE_API_GO_EXPERIMENTAL_DISABLE_DEFAULT_DEADLINE to "true" prior to client
45creation. This affects all Google Cloud Go client libraries. This opt-out
46mechanism will be removed in a future release. File an issue at
47https://github.com/googleapis/google-cloud-go if the default deadlines
48cannot work for you.
49
50Do not attempt to control the initial connection (dialing) of a service by setting a
51timeout on the context passed to NewClient. Dialing is non-blocking, so timeouts
52would be ineffective and would only interfere with credential refreshing, which uses
53the same context.
54
55
56Connection Pooling
57
58Connection pooling differs in clients based on their transport. Cloud
59clients either rely on HTTP or gRPC transports to communicate
60with Google Cloud.
61
62Cloud clients that use HTTP (bigquery, compute, storage, and translate) rely on the
63underlying HTTP transport to cache connections for later re-use. These are cached to
64the default http.MaxIdleConns and http.MaxIdleConnsPerHost settings in
65http.DefaultTransport.
66
67For gRPC clients (all others in this repo), connection pooling is configurable. Users
68of cloud client libraries may specify option.WithGRPCConnectionPool(n) as a client
69option to NewClient calls. This configures the underlying gRPC connections to be
70pooled and addressed in a round robin fashion.
71
72
73Using the Libraries with Docker
74
75Minimal docker images like Alpine lack CA certificates. This causes RPCs to appear to
76hang, because gRPC retries indefinitely. See https://github.com/googleapis/google-cloud-go/issues/928
77for more information.
78
79
80Debugging
81
82To see gRPC logs, set the environment variable GRPC_GO_LOG_SEVERITY_LEVEL. See
83https://godoc.org/google.golang.org/grpc/grpclog for more information.
84
85For HTTP logging, set the GODEBUG environment variable to "http2debug=1" or "http2debug=2".
86
87
88Client Stability
89
90Clients in this repository are considered alpha or beta unless otherwise
91marked as stable in the README.md. Semver is not used to communicate stability
92of clients.
93
94Alpha and beta clients may change or go away without notice.
95
96Clients marked stable will maintain compatibility with future versions for as
97long as we can reasonably sustain. Incompatible changes might be made in some
98situations, including:
99
100- Security bugs may prompt backwards-incompatible changes.
101
102- Situations in which components are no longer feasible to maintain without
103making breaking changes, including removal.
104
105- Parts of the client surface may be outright unstable and subject to change.
106These parts of the surface will be labeled with the note, "It is EXPERIMENTAL
107and subject to change or removal without notice."
108*/
109package cloud // import "cloud.google.com/go"
110