Relay Client

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.

API	HTTP/1.1 response
/v1/system/alive	200 OK if the relay client has successfully bootstrapped and is functional.
/v1/system/ready	200 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/metrics	provides 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 connection. 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"

{
  "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"

{
  "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 Kubernetes Secret to store STYRA_DAS_TOKEN

kubectl create secret generic relay-client-styra-das-token \
    --from-literal=STYRA_DAS_TOKEN=<Styra DAS token>

2. (OPTIONAL) Create Config Map with a Custom Root Certificate

kubectl create configmap relay-client-root-ca \
    --from-file=root-ca.crt=<filename: e.g. tls/root-ca.crt>

3. 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