Deploying agents

Creating an agent definition

1. Log in to IBM Cloud.
2. Access Schematics > Agents > Create Agent.
   • In Define agent details section:
     • Enter unique Agent name.
     • Select Location and Resource group from the drop down option.
     • Enter Tags, and Description for the agent.
   • In Assign to cluster section:
     • Select the IBM Cloud Kubernetes Service or the Red Hat OpenShift service.
     • Select your cluster name.
     • In the Define COS Instance
       • Enter the COS instance name
       • Enter the COS bucket name
       • Enter the COS bucket region
3. Click Define.
4. Click Validate to validate the cluster and IBM Cloud Object Storage configuration.
5. Click Deploy to deploy an agent.

Creating an agent definition using the CLI

As the first step, you must create an agent definition in your IBM Cloud account, with the configuration that are used to deploy the agent. For a complete list of an agent create options, see ibmcloud schematics agent create command.

Select the IBM Cloud region where you wish to define and manage your agent from. Set the CLI region command by running ibmcloud target -r <region>. This must be the same region as the location specified on the agent create command. The IBM Cloud Object Storage bucket location must be of the form eu-gb or us-south and not a city name.

Example agent create syntax. The text between < > must add with your values:

ibmcloud schematics agent create --name <agent-ga-prod-cli-jan-10> --location <us-south> --agent-location <us-south> --version <1.0.0> --infra-type <ibm_kubernetes> --cluster-id <cg3fgvad0dak571xxx> --cluster-resource-group <Default> --cos-instance-name <agent-cos-instance> --cos-bucket <agent-cos-bucket> --cos-location <us-east> --resource-group <Default>

Output

Creating agent...
OK
                    
ID               agent-ga-prod-cli-jan-10.soA.cd1c
Name             agent-ga-prod-cli-jan-10
Status           Defined
Version          1.0.0
Location         us-south
Agent Location   us-south
Resource Group   aac37f57b20142dba1a435c70aeb12df
Metadata         [Metadata]
                 - [git]
                 - [github.com] 

Record the Agent ID for use in subsequent commands. To display the agent details, you can use the agent get command.

Example

ibmcloud schematics agent get --id agent-ga-prod-cli-jan-10.soA.cd1c

Output

Retrieving agent...
OK
                    
ID               agent-ga-prod-cli-jan-10.soA.cd1c  
Name             agent-ga-prod-cli-jan-10   
Status           ACTIVE   
Version          1.0.0
Location         us-south
Agent Location   us-south
Resource Group   Default
Metadata         [Metadata]
                 - [git]
                 - [github.com]

Verifying prerequisites for agent deployment using the CLI

You can verify the agent definition and cluster availability by using the agent validate command. The validate performs a prerequisite check of the target agent infrastructure. The command takes the Agent ID as input returned by the agent create command. The output of the agent validate command displays the list of relevant Kubernetes and agent property names, the expected value, actual value, and the result as PASS or FAIL.

Example

ibmcloud schematics agent validate --id agent-ga-prod-cli-jan-10.soA.cd1c  

Output

Initiating agent validate...
Job ID	.ACTIVITY.600cadf9

Polling status...
Status	job_pending
Status	job_in_progress
Status	job_in_progress
Status	job_in_progress
Status	job_finished

Example

ibmcloud schematics agent get --id agent-ga-prod-cli-jan-10.soA.cd1c   

Output

Retrieving agent...
OK
                    
ID               agent-ga-prod-cli-jan-10.soA.cd1c    
Name             agent-ga-prod-cli-jan-10   
Status           ACTIVE   
Version             
Location         us-south   
Agent Location   us-south  
Resource Group   Default   

Recent Job   Job ID                             Status                  Last modified
DEPLOY       -                                  Deploy in progress      2024-01-10T09:54:32.607Z
VALIDATE     8b168c1e0e4b35708e95c2af9a99d9d4   Successful validation   2024-01-10T09:53:48.435Z

Deploying an agent using the CLI

You use the agent definition to deploy the agent with the agent deploy command. The agent deploy command takes the Agent ID as input. You can upgrade an existing deployment by using the force deploy option.

The agent deployment takes several minutes to complete.

ibmcloud schematics agent deploy --id agent-ga-prod-cli-jan-10.soA.cd1c  

Output

Initiating agent deploy...
Job ID	.ACTIVITY.465e9716

Example

ibmcloud schematics agent get --id agent-ga-prod-cli-jan-10.soA.cd1c 

Output

Retrieving agent...
OK
                    
ID               agent-ga-prod-cli-jan-10.soA.cd1c   
Name             agent-ga-prod-cli-jan-10  
Status           ACTIVE   
Version          1.0.0   
Location         us-south  
Agent Location   us-south  
Resource Group   Default   
                 
