Metadata-Version: 2.4
Name: service-lookup
Version: 0.3.0
Summary: Update host:port in YAML service URLs by service name and Kubernetes cluster
Author-email: Pavlos Smith <paulsmith4561@proton.me>
License-Expression: GPL-3.0
Project-URL: homepage, https://github.com/iByteABit256/service-lookup
Project-URL: repository, https://pypi.org/project/service-lookup/
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: keyboard>=0.13.5
Requires-Dist: psutil>=7.2.2
Requires-Dist: pynput>=1.8.1
Requires-Dist: ruamel-yaml>=0.18.14
Requires-Dist: toml-rs>=0.3.12
Dynamic: license-file

# Service-Lookup Utility

A Python-based tool for updating YAML configuration files with dynamic host and port information from Kubernetes clusters. This utility is designed to streamline service discovery and configuration management in microservice environments.

## Table of Contents

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)

## Features

- **Dynamic Service Discovery**: Automatically discover services running in a Kubernetes cluster and update your YAML configuration files accordingly.
- **Port Forwarding**: Port forward Kubernetes services to your local machine for development and testing purposes.
- **Setup from Lens Utility**: Configure your environment with a simple setup command if using [Lens](https://k8slens.dev/).
- **Configuration**: Persistent configuration with TOML format.
- **Cross-Platform**: Works on Linux and Windows.

## Example
```bash
service-lookup --root . --namespace dev --services service1,service2 --use-lens --exclude ./target

Port-forwarding service service1 from target port 8080 to local port 24836
Port-forwarding service service2 from target port 8080 to local port 24837

✅ Updated: service1/service1-adapter/src/main/resources/application-service1-adapter.yml
✅ Updated: service2/service2-adapter/src/main/resources/application-service2-adapter.yml

Press 'ctrl+q' to clean ports and exit.

✅ Process 3740 terminated.
✅ Process 30260 terminated.
✅ Process 31400 terminated.
```

## Requirements

- Python 3.12 or later
- `kubectl` installed and configured
- Access to a Kubernetes cluster

### For Local Build
- [uv](https://docs.astral.sh/uv/)

## Installation from PyPI

```bash
pip install service-lookup
```

### PATH Configuration

To call `service-lookup` directly from any directory, ensure the Python scripts directory is in your system's PATH environment variable.

The typical locations are:
- **Linux/macOS**: `~/.local/bin/` or the `bin` directory of your Python installation
- **Windows**: The `Scripts` directory within your Python installation

## Installation From Repository

1. **Clone the Repository**:
   ```bash
   git clone https://github.com/iByteABit256/service-lookup.git
   cd service-lookup
   ```

2. **Install Dependencies**:
   ```bash
   uv sync
   ```

3. **Add to pip modules (Optional)**
   ```bash
   pip install .
   ```

4. **Ensure `kubectl` is Installed**:
   Make sure you have `kubectl` installed and configured to access your Kubernetes cluster. You should either have a `.kubeconfig` file or run the setup command if you're using [Lens](https://k8slens.dev/).

## Usage

To use the utility, run the main script with the desired options:

### Basic Command

```bash
service-lookup --root /path/to/root --namespace your-namespace --services service1,service2 --exclude path/to/exclude,another/path/to/exclude
```

### Setup Environment from Kubernetes Lens

To set up your environment based on your [Lens](https://k8slens.dev/) configuration, use the `--use-lens` parameter:

```bash
service-lookup --root /path/to/root --namespace your-namespace --services service1,service2 --exclude path/to/exclude,another/path/to/exclude --use-lens
```

### With Mappings

If you have predefined mappings:

```bash
service-lookup --root /path/to/root --map service1=localhost:8080,service2=localhost:8081 --exclude path/to/exclude,another/path/to/exclude
```

### Restore Files After Cleanup

To automatically restore original YAML files when cleaning up port-forwarded services:

```bash
service-lookup --restore --namespace dev --services service1,service2
```

### Options

- `-r`, `--root`: Root directory to search YAML files.
- `-e`, `--exclude`: Comma-separated list of paths to exclude.
- `-m`, `--map`: Comma-separated service=host:port pairs.
- `-n`, `--namespace`: Kubernetes namespace to discover services.
- `-s`, `--services`: Comma-separated list of service names to port forward. Default value is '*' which means every service in the mapping file.
- `-f`, `--mapping-file`: Path to JSON file with service_name -> kubernetes_service_name mappings.
- `-k`, `--kubeconfig`: Specify kubeconfig file path.
- `-c`, `--cluster`: Specify Kubernetes cluster, otherwise first matching namespace from any cluster will be used when using the `--use-lens` option.
- `-l`, `--use-lens`: Use kubeconfigs from Lens.
- `-t`, `--request-timeout`: The length of time to wait before giving up on a single server request, default is 10s.
- `-R`, `--restore`: Restores updated files after cleanup (default: false).
- `--invalidate-cache`: Invalidates the namespace cache.

## Configuration

### Configuration File

Service-lookup supports a TOML configuration file located at:

- **Linux/macOS**: `~/.config/service-lookup/config.toml`
- **Windows**: `%USERPROFILE%\.config\service-lookup\config.toml`

Example configuration:

```toml
# Default configuration for service-lookup
use_lens_by_default = false      # Use Lens kubeconfigs automatically
revert_after_cleanup = false     # Restore original files when cleaning up
cache_invalidation_seconds = 864000  # Namespace cache duration (default: 10 days)
```

### Service Mappings

Create a `service_mappings.json` file to map local service names to Kubernetes service names:

```json
{
    "local-service-a-name": "kubernetes-service-a-name",
    "local-service-b-name": "kubernetes-service-b-name"
}
```

Running without the `--services` option searches for every service in the mappings file above.

### Exclusion Paths

Use the `--exclude` option to specify paths in the root directory that should be excluded from updates.

### Namespace Caching

The tool caches Kubernetes namespace information to improve performance. The cache is stored at:

- **Linux/macOS**: `~/.cache/service-lookup/namespaces.yaml`
- **Windows**: `%USERPROFILE%\.cache\service-lookup\namespaces.yaml`

Cache can be invalidated using:
- `--invalidate-cache` command-line option
- Waiting for the `cache_invalidation_seconds` period to expire (configured in config.toml)

## Contributing

All contributions are welcome! Before making changes, check out the
[test environment guide](test-env/README.md) to learn how to run the tool
locally.

To contribute:

1. Fork the repository on GitHub.
2. Create a new branch for your feature or fix.
3. Commit your changes and push your branch to GitHub.
4. Submit a pull request for review.

## License

This project is licensed under the GNU GPL-3.0 License. See the [LICENSE](LICENSE) file for more details.
