gocloud.dev: gocloud.dev Index | Files | Directories

package cloud

import "gocloud.dev"

Package cloud contains a library and tools for open cloud development in Go.

The Go Cloud Development Kit (Go CDK) allows application developers to seamlessly deploy cloud applications on any combination of cloud providers. It does this by providing stable, idiomatic interfaces for common uses like storage and databases. Think `database/sql` for cloud products.

At the core of the Go CDK are common "portable types" implemented by cloud providers. For example, objects of the blob.Bucket portable type can be created using gcsblob.OpenBucket, s3blob.OpenBucket, or any other provider. Then, the blob.Bucket can be used throughout your application without worrying about the underlying implementation.

The Go CDK works well with a code generator called Wire (https://github.com/google/wire/blob/master/README.md). It creates human-readable code that only imports the cloud SDKs for providers you use. This allows the Go CDK to grow to support any number of cloud providers, without increasing compile times or binary sizes, and avoiding any side effects from `init()` functions.

For sample applications and a tutorial, see the samples directory (https://github.com/google/go-cloud/tree/master/samples).

URLs

In addition to creating portable types via provider-specific constructors (e.g., creating a blob.Bucket using s3blob.OpenBucket), many portable types can also be created using a URL. The scheme of the URL specifies the provider, and each provider implementation has code to convert the URL into the data needed to call its constructor. For example, calling blob.OpenBucket with s3blob://my-bucket will return a blob.Bucket created using s3blob.OpenBucket.

Each portable API package will document the types that it supports opening by URL; for example, the blob package supports Buckets, while the pubsub package supports Topics and Subscriptions. Each provider implementation will document what scheme(s) it registers for, and what format of URL it expects.

Each portable type URL opener will accept URL schemes with an <api>+ prefix (e.g., blob+file:///dir" instead of "file:///dir", as well as schemes with an <api>+<type>+ prefix (e.g., blob+bucket+file:///dir).

Each portable API package should include an example using a URL, and many providers will include provider-specific examples as well.

URL Muxes

Each portable type that's openable via URL will have a top-level function you can call, like blob.OpenBucket. This top-level function uses a default instance of an URLMux multiplexer to map schemes to a provider-specific opener for the type. For example, blob has a BucketURLOpener interface that providers implement and then register using RegisterBucket.

Many applications will work just fine using the default mux through the top-level Open functions. However, if you want more control, you can create your own URLMux and register the provider URLOpeners you need. Most providers will export URLOpeners that give you more fine grained control over the arguments needed by the constructor. In particular, portable types opened via URL will often use default credentials from the environment. For example, the AWS URL openers use the credentials saved by "aws login" (we don't want to include credentials in the URL itself, since they are likely to be sensitive).

- Instantiate the provider's URLOpener with the specific fields you need.
  For example, s3blob.URLOpener{ConfigProvider: myAWSProvider} using a
  ConfigProvider that holds explicit AWS credentials.
- Create your own instance of the URLMux, e.g., mymux := new(blob.URLMux).
- Register your custom URLOpener on your mux, e.g.,
  mymux.RegisterBucket(s3blob.Scheme, myS3URLOpener).
- Now use your mux to open URLs, e.g. mymux.OpenBucket('s3://my-bucket').

Escaping the abstraction

It is not feasible or desirable for APIs like blob.Bucket to encompass the full functionality of every provider. Rather, we intend to provide a subset of the most commonly used functionality. There will be cases where a developer wants to access provider-specific functionality, such as unexposed APIs or data fields, errors or options. This can be accomplished using As functions.

As

As functions in the APIs provide the user a way to escape the Go CDK abstraction to access provider-specific types. They might be used as an interim solution until a feature request to the Go CDK is implemented. Or, the Go CDK may choose not to support specific features, and the use of As will be permanent.

Using As implies that the resulting code is no longer portable; the provider-specific code will need to be ported in order to switch providers. Therefore, it should be avoided if possible.

Each API will include examples demonstrating how to use its various As functions, and each provider implementation will document what types it supports for each.

Usage:

1. Declare a variable of the provider-specific type you want to access.

2. Pass a pointer to it to As.

3. If the type is supported, As will return true and copy the provider-specific type into your variable. Otherwise, it will return false.

Provider-specific types that are intended to be mutable will be exposed as a pointer to the underlying type.

Index

Package Files

doc.go

Directories

PathSynopsis
awsPackage aws provides fundamental Wire providers for Amazon Web Services (AWS).
aws/awscloudPackage awscloud contains Wire providers for AWS services.
aws/rdsPackage rds contains Wire providers that are common across RDS.
azure/azurecloudPackage azurecloud contains Wire providers for Azure services.
blobPackage blob provides an easy and portable way to interact with blobs within a storage location, hereafter called a "bucket".
blob/azureblobPackage azureblob provides a blob implementation that uses Azure Storage’s BlockBlob.
blob/driverPackage driver defines a set of interfaces that the blob package uses to interact with the underlying blob services.
blob/drivertestPackage drivertest provides a conformance test for implementations of driver.
blob/fileblobPackage fileblob provides a blob implementation that uses the filesystem.
blob/gcsblobPackage gcsblob provides a blob implementation that uses GCS.
blob/memblobPackage memblob provides an in-memory blob implementation.
blob/s3blobPackage s3blob provides a blob implementation that uses S3.
gcerrorsPackage gcerrors provides support for getting error codes from errors returned by Go CDK APIs.
gcpPackage gcp provides fundamental Wire providers and types for Google Cloud Platform (GCP).
gcp/cloudsqlPackage cloudsql contains Wire providers that are common across Google Cloud SQL.
gcp/gcpcloudPackage gcpcloud contains Wire providers for GCP services.
healthPackage health provides health check handlers.
health/sqlhealthPackage sqlhealth provides a health check for a SQL database connection.
internal/batcherPackage batcher supports batching of items.
internal/contributebotcontributebot is a service for keeping the Go Cloud Development Kit project tidy.
internal/docstorePackage docstore provides a portable implementation of a document store.
internal/docstore/driverPackage driver defines a set of interfaces that the docstore package uses to interact with the underlying services.
internal/docstore/drivertestPackage drivertest provides a conformance test for implementations of driver.
internal/docstore/memdocstorePackage memdocstore provides an in-memory implementation of the docstore API.
internal/escapePackage escape includes helpers for escaping and unescaping strings.
internal/gcerrPackage gcerr provides an error type for Go CDK APIs.
internal/ocPackage oc supports OpenCensus tracing and metrics for the Go Cloud Development Kit.
internal/retryPackage retry provides retry logic.
internal/testing/octestPackage octest supports testing of OpenCensus integrations.
internal/testing/replayPackage replay provides the ability to record and replay HTTP requests.
internal/testing/setup
internal/testing/terraformPackage terraform provides a function to read Terraform output.
internal/tracePackage trace provides support for OpenCensus tracing.
internal/useragentPackage useragent includes constants and utilitiesfor setting the User-Agent for Go CDK connections to GCP.
mysql/cloudmysqlPackage cloudmysql provides connections to managed MySQL Cloud SQL instances.
mysql/rdsmysqlPackage rdsmysql provides connections to AWS RDS MySQL instances.
postgres/cloudpostgresPackage cloudpostgres provides connections to managed PostgreSQL Cloud SQL instances.
postgres/rdspostgresPackage rdspostgres provides connections to AWS RDS PostgreSQL instances.
pubsubPackage pubsub provides an easy and portable way to interact with publish/ subscribe systems.
pubsub/awspubsubPackage awspubsub provides an implementation of pubsub that uses AWS SNS (Simple Notification Service) and SQS (Simple Queueing Service).
pubsub/azurepubsubPackage azurepubsub provides an implementation of pubsub using Azure Service Bus Topic and Subscription.
pubsub/driverPackage driver defines a set of interfaces that the pubsub package uses to interact with the underlying pubsub services.
pubsub/drivertestPackage drivertest provides a conformance test for implementations of driver.
pubsub/gcppubsubPackage gcppubsub provides a pubsub implementation that uses GCP PubSub.
pubsub/mempubsubPackage mempubsub provides an in-memory pubsub implementation.
pubsub/rabbitpubsubPackage rabbitpubsub provides an pubsub implementation for RabbitMQ.
requestlogPackage requestlog provides an http.Handler that logs information about requests.
runtimevarPackage runtimevar provides an easy and portable way to watch runtime configuration variables.
runtimevar/blobvarPackage blobvar provides a runtimevar implementation with variables read from a blob.Bucket.
runtimevar/constantvarPackage constantvar provides a runtimevar implementation with Variables that never change.
runtimevar/driverPackage driver provides the interface for providers of runtimevar.
runtimevar/drivertestPackage drivertest provides a conformance test for implementations of runtimevar.
runtimevar/etcdvarPackage etcdvar provides a runtimevar implementation with variables backed by etcd.
runtimevar/filevarPackage filevar provides a runtimevar implementation with variables backed by the filesystem.
runtimevar/paramstorePackage paramstore provides a runtimevar implementation with variables read from AWS Systems Manager Parameter Store (https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) Use NewVariable to construct a *runtimevar.Variable.
runtimevar/runtimeconfiguratorPackage runtimeconfigurator provides a runtimevar implementation with variables read from GCP Cloud Runtime Configurator (https://cloud.google.com/deployment-manager/runtime-configurator).
secretsPackage secrets provides an easy and portable way to encrypt and decrypt messages.
secrets/awskmsPackage awskms provides a secrets implementation backed by AWS KMS.
secrets/driverPackage driver defines interfaces to be implemented for providers of the secrets package.
secrets/drivertestPackage drivertest provides a conformance test for implementations of the secrets driver.
secrets/gcpkmsPackage gcpkms provides a secrets implementation backed by Google Cloud KMS.
secrets/localsecretsPackage localsecrets provides a secrets implementation using a locally locally provided symmetric key.
secrets/vaultPackage vault provides a secrets implementation using the Transit Secrets Engine of Vault by Hashicorp.
serverPackage server provides a preconfigured HTTP server with diagnostic hooks.
server/driverPackage driver defines an interface for custom HTTP listeners.
server/sdserverPackage sdserver provides the diagnostic hooks for a server using Stackdriver.
server/xrayserverPackage xrayserver provides the diagnostic hooks for a server using AWS X-Ray.

Updated 2019-03-18. Refresh now. Tools for package owners.