Overview

The built in Salt Stack based zero trust, control channel allow users to perform changes required at the node OS layer. This helps administrators send customized commands to cluster nodes operating in remote data centers, behind corporate firewalls. A Swagger based API is provided for these operations.

Rafay’s “node” agent is installed on every node in a Rafay MKS Kubernetes cluster.

• The node agent operates “below” the Kubernetes layer
• The node agent establishes a long lived connection with the Rafay Controller over port 443, outbound.
• This long running channel is used to perform in-place k8s software updates/upgrades and other operations from the Rafay controller.

Zero Trust Host Access (ZTHA) uses this channel to provide an API (programmatic usage) for administrative users to query/take action on remote nodes.

Important

Only users with a "Org Admin" role are allowed to send commands over this control channel.

---

High Level Approach

• The Org Admin calls the Swagger API specifying the "target nodes" and "commands"
• The API request is authenticated and authorized.
• The authorization process checks for the following:
• Do all the nodes belong to the projects in the Org?
• Is the user authorized to access the project?
• Once the API is called, the user is provided with a "Exec ID"
• The user needs to use the status API by specifying the "Exec ID" as input to query for status and receive the response to the commands sent.

An audit trail for all API calls are maintained with the following detail - Command executed (request) - User (API caller) - Target nodes - Project - Source IP address - Timestamp of request - Exec ID - Responses

---

APIs

Navigate to the Swagger UI page in the Rafay Platform to view the ZTHA APIs. The image below shows the three APIs for ZTHA.

---

Request API

Use this API to submit the commands to be executed remotely by the Rafay Node agents on Rafay MKS clusters.

/cmdexec/v1/projects/:project_id/edges/:edge_id/execute/

Example

{        
      "target" : "" (If node, specify the hostname and if cluster, this will be nil)
      "target_type" : "<node/cluster>""
      command: ""
      "content_type": "<string/base64>" (string is default)
      "timeout": 60 (default)
}

• Target is either array of nodes or a single cluster
• Any large script can be executed in a single command (base64 or otherwise)
• Users should not retry when the nodes are unreachable; thus call the API again
• Users cannot send commands to unapproved nodes. Only Approved and Provisioned nodes respond to commands

Important

Only the trimmed value is shown if the return standard output from the node is very large.

---

Response API

Enter the below command to fetch the required information.

/cmdexec/v1/projects/:project_id/edges/:edge_id/execution/:exec_id/

Provide the ID returned from the post request output

---

History API

The Rafay Controller maintains a history of all previously executed commands and their responses for auditing and governance purposes. These can be retrieved programmatically using the following API:

/cmdexec/v1/projects/:project_id/history/?limit=10&offset=0

• The query limit and offset control the history data count.
• The default limit is 10 responses
• The offset is 0 if no input is passed

---