Garden API

Garden API

The Garden API is a set of HTTP endpoints exposed by the Garden server. The API is mainly used by Diego to manage containers.

For golang clients (such as Diego), there is a golang client wrapper.

Endpoints

Method	Path	Description
GET	/ping	Pings a Garden server, succeeds if the server is running
GET	/capacity	Gets the capacity (total memory, total disk, max number of containers) of a Garden server
GET	/containers	Gets a list of existing container handles/IDs
POST	/containers	Creates a container
GET	/containers/bulk_info	Gets information about all the containers known to Garden
GET	/containers/bulk_metrics	Gets metrics (resource usage, age, etc.) for all the containers known to Garden
GET	/containers/:handle/info	Gets information about the container with the handle specified
DELETE	/containers/:handle	Deletes the container with the handle specified
PUT	/containers/:handle/stop	Kills all the processes of the container (i.e. the processes in its devices cgroup) except the container init process
PUT	/containers/:handle/files	Upload a file into a container
GET	/containers/:handle/files	Gets the content of a file from a container
GET	/containers/:handle/limits/bandwidth	Gets the container bandwidth limits (the implementation returns an empty struct though)
GET	/containers/:handle/limits/cpu	Gets the container CPU limits
GET	/containers/:handle/limits/disk	Gets the container disk limit (the implementation returns an empty struct though)
GET	/containers/:handle/limits/memory	Gets the container memory limits
POST	/containers/:handle/net/in	Allows a container port to be accessed externally on a port
POST	/containers/:handle/net/out	Allows a container to access external networks on a single ports
POST	/containers/:handle/net/out/bulk	Allows a container to access external networks on multiple ports
POST	/containers/:handle/processes	Runs a process in a container
GET	/containers/:handle/processes/:pid	Gets the handle (ID) of the process (NOTE: This is NOT the operating system process ID (PID)!)
GET	/containers/:handle/processes/:pid/attaches/:streamid/stdout	Gets a process standard out (stdout)
GET	/containers/:handle/processes/:pid/attaches/:streamid/stderr	Gets a process standard error (stderr)
PUT	/containers/:handle/grace_time	Sets the container grace time (the time the container survives if being inactive)
GET	/containers/:handle/properties	Gets all the properties of a container
GET	/containers/:handle/properties/:key	Gets a single container property
PUT	/containers/:handle/properties/:key	Sets a single container property
DELETE	/containers/:handle/properties/:key	Deletes a container property
GET	/containers/:handle/metrics	Gets metrics of a container

Navigating between endpoint route and its implementation is a bit tricky (or maybe it's just me), so here is a list of places in the code to look for:

• routes.go defines the API HTTP routes
• server.go wires those routes to HTTP handlers
• gardener.go is where non-container specific operations (e.g. GET /containers) are implemented
• container.go is where container operations (e.g. GET /containers/:handle/metrics) are implemented

Gaol

Gaol is an unofficial Garden API CLI client which is pretty useful to quickly try things out (e.g. create a container, run a process, attach to a container). It does not expose the complete Garden API but you can always clone it and extend it to fit into the concrete situation. See the Don't Panic -> Calling the Garden API section for more details.