Recent Job   Job ID               Status                 Last modified   
DEPLOY       .ACTIVITY.465e9716   Triggered deployment   2024-01-10T10:20:48.435Z
VALIDATE     8b168c1e0e4b35708e   Successful validation   2024-01-10T09:53:48.435Z

Verifying the agent deployment using the CLI

You can verify the health of the recently deployed agent by using the agent health command. The command takes the Agent ID as input. The output displays the list of relevant Kubernetes with the agent health property names, the expected value, actual value, and the result as PASS or FAIL.

Example

ibmcloud schematics agent health --id agent-ga-prod-cli-jan-10.soA.cd1c  

Output

Initiating agent health...
Job ID	.ACTIVITY.f6f77588

Example

ibmcloud schematics agent get --id agent-ga-prod-cli-jan-10.soA.cd1c  

Output

Retrieving agent...
OK
                    
ID               agent-ga-prod-cli-jan-10.soA.cd1c   
Name             agent-ga-prod-cli-jan-10   
Status           ACTIVE   
Version             
Location         us-south  
Agent Location   us-south  
Resource Group   Default   
                 
Recent Job   Job ID                             Status                   Last modified   
DEPLOY       f5c6987ce53032547b6d5d5f870dfe5f   Job Success               0001-01-01T00:00:00.000Z   
HEALTH       .ACTIVITY.f6f77588                 Triggered health check   2023-03-27T12:31:15.326Z 

In addition, you can use the Kubernetes CLI (kubectl) or Kubernetes dashboard of your cluster to view the status and logs of the agent related microservices, Pods, Deployment, Configmap, and Cluster bindings in the namespaces, schematics-agent-observe, schematics-sandbox, schematics-runtime and schematics-job-runtime.

Creating an agent using the Schematics API

Follow the steps to create an IAM access token and authenticate with Schematics through the API. For more information, see Create an agent by using API.

Example

  POST /v2/agents HTTP/1.1
  Host: schematics.cloud.ibm.com
  Content-Type: application/json
  Authorization: Bearer 

  {
    "name": "agentb1-gsmforvpc",
    "description": "Create Agent",
    "resource_group": "Default",
    "tags": [
        "env:prod",
        "mytest"
    ],
    "version": "v1.0.0",
    "schematics_location": "eu-de",
    "agent_location": "Frankfurt MZR",
    "agent_infrastructure": {
        "infra_type": "ibm_kubernetes",
        "cluster_id": "cg3fgvad0dak571op4g0",
        "cluster_resource_group": "Default",
        "cos_instance_name": "agent-cos-instance",
        "cos_bucket_name": "agent-cos-bucket"
    },
    "user_state": {
        "state": "enable"
    }
}

Verify that the agent definition is created successfully as shown in the output. Record the agent ID for use in subsequent commands. For example, agentb1-gsmforvpc.soA.115c.

Output

  {
      "name": "agentb1-gsmforvpc",
      "description": "Create Agent",
      "resource_group": "aac37f57b20142dba1a435c70aeb12df",
      "tags": [
          "env:prod",
          "mytest"
      ],
      "version": "v1.0.0",
      "schematics_location": "eu-de",
      "agent_location": "Frankfurt MZR",
      "user_state": {
          "state": "enable",
          "set_by": "xxxx@in.ibm.com",
          "set_at": "2023-03-16T18:08:18.399224788Z"
      },
      "agent_crn": "crn:v1:bluemix:public:schematics:eu-de:a/1f7277194bb748cdxxxxxxxxxxx42-0d59-415c-a6ce-0b662f520a4d:agent:agentb1-gsmforvpc.soA.115c",
      "id": "agentb1-gsmforvpc.soA.115c",
      "created_at": "2023-03-16T18:08:18.39924616Z",
      "creation_by": "xxxxx@in.ibm.com",
      "updated_at": "0001-01-01T00:00:00Z",
      "system_state": {
          "status_code": "draft"
      },
      "agent_kpi": {}
  }

Now, run the agent deploy API with the agent ID to create the Schematics workspace that deploys the agent. The agent deploy operation starts both the agent validate, and agent deploy operations to setup the agent.

Syntax

  PUT /v2/agents/<enter your agentID>/deploy HTTP/1.1
  Host: schematics.cloud.ibm.com
  Content-Type: application/json
  Authorization: Bearer 

Example

  PUT /v2/agents/agentb1-gsmforvpc.soA.115c/deploy HTTP/1.1
  Host: schematics.cloud.ibm.com
  Content-Type: application/json
  Authorization: Bearer 

Output

{
    "workspace_id": "eu-de.workspace.agentb1-gsmforvpc-deploy.1xxxxdf",
    "job_id": ".ACTIVITY.7f40fdc0",
    "updated_at": "2023-03-16T18:13:27.217864196Z",
    "updated_by": "xxxx@in.ibm.com",
    "status_code": "PENDING",
    "status_message": "Triggered deployment"
}