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 examples below. 32 33Google Application Default Credentials (ADC) is the recommended way to authorize 34and authenticate clients. For information on how to create and obtain 35Application Default Credentials, see 36https://cloud.google.com/docs/authentication/production. Here is an example 37of a client using ADC to authenticate: 38 client, err := secretmanager.NewClient(context.Background()) 39 if err != nil { 40 // TODO: handle error. 41 } 42 _ = client // Use the client. 43 44You can use a file with credentials to authenticate and authorize, such as a JSON 45key file associated with a Google service account. Service Account keys can be 46created and downloaded from 47https://console.cloud.google.com/iam-admin/serviceaccounts. This example uses 48the Secret Manger client, but the same steps apply to the other client libraries 49underneath this package. Example: 50 client, err := secretmanager.NewClient(context.Background(), 51 option.WithCredentialsFile("/path/to/service-account-key.json")) 52 if err != nil { 53 // TODO: handle error. 54 } 55 _ = client // Use the client. 56 57In some cases (for instance, you don't want to store secrets on disk), you can 58create credentials from in-memory JSON and use the WithCredentials option. 59The google package in this example is at golang.org/x/oauth2/google. 60This example uses the Secret Manager client, but the same steps apply to 61the other client libraries underneath this package. Note that scopes can be 62found at https://developers.google.com/identity/protocols/oauth2/scopes, and 63are also provided in all auto-generated libraries: for example, 64cloud.google.com/go/secretmanager/apiv1 provides DefaultAuthScopes. Example: 65 ctx := context.Background() 66 creds, err := google.CredentialsFromJSON(ctx, []byte("JSON creds"), secretmanager.DefaultAuthScopes()...) 67 if err != nil { 68 // TODO: handle error. 69 } 70 client, err := secretmanager.NewClient(ctx, option.WithCredentials(creds)) 71 if err != nil { 72 // TODO: handle error. 73 } 74 _ = client // Use the client. 75 76 77Timeouts and Cancellation 78 79By default, non-streaming methods, like Create or Get, will have a default deadline applied to the 80context provided at call time, unless a context deadline is already set. Streaming 81methods have no default deadline and will run indefinitely. To set timeouts or 82arrange for cancellation, use contexts. Transient 83errors will be retried when correctness allows. 84 85Here is an example of how to set a timeout for an RPC, use context.WithTimeout: 86 ctx := context.Background() 87 // Do not set a timeout on the context passed to NewClient: dialing happens 88 // asynchronously, and the context is used to refresh credentials in the 89 // background. 90 client, err := secretmanager.NewClient(ctx) 91 if err != nil { 92 // TODO: handle error. 93 } 94 // Time out if it takes more than 10 seconds to create a dataset. 95 tctx, cancel := context.WithTimeout(ctx, 10*time.Second) 96 defer cancel() // Always call cancel. 97 98 req := &secretmanagerpb.DeleteSecretRequest{Name: "projects/project-id/secrets/name"} 99 if err := client.DeleteSecret(tctx, req); err != nil { 100 // TODO: handle error. 101 } 102 103Here is an example of how to arrange for an RPC to be canceled, use context.WithCancel: 104 ctx := context.Background() 105 // Do not cancel the context passed to NewClient: dialing happens asynchronously, 106 // and the context is used to refresh credentials in the background. 107 client, err := secretmanager.NewClient(ctx) 108 if err != nil { 109 // TODO: handle error. 110 } 111 cctx, cancel := context.WithCancel(ctx) 112 defer cancel() // Always call cancel. 113 114 // TODO: Make the cancel function available to whatever might want to cancel the 115 // call--perhaps a GUI button. 116 req := &secretmanagerpb.DeleteSecretRequest{Name: "projects/proj/secrets/name"} 117 if err := client.DeleteSecret(cctx, req); err != nil { 118 // TODO: handle error. 119 } 120 121To opt out of default deadlines, set the temporary environment variable 122GOOGLE_API_GO_EXPERIMENTAL_DISABLE_DEFAULT_DEADLINE to "true" prior to client 123creation. This affects all Google Cloud Go client libraries. This opt-out 124mechanism will be removed in a future release. File an issue at 125https://github.com/googleapis/google-cloud-go if the default deadlines 126cannot work for you. 127 128Do not attempt to control the initial connection (dialing) of a service by setting a 129timeout on the context passed to NewClient. Dialing is non-blocking, so timeouts 130would be ineffective and would only interfere with credential refreshing, which uses 131the same context. 132 133 134Connection Pooling 135 136Connection pooling differs in clients based on their transport. Cloud 137clients either rely on HTTP or gRPC transports to communicate 138with Google Cloud. 139 140Cloud clients that use HTTP (bigquery, compute, storage, and translate) rely on the 141underlying HTTP transport to cache connections for later re-use. These are cached to 142the default http.MaxIdleConns and http.MaxIdleConnsPerHost settings in 143http.DefaultTransport. 144 145For gRPC clients (all others in this repo), connection pooling is configurable. Users 146of cloud client libraries may specify option.WithGRPCConnectionPool(n) as a client 147option to NewClient calls. This configures the underlying gRPC connections to be 148pooled and addressed in a round robin fashion. 149 150 151Using the Libraries with Docker 152 153Minimal docker images like Alpine lack CA certificates. This causes RPCs to appear to 154hang, because gRPC retries indefinitely. See https://github.com/googleapis/google-cloud-go/issues/928 155for more information. 156 157 158Debugging 159 160To see gRPC logs, set the environment variable GRPC_GO_LOG_SEVERITY_LEVEL. See 161https://godoc.org/google.golang.org/grpc/grpclog for more information. 162 163For HTTP logging, set the GODEBUG environment variable to "http2debug=1" or "http2debug=2". 164 165 166Inspecting errors 167 168Most of the errors returned by the generated clients can be converted into a 169`grpc.Status`. Converting your errors to this type can be a useful to get 170more information about what went wrong while debugging. 171 if err != { 172 if s, ok := status.FromError(err); ok { 173 log.Println(s.Message()) 174 for _, d := range s.Proto().Details { 175 log.Println(d) 176 } 177 } 178 } 179 180Client Stability 181 182Clients in this repository are considered alpha or beta unless otherwise 183marked as stable in the README.md. Semver is not used to communicate stability 184of clients. 185 186Alpha and beta clients may change or go away without notice. 187 188Clients marked stable will maintain compatibility with future versions for as 189long as we can reasonably sustain. Incompatible changes might be made in some 190situations, including: 191 192- Security bugs may prompt backwards-incompatible changes. 193 194- Situations in which components are no longer feasible to maintain without 195making breaking changes, including removal. 196 197- Parts of the client surface may be outright unstable and subject to change. 198These parts of the surface will be labeled with the note, "It is EXPERIMENTAL 199and subject to change or removal without notice." 200*/ 201package cloud // import "cloud.google.com/go" 202