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.
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.
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
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 rundo 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:
Subsequent builds are much faster because intermediate results are cached (in build/assets directory).
To clear and rebuild from scratch, run the make clean.
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
...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.
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.