planet

README

Planet

Warning Planet was archived 2023-07-01.

Please see the Gravity README.md for more information.

Planet is a containerized Kubernetes environment. It is a self-containerizing Debian image with Kubernetes services running inside. Gravity is the recommended way to deploy planet containers.

Installation

Planet images are automatically packaged by Gravity - this is the easiest way to use and hack on planet. See the development section below for details on how to build & hack on planet locally.

Details of Operation

Planet is a generic container image with executable entry points -- it is an archived root filesystem Planet uses libcontainer to self-containerize. Planet launches systemd inside the container as the main process which manages the lifetime of all the other services - Kubernetes, among others. A planet binary is available within planet at rootfs/usr/bin/planet

That planet binary defines all entry points for this package. Here is a brief summary of the planet interface:

Commands:
  help [<command>...]
    Show help.

  version
    Print version information

  start [<flags>]
    Start Planet container

  agent --leader-key=LEADER-KEY --election-key=ELECTION-KEY [<flags>]
    Start Planet Agent

  stop
    Stop planet container

  enter [<flags>] [<cmd>]
    Enter running planet container

  status [<flags>]
    Query the planet cluster status

  test --kube-addr=KUBE-ADDR [<flags>]
    Run end-to-end tests on a running cluster

  device add --data=DATA
    Add new device to container

  device remove --node=NODE
    Remove device from container

  etcd promote --name=NAME --initial-cluster=INITIAL-CLUSTER --initial-cluster-state=INITIAL-CLUSTER-STATE
    Promote etcd running in proxy mode to a full member

  leader pause
    Pause leader election participation for this node

  leader resume
    Resume leader election participation for this node

  leader view --leader-key=LEADER-KEY
    Display the IP address of the active master

Building (installing from source)

Prerequisites for planet development are:

• docker version >= 1.8.2 is required. For development, you need to be inside docker group and have the docker daemon running so the typical docker commands like docker run do not require sudo permissions. Here's official docker configuration reference.
• (optional) vagrant version >= 1.7.4

The building process has been tested on Debian 8 and Ubuntu 15.04.

The output of Planet build is a tarball that goes into build/$TARGET:

Following are the most common targets:

• make production - builds a planet image. These are the images used by Gravity.

Building planet for the first time takes considerable amount of time since it has to download/build/configure quite a few dependencies:

• Kubernetes
• docker registry
• flannel
• etcd

Subsequent builds are much faster because intermediate results are cached (in build/assets directory). To clear and rebuild from scratch, run the make clean.

Upgrading dependencies

If your patch depends on new go packages, the dependencies must:

• be licensed via Apache2 license
• be approved by core Planet contributors ahead of time
• be vendored via go modules

Non-go (root fs) dependencies are encapsulated into their own build packages rooted at build.assets.

For instance, to upgrade etcd, edit build.assets/makefiles/etcd/etcd.mk:

...
VER := v2.2.3
...

The version of Kubernetes is defined in the root makefile:

...
KUBE_VER := v1.17.9
...

Planet Design

Planet Daemon

Once started, planet will continue running and waiting for the main systemd process to end. The container environment is encapsulated by the box package. As part of its operation, planet will also start a web server to enable remote process control. The server listens on the unix socket (in a /var/run/planet.sock by default) and is capable of running commands inside the container on behalf of the client - this is how the commands planet stop and planet enter are implemented.

Planet Agent

One additional service is the agent. Agent is responsible for maintaining the health status of the cluster (obtainable with planet status) and implementing the master fail-over by dynamically promoting nodes to master should the active master fail.