consul services register: Register a Service in CI
consul services register tells the local agent about a service so it appears in the catalog and DNS.
After a deploy step starts a process, registering it with Consul makes it discoverable. The command takes either flags or an HCL/JSON definition file.
What it does
consul services register submits a service definition to the local agent. The agent then advertises the service in the catalog, answers DNS for it, and runs any health checks in the definition. Services registered this way live as long as the agent (or until deregistered).
Common usage
# from a definition file
consul services register web.hcl
# inline via flags
consul services register \
-name=web -port=8080 -tag=v2 -address=10.0.0.5Options
| Flag | What it does |
|---|---|
| <file> | Path to an HCL or JSON service definition |
| -name <name> | Service name (when not using a file) |
| -id <id> | Unique service ID (defaults to name) |
| -port <n> | Service port |
| -address <addr> | Service address advertised in the catalog |
| -tag <tag> | Repeatable tag for filtering and routing |
| -meta <k>=<v> | Repeatable service metadata |
In CI
Registering with the local agent (this command) is the agent pattern; it deregisters cleanly with consul services deregister -id=web. For a service the agent does not run locally, prefer the agent config or the catalog API instead.
Common errors in CI
"Cannot specify both -id and a service definition file" means you mixed flags with a file argument. "Invalid service definition: ... 1 error occurred" with "service name is required" means the file is missing the name field. "Unexpected response code: 403 (Permission denied)" means the token lacks service:write for that name.