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.

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.
• Configuration: Persistent configuration with TOML format.
• Cross-Platform: Works on Linux and Windows.

Example

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

Installation from PyPI

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:

   git clone https://github.com/iByteABit256/service-lookup.git
   cd service-lookup
   

2. Install Dependencies:

   uv sync
   

3. Add to pip modules (Optional)

   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.

Usage

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

Basic Command

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 configuration, use the --use-lens parameter:

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:

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:

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. Defaults to the default_service_mappings_path configuration property (~/.config/service-lookup/service_mappings.json).
• -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:

# 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)
default_service_mappings_path = "~/.config/service-lookup/service_mappings.json"  # Path used when -f is not given

Service Mappings

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

{
    "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: ~/.cache/service-lookup/namespaces.yaml
• macOS: ~/Library/Caches/service-lookup/namespaces.yaml
• Windows: %LOCALAPPDATA%\service-lookup\Cache\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

Human contributions are welcome! Before making changes, check out the test environment guide 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 file for more details.