Advanced

Plugin Operation Details

Primary (Core) Operations

This operation queries all the running instances: - inst_describe_init - return all running instances (this is used only when a new model is loaded, to gather the current application state)

These operations create and destroy individual component instances:

  • inst_create - create new instances of a component. Arguments: { selector : "new" }
  • inst_destroy - tear down running instances of a component. Arguments: { selector : "(new|old)" }. Use "old" on the normal forward path in an upgrade plan, when the old instance should be torn down. "new" should be used in steps on failure recovery path, to remove new instances that failed.

For environments that natively support the notion of a multi-instance service (e.g., Docker Swarm service), there is an alternate set of instance management operations:

  • inst_deploy_all_async - initiate deploy (create or upgrade) of all instances of a component.
  • inst_scale_all_async - scale number of instances (replicas) of a component, without changing the subset of instances that remain running.
  • inst_rollback_all_async - rollback a changed component to a prior specification for all of its instances (incl. # replicas, image, settings, etc.)
  • inst_wait_all_updated - waits until a xxx_async operation completes and return the full set of instances. Use selector to direct the instances to new or old groups, respectively.
  • inst_destroy_all - destroy all instances of a component (synchronous, no need to call inst_wait_all_updated)

Calling plugins as application components

In addition, as some environments can restrict network access to private (non-exposed) application instances, the core plugins may provide operations for executing plugins in the context of an application:

  • call_plugin - call a Skopos plugin as part of the application (usually, as a container or VM). The container image is provided explicitly, allowing for user-defined plugins (for built-in plugins, see the next operation).
  • call_builtin_plugin - call a built-in Skopos plugin (e.g., http) as part of the application using the Skopos existing container (no external container image specification is required for that plugin)

These operations pass all parameters to the plugin being called except a set plugin_xxx parameters that define the plugin to call: plugin_action, plugin_image, plugin_network, plugin_timeout, plugin_logfile, plugin_name (built-in only)

Service Discovery Operations

  • sd_attach - register a component instance with service discovery (so that other components can access it). (NOTE: new instances may be created in attached state; this operation should do nothing and return success if an instance is already registered). This operation may be asynchronous and only initiate the registration, returning before the instance is actually visible via service discovery. See sd_wait_join below. Arguments: { selector : "new|old" }. The selector specifies whether the operation is applied to new instances (e.g., during deploy or upgrade) or to old instances (e.g., to re-connect an old instance as part of a rollback, if an upgrade fails).
  • sd_detach - remove an instance from service discovery. As with sd_attach, this should do nothing and return success if the instance is not registered. Arguments: same as for sd_attach.
  • sd_wait_join - wait for an instance to be registered. This operation may do nothing if registration with sd_attach is completed synchronously. Otherwise, it blocks until the instance registration has completed. The wait is always limited by a timeout. All plugins that support the service discovery operations allow configuring this timeout. Arguments: same as for sd_attach.

Load Balancer Operations

  • lb_attach - connect a component instance to an external gateway (load balancer), making it possible for it to receive requests forwarded by the load balancer. This operation may be asynchronous and return before the load balancer has actually changed state and began forwarding requests to the new instance. See lb_wait_join below. Arguments: { target : "*lb_name*", selector : "new|old" }. The target argument gives the symbolic name of the load balancer to connnect to. This name is mapped to an actual load balancer by using the data in the plugin configuration (as described in the configuration section for each plugin that supports LB operations). A single application can have more than one load balancer defined.
  • lb_detach - remove a component instance from the distribution list of an external gateway, so it no longer receives new requests. Any pending requests should be allowed to complete and not be distrupted by this operation. Arguments: same as for lb_attach.
  • lb_wait_join - wait for a the load balancer to complete the process of connecting a new instance. This operation should block until the load balancer's state has changed to enable forwarding requests to the specific instance (i.e., the instance should have passed any checks performed by the load balancer and appear as "healthy" on its list of targets). The wait is always limited by a configurable timeout (the operation fails if the timeout expires). Arguments: same as for lb_attach.

Extended Operations - docker and docker-swarm Plugins

(WIP, detailed descriptions to be added)

The 'docker' plugin supports the following additional operations: image_pull, image_check, inst_stop, inst_start, inst_attach, inst_detach (?are these used?), inst_signal, comp_signal, network_create

network_create

Create an application-scope network. The network is named {}_default, where {} is replaced with the project name. It creates a Docker bridge network for use by the application. NOTE it is possible to create a network for the application without using the plugin (e.g., with the 'docker network' CLI command). If the network already exists, network_create will do nothing.

image_check

This operation verifies whether a given image exists and is accessible to Skopos.

Using Plugins in a Plan

Plugins are used in all plan steps that involve an action on the deployment environment (Skopos communicates with the environment only via plugins). These steps are called 'actions' and look like this in the plan description:

        class: action
        plugin: ec2-asg
        action: inst_create
        arguments: { selector : "new" }

All of the keys are required. Any action that operates on instances must have the selector argument, specifying either "new" (perform the action on the "new" set of instances, e.g., those that are being created and configured during an upgrade), or "old" (perform the action on the instances being replaced during upgrade). Some of the plugin actions require additional arguments, these are documented in the detail sections below.

Note the plugin steps do not (and need not) specify component class they are working on. They are always found in a "component group" in the plan and the group defines which type of component this is and the engine keeps track of all instances of this component that exist and passes them on to the plugins as needed.

The script plugins have a simpler step format:

        class: action
        exec: [ "log", "some text to log" ]

Or, if the script arguments do not have spaces in them, this form is also accepted:

        class: action
        exec: log SaveThis!

Unlike the regular plugins, scripts do not automatically receive any state information from the engine, such as the component instance being currently worked on. It can be passed explicitly using a substitution, like this:

        class: action
        exec: [ "log", "just created {{.new}}" ]