Agents
OpsChain agents perform long-running tasks, in contrast to changes and workflow runs which are short-lived.
An agent runs as a Kubernetes pod on the same cluster that hosts OpsChain. Agents can be stopped to free up cluster resources and restarted later, and OpsChain provides access to each agent's logs and audit history through the GUI.
The agents table
Each row includes:
| Column | Description |
|---|---|
| Name | The name of the agent. |
| Code | The agent's unique code. |
| Status | Running, Running (outdated), Stopping, Stopped or Failed. Error is shown for any other state reported for the agent, and Unknown when no status has been reported. |
| Template & version | The agent template and the template version the agent uses. |
| Description | A short summary or purpose of the agent. |
| Archived | Indicates the archival status of the agent. |
| Buttons & links | Function |
|---|---|
| Bulk actions | Archive or restore the selected agents. |
| Search | Filter the contents of the table by the text you type. |
| Include archived | List archived agents alongside active ones. |
| Columns | Hide or display columns in the table. |
| CSV | Download the agents as a CSV file. Archived agents are included only when Include archived is ticked; the search is not applied. |
| Create agent | Add a new agent to the project. |
The Linked agents tab of an agent template version lists agents in a table with a Parent column, giving the project and agent codes, in place of Status and Template & version.
Where an agent runs
Each agent runs at one site. The agent's overview names it in a Site pill, and the agents table shows an agent that is running at another site as running, the same as one running here.
An agent's own logs are held in the database, so they are readable from any site. Its debug logs are the Kubernetes events of its pod, so they can only be read at the site whose Kubernetes holds it — open the agent from that site's GUI to see them. An agent that is stopped, or whose image has not been built yet, has no pod and so no debug logs, and the Debug logs tab under Logs says so. The Active image SHA of an agent hosted at another site is the image the agent was started with rather than a reading of the running pod, and its tooltip says so.
When an agent's container fails
If Kubernetes ends an agent's container for good, for example by evicting its pod when the node runs low on disk space, or the container disappears, the site running the agent notices within a minute. It stops the agent, and every site then shows the agent as Failed with the reason. An api:agent:failed event records the failure. OpsChain does not restart a failed agent on its own. Start it to run it again.
An agent that no node has room for shows as Unschedulable.
Agent templates
OpsChain agents are based on templates that reference a Git remote. An agent template is created by selecting the relevant Git remote and supplying a code and a name. The agent code allows a single Git repository to contain the code for multiple agents.
Promoting an agent to a new template version
Once an agent has been created, its template cannot be changed. To alter the agent's configuration, either update the agent's properties or create a new version of the existing agent template and assign it to the desired agent.
Agent images
The container image used by an agent is built from the Git repository and commit referenced by the agent template version, using a custom Dockerfile from that repository if one is present - see custom Dockerfile locations.
An agent's image can be rebuilt manually as needed (for example after fixing a failure, or to pick up the latest layers from a non-idempotent build step).
Agent images live in the image registry of the site that built them. When you start an agent, OpsChain checks that its image is in the registry of the site handling the start, rather than assuming a past successful build is enough — an image can be removed by an agent image cleanup, and in a high availability deployment it may have been built at a different site.
If the image is not there, OpsChain builds it and automatically starts the agent once that build finishes.
An agent image built by an OpsChain version whose logs went through the log aggregator cannot send its log output to the current version, which receives it directly (see log ingestion). OpsChain refuses to start an agent whose only image was built by an earlier version, and shows an agent still running on such an image as Running (outdated). Rebuild the agent's image, then start it again.
Interacting with agents
An agent's page has these tabs, as well as Audit history, Properties and Settings:
| Tab | Function |
|---|---|
| Overview | The agent's details and current status, including its site and image. |
| Logs | Agent logs shows the agent's own log output. Debug logs shows the Kubernetes events of its pod - see where an agent runs. |
| Lifecycle events | Each build of the agent's image and each start and stop of the agent, with who requested it, its status and its log. Filter the list by event type with Filter events. A build whose image was removed by data cleanup is marked Image removed, and the build the agent is running is marked Currently in use. |
Selecting a successful build that is not in use shows Start agent with this image while the agent is stopped, or Restart agent with this image while it is running, so you can return the agent to an earlier image. This needs permission to update the agent.
From the agent details page you can:
- start and stop the agent (stopping removes the pod and frees its cluster resources; restarting recreates it)
- view the agent's logs
- view the agent's audit history
- rebuild the agent's container image
Starting, stopping and rebuilding need permission to update the agent. Without it, those buttons are disabled.
Creating your own agents
See our agent development guide for a walkthrough of building your own agent templates from scratch.