plug

Install

Two pieces: one agent per cluster, and the plug CLI on each developer's machine, installed from that agent. The agent is the same image everywhere; only the way it is deployed, and the right it needs to publish a name, change with the platform.

• Docker Compose
• Docker Swarm
• Kubernetes
• OpenShift and OKD
• One agent for several stacks
• The CLI, on each machine

Whatever the platform, the agent lets in whoever reaches its port until you set PLUG_ADMISSION: invite, and a session reaches what the agent reaches. Read the security model before deploying it on a shared network.

Docker Compose

Add the agent to the stack you want to reach. It joins the stack's network by itself:

• The Docker socket is required: the agent creates your -s name as a small signpost container. It is root on the host; mount it only on a host you trust. Without it the agent does not start.
• With PLUG_ADMISSION: invite, mount the plug-members volume the comment shows, or the agent does not start.
• The port (2222 here) is a convention: publish any, and give it to the profile.

Docker Swarm

The same service, deployed with the stack (docker stack deploy). Two differences:

• The signpost is a Swarm service, so the agent runs on a manager, as one replica (the deploy: block above). The signpost joins the stack's overlay whether or not it is attachable.
• With PLUG_ADMISSION: invite, the agent keeps its members in a Swarm config by itself: nothing to mount.

Through the routing mesh the agent answers on any node's address. Details: Docker, Compose and Swarm.

Kubernetes

Apply the manifest in the namespace where the services you work on live:

kubectl -n my-namespace apply -f plug-k8s.yaml

• No socket: a namespace-scoped Role lets the agent create a Service for your name, repoint one it takes over, and read a workload's environment and volumes. Each rule and its reason: Kubernetes and OpenShift.
• Reach it on the NodePort the manifest publishes (32222), or with no exposed port, through the API server and each developer's own kubeconfig:

  kubectl -n my-namespace port-forward svc/plug 2222:2222

  content_copy
• Re-apply the manifest when you upgrade the agent: plug update moves the image, not the Role, and plug doctor names any rule a newer agent is missing.

OpenShift and OKD

The same manifest and the same Role, admitted by the default restricted-v2 SCC with nothing to grant: the agent runs as the uid the cluster picks, never root, and asks for no capability. CI runs it on MicroShift built from OKD, installs plug from it and opens sessions through it. Details: OpenShift and OKD.

One agent for several stacks

On Docker or Swarm, a single agent can cover several stacks: deploy deploy/plug-stack.yml and list their networks. The networks it is attached to are exactly what sessions reach.

curl -fsSLO https://raw.githubusercontent.com/softwarity/plug/main/deploy/plug-stack.yml
# edit the networks: section, then:
docker stack deploy -c plug-stack.yml plug

The CLI, on each machine

From the cluster, in one line: the agent serves the binary for your system. The install grants plug its privilege once; no later run needs it.

Linux and macOS:

ssh -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null get@<cluster-host> install | sh

Windows, from Git Bash (it ships with Git for Windows):

cluster=<cluster-host>
ssh -n -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null get@$cluster install-windows \
  | bash -s -- $cluster 2222

The install does not check the agent's host key; plug pins it on the first connection after. The binaries are signed, and plug verifies the signature before granting itself privilege (security model). Then run your first command: Getting started.