Skip to main content

Relay Client

A relay-client can be used to proxy requests between Styra DAS and the base-url that the client is configured with. It establishes a persistent websocket connection with a relay-server running on Styra DAS and executes relayed HTTP requests on the configured base-url. You can install a relay-client on your private infrastructure to provide a secure connection between Styra DAS and your Git servers. This allows Styra DAS to use Git as a storage backend, even when the Git repositories are not accessible from Styra's network. The relay-client is stateless and multiple replicas of the client can be run simultaneously for availability.

Configure Flags

The following flags must be configured to run the relay-client:

FlagTypeDescription
base-urlStringBase URL to relay requests to (for example, https://mycompany.github.com).
client-keyStringThe client key that this instance should register on the relay-server with. Valid characters include letters, numbers, underscore and hyphen.
server-urlStringSecure websocket URL of Styra DAS relay-server (for example, wss://${STYRA_DAS_URL}/v1/relay/register).
styra-tokenStringAPI token for authentication with Styra DAS
note

base-url should point to the Git API server's absolute address and not the complete path to the targeted repository. For example, for relaying to repository https://mycompany.github.com/hooli/foo.git, the base-url should be https://mycompany.github.com.

On instantiation, the relay-client connects to the configured relay-server URL with a client-key of your choice. The client-key string MUST consist of valid characters. If a connection is successfully established then the client's readiness checks will succeed. Otherwise, the client will continue to retry the connection to the relay-server with an exponential backoff and will mark itself as not ready.

note
  1. A sample deployment manifest for relay-client is available when you run relay-client as a Kubernetes deployment.

  2. If the base-url host uses a custom certificate then use the instructions to configure relay-client to trust the custom certificate.

Register relay-client on Styra DAS

Styra DAS exposes an API GET /v1/relay/clients to retrieve a list of registered relay-clients.

It returns a list of clients registered with the relay-server. Each relay client is uniquely identified using a combination of:

  1. client_key: The key that the relay-client is bootstrapped with.
  2. client_id: An autogenerated unique id that the client registers with on the relay-server.
  3. remote_address: IP address and host combination of the relay-client as seen by the relay-server.

Sample cURL:

curl -H "Authorization: Bearer ${STYRA_TOKEN}" \
"https://${STYRA_DAS_URL}/v1/relay/clients"
response.json
{
"result": [
{
"client_key": "TEST-TOKEN",
"client_id": "abb93de8-2e47-46d5-8953-c4ef23c761d1",
"remote_address": "100.125.55.57:54234"
}
]
}

After a relay-client is successfully registered with Styra DAS, it can be used in Styra DAS for configuring Git with systems, stacks, libraries, or workspaces.

Configure a System

Configure a system to use the Relay Setup:

  1. Obtain the HTTPS URL for the repository. For example, https://mycompany.github.com/hooli/policy.git.

  2. Replace the scheme and host with a URL to the relay-server:8080. For example: given the above URL, the replaced URL is: http://relay-server:8080/v1/relay/<client-key>/hooli/policy.git. Provide this modified URL in the Git repository (required) input field located in Settings >> Git Repository pane.

  3. Configure the rest of the Git settings as before. For example: credentials, reference, path, and so on.

  4. Ensure that at least one relay-client instance is registered with the relay-server for the configured client-key.

  5. The system should now be setup to use the relay-client and the synchronization can be monitored through the Git status page in the system's settings.

note
  1. The steps to configure a system also apply to stacks and workspaces.
  2. The client-key can be set to any valid string composed with upper and lowercase letters, numbers, underscores and hyphens.
  3. Git Relay setup is only available for HTTPS based authentication and does not work with SSH auth.

Monitoring relay-client

relay-client exposes the following HTTP endpoints that can be used to monitor its operation.

APIHTTP/1.1 response
/v1/system/alive200 OK if the relay client has successfully bootstrapped and is functional.
/v1/system/ready200 OK if the relay client has an active websocket connection to the configured Styra DAS instance.
500 Internal Server Error if the websocket connection hasn't been established or is unhealthy.
/v1/system/metricsprovides standard client_golang prometheus metrics for the relay-client.
tip

It may take the readiness check a period of 30s to detect a failed connection.

Removing a relay client

The relay-server hosted on Styra DAS is responsible for managing any registered relay-clients. It automatically detects unhealthy relay-clients and removes them from its roster. A removal of a relay-client also closes the associated websocket connection thus preventing it from being used for any further relay-based interactions. Moreover, if the relay-client detects an erroneous removal, it attempts to re-establish a new websocket connnection. This allows the relay workflow to be resilient.

There are additional provisions for force-removing relay-clients from the relay-server's state using the APIs exposed by Styra DAS.

Each relay-client has an associated unique ID that can be listed by querying the /v1/relay/clients endpoint on Styra DAS.

curl -H "Authorization: Bearer ${STYRA_API_TOKEN}" \
"https://${STYRA_DAS_URL}/v1/relay/clients"
response.json
{
"result": [
{
"client_key": "CLIENT-KEY",
"client_id": "abb93de8-2e47-46d5-8953-c4ef23c761d1",
"remote_address": "192.168.186.227:35290"
},
{
"client_key": "CLIENT-KEY",
"client_id": "fab83ac7-3a90-81d3-4381-d91a3bd892f0",
"remote_address": "192.168.186.227:35292"
},
{
"client_key": "ANOTHER-KEY",
"client_id": "67c016cc-f227-4ebc-86de-4599e786e76d",
"remote_address": "192.168.186.227:45924"
}
]
}

A relay-client can be evicted by issuing a DELETE on the /v1/relay/clients/{id} API as illustrated by the following API calls.

Remove relay-client by ClientKey

The following API call deletes ALL relay-clients registered with client_key: CLIENT-KEY.

curl -XDELETE -H "Authorization: Bearer ${STYRA_API_TOKEN}" \
"https://${STYRA_DAS_URL}/v1/relay/clients/CLIENT-KEY"
response.json
{
"result": [
{
"client_key": "CLIENT-KEY",
"client_id": "abb93de8-2e47-46d5-8953-c4ef23c761d1",
"remote_address": "192.168.186.227:35290"
},
{
"client_key": "CLIENT-KEY",
"client_id": "fab83ac7-3a90-81d3-4381-d91a3bd892f0",
"remote_address": "192.168.186.227:35292"
}
]
}

Remove relay-client by ID

The following API call deletes ONLY the first relay-client from the list above, with client_key: CLIENT-KEY and client_id: abb93de8-2e47-46d5-8953-c4ef23c761d1.

curl -XDELETE -H "Authorization: Bearer ${STYRA_API_TOKEN}" \
"https://${STYRA_DAS_URL}/v1/relay/clients/CLIENT-KEY?id=abb93de8-2e47-46d5-8953-c4ef23c761d1"
response.json
{
"result": [
{
"client_key": "CLIENT-KEY",
"client_id": "abb93de8-2e47-46d5-8953-c4ef23c761d1",
"remote_address": "192.168.186.227:35290"
}
]
}

A subsequent attempt to list the relay-clients may display a shortened list without the evicted relay-clients if they were in a bad state. Otherwise, since the remote relay-client process is configured to detect broken connections and automatically reconnect, the list may display the same number of relay clients. Although the ID of the reconnected relay-client remains the same, the remote address will be updated with a new port on the client to indicate a fresh connection.

More details can be found in the API spec for relay endpoint.

References

Trust a Self-Signed Certificate on relay-client

If the base-url host uses a custom self-signed certificate, then relay-client must be configured to trust the certificate so that it can correctly relay requests to it. You can achieve this by using the SSL_CERT_FILE environment variable to point to the trusted certificate.

For more information, see OpenSSL cert locations.

Run relay-client as a Kubernetes Deployment

A minimal config to run relay-client.

  1. Create a Kuberenetes Secret to store STYRA_DAS_TOKEN
kubectl create secret generic relay-client-styra-das-token \
--from-literal=STYRA_DAS_TOKEN=<Styra DAS token>
  1. (OPTIONAL) Create Config Map with a Custom Root Certicate
kubectl create configmap relay-client-root-ca \
--from-file=root-ca.crt=<filename: e.g. tls/root-ca.crt>
  1. Create Deployment for relay-client by customizing the following manifest.
apiVersion: apps/v1
kind: Deployment
metadata:
name: relay-client
spec:
replicas: 1
selector:
matchLabels:
app: relay-client
template:
metadata:
labels:
app: relay-client
spec:
hostPID: false
hostIPC: false
hostNetwork: false
securityContext:
runAsNonRoot: true
runAsUser: 1000
containers:
- name: relay-client
image: styra/relay-client:0.1.6
imagePullPolicy: Always
args:
- --base-url=https://github.com
- --server-url=wss://${STYRA_DAS_URL}/v1/relay/register
- --client-key=TEST-TOKEN
- --styra-token=$(STYRA_DAS_TOKEN)
securityContext:
allowPrivilegeEscalation: false
privileged: false
capabilities:
drop:
- ALL
env:
- name: STYRA_DAS_TOKEN
valueFrom:
secretKeyRef:
name: relay-client-styra-das-token
key: STYRA_DAS_TOKEN
# uncomment when using a custom CA
# - name: SSL_CERT_FILE
# value: /cacerts/root-ca.crt
livenessProbe:
failureThreshold: 3
httpGet:
path: /v1/system/alive
port: 8080
scheme: HTTP
initialDelaySeconds: 10
periodSeconds: 10
successThreshold: 1
timeoutSeconds: 1
readinessProbe:
failureThreshold: 3
httpGet:
path: /v1/system/ready
port: 8080
scheme: HTTP
initialDelaySeconds: 10
periodSeconds: 5
successThreshold: 1
timeoutSeconds: 1
resources:
limits:
cpu: 500m
memory: 512Mi
requests:
cpu: 100m
memory: 128Mi
# uncomment when using a custom CA
# volumeMounts:
# - name: custom-root-ca-cert-volume
# mountPath: /cacerts
# readOnly: true
# volumes:
# - name: custom-root-ca-cert-volume
# configMap:
# name: relay-client-root-ca

Adjusting the log level on relay-client

The relay-client emits logs at the Info level by default. However, for troubleshooting errors like certificate mismatches or connection resets, the log-level can be dynamically adjusted. The following commands MUST be run in the same network namespace as a running relay-client process. If the relay-client runs as a kubernetes pod then this means that the user MUST create a kubectl exec session before running these commands.

/styra $ relay-client log --help
Allows to display structured log's configuration and modify it.

With no flags specified outputs current configuration.

Use --level flag to output logs at specified level and above.
Use --ttl flag to override default TTL value. This value configures
the interval after changes will be reset to default values

List of available log levels:
fatal (-1), error (0), warn (1), info (2), debug (3), trace (4)

Usage:
relay-client log [flags]

Flags:
-h, --help help for log
-l, --level string log level, one of: fatal (-1), error (0), warn (1), info (2), debug (3), trace (4)
-t, --ttl duration ttl for log level change, max 24h

Command to set the log level to debug:

/styra $ relay-client log --level=debug
Configuration has been updated:

Current log settings:
Level: debug (3)

TTL: 10m