Skip to main content
Consul Services provides service discovery and health monitoring for your microservices architecture. Register services, manage instances, and organize with tags and metadata.

​
Key Concepts

Service Discovery

Services register themselves and can be discovered by name, enabling dynamic configuration.

Multiple Instances

Each service can have multiple instances running on different addresses and ports.

Tags

Categorize and filter services using tags (e.g., production, v2, primary).

Metadata

Attach key-value metadata for configuration, versioning, or custom attributes.

​
Required Permissions

ActionPermission
View servicesiam:project:cicd:consul:read
Register/Update servicesiam:project:cicd:consul:write
Delete servicesiam:project:cicd:consul:delete

​
Service vs Instance

TermDescription
ServiceLogical name for a capability (e.g., api, web, database)
InstanceA running copy of the service at a specific address:port
One service can have many instances. For example, an api service might have 3 instances running on different servers for load balancing.

​
How to Register a Service

1

Select Consul Instance

Choose the target Consul cluster from the dropdown.
2

Click Register Service

Click the Register Service button.
3

Enter Service Details

  • Service Name (required): Logical name (e.g., my-api)
  • Service ID (required): Unique instance identifier
  • Address (required): IP address or hostname
  • Port (required): Port number (1-65535)
4

Add Tags (Optional)

Type a tag and press Enter or click + to add. Tags help with filtering and routing.
5

Add Metadata (Optional)

Click Add to create key-value pairs for custom metadata.
6

Register

Click Register Service to complete registration.

​
How to View Service Instances

1

Find the Service

Locate the service in the table using search or scrolling.
2

Expand the Row

Click the chevron (arrow) on the left to expand the service row.
3

View Instances

Each instance shows its ID, address, port, and associated tags.

​
How to Add an Instance to Existing Service

1

Find the Service

Locate the service in the table.
2

Open Actions Menu

Click the three-dot menu on the service row.
3

Select Add Instance

Click Add Instance. The drawer opens with the service name pre-filled.
4

Enter Instance Details

Provide unique ID, address, port, and optionally tags/metadata.
5

Register

Click Register Service to add the new instance.

​
How to Duplicate an Instance

Create a copy of an existing instance with the same configuration.
1

Expand the Service

Click the chevron to show instances.
2

Find the Instance

Locate the instance card you want to duplicate.
3

Open Actions Menu

Click the three-dot menu on the instance card.
4

Select Duplicate

Click Duplicate. The drawer opens with pre-filled values.
5

Modify and Register

Change the ID (auto-appended with -copy) and any other values, then register.
Duplicating is useful for quickly scaling a service by creating similar instances with different addresses or ports.

​
How to Delete a Service Instance

1

Expand the Service

Show instances by clicking the chevron.
2

Find the Instance

Locate the instance card to delete.
3

Open Actions Menu

Click the three-dot menu.
4

Select Delete

Click Delete and confirm the action.

​
How to Delete an Entire Service

Deleting a service removes all its instances.
1

Find the Service

Locate the service in the table.
2

Open Actions Menu

Click the three-dot menu on the service row.
3

Select Delete Service

Click Delete Service.
4

Confirm

Confirm the deletion. All instances are deregistered.
Deleting a service deregisters all instances. This may impact applications depending on service discovery.

​
Bulk Operations

Select multiple instances for bulk operations.

​
Selecting Instances

  1. Expand a service to show instances
  2. Check individual instance checkboxes, or
  3. Use the Select All checkbox to select all instances of a service

​
Available Bulk Actions

When instances are selected, a floating action bar appears:
ActionDescription
Add TagsAdd tags to all selected instances
Add MetaAdd metadata key-value pairs to all selected instances
ExportDownload selected instances as JSON
ClearDeselect all instances

​
Tags Best Practices

Use tags for: 
environment: production, staging, development
version: v1, v2, v3
role: primary, replica, backup
region: us-east, eu-west, ap-south
canary: true (for canary deployments)
Tags enable:
  • Filtering in the UI
  • Service mesh routing rules
  • DNS-based service discovery

​
Metadata Best Practices

Use metadata for: 
{
  "version": "2.1.0",
  "git_sha": "abc123",
  "owner": "platform-team",
  "docs": "https://wiki.example.com/api"
}
Metadata is useful for:
  • Version tracking
  • Ownership information
  • Documentation links
  • Custom configuration

​
Troubleshooting

  • Refresh the page or click the refresh button
  • Verify the correct Consul instance is selected
  • Check that the service was registered successfully
  • Confirm network connectivity to Consul
  • You need write permission for Consul services
  • Verify port is a valid number (1-65535)
  • Service name is required
  • Check Consul instance is healthy
  • The service may have no registered instances
  • Instances may have been deregistered
  • Check network connectivity
  • Try refreshing the page
  • You need delete permission for Consul services
  • The operation may be in progress
  • Some instances may fail to deregister
  • Ensure you press Enter or click + after typing each tag
  • Tags cannot be empty strings
  • Check for duplicate tags (they’re ignored)

​
FAQ

Service Name is the logical name shared by all instances (e.g., api). Service ID is a unique identifier for each specific instance (e.g., api-server-1, api-server-2). Multiple instances share the same service name but have different IDs.
Consul doesn’t support in-place editing. To modify an instance, delete it and re-register with the new configuration, or use the duplicate feature as a starting point.
The instance is deregistered from Consul immediately. Applications using service discovery will no longer route traffic to that instance. Health checks for that instance are also removed.
Health checks are configured separately in Consul. This UI shows services and their registration status. For health check configuration, use Consul directly or configure checks when deploying services.
Yes. Each Consul instance (datacenter) has its own service catalog. Register services in each datacenter where they run. Cross-datacenter discovery requires Consul federation.
The address is the IP or hostname where the service instance is reachable. If left empty, Consul uses the agent’s address. For containers, use the container’s IP or the host’s IP with appropriate port mapping.