Skip to content

Latest commit

 

History

History
645 lines (529 loc) · 11.8 KB

configuration.md

File metadata and controls

645 lines (529 loc) · 11.8 KB

Configuration

The configuration file used by ops (such as one passed as a parameter, e.g. ops --config myconfig.json) specifies various options and attributes of code execution, such as files to include, arguments, and environment variables. This file follows the standard json format.

For a complete sample of a configuration, see our sample.

Configuration Attributes

Args {#args}

An array of commands to execute when running the image:

{
    "Args": ["ex.js"]
}

BaseVolumeSz {#base_volume_size}

The BaseVolumeSz is an optional parameter you can pass to specify the size of the base volume. By default the size is the end of blocks written by TFS.

To specify 100 megabytes:

{
    "BaseVolumeSz": "100m"
}

To specify 1 gigabyte:

{
    "BaseVolumeSz": "1g"
}

Boot {#boot}

TODO

BuildDir {#build_dir}

TODO

CloudConfig {#cloudconfig}

The CloudConfig configures various attributes about the cloud provider, we want to use with ops.

BucketName {#cloudconfig.bucketname}

Bucket name is used to store Ops built image artifacts.

{
    "CloudConfig": {
        "BucketName": "my-bucket"
    }
}

DomainName {#cloudconfig.domain_name}

Updates DNS entry with the started instance IP.

{
    "CloudConfig": {
        "DomainName": "ops.city"
    }
}

EnableIPv6 {#cloudconfig.enable_ipv6}

This option is only supported on AWS.

If EnableIPv6 is set to true and a VPC is created, the new VPC will have ipv6 support. Otherwise, it doesn't affect the selected VPC ipv6 support.

{
    "CloudConfig": {
        "EnableIPv6": true
    }
}

Flavor {#cloudconfig.flavor}

Specifies the machine type used to create an instance. Each cloud provider has different types descriptions.

{
    "CloudConfig": {
        "Flavor": "t2.micro"
    }
}

ImageName {#cloudconfig.imagename}

Specifies the image name in the cloud provider.

{
    "CloudConfig": {
        "ImageName": "web-server"
    }
}

Platform {#cloudconfig.platform}

Cloud provider we want to use with ops CLI.

Currently supported platforms:

  • Google Cloud Platform gcp
  • AWS aws
  • Vultr vultr
  • Vmware vsphere
  • Azure azure
  • Openstack openstack
  • Upcloud upcloud
  • Hyper-v hyper-v See further instructions about the cloud provider in dedicated documentation page.
{
    "CloudConfig": {
        "Platform": "gcp"
    }
}

ProjectID {#cloudconfig.projectid}

Project ID is used in some cloud providers to identify a workspace.

{
    "CloudConfig": {
        "ProjectID": "proj-1000"
    }
}

SecurityGroup {#cloudconfig.security_group}

Allows an instance to use an existing security group in the cloud provider.

On AWS, both the name and the id of the security group may be used as value.

{
    "CloudConfig": {
        "SecurityGroup": "sg-1000"
    }
}

Subnet {#cloudconfig.subnet}

Allows an instance to use an existing subnet in the cloud provider.

On AWS, both the name and the id of the subnet may be used as value.

{
    "CloudConfig": {
        "Subnet": "sb-1000"
    }
}

Tags {#cloudconfig.tags}

A list of keys and values to provide more context about an instance or an image. There are a set of pre-defined tags to identify the resources created by ops.

{
    "CloudConfig": {
        "Tags": [
            {
                "key": "instance-owner",
                "value": "joe-smith"
            },
            {
                "key": "function",
                "value": "web-server"
            }
        ]
    }
}

Zone {#cloudconfig.zone}

Zone is used in some cloud providers to identify the location where cloud resources are stored.

{
    "CloudConfig": {
        "Zone": "us-west1-b"
    }
}

VPC {#cloudconfig.vpc}

Allows instance to use an existing vpc in the cloud provider.

On AWS, both the name and the id of the vpc may be used as value.

{
    "CloudConfig": {
        "VPC": "vpc-1000"
    }
}

Debugflags {#debugflags}

TODO

Dirs {#dirs}

An array of directory locations to include into the image:

{
    "Dirs": ["myapp/static"]
}

File layout on local host machine:

-myapp
    app
    -static
        -example.html
        -stylesheet
            -main.css

File layout on VM:

/myapp
    app
    /static
        -example.html
        /stylesheet
            -main.css

Env {#env}

A map of environment variables:

{
    "Env": {
        "Environment": "development",
        "NODE_DEBUG": "*"
    }
}

Files {#files}

An array of file locations to include into the image:

{
    "Files": ["ex.js"]
}

Force {#force}

TODO

Kernel {#kernel}

TODO

ManifestPassthrough {#manifestpassthrough}

There is the concept of the manifest in Nanos where there exists many other config options that don't boil up to ops configuration, however, sometimes you still wish to pass these settings down to the manifest. Certain klibs, in particular, have variables that need to be set. To set them do this:

{
  "ManifestPassthrough": {
    "my_manifest_setting": "some_value"
  }
}

MapDirs {#mapdirs}

A map of a local directory to a different path on the guest VM. For example the below adds all files under /etc/ssl/certs on host to /usr/lib/ssl/certs on VM.

{
    "MapDirs": {"/etc/ssl/certs/*": "/usr/lib/ssl/certs" },
}

Mounts {#mounts}

TODO

NameServer {#nameserver}

The DNS server to use for DNS resolution. By default it is Google's 8.8.8.8.

{
    "NameServer": "10.8.0.1"
}

NightlyBuild {#nightly_build}

TODO

NoTrace {#no_trace}

TODO

Program {#program}

TODO

ProgramPath {#program_path}

TODO

RebootOnExit

There is an option to reboot your application immediately if it crashes that is turned off by default, but you can enable it.

{
    "RebootOnExit": true
}

RunConfig {#runconfig}

The RunConfig configures various attributes about the runtime of the ops instance, such as allocated memory and exposed ports.

Accel {#runconfig.accel}

Defines whether hardware acceleration should be enabled in qemu. This option is enabled by default.

{
    "RunConfig": {
        "Accel": true
    }
}

Bridged {#runconfig.bridged}

Connects the unikernel network interface to a bridge with the name br0. The bridge name may be overriden with the property BridgeName.

{
    "RunConfig": {
        "Bridged": true
    }
}

BridgeName {#runconfig.bridge_name}

Connects the unikernel network interface to a bridge with the name specified. If the bridge does not exist in host machine it is created.

{
    "RunConfig": {
        "BridgeName": "br1"
    }
}

CPUs {#runconfig.cpus}

Specifies the number of CPU cores the unikernel is allowed to use.

{
    "RunConfig": {
        "CPUs": 2
    }
}

Debug {#runconfig.debug}

Opens a port in unikernel to allow a connection with the GDB debugger. See further instructions in Debugging. If debug is set to true the hardware acceleration (accel) is disabled.

{
    "RunConfig": {
        "Debug": true
    }
}

Gateway {#runconfig.gateway}

Defines the default gateway IP of the network interface.

{
    "RunConfig": {
        "Gateway": "192.168.1.255"
    }
}

GdbPort {#runconfig.gdb_port}

Define the gdb debugger port. It only takes effect if debug is enabled. By default the GdbPort is 1234.

{
    "RunConfig": {
        "GdbPort": 1234,
        "Debug": true
    }
}

Imagename {#runconfig.image}

Sets the name of the image file.

{
    "RunConfig": {
        "Imagename": "web-server"
    }
}

InstanceName {#runconfig.instance_name}

Sets the name of the instance.

{
    "RunConfig": {
        "InstanceName": "web-server-instance"
    }
}

IPAddress {#runconfig.ipaddress}

Defines the IP address of the network interface.

{
    "RunConfig": {
        "IPAddress": "192.168.1.75"
    }
}

The IP address has to be specified along with the netmask{#runconfig.netmask} and the gateway{#runconfig.gateway}, so the unikernel can assign the IP address to the network interface.

{
    "RunConfig": {
        "IPAddress": "192.168.1.75",
        "NetMask": "255.255.255.0",
        "Gateway": "192.168.1.1"
    }
}

IPv6Address {#runconfig.ipv6address}

Defines the static IPv6 address of the network interface.

{
    "RunConfig": {
        "IPv6Address": "FE80::46F:65FF:FE9C:4861"
    }
}

Klibs {#runconfig.klibs}

For example to run the NTP klib (eg: ntpd):

{ "RunConfig":{ "Klibs":["ntp"] } }

Memory {#runconfig.memory}

Configures the amount of memory to allocated to qemu. Default is 128 MiB. Optionally, a suffix of "M" or "G" can be used to signify a value in megabytes or gigabytes respectively.

{
    "RunConfig": {
        "Memory": "2G"
    }
}

Mounts {#runconfig.mounts}

Defines a list of directories paths in the host machine whose data will be copied to the unikernel.

{
    "RunConfig": {
        "Mounts": ["./files","./assets"]
    }
}

NetMask {#runconfig.net_mask}

Defines the netmask of the network interface.

{
    "RunConfig": {
        "NetMask": "255.255.255.0"
    }
}

Background {#runconfig.background}

Starts unikernels in background. You can stop the unikernel using the onprem instances stop command.

{
    "RunConfig": {
        "Background": true
    }
}

Ports {#runconfig.ports}

A list of ports to expose. Alternatively, you can also use -p in the command line.

{
    "RunConfig": {
        "Ports": ["80", "8008"],
    }
}

ShowDebug {#runconfig.show_debug}

Enables printing more details about what ops is doing at the moment. Also, enables the printing of warnings and errors.

{
    "RunConfig": {
        "ShowDebug": true,
    }
}

ShowErrors {#runconfig.show_errors}

Enables printing errors with more details.

{
    "RunConfig": {
        "ShowErrors": true,
    }
}

ShowWarnings {#runconfig.show_warnings}

Enables printing warnings details.

{
    "RunConfig": {
        "ShowWarnings": true,
    }
}

TapName {#runconfig.tap_name}

Connects the unikernel to a network interface with the name specified. If the tap does not exist in host machine it is created.

{
    "RunConfig": {
        "TapName": "tap0"
    }
}

UDP {#runconfig.udp}

UDP is off by default. You can toggle UDP on via:

{
    "RunConfig": {
        "UDP": true
    }
}

UDPPorts {#runconfig.udp_ports}

Opens ports that use UDP protocol.

{
    "RunConfig": {
        "Ports": [60, 6006],
    }
}

Verbose {#runconfig.verbose}

Enables verbose logging for the runtime environment. As of now, it prints the command used to start qemu.

{
    "RunConfig": {
        "Verbose": true
    }
}

VolumeSizeInGb {#runconfig.volume_size_in_gb}

This property is only used by cloud provider openstack and sets the instance volume size. Default size is 1 GB.

{
    "RunConfig": {
        "VolumeSizeInGb": 2
    }
}

TargetRoot {#target_root}

TODO

Version {#version}

TODO

Sample Configuration File {#sample}

Below is a sample configuration file for a nodejs application.

{
	"Files": ["ex.js"],
	"Dirs": ["src"],
	"Args": ["ex.js "],
	"Env": {
		"NODE_DEBUG": "*",
		"NODE_DEBUG_NATIVE": "*"
	},
	"MapsDirs": {
		"src": "/myapp/code"
	},
	"Boot": "./staging/boot2.img",
	"Kernel": "./staging/stage4.img",
	"Mkfs": "./staging/mkfs",
	"DiskImage": "disk-image",
	"NameServer": "10.8.0.1",
	"RunConfig": {
		"Verbose": true,
		"Bridged": true,
		"Ports": [8008],
		"Memory": "2G"
	}
}