github.com/emc-advanced-dev/unik@v0.0.0-20190717152701-a58d3e8e33b7/docs/cli.md (about) 1 # Command-Line Interface 2 3 The UniK cli wraps calls to UniK's [REST API](api.md) to make using UniK easy. 4 5 * Managing Unik 6 * [`unik daemon`](cli.md#running-the-daemon) 7 * [`unik target`](cli.md#targeting-the-unik-daemon) 8 * [`unik providers`](cli.md#list-available-providers) 9 * [`unik compilers`](cli.md#list-available-compilers) 10 * Images 11 * [`unik build`](cli.md#building-an-image) 12 * [`unik images`](cli.md#list-available-images) 13 * [`unik describe-image`](cli.md#get-json-representation-of-a-specifig-image) 14 * [`unik delete-image`](cli.md#delete-an-image) 15 * Instances 16 * [`unik run`](cli.md#run-an-instance) 17 * [`unik instances`](cli.md#list-available-instances) 18 * [`unik describe-instance`](cli.md#get-json-representation-of-a-specifig-instance) 19 * [`unik delete-instance`](cli.md#delete-an-instance) 20 * [`unik stop`](cli.md#power-off-an-instance) 21 * [`unik start`](cli.md#power-on-an-instance) 22 * [`unik logs`](cli.md#retrieve-or-follow-instance-logs) 23 * Volumes 24 * [`unik create-volume`](cli.md#create-a-volume) 25 * [`unik volumes`](cli.md#list-volumes) 26 * [`unik attach-volume`](cli.md#attach-a-volume) 27 * [`unik detach-volume`](cli.md#detach-a-volume) 28 * [`unik delete-volume`](cli.md#delete-a-volume) 29 * Unik Hub 30 * [`unik login`](cli.md#login) 31 * [`unik push`](cli.md#push) 32 * [`unik pull`](cli.md#pull) 33 * [`unik search`](cli.md#search) 34 35 #### Running the daemon 36 The cli is used to start the UniK daemon. To start the daemon: 37 ``` 38 unik daemon 39 ``` 40 It is recommended to start the daemon as a background process with `&` as it is designed to be long-running. 41 42 `unik daemon` makes use of the following flags: 43 * `--debug` (bool, optional) more verbose logging for the daemon 44 * `--f string` (string, optional) path to [daemon config file](configure.md) (default is $HOME/.unik/daemon-config.yaml) 45 * `--logfile string` (string, optional) output logs to file (in addition to stdout) 46 * `--port int` (int, optional) listening port for daemon (default 3000) 47 * `--trace` (bool, optional) add stack trace to daemon logs 48 49 Example usage: 50 ``` 51 unik daemon --f ./my-config.yaml --port 12345 --debug --trace --logfile logs.txt 52 ``` 53 * will start the daemon using config file at my-config.yaml 54 * running on port 12345 55 * debug mode activated 56 * trace mode activated 57 * outputting logs to logs.txt 58 59 --- 60 61 #### Targeting the UniK daemon 62 Run 63 ``` 64 unik target --host localhost 65 ``` 66 If running UniK on your local machine. Otherwise 67 ``` 68 unik target --host host_address [--port port] 69 ``` 70 Will set the target to a remote UniK host. Use of the `port` flag is optional and only necessary if the `daemon` is running on a non-default (3000) port. 71 72 Note: 73 The target for client commands (commands other than `unik daemon`) can be overridden with the `--host` flag (to use a target other than the default). 74 75 --- 76 77 #### List available Providers 78 ``` 79 unik providers 80 ``` 81 Returns a list of providers available to the targeted unik backend. 82 83 --- 84 85 #### List available Compilers 86 ``` 87 unik compilers 88 ``` 89 Returns a list of compilers available to the targeted unik backend. 90 91 --- 92 93 #### Building an image 94 Compiles source files into a runnable unikernel image. 95 96 Images must be compiled using a specific compiler. Compilers are composed of 3 elements: 97 * **Base**: The Unikernel Base to build the image on. These include different unikernel implementations, such as [rumprun](https://github.com/rumpkernel/rumprun), [IncludeOS](https://gitter.im/hioa-cs/IncludeOS), etc. 98 * **Language**: The language/runtime the image should be built with. E.g. for a golang project, specify `-language go`. Languages supported depend on the unikernel base. 99 * **Provider**: The (cloud/hypervisor) provider the image should be built for. Supported providers depend on the unikernel base. 100 101 In order to see a list of all supported base/language/provider combinations, run `unik compilers` 102 103 Images must be compiled for a specific provider, specified with the `--provider` flag 104 To see a list of available providers, run `unik providers` 105 106 A unikernel base that is compatible with the provider must be specified with the `--base` flag. 107 108 A language runtime that is compatible with the base must be specified with the `--language` flag. 109 110 To see a table of all compatible base-language-provider combinations, run `unik compilers` 111 112 If you wish to attach volumes to instances of an image, the image must be compiled in advance 113 with a list of the expected mount points. e.g. for an application that reads from a '/data' folder, 114 the unikernel should be compiled with the flag `--mount /data` 115 116 Runtime arguments to be passed to your unikernel must also be specified at compile time. 117 You can specify arguments as a single string passed to the `--args` flag 118 119 Image names must be unique. If an image exists with the same name, you can force overwriting with the 120 --force flag 121 122 Example usage: 123 124 ``` 125 unik build --name myUnikernel --path ./myApp/src --base rump --language go --provider aws --mountpoint /foo --mountpoint /bar --args 'arg1 arg2 arg3' --force 126 ``` 127 * will create a Go unikernel named myUnikernel using the sources found in ./myApp/src, 128 * compiled using rumprun targeting AWS infrastructure, 129 * expecting a volume to be mounted at /foo at runtime, 130 * expecting another volume to be mounted at /bar at runtime, 131 * passing 'arg1 arg2 arg3' as arguments to the application when it is run, 132 * and deleting any previous existing instances and image for the name myUnikernel before compiling 133 134 Another example (using only the required parameters): 135 ``` 136 unik build -name anotherUnikernel -path ./anotherApp/src --base includeos --language cpp --provider virtualbox 137 ``` 138 139 Usage: 140 unik build [flags] 141 142 Flags: 143 * `--args string` (string,optional) to be passed to the unikernel at runtime 144 * `--base string` (string,required) name of the unikernel base to use 145 * `--force` (bool, optional) force overwriting a previously existing image with this name 146 * `--language string` (string,required) target language to build the sources for 147 * `--mountpoint value` (string,repeated) specify up to 8 mount points for volumes (default []) 148 * `--name string` (string,required) name to give the unikernel. must be unique 149 * `--path string` (string,required) path to root application sources folder 150 * `--provider string` (string,required) name of the target infrastructure to compile for 151 * `--no-cleanup` (bool, optional) tell UniK not to clean up any artifacts from the build process if building fails. for debugging purposes. 152 153 --- 154 155 #### List available images 156 ``` 157 unik images 158 ``` 159 Lists all available unikernel images across providers. Includes important information for running and managing instances, including the required mount points for the image. 160 161 --- 162 163 #### Get JSON representation of a specifig image: 164 ``` 165 unik describe-image --image IMAGE_NAME 166 ``` 167 168 --- 169 170 #### Delete an image 171 ``` 172 unik delete-image --image IMAGE_NAME 173 ``` 174 Use `--force` to force deleting unikernel and associated instances if any instances of this image are currently running. 175 176 --- 177 178 #### Run an instance 179 ``` 180 unik run --instanceName INSTANCE_NAME --imageName IMAGE_TO_USE 181 ``` 182 183 Deploys a running instance from a unik-compiled unikernel disk image. 184 The instance will be deployed on the provider the image was compiled for. 185 e.g. if the image was compiled for virtualbox, unik will attempt to deploy 186 the image on the configured virtualbox environment. 187 188 'unik run' requires a unik-managed volume (see 'unik volumes' and 'unik create volume') 189 to be attached and mounted to each mount point specified at image compilation time. 190 This means that if the image was compiled with two mount points, /data1 and /data2, 191 'unik run' requires 2 available volumes to be attached to the instance at runtime, which 192 must be specified with the flags --vol SOME_VOLUME_NAME:/data1 --vol ANOTHER_VOLUME_NAME:/data2 193 If no mount points are required for the image, volumes cannot be attached. 194 195 environment variables can be set at runtime through the use of the -env flag. 196 197 Example usage: 198 199 ``` 200 unik run --instanceName newInstance --imageName myImage --vol myVol:/mount1 --vol yourVol:/mount2 --env foo=bar --env another=one --memory 1234 201 ``` 202 * will create and run an instance of myImage on the provider environment myImage is compiled for 203 * instance will be named newInstance 204 * instance will attempt to mount unik-managed volume myVol to /mount1 205 * instance will attempt to mount unik-managed volume yourVol to /mount2 206 * instance will boot with env variable `foo` set to `bar` 207 * instance will boot with env variable `another` set to `one` 208 * instance will get 1234 MB of memory 209 * note that run must take **exactly** one --vol argument for each mount point defined in the image specification 210 211 Flags: 212 * `--env value` (string,repeated) set any number of environment variables for the instance. must be in the format KEY=VALUE (default []) 213 * `--imageName string` (string,required) image to use 214 * `--instanceName string` (string,required) name to give the instance. must be unique 215 * `--vol value` (string,repeated) each --vol flag specifies one volume id and the corresponding mount point to attach to the instance at boot time. volumes must be attached to the instance for each mount point expected by the image. run 'unik image (image_name)' to see the mount points required for the image. specified in the format 'volume_id:mount_point' (default []) 216 * `--instanceMemory` (int, optional) amount of memory (in MB) to assign to the instance. if none is given, the provider default will be used 217 * `--no-cleanup` (bool, optional) tell UniK not to clean up any artifacts from the launch instance process if launching fails. for debugging purposes. 218 * `--debug-mode` (bool, optional) runs the instance in Debug mode so GDB can be attached. Currently only supported on QEMU provider 219 --- 220 221 #### List available instances 222 ``` 223 unik instances 224 ``` 225 Lists all available unikernel instances across providers. 226 227 --- 228 229 #### Get JSON representation of a specifig instance: 230 ``` 231 unik describe-instance --instance INSTANCE_NAME 232 ``` 233 234 --- 235 236 #### Delete an instance 237 ``` 238 unik delete-instance --instance INSTANCE_NAME 239 ``` 240 Use `--force` to force deleting an instance that is powered on 241 242 --- 243 244 #### Power Off an Instance 245 ``` 246 unik stop --instance INSTANCE_NAME 247 ``` 248 Powering off an instance is a necessary step to attach or detach volumes after an instance has been created. 249 250 ---- 251 252 #### Power On an Instance 253 ``` 254 unik start --instance INSTANCE_NAME 255 ``` 256 257 --- 258 259 #### Retrieve or Follow Instance Logs 260 ``` 261 unik logs --instance INSTANCE_NAME 262 ``` 263 Retrieves logs from a running unikernel instance. 264 265 Cannot be used on an instance in powered-off state. 266 Use the `--follow` flag to attach to the instance's stdout 267 Use `--delete` in combination with `--follow` to force automatic instance 268 deletion when the HTTP connection to the instance is broken (by client 269 disconnect). The `--delete` flag is typically intended for use with 270 orchestration software such as cluster managers which may require 271 a persistent http connection managed instances. 272 273 Example usage: 274 ``` 275 unik logs --instance myInstance 276 ``` 277 * will return captured stdout from myInstance since boot time 278 279 ``` 280 unik logs --instance myInstance --follow --delete 281 ``` 282 * will open an http connection between the cli and unik backend which streams stdout from the instance to the client 283 * when the client disconnects (i.e. with Ctrl+C) unik will automatically power down and terminate the instance 284 285 --- 286 287 ##### Create a Volume 288 289 ``` 290 unik create-volume 291 ``` 292 Creates a data volume which can be attached to and detached from 293 unik-managed instances. 294 295 Volumes can be created from a directory, which will copy the contents 296 of the directory onto the volume. Empty volume can also be created. 297 298 Volumes will persist after instances are deleted, allowing application data 299 to be persisted beyond the lifecycle of individual instances. 300 301 If specifying a data folder (with --data), specifying a size for the volume is 302 not necessary. UniK will automatically size the volume to fit the data provided. 303 A larger volume can be requested with the --size flag. 304 305 If no data directory is provided, --size is a required parameter to specify the 306 desired size for the empty volume to be created. 307 308 Volumes are created for a specific provider, specified with the --provider flag. 309 Volumes can only be attached to instances of the same provider type. 310 To see a list of available providers, run 'unik providers' 311 312 Volume names must be unique. If a volume exists with the same name, you will be 313 required to remove the volume with 'unik delete-volume' before the new volume 314 can be created. 315 316 --size parameter uses MB 317 318 Example usage: 319 unik create-volume --name myVolume --data ./myApp/data --provider aws 320 321 * will create an EBS-backed AWS volume named myVolume using the data found in ./myApp/src, 322 * the size will be either 1GB (the default minimum size on AWS) or greater, if the size of the 323 volume is greater 324 325 326 Another example (empty volume): 327 unik create-volume -name anotherVolume --size 500 -provider vsphere 328 329 * will create a 500mb sparse vmdk file and upload it to the vsphere datastore, 330 where it can be attached to a vsphere instance 331 332 Flags: 333 * `--size int` (int,special) size to create volume in MB. optional if --data is provided 334 * `--data string` (string,special) path to data folder. optional if --size is provided 335 * `--name string` (string,required) name to give the unikernel. must be unique 336 * `--provider string` (string,required) name of the target infrastructure to compile for 337 * `--no-cleanup` (bool, optional) tell UniK not to clean up any artifacts from the build process if building fails. for debugging purposes. 338 339 --- 340 341 ##### List Volumes 342 343 ``` 344 unik volumes 345 ``` 346 Lists all available unik-managed volumes across providers. 347 348 `ATTACHED-INSTANCE` gives the instance ID of the instance a volume 349 is attached to, if any. Only volumes that have no attachment are 350 available to be attached to an instance. 351 352 --- 353 354 ##### Attach a Volume 355 356 ``` 357 unik attach-volume --instance INSTANCE_ID --volume VOLUME_ID --mountPoint MOUNT_POINT 358 ``` 359 360 Attaches a volume to a stopped instance at a specified mount point. 361 You specify the volume by name or id. 362 363 The volume must be attached to an available mount point on the instance. 364 Mount points are image-specific, and are determined when the image is compiled. 365 366 For a list of mount points on the image for this instance, run `unik images`, or 367 `unik describe image` 368 369 If the specified mount point is occupied by another volume, the command will result 370 in an error 371 372 Flags: 373 * `--force` (bool, optional) force deleting volume in the case that it is running 374 * `--instance string` (string,required) name or id of instance to attach to. unik accepts a prefix of the name or id 375 * `--mountPoint string` (string,required) mount path for volume. this should reflect the mappings specified on the image. run 'unik describe-image' to see expected mount points for the image 376 * `--volume string` (string,required) name or id of volume to attach. unik accepts a prefix of the name or id 377 378 --- 379 380 ##### Detach a Volume 381 382 ``` 383 unik detach-volume --volume VOLUME_ID 384 ``` 385 386 Detaches a volume to a stopped instance at a specified mount point. 387 You specify the volume by name or id. 388 389 After detaching the volume, the volume can be mounted to another instance. 390 391 If the instance is not stopped, detach will result in an error. 392 393 Aliases: 394 detach-volume, detach 395 396 397 Flags: 398 * `--volume string` (string,required) name or id of volume to detach. unik accepts a prefix of the name or id 399 400 --- 401 402 ##### Delete a Volume 403 404 ``` 405 unik delete-volume --volume VOLUME_NAME [--force] 406 ``` 407 408 * `--force` forces detaching the volume before deletion if it is currently attached. 409 410 --- 411 412 ##### Login 413 414 ``` 415 unik login 416 ``` 417 418 * Log in to a Unik Repository to pull & push images 419 * This does not actually authenticate (as Unik Hubs are stateless), but sets client configuration at `~/.unik/hub-config.yaml` 420 421 --- 422 423 ##### Push 424 425 ``` 426 unik push --image myImage 427 ``` 428 429 * Pushes a compiled image from local provider (Xen, Virtualbox, or QEMU) to an S3-backed Hub Repository 430 431 --- 432 433 ##### Pull 434 435 ``` 436 unik pull --image myImage --provider virtualbox|qemu|xen 437 ``` 438 439 * Pull a compiled image from an S3-backed Hub Repository to local provider (Xen, Virtualbox, or QEMU) to an S3-backed Hub Repository 440 * Provider specifies the architecture the image is specified for. 441 --- 442 443 ##### Search 444 445 ``` 446 unik search [image_name] 447 ``` 448 449 * Searches available images. Optional filter by `image_name`