agent

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 18, 2024 License: AGPL-3.0 Imports: 33 Imported by: 0

README

Viam Agent

A self-updating service manager that maintains the lifecycle for viam-server (as built from RDK) and other Viam provided system services.

Requirements

Currently, viam-agent is only supported on Linux, for amd64 (x86_64) and arm64 (aarch64) CPUs.

Installation

Your system will need to have curl available.

Automatic

The smart machine config /etc/viam.json can be installed automatically if you have an API key and part ID available. Modify the following command by inserting your actual details. (Be sure to remove the surrounding < > characters of the placeholders.)

sudo /bin/sh -c "VIAM_API_KEY_ID=<KEYID> VIAM_API_KEY=<KEY> VIAM_PART_ID=<PARTID>; $(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)"
Manual configuration

Make sure you've already installed your robot's configuration file to /etc/viam.json then run the following:

sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)"

Provisioning and Networking

The current version of viam-agent includes a device provisioning subsystem that can help set up wifi and smart machine configs. For more info, see the Provisioning Subsystem

Management

Viam Agent will install itself as a systemd service named viam-agent. Start/stop/restart it with systemctl
Ex: sudo systemctl restart viam-agent

Notes

The agent will automatically update both itself and viam-server. However, it is up to the user to restart the service to use the new version.
For the agent itself restart the service (per the management command above) or reboot. Note this will restart viam-server as well.
viam-server may be restarted via the normal "restart" button in the cloud App, or as part of the full agent restart per above.

Uninstall

To remove the agent and all viam configuration completely, run the following script.

sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/uninstall.sh)"

Configuration

Configuration is maintained via the "agent" section of the device's config in the viam App. Below is an example config section:

{
  "agent": {
    "viam-agent": {
      "release_channel": "stable",
      "pin_version": "1.2.3",
      "pin_url": "http://example/test.binary",
      "disable_subsystem": false
    },
    "viam-server": {
      "attributes": {
        "fast_start": true
      }
    },
    "agent-provisioning": {
      "release_channel": "stable"
    },
    "agent-syscfg": {
      "release_channel": "stable"
    }
  }
}

Above there are (currently) four subsystems, viam-agent (the main agent program itself), viam-server (the core of the robot/device), agent-provisioning (provides early setup and network management. Provisioning Details ), and agent-syscfg (provides various OS/system configuration tweaks Syscfg Details)

Each section primarily controls updates for that subsystem, using one of three settings, pin_url (highest priority), pin_version (checked/used only if pin_url is unset or empty), and release_channel (used by default, and defaults to stable, but only if pin_url and pin_version are both unset.) The example above gives all three for visual clarity, but is not actually needed. In this case, only pin_url would be used.

For release channel, "stable" generally means semantically versioned releases that are tested before release, and are relatively infrequent, but will automatically upgrade when a new version is released. Using pin_version allows one to "lock" the subsystem to an explcit version (as provided by the release channel) no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel.) Lastly, pin_url can be used to point to a specific binary. Typically this is only used for testing/troubleshooting.

The disable_subsystem setting can be set to true if you don't wish to use/start a particular subsystem.

Note that only sections/settings you explicitly want to modify need to be included in the config. By default, all subsystems will use the stable release channel, so no configuration at all is needed to get that behavior. E.g. in the example above, viam-server will still get stable releases, as none of the update-related values are being modified, but it will ALSO use the fast_start behavior detailed below. For another example, the agent-provisioning or agent-syscfg sections could be left out entirely, and the device will use a default config for those subsystems anyway. To actually disable one, the section can be added, and disable_subsystem to to true

FastStart Mode

This bypasses the normal network/online wait and update checks during inital startup, and executes viam-server as quickly as possible. Useful if you have a device that often starts when offline or on a slow connection, and having the latest version immediately after start isn't required. Note that normal, periodic update checks will continue to run afterwards. This only affects initial startup sequencing.

To use it, set "fast_start": true in the attributes for the viam-server subsystem. Alternately, set VIAM_AGENT_FASTSTART=1 in your environment.

Development

Makefile Targets
  • make will build a viam-agent for your current CPU architecture. Note that as only linux is supported, this will be a linux binary.
  • make arm64 arm64 specific build.
  • make amd64 amd64 specific.
  • make all will build for all (both) supported architectures.
  • make lint to lint.
Version Tagging

The makefile will attempt to get a tagged version from Git. If you want to manually force a version, set TAG_VERSION=0.1.2 in the make command.
Note that there is no "v" in the actual version, though it is expected in git. E.g. a git tag of v0.1.2 becomes TAG_VERSION=0.1.2
Ex: make all TAG_VERSION=0.1.2

DevMode

