Formic

Overview

This is a library to support building IT automation tools in Swift, taking a lot of inspiration from existing and past IT automation tools. This library is intended to support building CLI executables with swift-argument-parser, or other dedicated tooling for managing remote system. If you’ve just stumbled into this project, it isn’t intended to be a full-bore replacement for any existing tools commonly used for DevOps/SRE/IT Automation. Quite a bit is inspired by Ansible, with a goal of building pre-set sequences of tasks that do useful operational work. For more information on the project, see Package Goals and Architecture.

To use formic, create an instance of Engine, handing it a configured logger if you want to see informational or detailed about while commands are executed, and use Engine/run(host:displayProgress:verbosity:commands:) or Engine/run(hosts:displayProgress:verbosity:commands:) to run commands on those hosts. Formic works with the idea of running a set of commands against a single host, or all of those same commands against a set of hosts. A Host in formic holds the collection of network address as well as credentials needed to access the host.

var logger = Logger(label: "updateExample")
logger.logLevel = .info 
// use `.trace` for detailed output of raw commands invoked as well 
// as the standard output and standard error returned from commands.

let engine = Engine(logger: logger)

guard let hostAddress = Host.NetworkAddress(hostname) else {
    fatalError("Unable to parse the provided host address: \(hostname)")
}
let targetHost: Host = try Host(hostAddress, 
                                sshPort: port, 
                                sshUser: user, 
                                sshIdentityFile: privateKeyLocation)

// environment variables to use while invoking commands on the remote host
let debUnattended = ["DEBIAN_FRONTEND": "noninteractive", 
                     "DEBCONF_NONINTERACTIVE_SEEN": "true"]

try await engine.run(
    host: targetHost, displayProgress: true, verbosity: verbosity,
    commands: [
        // Apply all current upgrades available
        ShellCommand("sudo apt-get update -q", env: debUnattended),
        ShellCommand("sudo apt-get upgrade -y -qq", env: debUnattended),
    ])

For a more fleshed out example, review the example source for the updateExample CLI executable.

Running Playbooks

• actor Engine

  An engine that runs playbooks and exposes the results.

• struct CommandExecutionResult

  The result of executing a command.

• Verbosity

Commands

• class Host
• protocol Command

  A type that represents a command, run locally or remotely.

• struct CommandOutput

  The structured output of a shell command.

• enum CommandError

  An error that occurs when running a command.

Built-in Commands

• struct ShellCommand

  A command to run on a local or remote host.

• SSHCommand
• struct CopyFrom

  A command to transfer a file from a remote URL into the host.

• struct CopyInto

  A command to transfer a file into the host.

• struct AnyCommand

  A general command that is run against a host.

• struct VerifyAccess

  A command to verify access to a host.

Resources

• struct OperatingSystem

  The kind of operating system.

• struct Dpkg

  A debian package resource.

• protocol Resource

  A type that can be queried from a host to provide information about itself.

• protocol ParsedResource

  A resource that provides an inquiry command and parser to return the state of the resource.

• protocol StatefulResource<DeclarativeStateType>

  A type of resource that can be retrieved and resolved to a desired state using a declaration.

• enum ResourceError

  An error that occurs when running a command.

Resource Parsers

• struct SwarmJoinCommand

  A parser that converts the STDOUT from a swarm init command into a ShellCommand.

Singular Resources

• protocol SingularResource

  A type of resource that exists in singular form on a Host.

Collections of Resources

• protocol CollectionResource

  A collection of resources that can be found and queried from a host.

About Formic

• Package Goals and Architecture

  An overview of how and why this package exists, and what it’s intended to do.

  Read More