1package garden 2 3import "time" 4 5//go:generate counterfeiter . Client 6type Client interface { 7 // Pings the garden server. Checks connectivity to the server. The server may, optionally, respond with specific 8 // errors indicating health issues. 9 // 10 // Errors: 11 // * garden.UnrecoverableError indicates that the garden server has entered an error state from which it cannot recover 12 Ping() error 13 14 // Capacity returns the physical capacity of the server's machine. 15 // 16 // Errors: 17 // * None. 18 Capacity() (Capacity, error) 19 20 // Create creates a new container. 21 // 22 // Errors: 23 // * When the handle, if specified, is already taken. 24 // * When one of the bind_mount paths does not exist. 25 // * When resource allocations fail (subnet, user ID, etc). 26 Create(ContainerSpec) (Container, error) 27 28 // Destroy destroys a container. 29 // 30 // When a container is destroyed, its resource allocations are released, 31 // its filesystem is removed, and all references to its handle are removed. 32 // 33 // All resources that have been acquired during the lifetime of the container are released. 34 // Examples of these resources are its subnet, its UID, and ports that were redirected to the container. 35 // 36 // TODO: list the resources that can be acquired during the lifetime of a container. 37 // 38 // Errors: 39 // * TODO. 40 Destroy(handle string) error 41 42 // Containers lists all containers filtered by Properties (which are ANDed together). 43 // 44 // Errors: 45 // * None. 46 Containers(Properties) ([]Container, error) 47 48 // BulkInfo returns info or error for a list of containers. 49 BulkInfo(handles []string) (map[string]ContainerInfoEntry, error) 50 51 // BulkMetrics returns metrics or error for a list of containers. 52 BulkMetrics(handles []string) (map[string]ContainerMetricsEntry, error) 53 54 // Lookup returns the container with the specified handle. 55 // 56 // Errors: 57 // * Container not found. 58 Lookup(handle string) (Container, error) 59} 60 61// ContainerSpec specifies the parameters for creating a container. All parameters are optional. 62type ContainerSpec struct { 63 64 // Handle, if specified, is used to refer to the 65 // container in future requests. If it is not specified, 66 // garden uses its internal container ID as the container handle. 67 Handle string `json:"handle,omitempty"` 68 69 // GraceTime can be used to specify how long a container can go 70 // unreferenced by any client connection. After this time, the container will 71 // automatically be destroyed. If not specified, the container will be 72 // subject to the globally configured grace time. 73 GraceTime time.Duration `json:"grace_time,omitempty"` 74 75 // Deprecated in favour of Image property 76 RootFSPath string `json:"rootfs,omitempty"` 77 78 // Image contains a URI referring to the root file system for the container. 79 // The URI scheme must either be the empty string or "docker". 80 // 81 // A URI with an empty scheme determines the path of a root file system. 82 // If this path is empty, a default root file system is used. 83 // Other parts of the URI are ignored. 84 // 85 // A URI with scheme "docker" refers to a Docker image. The path in the URI 86 // (without the leading /) identifies a Docker image as the repository name 87 // in the default Docker registry. If a fragment is specified in the URI, this 88 // determines the tag associated with the image. 89 // If a host is specified in the URI, this determines the Docker registry to use. 90 // If no host is specified in the URI, a default Docker registry is used. 91 // Other parts of the URI are ignored. 92 // 93 // Examples: 94 // * "/some/path" 95 // * "docker:///onsi/grace-busybox" 96 // * "docker://index.docker.io/busybox" 97 Image ImageRef `json:"image,omitempty"` 98 99 // * bind_mounts: a list of mount point descriptions which will result in corresponding mount 100 // points being created in the container's file system. 101 // 102 // An error is returned if: 103 // * one or more of the mount points has a non-existent source directory, or 104 // * one or more of the mount points cannot be created. 105 BindMounts []BindMount `json:"bind_mounts,omitempty"` 106 107 // Network determines the subnet and IP address of a container. 108 // 109 // If not specified, a /30 subnet is allocated from a default network pool. 110 // 111 // If specified, it takes the form a.b.c.d/n where a.b.c.d is an IP address and n is the number of 112 // bits in the network prefix. a.b.c.d masked by the first n bits is the network address of a subnet 113 // called the subnet address. If the remaining bits are zero (i.e. a.b.c.d *is* the subnet address), 114 // the container is allocated an unused IP address from the subnet. Otherwise, the container is given 115 // the IP address a.b.c.d. 116 // 117 // The container IP address cannot be the subnet address or the broadcast address of the subnet 118 // (all non prefix bits set) or the address one less than the broadcast address (which is reserved). 119 // 120 // Multiple containers may share a subnet by passing the same subnet address on the corresponding 121 // create calls. Containers on the same subnet can communicate with each other over IP 122 // without restriction. In particular, they are not affected by packet filtering. 123 // 124 // Note that a container can use TCP, UDP, and ICMP, although its external access is governed 125 // by filters (see Container.NetOut()) and by any implementation-specific filters. 126 // 127 // An error is returned if: 128 // * the IP address cannot be allocated or is already in use, 129 // * the subnet specified overlaps the default network pool, or 130 // * the subnet specified overlaps (but does not equal) a subnet that has 131 // already had a container allocated from it. 132 Network string `json:"network,omitempty"` 133 134 // Properties is a sequence of string key/value pairs providing arbitrary 135 // data about the container. The keys are assumed to be unique but this is not 136 // enforced via the protocol. 137 Properties Properties `json:"properties,omitempty"` 138 139 // TODO 140 Env []string `json:"env,omitempty"` 141 142 // If Privileged is true the container does not have a user namespace and the root user in the container 143 // is the same as the root user in the host. Otherwise, the container has a user namespace and the root 144 // user in the container is mapped to a non-root user in the host. Defaults to false. 145 Privileged bool `json:"privileged,omitempty"` 146 147 // Limits to be applied to the newly created container. 148 Limits Limits `json:"limits,omitempty"` 149 150 // Whitelist outbound network traffic. 151 // 152 // If the configuration directive deny_networks is not used, 153 // all networks are already whitelisted and passing any rules is effectively a no-op. 154 // 155 // Later programmatic NetOut calls take precedence over these rules, which is 156 // significant only in relation to logging. 157 NetOut []NetOutRule `json:"netout_rules,omitempty"` 158 159 // Map a port on the host to a port in the container so that traffic to the 160 // host port is forwarded to the container port. 161 // 162 // If a host port is not given, a port will be acquired from the server's port 163 // pool. 164 // 165 // If a container port is not given, the port will be the same as the 166 // host port. 167 NetIn []NetIn `json:"netin,omitempty"` 168} 169 170type ImageRef struct { 171 URI string `json:"uri,omitempty"` 172 Username string `json:"username,omitempty"` 173 Password string `json:"password,omitempty"` 174} 175 176type Limits struct { 177 Bandwidth BandwidthLimits `json:"bandwidth_limits,omitempty"` 178 CPU CPULimits `json:"cpu_limits,omitempty"` 179 Disk DiskLimits `json:"disk_limits,omitempty"` 180 Memory MemoryLimits `json:"memory_limits,omitempty"` 181 Pid PidLimits `json:"pid_limits,omitempty"` 182} 183 184// BindMount specifies parameters for a single mount point. 185// 186// Each mount point is mounted (with the bind option) into the container's file system. 187// The effective permissions of the mount point are the permissions of the source directory if the mode 188// is read-write and the permissions of the source directory with the write bits turned off if the mode 189// of the mount point is read-only. 190type BindMount struct { 191 // SrcPath contains the path of the directory to be mounted. 192 SrcPath string `json:"src_path,omitempty"` 193 194 // DstPath contains the path of the mount point in the container. If the 195 // directory does not exist, it is created. 196 DstPath string `json:"dst_path,omitempty"` 197 198 // Mode must be either "RO" or "RW". Alternatively, mode may be omitted and defaults to RO. 199 // If mode is "RO", a read-only mount point is created. 200 // If mode is "RW", a read-write mount point is created. 201 Mode BindMountMode `json:"mode,omitempty"` 202 203 // BindMountOrigin must be either "Host" or "Container". Alternatively, origin may be omitted and 204 // defaults to "Host". 205 // If origin is "Host", src_path denotes a path in the host. 206 // If origin is "Container", src_path denotes a path in the container. 207 Origin BindMountOrigin `json:"origin,omitempty"` 208} 209 210type Capacity struct { 211 MemoryInBytes uint64 `json:"memory_in_bytes,omitempty"` 212 DiskInBytes uint64 `json:"disk_in_bytes,omitempty"` 213 MaxContainers uint64 `json:"max_containers,omitempty"` 214} 215 216type Properties map[string]string 217 218type BindMountMode uint8 219 220const BindMountModeRO BindMountMode = 0 221const BindMountModeRW BindMountMode = 1 222 223type BindMountOrigin uint8 224 225const BindMountOriginHost BindMountOrigin = 0 226const BindMountOriginContainer BindMountOrigin = 1 227