Getting started #

Install and Setup #

Saya is work-in-progess, currently available on linux/amd64 and tested on Ubuntu, Debian, Fedora. Please consult the Supported Platforms for more details.

You can install Saya with necessary dependencies and configurations on supported platforms using the following commands.

curl {{downloadUrl}}
unzip {{downloadedZip}}
sudo saya setup --compute-type localhost --target localhost

Build and Run images #

You build virtual machine images the same way you build container images with docker-cli. The example below builds and runs an http server image (webserver:v1) based on alpine, python3, and the python http.server package.

# amd64 / same context / same Dockerfile
mkdir -p demo_pjt ; cd demo_pjt
echo "serve me" > serve-me.txt
cat <<EOF > Dockerfile
FROM alpine

USER root
RUN apk add python3

RUN addgroup -S server && adduser -S server -G server
USER server:server
RUN mkdir /home/server/data/
COPY --chown=server:server serve-me.txt /home/server/data/

WORKDIR /home/server/data/
CMD python3 -m http.server 8000
EOF

# build an image tagged as websever:v1
saya image build -t websever:v1 .

# list images
saya image ls

# run websever:v1
saya vm run webserver:v1

# list VMs
saya vm ls

# stop vm
saya vm stop <vm-id>

# start stopped vm
saya vm start <vm-id>

# removed stopped vm
saya vm rm <vm-id>

Pushing images #

Push image to default repository #

The image build cmd should have produced a result similar to this:

To push webserver:v1 into the default repository simply run:

saya image push websever:v1

Configure S3 as remote default repository #

Add the following in your .saya.yaml configuration file:

# s3 as default push repo
repo-type: s3
s3-bucket: '<your-bucket>' 
s3-base-key: '<your-base-key>'

Pushing webserver:v1 will generate the following s3 objects:

• s3://<your-bucket>/<your-base-key>/appserver/v1/linux/amd64/img.ova
• s3://<your-bucket>/<our-base-key>/webserver/v1/linux/amd64/img.ova.meta
• s3://<your-bucket>/<your-base-key>/webserver/v1/linux/amd64/img.ova.sha256

Location of the configuration file #

Saya reads its configuration from a .saya.yaml configuration file.

The search directories are:

• current directory
• ${Home}/.saya/.saya.yaml
• /etc/saya/.saya.yaml

The first existing configuration file is loaded. No merging will be performed.

Can I try Saya without setup? #

Yes!
Without setup though networking will be limited (especially when qemu is used as compute type). Saya uses SSH to apply configuration specified in instruction files(Dockerfile, Sayafile). Manual network configuration, which only uses NAT-networking for virtualbox or USER-networking for qemu, must provide port forwarding to the guest SSH service port(22).

Limitations:

• Virtualbox

  Virtualbox will likely have at least one hostonlyif setup. Saya will pick it to provide full-networking and use the default nat to provide internet access.
  If no hostonlyif network is defined, Saya will only provide a network interface based on NatNet with SSH access configured using port forwarding. Manual nic definition is required to access other ports. E.g.:

# ssh access by forwarding host localhost:2222 to guest port  22
# application service port access by forwarding host localhost:8000 to guest port 8000
saya image run websever:v1 --nic "type=nat, host-nic=, net-name=, hw=, hostfwd=tcp::8000-:8000 hostfwd=tcp::22222-:22"

• Qemu

  Qemu networking will be limited to user-networking without prior configuration. Saya will setup port forwarding for SSH access. Manual nic definition is required to access other ports. E.g.:

# ssh access by forwarding host localhost:2222 to guest port  22
# application service port access by forwarding host localhost:8000 to guest port 8000
saya image run websever:v1 --nic "type=user, host-nic=, net-name=, hw=, hostfwd=tcp::8000-:8000 hostfwd=tcp::22222-:22"

How to map from-image tag #

FROM image requirement #

Saya requires the location of the base image and the OS variant to build images. It therefore provides specification mechanisms using annotation, CLI parameters, environment variables or configuration files. Images in the local repository are stored with the appropriate meta-data to meet the requirement. Saya is also able to automatically map certain image tags. For all other cases manual specification is necessary.

Automatic mapping #

The following tags can be automatically mapped:

• alpine:version, with version being

  • latest
  • or an official release version found at https://alpinelinux.org/ (from 3.14.0 or higher)

• ubuntu:version, with version being

  • latest
  • or a codename (bionic or higher)
  • or an official major.minor version (18.04 or higher)
  • or an official major.minor.patch version (18.04.1 or higher)

• debian:version, with version being

  • latest
  • or a codename (bullseye or higher)
  • or a major version (10 or higher)
  • or an official version major.minor.patch

Mapping by configuration #

The ubuntu base amd64 image located at http://example.com/vm/imgs/ubuntu-20.04-server-cloudimg-amd64.ova can be mapped to the tag saya/ubuntu-sut using the following specifications:

• Annotation in an instruction file

  docker

  # Note that an annotation starts with #@
  #@image.mapping linux/amd64:saya/ubuntu-sut:latest=http://example.com/vm/imgs/ubuntu-20.04-server-cloudimg-amd64.ova
  #@os.variant ubuntu
  FROM saya/ubuntu-sut
  ....
  

• CLI parameter

  bash

  saya image build --from-mapping  linux/amd64:saya/ubuntu-sut:latest=http://example.com/vm/imgs/ubuntu-20.04-server-cloudimg-amd64.ova --os-variant ubuntu
  

• Environment variable

  bash

  SAYA_FROM_MAPPING="linux/amd64:saya/ubuntu-sut:latest=http://example.com/vm/imgs/ubuntu-20.04-server-cloudimg-amd64.ova"
  SAYA_OS_VARIANT=ubuntu
  saya image build ....
  

• config file .saya.yaml

  yaml

  ....
  from-mapping:
      "linux/amd64:saya/ubuntu-sut:latest": "http://example.com/vm/imgs/ubuntu-20.04-server-cloudimg-amd64.ova"
      "linux/arm64:saya/ubuntu-sut:latest": "http://example.com/vm/imgs/ubuntu-20.04-server-cloudimg-armd64.ova"
  ....
  

Image mapping follows the following formats:

• [platform]:name:[version]=location
• platform := os[/arch[/variant]]
  • the default value is the host platform
• location := file-path|http-url|s3-url
• default version is latest

Given the defaulting and your host platform being linux/amd64, then
     linux/amd64:saya/ubuntu-sut:latest=http://example.com/vm/imgs/ubuntu-20.04-server-cloudimg-amd64.ova
is equivalent to
     :saya/ubuntu-sut:=http://example.com/vm/imgs/ubuntu-20.04-server-cloudimg-amd64.ova