Agents installation specification

skabashnyuk commented 7 years ago

agent installation workflow
agent installation API (how client should connect to it, stream and interpret data)

garagatyi commented 7 years ago

Glossary:

WS - workspace

Master - Bootstrapper workflow

Master starts WS.
Master starts Machine and passes needed environment configuration and an object that contains full definition of agents (including install scripts and dependent agents) in order they are supposed to be started. It is up to implementation to decide how binaries of Bootstrapper should be delivered into machine. Agents config file format:
```
[
{
  "id":"exec",      
  "description":"Agent for command execution",
  "version":"1.0",
  "script":"$HOME/che/exec-agent -addr :4412",
  "servers":{
     "execAgent":{
        "port":"4412/tcp",
        "protocol":"http",
        "path":"/exec"
     }
  }
}
]
```
Master adds Machine into lists of machines waiting for status confirmation.
If Machine doesn’t update status that moves it to the next step of booting until timeout expires Master stops machine forcefully and declares that it failed booting. WS start fails too.
Machine starts.
Machine gets Bootstrapper binaries and starts it.
Machine starts Bootstrapper and passes path to agents definition file.
Machine adds Bootstrapper logs into machine logs. It is supposed that logs of this agent should have appropriate prefix, e.g. [Bootstrapper].
Bootstrapper opens WebSocket connection to master and notifies master that it was started.
Bootstrapper starts agents defined by file one-by-one.
Bootstrapper notifies master about states of agents.
Master waits for successful state of all agents in all machines and performs check of ws-agent that its API is responding. If it is not true and ws-agent start timeout expires WS is treated as failed booting and should be forcefully stopped.

Bootstrapper - agents workflow:

Bootstrapper notifies Master that it started
Bootstrapper notifies Master that particular agent starts
Bootstrapper executes agent installation script
Bootstrapper streams agent logs and states to interested sides
Bootstrapper checks agent for installation state:
1. If Agent contains server
  1. Bootstrapper checks connection to socket on local port of machine
  2. If it is successful agent is treated as started
  3. Otherwise check is repeated with some delay.
  4. If agent boot time expires and last check failed agent is treated as failed
2. If Agent contains multiple servers
  1. The same, but Bootstrapper checks all ports
3. If Agent doesn’t contain server
  1. IA waits until installation ends.
  2. If installation script exit code 0 agent is treated as booted.
  3. If installation script exit code differs from 0 agent is treated as failed
  4. If installation doesn’t end when installation time expires agent is treated as failed.
Bootstrapper notifies Master about state of agent

Note:

it is supposed that Bootstrapper will communicate with Master and clients using JSONRPC protocol we started using recently for communication between ws-agent and IDE client.

Bootstrapper events

Bootstrapper is ready to push events. Occurs when bootstrapper is configured to push events on start, it connects to the specified websocket url(workspace master probably) and publishes this event before any other event.

{
"jsonrpc": "2.0",
"method": "bootstrapper/statusChanged",
"params": {
"status": "STARTING",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

Bootstrapping done, everything is started ok.

{
"jsonrpc": "2.0",
"method": "bootstrapper/statusChanged",
"params": {
"status": "DONE",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

Bootstrapping failed(when any agent fails or any error occurs), followed by disconnect and os.Exit(1).

{
"jsonrpc": "2.0",
"method": "bootstrapper/statusChanged",
"params": {
"status": "FAILED",
"error" : "couldn't start agent X",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

Installer events

Bootstrapper starts installer X

{
"jsonrpc": "2.0",
"method": "installer/statusChanged",
"params": {
"status": "STARTING",
"installer": "org.eclipse.che.ws-agent",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

Bootstrapper successfully started installer X(No server defined)

{
"jsonrpc": "2.0",
"method": "installer/statusChanged",
"params": {
"status": "DONE",
"installer": "org.eclipse.che.ws-agent",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

Bootstrapper successfully started installer X(Server defined)

{
"jsonrpc": "2.0",
"method": "installer/statusChanged",
"params": {
"status": "RUNNING",
"installer": "org.eclipse.che.ws-agent",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

Bootstrapper failed to start Installer X

{
"jsonrpc": "2.0",
"method": "installer/statusChanged",
"params": {
"status": "FAILED",
"installer": "org.eclipse.che.my-agent",
"error": "Install script exit code -1",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

Installer X stderr

{
"jsonrpc": "2.0",
"method": "installer/log",
"params": {
"text": "no command found",
"stream": "STDERR",
"installer": "org.eclipse.che.ws-agent",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

Installer X stdout

{
"jsonrpc": "2.0",
"method": "installer/log",
"params": {
"text": "Starting server...",
"stream": "STDOUT",
"installer": "org.eclipse.che.ws-agent",
"machineName": "my-machine",
"runtimeId": {
  "workspaceId": "workspace123",
  "envName": "default",
  "owner": "user123"
},
"time": "2017-02-23T16:22:22.50287146+02:00"
}
}

akorneta commented 7 years ago

Added specification for installer config into 2nd item.

voievodin commented 7 years ago

Changed name Installer to Bootstrapper

TylerJewell commented 7 years ago

Bootstrapper

Tyler : 978-884-5355

On June 12, 2017 at 10:52 GMT, Yevhenii Voevodin notifications@github.com wrote:

Changed name Installer to Bootstraper

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

voievodin commented 7 years ago

Defined bootstrapper events.

voievodin commented 7 years ago

Changed bootstrapper/statusChanged status from READY to STARTING

voievodin commented 7 years ago

Runtime ID format updated from

{
      "workspace": "workspace123",
      "environment": "default",
      "owner": "user123"
}

to

{
      "workspaceId": "workspace123",
      "envName": "default",
      "owner": "user123"
}

eclipse-che / che