KOP CLI - Agents - Rafay Product Documentation

Agents

The repo agent is a service that you deploy and operate in the local network or VPC and therefore, the controller can securely connect to the artifact repositories.

The table below describes the list of actions that can be performed on "repository" using the RCTL CLI Utility.

Resource	Create	Get	Delete	Share
Agent	YES	YES	YES	Yes

Create/Update Agent

Use the below "declarative" approaches to manage the agents

Declarative

Users have two options to choose from the deployment type when creating GitOps agent

Kubernetes deployment type, where the cluster mapping is mandatory
Docker deployment type. This type will allow the customer to deploy the GitOps agent as a standalone object on any machine without the need of a cluster

Kubernetes Deployment Type

To create/update an agent with Kubernetes Deployment Type, use the below command

./rctl apply -f agents-spec.yml

An illustrative example of the agent spec YAML file is shown below

apiVersion: gitops.k8smgmt.io/v3
kind: Agent
metadata:
  name: agent-demo
  project: sample-project
spec:
  active: true
  cluster:
    name: demo-new1
  type: Cluster

Docker Deployment Type

Step 1: To create an agent with Docker Deployment Type, use the below command

./rctl create agent -f <docker-agent.yaml> --download

An illustrative example of the agent spec YAML file is shown below with the agent name agent-demo

apiVersion: gitops.k8smgmt.io/v3
kind: Agent
metadata:
  name: agent-demo
  project: defaultproject
spec:
  active: true
  type: Docker

The download flag used in the create agent command downloads two files:

docker-compose.yml: A YAML file that contains the definition of docker services and volumes, which helps the customers to deploy the GitOps agent as a standalone docker container
relayConfigData.json: A JSON file that consists of configuration data where the relay agent can communicate with the core using this file

Below is an example of the downloaded files

docker-compose File

version: "3"
services:
  cd-agent-7dkgjkx:
    image: registry.dev.rafay-edge.net:5000/dev/cd-agent:20220124202911
    command: --cdrelay-agent
    volumes:
      - ./relayConfigData-7dkgjkx.json:/etc/config/relayConfigData
      - tmp-dir-7dkgjkx:/tmp
      - cdagent-volume-7dkgjkx:/opt/rafay
    container_name: cd-agent-7dkgjkx
volumes:
  tmp-dir-7dkgjkx:
  cdagent-volume-7dkgjkx:

relayConfigData File

{
  "agentID": "7dkgjkx",
  "maxDials": "2",
  "relays": [
    {
      "token": "c7nq57hqf0ds3b6dcf80",
      "addr": "console-my-testbed.dev.rafay-edge.net:443",
      "endpoint": "*.core-connector-my-testbed.cdrelay.core.dev.rafay-edge.net:443",
      "name": "rafay-core-cd-relay-agent",
      "templateToken": "c79akdpqf0dts50fe6ng"
    }
  ]
}

Output Directory

To download the relayConfigData and docker-compose files in the required location, use the below command

./rctl create agent -f <docker-agent.yaml> --download --output-dir -/<location>/

Steps 2: Once the download is successful, the system provides a docker compose command. Run this command to bring the agent up as a standalone docker container

docker-compose -f docker-compose-<agent_id>.yml up -d

Alternate Command

To perform the files download action and also bring up the new agent in a single step, use the below command.

./rctl create agent -f <docker-agent.yaml> --run output-dir -/<location>/

Step 3: The output shows a message on successful creation of Network, Volume and Container. The controller gets updated in a few minutes and shows the newly created agent in Healthy and Activated status (example agent name: agent-demo)

Down the agents

Use the below command to bring down the active agents

docker-compose -f docker-compose-<agent_id>.yml down

Download Agent(s)

Use the below command to download the existing agents

./rctl download agent <agent-name>

Perform Step 1 and Step 2 to create an agent, based on this config details if required

Agents Configuration

This configuration enables dynamic management of resource limits, worker counts, and scheduling policies, reducing the need for manual cluster updates

The following YAML configuration example demonstrates how to set resource limits, scheduling policies, and concurrency settings for a GitOps agent.

apiVersion: gitops.k8smgmt.io/v3
kind: Agent
metadata:
  name: agent-name
  project: defaultproject
