package module
v0.2.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Dec 23, 2018 License: MIT Imports: 6 Imported by: 11


   _____ __       ____
  / ___// /____  / / /___ ______
  \__ \/ __/ _ \/ / / __ `/ ___/
 ___/ / /_/  __/ / / /_/ / /

Simplified Container Runtime Cluster

Stellar is designed to provide simple container runtime clustering. One or more nodes are joined together to create a cluster. The cluster is eventually consistent making it ideal for transient workloads or edge computing where nodes are not always guaranteed to have high bandwidth, low latency connectivity.


There are several container platforms and container orchestrators out there. However, they are too complex for my use. I like simple infrastructure that is easy to deploy and manage, tolerates failure cases and is easy to debug when needed. With the increased tolerance in failure modes, this comes at a consistency cost. It may not be for you. Use the best tool for your use case. Enjoy :)


  • Container execution via containerd
  • Multihost Networking via CNI
  • Service Discovery via DNS
  • Cluster event system via NATS
  • Builtin Proxy using Radiant (zero downtime reloads, canary deploys, health checks, automatic HTTPS)
  • Masterless design
  • Efficient use of system resources
  • Simple daemon deployment


For official releases, see the Releases

You can also grab the latest Master Build


In order to build Stellar you will need the following:

Once you have the requirements you can build.

If you change / update the protobuf definitions you will need to generate:

make generate

To build the binaries (client and server) run:



Alternatively you can use Docker to build:

To generate protobuf:

make docker-generate

To build binaries:

make docker-build


To run Stellar, once you have a working containerd installation follow these steps:

  • Install Containerd
  • Build binaries or get a release
  • Copy /bin/sctl to /usr/local/bin/
  • Copy /bin/stellar to /usr/local/bin/
  • Copy /bin/stellar-cni-ipam to /opt/containerd/bin/ or /opt/cni/bin

First, we will generate a config:

$> stellar config > stellar.conf

This will produce a default configuration. Edit the addresses to match your environment. For this example we will use the IP

    "ConnectionType": "local",
    "ClusterAddress": "",
    "AdvertiseAddress": "",
    "Debug": false,
    "NodeID": "dev",
    "GRPCAddress": "",
    "TLSServerCertificate": "",
    "TLSServerKey": "",
    "TLSClientCertificate": "",
    "TLSClientKey": "",
    "TLSInsecureSkipVerify": false,
    "ContainerdAddr": "/run/containerd/containerd.sock",
    "Namespace": "default",
    "DataDir": "/var/lib/stellar",
    "StateDir": "/run/stellar",
    "Bridge": "stellar0",
    "UpstreamDNSAddr": "",
    "ProxyHTTPPort": 80,
    "ProxyHTTPSPort": 443,
    "ProxyTLSEmail": "",
    "GatewayAddress": "",
    "EventsAddress": "",
    "EventsClusterAddress": "",
    "EventsHTTPAddress": "",
    "CNIBinPaths": [
    "Peers": [],
    "Subnet": ""

To start the initial node run:

$> stellar -D server --config stellar.conf

To join additional nodes simply add the AdvertiseAddress of the first node to the Peers config option of the second node:

For example:

    "ConnectionType": "local",
    "ClusterAddress": "",
    "AdvertiseAddress": "",
    "Debug": false,
    "NodeID": "dev",
    "GRPCAddress": "",
    "TLSServerCertificate": "",
    "TLSServerKey": "",
    "TLSClientCertificate": "",
    "TLSClientKey": "",
    "TLSInsecureSkipVerify": false,
    "ContainerdAddr": "/run/containerd/containerd.sock",
    "Namespace": "default",
    "DataDir": "/var/lib/stellar",
    "StateDir": "/run/stellar",
    "Bridge": "stellar0",
    "UpstreamDNSAddr": "",
    "ProxyHTTPPort": 80,
    "ProxyHTTPSPort": 443,
    "ProxyTLSEmail": "",
    "GatewayAddress": "",
    "EventsAddress": "",
    "EventsClusterAddress": "",
    "EventsHTTPAddress": "",
    "CNIBinPaths": [
    "Peers": [""],
    "Subnet": ""

You will now have a two node cluster. To see node information, use sctl.

$> sctl --addr cluster nodes
NAME                ADDR                OS                       UPTIME              CPUS                MEMORY (USED)
stellar-00      Linux (4.17.0-3-amd64)   7 seconds           2                   242 MB / 2.1 GB
stellar-01      Linux (4.17.0-3-amd64)   6 seconds           2                   246 MB / 2.1 GB

Deploying an Application

To deploy an application, create an application config. For example, create the following as example.conf:

    "name": "example",
    "labels": [
    "services": [
            "name": "redis",
            "image": "",
            "runtime": "io.containerd.runtime.v1.linux",
            "process": {
                "uid": 0,
                "gid": 0,
                "args": ["redis-server"]
            "labels": [
            "network": true

Then run the following to deploy:

$> sctl --addr apps create -f ./example.conf

You should now see the application deployed:

$> sctl --addr apps list
NAME                SERVICES
example             1

$> sctl --addr apps inspect example
Name: example
  - Name: example.redis
    Runtime: io.containerd.runtime.v1.linux
    Snapshotter: overlayfs

By default all applications that have networking enabled will have a corresponding nameserver record created. To view the records use the following:

$> sctl --addr nameserver list
NAME                    TYPE                VALUE                                            OPTIONS
example.redis.stellar   A         
example.redis.stellar   TXT                 node=stellar-00; updated=2018-09-08T10:71:02-04:00




View Source
const (
	// APIVersion is the version of the API
	APIVersion = "v1"
	// StellarNetworkLabel is the label to identify that a container should use stellar networking
	StellarNetworkLabel = ""
	// StellarApplicationLabel is the label to identify that a container belongs to the stellar app
	StellarApplicationLabel = ""
	StellarExtensionID      = ""
	StellarServiceExtension = StellarExtensionID + "/Service"


This section is empty.


func DefaultContainerd

func DefaultContainerd(addr, namespace string) (*containerd.Client, error)


type Config

type Config struct {
	// NodeID is the id of the node
	NodeID string
	// GRPCAddress is the address for the grpc server
	GRPCAddress string
	// TLSCertificate is the certificate used for grpc communication
	TLSServerCertificate string
	// TLSKey is the key used for grpc communication
	TLSServerKey string
	// TLSClientCertificate is the client certificate used for communication
	TLSClientCertificate string
	// TLSClientKey is the client key used for communication
	TLSClientKey string
	// TLSInsecureSkipVerify disables certificate verification
	TLSInsecureSkipVerify bool
	// AgentConfig is the element config for the server
	AgentConfig *element.Config `json:"-"`
	// ContainerdAddr is the address to the containerd socket
	ContainerdAddr string
	// Namespace is the containerd namespace to manage
	Namespace string
	// Subnet is the subnet to use for stellar networking
	Subnet *net.IPNet
	// DataDir is the directory used to store stellar data
	DataDir string
	// State is the directory to store run state
	StateDir string
	// Bridge is the name of the bridge for networking
	Bridge string
	// UpstreamDNSAddr is the address to use for external queries
	UpstreamDNSAddr string
	// ProxyHTTPPort is the http port to use for the proxy service
	ProxyHTTPPort int
	// ProxyHTTPSPort is the https port to use for the proxy service
	ProxyHTTPSPort int
	// ProxyTLSEmail is the email address used when requesting letsencrypt certs
	ProxyTLSEmail string
	// ProxyHealthcheckInterval is the interval used by the proxy service to check upstreams
	ProxyHealthcheckInterval time.Duration
	// GatewayAddress is the http addr to use for the http/json API
	GatewayAddress string
	// EventsAddress is the address for the events service
	EventsAddress string
	// EventsClusterAddress is the address for the events cluster service
	EventsClusterAddress string
	// EventsHTTPAddress is the management address for the events service
	EventsHTTPAddress string
	// CNIBinPaths are paths to search for CNI plugin binaries
	CNIBinPaths []string

Config is the configuration used for the stellar server Note: in order to make user configuration from file a better user experience there is a custom marshal/unmarshal below. Those must be updated if fields are added or removed from `Config`.

func (*Config) MarshalJSON added in v0.2.0

func (c *Config) MarshalJSON() ([]byte, error)

MarshalJSON is a custom json marshaller for better ux

func (*Config) UnmarshalJSON added in v0.2.0

func (c *Config) UnmarshalJSON(data []byte) error

UnmarshalJSON is a custom json unmarshaller for better ux

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL