Documentation
¶
Overview ¶
Package cloudrun runs Cloud Run services locally.
An image runs as a container, through Docker, because that is what Cloud Run deploys. This is the path to use when the container is the thing being tested: its base image, its entrypoint, what it bundles.
A source directory instead runs as a process. Cloud Run's contract with your code is small — an HTTP server on $PORT — and a process honours it without a container build, which is faster and needs no daemon. It is a convenience, not an emulation of Cloud Run: nothing about the container is exercised.
The rest of cloudrig needs no Docker. This service does, for images.
Index ¶
- Constants
- Variables
- func DockerAvailable(ctx context.Context) bool
- type API
- type Instance
- func (i *Instance) ContainerID() string
- func (i *Instance) Location() string
- func (i *Instance) LogSnapshot() []string
- func (i *Instance) Name() string
- func (i *Instance) Project() string
- func (i *Instance) Revision() string
- func (i *Instance) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (i *Instance) Stop() error
- func (i *Instance) URL() string
- type Options
- type Registry
- func (r *Registry) Delete(project, location, name string) error
- func (r *Registry) Deploy(ctx context.Context, svc Service, o Options) (Service, error)
- func (r *Registry) Describe(project, location, name string) (Service, bool)
- func (r *Registry) Instance(project, location, name string) (*Instance, bool)
- func (r *Registry) List(project, location string) []Service
- func (r *Registry) Route(escapedPath string) (http.Handler, string, bool)
- func (r *Registry) StopAll()
- type Service
Constants ¶
const ( DefaultProject = "cloudrig-local" DefaultLocation = "us-central1" )
Defaults for a deploy that does not say.
const ContainerPort = 8080
ContainerPort is what a Cloud Run container is told to listen on. Cloud Run sets $PORT to 8080 unless the service says otherwise, and the container publishes that port to one the host picks.
const SourcePrefix = "source:"
SourcePrefix marks an image field that names a source directory rather than a container image. Cloud Run's API has nowhere to say "run this directory", so this is cloudrig's own spelling of it.
Variables ¶
var ErrSourceOverNetwork = errors.New(
"a source directory cannot be deployed over the API, because it runs a program on the " +
"emulator's machine: deploy an image, or use cloudrun.Registry.Deploy from your own code")
ErrSourceOverNetwork is returned when a request asks the emulator to run a directory from this machine.
var Prefixes = []string{"/apis/serving.knative.dev/"}
Prefixes are the path prefixes this service claims. The Knative one is its own; /v1/ is shared with Cloud Functions and Pub/Sub, so the front door asks which service has a route rather than splitting on the prefix.
var StartupTimeout = 10 * time.Second
StartupTimeout bounds how long a container may take to listen. Cloud Run's own default is four minutes; a local process that has not listened in ten seconds has failed, and waiting longer only delays the log that says why. It is a var, not a const, so the test suite can raise it: under `go test -race` with every package running at once the machine is saturated and a freshly-forked process is starved well past ten seconds.
Functions ¶
func DockerAvailable ¶
DockerAvailable reports whether a container can be run here. Deploying an image without a daemon is a clear error rather than a confusing one.
Types ¶
type API ¶
type API struct {
// contains filtered or unexported fields
}
API serves the Cloud Run Admin API.
Two surfaces, because gcloud uses both: the regional one is Knative's serving API under /apis/serving.knative.dev/v1, and the global one is /v1/projects/{project}/locations/{location}/services, which is what `gcloud run services list` without a --region reaches.
type Instance ¶
type Instance struct {
// contains filtered or unexported fields
}
Instance is a running service.
func (*Instance) ContainerID ¶
ContainerID is the container behind a service, or empty for one running as a process.
func (*Instance) LogSnapshot ¶
type Options ¶
type Options struct {
// Env is added to the child's environment, as KEY=VALUE.
Env []string
// Stderr receives the child's output as well as the log ring.
Stderr io.Writer
}
Options configure a run.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds the running services. It is the single source of truth: the API is a view over this, never a second store, so a deploy that the API reports cannot be one that nothing is serving.
func (*Registry) Route ¶
Route resolves a request path to a service. The emulator addresses one as /{location}-{project}/{service}/..., mirroring the functions layout.
The prefix is matched against what is deployed rather than parsed: both a location and a project contain hyphens, so "us-central1-cloudrig-local" cannot be split by looking at it. Comparing against known services has no such ambiguity, and there are never many.
type Service ¶
type Service struct {
Project string
Location string
Name string
// Image is a container image to run, which is what Cloud Run deploys. It
// needs a container runtime.
Image string
// Source is a directory to build and run as a process instead. It is the
// faster path and needs no Docker, but it is not what Cloud Run does: it
// honours the contract — an HTTP server on $PORT — without the container.
Source string
// Env is what the service sees, as KEY=VALUE.
Env []string
// Memory and CPU are Kubernetes quantities, as gcloud sends them:
// "512Mi", "1Gi", "1", "500m". They are applied to the container, so a
// service that would be killed for exceeding its memory is killed here
// too. They mean nothing to a source deploy, which is not a container.
Memory string
CPU string
// Generation counts deploys, so each one names a new revision the way
// Cloud Run does.
Generation int
}
Service is a deployed Cloud Run service.
func (Service) ResourceName ¶
ResourceName is the v2 API's name for the service.
Source Files