Skip to content

Commit 59e7f66

Browse files
waggledanswaggledans
committed
sauce-connect-5/operation: adding api-server/readiness separate doc
1 parent 8fe6c17 commit 59e7f66

File tree

4 files changed

+119
-25
lines changed

4 files changed

+119
-25
lines changed

‎docs/secure-connections/sauce-connect-5/operation/api-server.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
id: api-server
3+
title: Sauce Connect Proxy API Server
4+
sidebar_label: API Server
5+
---
6+
7+
import useBaseUrl from '@docusaurus/useBaseUrl';
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
11+
Sauce Connect Proxy, optionally, exposes an API server that allows obtain information about the local Sauce Connect Proxy instance.
12+
The API interface is configured with the [`--api-address`](/dev/cli/sauce-connect-5/run/#--api-address) flag.
13+
14+
```bash
15+
--api-address :8080 # listens on all the interfaces' port 8080
16+
--api-address 127.0.0.1:8081 # listens on 127.0.0.1 port 8081
17+
```
18+
19+
20+
## Endpoints
21+
22+
The table below summarizes available endpoints.
23+
24+
| Path | Description |
25+
| :--------- | :----------------------------------------------------------------------------------------------------- |
26+
| `/readyz` | Returns 200 response code when Sauce Connect Proxy is ready, 503 otherwise. |
27+
| `/healthz` | Returns 200 response code when Sauce Connect Proxy is connected, 503 otherwise. |
28+
| `/info` | Returns runtime information about the tunnel instance. |
29+
| `/metrics` | Exposes [Prometheus](https://prometheus.io/) metrics. |
30+
| `/configz` | Returns the configuration values. |
31+
| `/pac` | Returns the PAC content being configured with the [`--pac`](/dev/cli/sauce-connect-5/run/#--pac) flag. |
32+
| `/version` | Returns the Sauce Connect Proxy instance version and build info. |
33+
34+
### Info
35+
36+
The `/info` response contains a JSON document containing runtime information of the Sauce Connect instance:
37+
38+
```json
39+
{
40+
"tunnel_id": "ab2cf344d4fc40d2bdc36b2fe6535c6b",
41+
"tunnel_name": "ci-tunnel-1",
42+
"tunnel_server": "1.2.3.4:443",
43+
"tunnel_host": "tunnel-123abc.tunnels.us-west-4.saucelabs.com"
44+
}
45+
```
46+
47+
### Readiness
48+
49+
The `/readyz` response is used to determine when Sauce Connect Proxy is ready to accept jobs. It returns 200 response code when Sauce Connect Proxy is ready, and 503 otherwise.
50+
51+
## More Information
52+
53+
- [Sauce Connect Proxy Overview](/secure-connections/sauce-connect/)
54+
- [Sauce Connect Proxy 5 CLI Reference](/dev/cli/sauce-connect-5/run/)

‎docs/secure-connections/sauce-connect-5/operation/monitoring.md

+1-25
Original file line numberDiff line numberDiff line change
@@ -26,31 +26,7 @@ You can manage and monitor all Sauce Connect Proxy tunnel activity from the Sauc
2626

2727
## Local API Server
2828

29-
Sauce Connect Proxy exposes an API that allows obtain information about the local Sauce Connect Proxy instance. The API interface is configured with the [`--api-address`](/dev/cli/sauce-connect-5/run/#--api-address) flag.
30-
The table below summarizes available endpoints.
31-
32-
| Path | Description |
33-
| :--------- | :----------------------------------------------------------------------------------------------------- |
34-
| `/readyz` | Returns 200 response code when Sauce Connect Proxy is ready, 503 otherwise. |
35-
| `/healthz` | Returns 200 response code when Sauce Connect Proxy is connected, 503 otherwise. |
36-
| `/info` | Returns runtime information about the tunnel instance. |
37-
| `/metrics` | Exposes [Prometheus](https://prometheus.io/) metrics. |
38-
| `/configz` | Returns the configuration values. |
39-
| `/pac` | Returns the PAC content being configured with the [`--pac`](/dev/cli/sauce-connect-5/run/#--pac) flag. |
40-
| `/version` | Returns the Sauce Connect Proxy instance version and build info. |
41-
42-
### Info Endpoint
43-
44-
The `/info` Endpoint contains a JSON document containing runtime information of the Sauce Connect instance:
45-
46-
```json
47-
{
48-
"tunnel_id": "ab2cf344d4fc40d2bdc36b2fe6535c6b",
49-
"tunnel_name": "ci-tunnel-1",
50-
"tunnel_server": "1.2.3.4:443",
51-
"tunnel_host": "tunnel-123abc.tunnels.us-west-4.saucelabs.com"
52-
}
53-
```
29+
See [Sauce Connect Proxy API Server](/secure-connections/sauce-connect-5/operation/api-server).
5430

5531
## Prometheus metrics
5632

‎docs/secure-connections/sauce-connect-5/operation/readiness-checks.md

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
id: readiness-checks
3+
title: Sauce Connect Proxy Readiness Checks
4+
sidebar_label: Readiness Checks
5+
---
6+
7+
import useBaseUrl from '@docusaurus/useBaseUrl';
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
11+
To run tests using an ephemeral tunnel, it's important to be sure the tunnel is ready to accept jobs. Jobs that are run when the tunnel is still in a booting state could fail because the tunnel won't be available.
12+
13+
There are four approaches to check for readiness:
14+
15+
* Manual testing
16+
* Using the Status Server HTTP Endpoint
17+
* Using the ready file
18+
* Using the REST API
19+
20+
## Manual Testing
21+
22+
If you are starting a tunnel manually for local testing, the SC client will print a message to console (or log file):
23+
24+
```
25+
2024/01/29 22:19:47.559711 [control] [INFO] Sauce Connect is up, you may start your tests
26+
```
27+
28+
## CI/CD Testing
29+
30+
### API Server HTTP Endpoint
31+
32+
Sauce Connect Proxy (5.0.0 or newer) provides a local [API server](/secure-connections/sauce-connect-5/operation/api-server). The following simple shell script allows blocking execution until the tunnel is ready.
33+
34+
```bash
35+
sc --api-address :8032 …
36+
until [ "$(curl -s -o /dev/null -w ''%{http_code}'' localhost:8032/readyz)" == "200" ]
37+
do
38+
sleep 2
39+
done
40+
echo "Sauce Connect Proxy is ready"
41+
```
42+
43+
### Tunnels REST API
44+
45+
The [Sauce Connect REST API](/dev/api/connect/#get-tunnels-for-a-user) provides metadata on tunnels. One of the keys `is_ready` is a boolean that tracks the state of the tunnel. This method can be used for jobs that don't have access to the tunnel's filesystem or network. It will need some logic to find the right tunnel, since the `tunnel_id` is probably not known when the request is sent.
46+
47+
When the `/tunnels?full=true` call is made, an array of tunnel objects is sent back with metadata. Each item could be checked for a matching `tunnel_identifier`, and once the correct tunnel is found, the `is_ready` flag could be checked.
48+
49+
```bash
50+
curl --user ${SAUCE_USERNAME}:${SAUCE_ACCESS_KEY} https://api.us-west-1.saucelabs.com/rest/v1/${SAUCE_USERNAME}/tunnels?full=true
51+
52+
[
53+
{
54+
...
55+
"id": "674442d71ffe446aa854a24a4c1c8bdd",
56+
"is_ready": true,
57+
...
58+
"tunnel_identifier": "jenkins-job-1234"
59+
...
60+
}
61+
]
62+
```

‎sidebars.js

+2
Original file line numberDiff line numberDiff line change
@@ -967,7 +967,9 @@ module.exports = {
967967
'secure-connections/sauce-connect-5/operation/overview',
968968
'secure-connections/sauce-connect-5/operation/configuration',
969969
'secure-connections/sauce-connect-5/operation/proxies',
970+
'secure-connections/sauce-connect-5/operation/api-server',
970971
'secure-connections/sauce-connect-5/operation/monitoring',
972+
'secure-connections/sauce-connect-5/operation/readiness-checks',
971973
'secure-connections/sauce-connect-5/operation/docker',
972974
'secure-connections/sauce-connect-5/operation/kubernetes',
973975
'secure-connections/sauce-connect-5/operation/systemd',

0 commit comments

Comments
 (0)