> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Services

> Service discovery and registration with HashiCorp Consul

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

## Key Concepts

<CardGroup cols={2}>
  <Card title="Service Discovery" icon="magnifying-glass">
    Services register themselves and can be discovered by name, enabling dynamic configuration.
  </Card>

  <Card title="Multiple Instances" icon="server">
    Each service can have multiple instances running on different addresses and ports.
  </Card>

  <Card title="Tags" icon="tags">
    Categorize and filter services using tags (e.g., `production`, `v2`, `primary`).
  </Card>

  <Card title="Metadata" icon="hashtag">
    Attach key-value metadata for configuration, versioning, or custom attributes.
  </Card>
</CardGroup>

## Required Permissions

| Action                   | Permission                       |
| ------------------------ | -------------------------------- |
| View services            | `iam:project:cicd:consul:read`   |
| Register/Update services | `iam:project:cicd:consul:write`  |
| Delete services          | `iam:project:cicd:consul:delete` |

## Service vs Instance

| Term         | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| **Service**  | Logical name for a capability (e.g., `api`, `web`, `database`) |
| **Instance** | A 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

<Steps>
  <Step title="Select Consul Instance">
    Choose the target Consul cluster from the dropdown.
  </Step>

  <Step title="Click Register Service">
    Click the **Register Service** button.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Add Tags (Optional)">
    Type a tag and press Enter or click + to add. Tags help with filtering and routing.
  </Step>

  <Step title="Add Metadata (Optional)">
    Click **Add** to create key-value pairs for custom metadata.
  </Step>

  <Step title="Register">
    Click **Register Service** to complete registration.
  </Step>
</Steps>

## How to View Service Instances

<Steps>
  <Step title="Find the Service">
    Locate the service in the table using search or scrolling.
  </Step>

  <Step title="Expand the Row">
    Click the chevron (arrow) on the left to expand the service row.
  </Step>

  <Step title="View Instances">
    Each instance shows its ID, address, port, and associated tags.
  </Step>
</Steps>

## How to Add an Instance to Existing Service

<Steps>
  <Step title="Find the Service">
    Locate the service in the table.
  </Step>

  <Step title="Open Actions Menu">
    Click the three-dot menu on the service row.
  </Step>

  <Step title="Select Add Instance">
    Click **Add Instance**. The drawer opens with the service name pre-filled.
  </Step>

  <Step title="Enter Instance Details">
    Provide unique ID, address, port, and optionally tags/metadata.
  </Step>

  <Step title="Register">
    Click **Register Service** to add the new instance.
  </Step>
</Steps>

## How to Duplicate an Instance

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

<Steps>
  <Step title="Expand the Service">
    Click the chevron to show instances.
  </Step>

  <Step title="Find the Instance">
    Locate the instance card you want to duplicate.
  </Step>

  <Step title="Open Actions Menu">
    Click the three-dot menu on the instance card.
  </Step>

  <Step title="Select Duplicate">
    Click **Duplicate**. The drawer opens with pre-filled values.
  </Step>

  <Step title="Modify and Register">
    Change the ID (auto-appended with `-copy`) and any other values, then register.
  </Step>
</Steps>

<Tip>
  Duplicating is useful for quickly scaling a service by creating similar instances with different addresses or ports.
</Tip>

## How to Delete a Service Instance

<Steps>
  <Step title="Expand the Service">
    Show instances by clicking the chevron.
  </Step>

  <Step title="Find the Instance">
    Locate the instance card to delete.
  </Step>

  <Step title="Open Actions Menu">
    Click the three-dot menu.
  </Step>

  <Step title="Select Delete">
    Click **Delete** and confirm the action.
  </Step>
</Steps>

## How to Delete an Entire Service

Deleting a service removes all its instances.

<Steps>
  <Step title="Find the Service">
    Locate the service in the table.
  </Step>

  <Step title="Open Actions Menu">
    Click the three-dot menu on the service row.
  </Step>

  <Step title="Select Delete Service">
    Click **Delete Service**.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. All instances are deregistered.
  </Step>
</Steps>

<Warning>
  Deleting a service deregisters all instances. This may impact applications depending on service discovery.
</Warning>

## 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:

| Action       | Description                                            |
| ------------ | ------------------------------------------------------ |
| **Add Tags** | Add tags to all selected instances                     |
| **Add Meta** | Add metadata key-value pairs to all selected instances |
| **Export**   | Download selected instances as JSON                    |
| **Clear**    | Deselect 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:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Service not appearing in list" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot register service" icon="circle-question">
    * You need write permission for Consul services
    * Verify port is a valid number (1-65535)
    * Service name is required
    * Check Consul instance is healthy
  </Accordion>

  <Accordion title="Instances not showing when expanded" icon="circle-question">
    * The service may have no registered instances
    * Instances may have been deregistered
    * Check network connectivity
    * Try refreshing the page
  </Accordion>

  <Accordion title="Cannot delete service" icon="circle-question">
    * You need delete permission for Consul services
    * The operation may be in progress
    * Some instances may fail to deregister
  </Accordion>

  <Accordion title="Tags not saving" icon="circle-question">
    * Ensure you press Enter or click + after typing each tag
    * Tags cannot be empty strings
    * Check for duplicate tags (they're ignored)
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between Service Name and Service ID?">
    **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.
  </Accordion>

  <Accordion title="Can I edit an existing service instance?">
    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.
  </Accordion>

  <Accordion title="What happens when I delete an instance?">
    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.
  </Accordion>

  <Accordion title="How do health checks work?">
    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.
  </Accordion>

  <Accordion title="Can I register the same service in multiple datacenters?">
    Yes. Each Consul instance (datacenter) has its own service catalog. Register services in each datacenter where they run. Cross-datacenter discovery requires Consul federation.
  </Accordion>

  <Accordion title="What's the address field for?">
    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.
  </Accordion>
</AccordionGroup>