Haconiwa - the mruby on container

Tha haconiwa teaser site

Haconiwa

Build Status

mRuby on Container / helper tools with DSL for your handmade linux containers.

Haconiwa (箱庭 - a miniature garden) is a container builder DSL, by which you can choose any container-related technologies as you like:

Haconiwa is written in mruby, so you can utilize Ruby DSL for creating your own container.

Install binary

haconiwa packages are provided via packagecloud.

Available for: CentOS >= 7 / Ubuntu Trusty / Ubuntu Xenial / Debian jessie (which are supported by best effort...)

Other linuxes users can just download binaries from latest:

VERSION=0.2.2
wget https://github.com/haconiwa/haconiwa/releases/download/v${VERSION}/haconiwa-v${VERSION}.x86_64-pc-linux-gnu.tgz
tar xzf haconiwa-v${VERSION}.x86_64-pc-linux-gnu.tgz
sudo install hacorb hacoirb haconiwa /usr/local/bin
haconiwa
# haconiwa - The MRuby on Container
# commands:
#     run       - run the container
#     attach    - attach to existing container
#     version   - show version
#     revisions - show mgem/mruby revisions which haconiwa bin uses

NOTE: If you'd like using cgroup-related features, install cgroup package such as cgroup-lite (Ubuntu) or cgroup-bin (Debian). If you would not, these installation are not required.

Example

Create the file example.haco:

Haconiwa::Base.define do |config|
  config.name = "new-haconiwa001" # to be hostname

  config.cgroup["cpu.shares"] = 2048
  config.cgroup["memory.limit_in_bytes"] = "256M"
  config.cgroup["pid.max"] = 1024

  config.add_mount_point "/var/another/root/etc", to: "/var/your_rootfs/etc", readonly: true
  config.add_mount_point "/var/another/root/home", to: "/var/your_rootfs/home"
  config.mount_independent_procfs
  config.chroot_to "/var/your_rootfs"

  config.namespace.unshare "ipc"
  config.namespace.unshare "uts"
  config.namespace.unshare "mount"
  config.namespace.unshare "pid"

  config.capabilities.allow :all
  config.capabilities.drop "cap_sys_admin"
end

Then use haconiwa binary installed with thie gem.

$ haconiwa run example.haco

When you want to attach existing container:

$ haconiwa attach example.haco

Note: attach subcommand allows to set PID(--target) or container name(--name) for dynamic configuration. And attach is not concerned with capabilities which is granted to container. So you can drop or allow specific caps with --drop/--allow.

DSL spec

You can pick your own parameters for your use case of container. e.g. just using mount namespace unshared, container with common filesystem, limit the cgroups for big resource job and so on.

Please look into sample directory.

Programming the container world by mruby

e.g.:

Namespace.unshare(Namespace::CLONE_NEWNS)
Namespace.unshare(Namespace::CLONE_NEWPID)

m = Mount.new

m.make_private "/"
m.bind_mount "/var/lib/myroot", "/var/lib/haconiwa/root"

Dir.chroot "/var/lib/haconiwa"
Dir.chdir "/"

c = Process.fork {
  m.mount "proc", "/proc", :type => "proc"
  Exec.exec "/bin/sh"
}
pid, ret = Process.waitpid2 c
puts "Container exited with: #{ret.inspect}"

See dependent gem's READMEs.

Development

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/haconiwa/haconiwa. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

TODOs

License

Haconiwa core is under the GPL v3 License: See LICENSE file.

Bundled libraries (libcap, libcgroup, libargtable and mruby) are licensed by each authors. See LICENSE_* file.

For other mgems' licenses, especially ones which are not bundled by mruby-core, please refer their github.com repository.