Overview

Rafay's Zero Trust Host Access (ZTHA) is a control channel that enables Org Admins to send custom commands to nodes in one of multiple Rafay MKS Kubernetes Clusters. The cluster nodes can be operating in remote data centers, behind corporate firewalls.

Administrators can use the platform's Swagger based API to use this capability programmatically.

As you can see from the image above, a 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

Zero Trust Host Access (ZTHA) uses this control 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 an "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 information:

• 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 (base64 encoded) can be executed in a single command

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

Only nodes that are Approved, Provisioned nodes that are currently Reachable respond to commands. Nodes may be unreachable due to networking issues in the data center etc.

Response API

Enter the below command to fetch the required information. Provide the Exec ID returned from the post request from the above API request.

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

History API

The controller maintains a history of all previously executed commands and their responses for auditing and governance purposes. These can be retrieved programmatically using the history 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

Examples

We have provided three examples showcasing different scenarios for how administrators can leverage the ZTHA APIs on remote Rafay MKS Kubernetes clusters.

1. Single Command to Identified Nodes in a Cluster
2. Single Command to an Identified Cluster
3. Multiple Commands to Identified Nodes in a Cluster
4. Retrieve History of Commands