Shuttleproxy

Shuttleproxy lets Sauron collect metrics when it cannot directly reach your service. A client near your service reads its /metrics address and connects out to Sauron. Start with direct scraping if Sauron can reach that address without Shuttleproxy.

When do I need Shuttleproxy?

Use Shuttleproxy when:

• Your target exposes Prometheus-compatible metrics.
• Sauron Prometheus cannot directly reach the target because ingress is blocked.
• The network running the Shuttleproxy client can reach the target host, port, and metrics path.
• The network running the Shuttleproxy client can make outbound HTTPS connections to the Sauron Shuttleproxy endpoint.
• You know which Sauron and region should scrape the target.

Ask your service owner for the /metrics address and your Sauron owner for the approved Shuttleproxy endpoint, domain and client IDs, and credential. If any is missing, stop before deploying a client.

Architecture overview

The diagram shows the Sauron services and customer-side components involved in Shuttleproxy scraping.

Component	Role
Sauron instance	Monitoring and observability instance where services such as Grafana and Prometheus run.
API Server	Sauron service used to manage Prometheus and Alertmanager configuration.
Prometheus	Sauron service that collects metrics from application services and other resources.
Shuttleproxy server	Sauron service that allows Prometheus to scrape metrics from remote network environments without requiring ingress into that environment.
Shuttleproxy client	Customer-side component that connects to the Shuttleproxy server and reaches the target metrics endpoint.
Application	Service that exposes a Prometheus-compatible /metrics endpoint.
Kubernetes API server	Optional source for dynamic discovery when the monitored application is deployed on Kubernetes.

Prove it works before production

After setting up the client with the client guide, check the path before relying on it in production:

1. Confirm the Shuttleproxy client can resolve the Shuttleproxy endpoint DNS name.
2. Confirm the client can make outbound HTTPS connections to the Shuttleproxy endpoint.
3. Confirm the domain ID and client ID match the intended Sauron setup.
4. Confirm the client can reach the target host and port.
5. Confirm the target appears on the Prometheus targets page and is UP.
6. Query one metric from your service in Prometheus. UP alone only proves Sauron reached the target.
7. If registration or scraping fails, collect client log lines and the Prometheus target error with passwords, tokens, and private keys removed.

Prometheus scrape configuration

Shuttleproxy is used with Prometheus scrape configuration. The main scrape job types are:

Scrape job type	When it applies
Dynamic discovery	Prometheus discovers target metrics endpoints through a supported service discovery mechanism, such as a Kubernetes API server.
Static	Each target metrics endpoint is identified with its IP address or DNS name and port.
File-based discovery	Configuration files contain statically defined targets, and Prometheus picks up file changes automatically.

Dynamic discovery scrape jobs apply to environments where services are deployed on Kubernetes. Static and file-based discovery can apply to all environments.

For detailed scrape configuration examples, see:

• Dynamic Discovery Prometheus Scrape
• Pod Dynamic Discovery Scrape Job Example
• Service Endpoint Dynamic Discovery Scrape Job Example
• Dynamic Prometheus Scrape Using Shuttle Proxy Domain Feature
• File-Based Service Discovery Scrape
• Basic Static Prometheus Scrape Job
• Static Prometheus Scrape Using Shuttle Proxy Domain Feature
• Federating Metrics from Prometheus Servers using Shuttle Proxy

Domains

If your Sauron scrapes targets in more than one network domain, ask its owner which Shuttleproxy domain and client ID each target should use.

For more information, see:

• Domains
• Scraping HTTPS targets in non-default domains

Shuttleproxy client guide

The Shuttleproxy client can be deployed in containerized environments such as Docker or Kubernetes.

For deployment details, see:

• Shuttle Proxy Client User Guide
• Docker Deployment
• Kubernetes Deployment

IP whitelisting and network rules

Shuttleproxy has a server side and a client side, so ingress and egress rules can be confusing when configuring on-prem or restricted-network access.

Customer egress policy

The Shuttleproxy client needs outbound HTTPS access to this instance's Shuttleproxy server. Get its hostname from Console Endpoints and ask your network owner to allow that destination and port. If your firewall requires IP ranges, have the network owner and Sauron team confirm the current load balancer addresses and how to update them when they change. Do not use all OCI public CIDRs as a default allowlist for this task.

Customer ingress policy

The Shuttleproxy path normally needs no inbound connection to the client network. If you also use a direct scrape, review that target's ingress rule separately with your network owner. Use the current source CIDRs from Sending Metrics for that direct scrape.

Sauron ingress policy

For on-prem customers, Sauron's own ingress rules may need to be updated because Sauron instances generally allow all OCI regions and not external internet traffic.

If you connect from the public internet, provide the CIDRs of your firewall or other egress points to the Sauron team.

Tips and checks

Check: Confirm client DNS, outbound HTTPS, target reachability, and the Prometheus target error. Read the client log for registration or scrape errors.