Agent configuration syntax reference

This topic provides reference information for the HCP Waypoint agent configuration syntax.

Introduction

HCP Waypoint agents let you execute actions inside private environments. Refer to create and manage agents for more information.

Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements for the HCP Waypoint agent configuration.

• group: map
  • action: map
    • run: map
      • command: string or array of strings
      • docker: map
    • http: map
      • url: string
    • operation: map

Complete configuration

group "<group name>" {
  action "<action name>" {
    run {
      command = <command to execute>
    }
  }

  action "<action name>" {
    http {
      url = <URL to send the request to>
    }
  }

  action "<action name>" {
    operation {
      status {
        message = <log message>
        values = { <key>: <value> }
        status = "running|complete|error"
      }
    }
    

    operation {
      run {
        command = <command to execute>
      }
    }

    operation {
      http {
        url = <URL to send the request to>
      }
    }
  }
}

Specification

This section provides details about the HCP Waypoint agent configuration syntax.

group

A group block can contain multiple action blocks.

action

An action block must contain only one of the following: a single run block, a single http block, or one or more operation blocks.

run

A run block defines a command or script that the action executes.

The command field may be a string or an array of strings. As an array of strings, the agent executes the command field as a single command. The follow example defines an action that runs the command echo hello world:

command = ["echo", "hello", "world"]

docker

If you define an optional docker block, the agent runs the command in the run block inside a docker container.

http

An http block defines an HTTP GET request for the action to make.

operation

An operation block can only contain a single run or http block.

status

A status block sends log information to HCP Waypoint. HCP Waypoint records and displays this information in an action's run output summary.

Example

The following is an example configuration file for an agent group called my-agent-group and it defines two actions:

1. The promote-to-staging action runs a local script named promote.sh.
2. The rollback action sends an HTTP GET request to the address defined in the url parameter.

group "my-agent-group" {
  action "promote-to-staging" {
    run {
      command = "./promote.sh"
    }
  }

  action "rollback" {
    http {
      url = "http://127.0.0.1/deployment/rollback"
    }
  }

  action "rollback-k8s-status" {
    operation {
      status {
        message = "Beginning rollback"
        values = { "target-rev": inputs.revision }
        status = "running"
      }
    }

    operation {
      run = ["kubectl", "rollout", "undo", "deployment/web",
             "--to-revision=#{inputs.revision}"]
    }

    operation {
      status {
        message = "Rollback completed"
        status = run.exit_code == 0 ? "complete" : "error"
      }
    }
  }
}