Agents

This page explains concepts associated with HCP Waypoint agents.

Background

HCP Waypoint agents allow HCP Waypoint actions to communicate with isolated, private, or on-premises infrastructure. When you deploy and manage agents within your private infrastructure, you can establish a simple connection between your environment and HCP Waypoints. This is useful for actions that need to communicate with isolated or on-premises services and infrastructure.

Agents also allow you to implement more complex, custom logic for your HCP Waypoint actions. Agents can run shell commands, execute scripts and binaries, start Docker containers, and send HTTP requests. For more information on what you can configure an agent action to do, refer to the agent configuration syntax reference.

Workflow

The following steps describe the process of running an agent, configuring an action, and running an action:

1. A platform engineer creates an agent group, a logical collection of agents connected to HCP Waypoint. Refer to create an agent group for instructions on how to complete this process.
2. A platform engineer configures an action in HCP Waypoint. Refer to create an action for instructions on how to complete this process.
3. A platform engineer creates an agent configuration file that includes definitions for each action assigned to the agent group. Refer to the agent configuration syntax reference for the configuration specification.
4. A platform engineer installs the HCP CLI in the environment that they will run the agent in. To install the CLI, refer to the install HCP CLI documentation.
5. A platform engineer authenticates and runs the agent in a secure environment. Refer to authenticate and run the agent for instructions on how to complete this process.
6. A platform engineer assigns the action to one or more HCP Waypoint template or application. Refer to assign an action to a template for instructions on how to complete this process.
7. An application engineer selects a template with an action assignment to create a new application.
8. An application engineer runs the action from the application page. Refer to run an action assigned to an application for instructions on how to complete this process.

Security

Every HCP Waypoint agent must be authenticated with HCP. For information on the different ways you can authenticate the HCP CLI, refer to authenticate and run the agent.

You can also configure a trust relationship between the HCP CLI and HCP to authenticate the agent. For information on how to set up this trust relationship with your OIDC provider, refer to the workload identity federation documentation.

Agents connect and communicate with HCP Waypoint using the gRPC protocol and encrypts all traffic using TLS.

When HCP Waypoint triggers an agent action, it sends all assigned variables to the agent. If your action variables contain any sensitive information, you should consider your agent, and the environment it runs in, just as sensitive.