Setting the environment variable VIAM_AGENT_DEVMODE=1 will skip the self-location check for the binary, so you can run it directly during development, without installing to /opt/viam.

Documentation

Overview

Package agent contains the public interfaces, functions, consts, and vars for the viam-server agent.

Index

Constants

View Source 
const (
	ShortFailTime   = time.Second * 30
	StartTimeout    = time.Minute
	StopTermTimeout = time.Second * 30
	StopKillTimeout = time.Second * 10
)
View Source 
const (
	SubsystemName = "viam-agent"
)

Variables

View Source 
var ErrSubsystemDisabled = errors.New("subsystem disabled")
View Source 
var ViamDirs = map[string]string{"viam": "/opt/viam"}

Functions

func CheckIfSame 

func CheckIfSame(path1, path2 string) (bool, error)

func DecompressFile 

func DecompressFile(inPath string) (outPath string, errRet error)

DecompressFile extracts a compressed file and returns the path to the extracted file.

func DownloadFile 

func DownloadFile(ctx context.Context, rawURL string) (outPath string, errRet error)

DownloadFile downloads a file into the cache directory and returns a path to the file. 

func ForceSymlink(orig, symlink string) error

func GetFileSum 

func GetFileSum(filepath string) (outSum []byte, errRet error)

func InitPaths added in v0.1.4 

func InitPaths() error

func SyncFS added in v0.3.0 

func SyncFS(syncPath string) (errRet error)

Types

type AgentSubsystem 

type AgentSubsystem struct {
	CacheData *CacheData
	// contains filtered or unexported fields
}

AgentSubsystem is a wrapper for the real subsystems, mostly allowing sharing of download/update code.

func NewAgentSubsystem 

func NewAgentSubsystem(
	ctx context.Context,
	name string,
	logger logging.Logger,
	subsys BasicSubsystem,
) (*AgentSubsystem, error)

NewAgentSubsystem returns a new wrapped subsystem.

func (*AgentSubsystem) HealthCheck 

func (s *AgentSubsystem) HealthCheck(ctx context.Context) error

HealthCheck calls the inner subsystem's HealthCheck() to verify, and logs failures/successes.

func (*AgentSubsystem) LoadCache 

func (s *AgentSubsystem) LoadCache() error

LoadCache loads the cached data for the subsystem from disk.

func (*AgentSubsystem) SaveCache 

func (s *AgentSubsystem) SaveCache() error

SaveCache saves the cached data to disk.

func (*AgentSubsystem) Start 

func (s *AgentSubsystem) Start(ctx context.Context) error

Start starts the subsystem.

func (*AgentSubsystem) Stop 

func (s *AgentSubsystem) Stop(ctx context.Context) error

Stop stops the subsystem.

func (*AgentSubsystem) Update 

func (s *AgentSubsystem) Update(ctx context.Context, cfg *pb.DeviceSubsystemConfig) (bool, error)

Update is the main function of the AgentSubsystem wrapper, as it's shared between subsystems. Returns true if a restart is needed.

func (*AgentSubsystem) Version 

func (s *AgentSubsystem) Version() string

Version returns the running version.

type BasicSubsystem 

type BasicSubsystem interface {
	// Start runs the subsystem
	Start(ctx context.Context) error

	// Stop signals the subsystem to shutdown
	Stop(ctx context.Context) error

	// HealthCheck reports if a subsystem is running correctly (it is restarted if not)
	HealthCheck(ctx context.Context) error
}

BasicSubsystem is the minimal interface.

type CacheData 

type CacheData struct {
	CurrentVersion  string                  `json:"current_version"`
	PreviousVersion string                  `json:"previous_version"`
	Versions        map[string]*VersionInfo `json:"versions"`
}

CacheData stores VersionInfo and the current/previous versions for (TODO) rollback.

type InternalSubsystem added in v0.2.0 

type InternalSubsystem struct {
	// contains filtered or unexported fields
}

InternalSubsystem is shared start/stop/update code between "internal" (not viam-server) subsystems.

func NewInternalSubsystem added in v0.2.0 

func NewInternalSubsystem(name string, extraArgs []string, logger logging.Logger, uploadAll bool) (*InternalSubsystem, error)

func (*InternalSubsystem) HealthCheck added in v0.2.0 

func (is *InternalSubsystem) HealthCheck(ctx context.Context) (errRet error)

HealthCheck sends a USR1 signal to the subsystem process, which should cause it to log "HEALTHY" to stdout.

func (*InternalSubsystem) Start added in v0.2.0 

func (is *InternalSubsystem) Start(ctx context.Context) error

func (*InternalSubsystem) Stop added in v0.2.0 

func (is *InternalSubsystem) Stop(ctx context.Context) error

func (*InternalSubsystem) Update added in v0.2.0 

