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
server-urlstringsecure websocket URL of Styra DAS relay-server (for example, wss://styra-das-id.styra.com/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. 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. 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-id.styra.com/v1/relay/clients"
{
"result": [
{
"client_key": "TEST-TOKEN",
"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 with characters and numbers.
  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.

References

Run relay-client as a Kubernetes Deployment

A minimal yaml to run relay-client.

important

Values for STYRA_TOKEN must be substituted with a valid token obtained from Styra DAS.

apiVersion: apps/v1
kind: Deployment
metadata:
name: relay-client
spec:
replicas: 1
selector:
matchLabels:
app: relay-client
template:
metadata:
labels:
app: relay-client
spec:
containers:
- name: relay-client
args:
- --base-url=https://github.com
- --server-url=wss://styra-das-id.styra.com/v1/relay/register
- --client-key=TEST-TOKEN
- --styra-token=$(STYRA_TOKEN)
env:
- name: STYRA_TOKEN
value: "INSERT STYRA_TOKEN HERE"
image: styra/relay-client:0.1.0
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
securityContext:
runAsNonRoot: true
runAsUser: 1000

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.