spec:
  active: true
  type: ClusterAgent
  cluster:
    name: democluster
  config:
    concurrency: 50
    docker:
      limits:
        cpu: '0.50'
        memory: 50M
    kubernetes:
      limits:
        cpu: 500m
        memory: 3Gi
      nodeSelector:
        demo: selector
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: name
                    operator: In
                    values:
                      - val
                  - key: demo
                    operator: In
                    values:
                      - selector1
                      - selector2
      tolerations:
        - effect: NoExecute
          key: demo
          operator: Equal
          tolerationSeconds: 100
          value: selector1
    environment:
      numWorkers: 15

Configuration Explained

Number of Workers (numWorkers: 15): The agent runs 15 workers to handle Environment Manager activities, increasing processing capacity. The default value is 10; in this example, an override value of 15 is provided

CPU Limits (cpu: 0.50 and cpu: 500m) : The agent can use up to 0.5 CPU cores
Memory Limits (memory: 50M and memory: 3Gi): The agent can use up to 50MB of memory in Docker and 3GB in Kubernetes
Concurrency Limits (concurrency: 50): The agent can handle up to 50 tasks at the same time, improving performance for multiple operations
Tolerations (tolerationSeconds: 100): The agent is allowed to run on certain restricted nodes and can stay there for 100 seconds even if the node has restrictions
Node Selector (demo: selector1): The agent will only run on nodes that have a label demo: selector1
Affinity (Node Selection Rules): The agent prefers to run on nodes with specific labels like name=val or demo=selector1/selector2, ensuring better placement

Agent Version

To upgrade a Kubernetes-based GitOps agent via CLI, specify the new version field under spec:

spec:
  active: true
  cluster:
    name: demo-new1
  type: Cluster
  version: v1.1.0

Note

If version is not specified, the agent version remains unchanged
Only active versions provided by Rafay can be specified for upgrades or downgrades

Share/Unshare Agents

Users are allowed to share/unshare the existing repository with one or more projects

Update the config spec with the sharing parameters and apply the update command

./rctl update agent -f filepath.yaml --v3

An illustrative example of a spec is given below that shares an agent with all the projects

apiVersion: gitops.k8smgmt.io/v3
kind: Agent
metadata:
  name: demo-agent
  project: defaultproject
spec:
  active: true
  cluster:
    name: eks-dp
  sharing:
    enabled: true
    projects:
    - name: '*'
  type: Cluster

Run the apply command to share the repository with other projects

./rctl apply -f filepath.yaml

List Agents

Use this command to retrieve the list of agents in the configured Project. The name of the agents, the type of agent and health status are returned. An illustrative example is shown below where RCTL retrieves the list of agents in the project "Demo".

./rctl get agent --v3

./rctl get agents --v3
+
| AGENT NAME         | TYPE    | HEALTH STATUS |
+--------------------+---------+---------------+
| agent-prod-27thaug | Cluster | true          |
+--------------------+---------+---------------+
| test-agent         | Cluster | true          |
+--------------------+---------+---------------+
| ss6-6s             | Cluster | true          |
+--------------------+---------+---------------+
| ss6-61             | Cluster | true          |
+--------------------+---------+---------------+

Get Specific Agent Info

Use this command to retrieve a specific agent's details in the configured project.

./rctl get agent agent_name --v3

Below is the illustrative example for the agent called "demo"

./rctl get agent demo --v3

./rctl get agents agent-prod-27thaug --v3
+
| AGENT NAME         | TYPE    | HEALTH STATUS |
+--------------------+---------+---------------+
| demo               | Cluster | true          |
+--------------------+---------+---------------+

Or you can use below command to get more information of an agent in json or yaml format

./rctl get agent <agent-name> -o json

./rctl get agent <agent-name> -o yaml

Example:

./rctl get agents agent-prod -o yaml --v3
apiVersion: gitops.k8smgmt.io/v3
kind: Agent
metadata:
  name: agent-prod
  project: prod-test
spec:
  active: true
  cluster:
    name: post-upgrade-eks
  sharing: {}
  type: Cluster
  version: r1.17.0
status:
  conditionStatus: 1
  conditionType: AgentUnhealthy
  lastUpdated:
    nanos: 362000655
    seconds: 1673251405
  reason: getting agent conn failed

Delete Agent

You can delete an agent in the configured project.

./rctl delete agent -f config.yaml --v3

Important Refer here for the deprecated RCTL commands