func (is *InternalSubsystem) Update(ctx context.Context, cfg *pb.DeviceSubsystemConfig, newVersion bool) (bool, error)

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager is the core of the agent process, and maintains the list of subsystems, as well as cloud connection.

func NewManager 

func NewManager(ctx context.Context, logger logging.Logger) (*Manager, error)

NewManager returns a new Manager.

func (*Manager) CheckUpdates 

func (m *Manager) CheckUpdates(ctx context.Context) time.Duration

CheckUpdates retrieves an updated config from the cloud, and then passes it to SubsystemUpdates().

func (*Manager) CloseAll 

func (m *Manager) CloseAll()

CloseAll stops all subsystems and closes the cloud connection.

func (*Manager) CreateNetAppender added in v0.4.0 

func (m *Manager) CreateNetAppender() (*logging.NetAppender, error)

CreateNetAppender creates or replaces m.netAppender. Must be called after config is loaded.

func (*Manager) GetConfig 

func (m *Manager) GetConfig(ctx context.Context) (map[string]*pb.DeviceSubsystemConfig, time.Duration, error)

GetConfig retrieves the configuration from the cloud, or returns a cached version if unable to communicate.

func (*Manager) LoadConfig added in v0.1.0 

func (m *Manager) LoadConfig(cfgPath string) error

func (*Manager) LoadSubsystems 

func (m *Manager) LoadSubsystems(ctx context.Context) error

LoadSubsystems runs at startup, before getting online.

func (*Manager) SelfUpdate 

func (m *Manager) SelfUpdate(ctx context.Context) (bool, error)

SelfUpdate is called early in startup to update the viam-agent subsystem before any other work is started.

func (*Manager) StartBackgroundChecks 

func (m *Manager) StartBackgroundChecks(ctx context.Context)

StartBackgroundChecks kicks off a go routine that loops on a timer to check for updates and health checks.

func (*Manager) StartSubsystem added in v0.1.0 

func (m *Manager) StartSubsystem(ctx context.Context, name string) error

StartSubsystem may be called early in startup when no cloud connectivity is configured.

func (*Manager) SubsystemHealthChecks 

func (m *Manager) SubsystemHealthChecks(ctx context.Context)

SubsystemHealthChecks makes sure all subsystems are responding, and restarts them if not.

func (*Manager) SubsystemUpdates 

func (m *Manager) SubsystemUpdates(ctx context.Context, cfg map[string]*pb.DeviceSubsystemConfig)

SubsystemUpdates checks for updates to configured subsystems and restarts them as needed.

type MatchingLogger added in v0.1.0 

type MatchingLogger struct {
	// contains filtered or unexported fields
}

MatchingLogger provides a logger that also allows sending regex matched lines to a channel.

func NewMatchingLogger added in v0.1.0 

func NewMatchingLogger(logger logging.Logger, isError, uploadAll bool) *MatchingLogger

NewMatchingLogger returns a MatchingLogger.

func (*MatchingLogger) AddMatcher added in v0.1.0 

func (l *MatchingLogger) AddMatcher(name string, regex *regexp.Regexp, mask bool) (<-chan []string, error)

AddMatcher adds a named regex to filter from results and return to a channel, optionally masking it from normal logging.

func (*MatchingLogger) DeleteMatcher added in v0.1.0 

func (l *MatchingLogger) DeleteMatcher(name string)

DeleteMatcher removes a previously added matcher.

func (*MatchingLogger) Write added in v0.1.0 

func (l *MatchingLogger) Write(p []byte) (int, error)

Write takes input and filters it against each defined matcher, before logging it.

type VersionInfo 

type VersionInfo struct {
	Version        string
	URL            string
	DlPath         string
	DlSHA          []byte
	UnpackedPath   string
	UnpackedSHA    []byte
	SymlinkPath    string
	Installed      time.Time
	StartCount     uint
	LongFailCount  uint
	ShortFailCount uint
}

VersionInfo records details about each version of a subsystem.

Source Files

View all Source files

Directories

Path Synopsis
cmd
viam-agent
Package subsystems defines the subsystem interface.
 Package subsystems defines the subsystem interface.
provisioning
Package provisioning contains the provisioning agent subsystem.
 Package provisioning contains the provisioning agent subsystem.
registry
Package registry is used to register subsystems from other packages.
 Package registry is used to register subsystems from other packages.
syscfg
Package syscfg contains the system configuration agent subsystem.
 Package syscfg contains the system configuration agent subsystem.
viamagent
Package viamagent is the subsystem for the viam-agent itself.
 Package viamagent is the subsystem for the viam-agent itself.
viamserver
Package viamserver contains the viam-server agent subsystem.
 Package viamserver contains the viam-server agent subsystem.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.