copyright

lastupdated

keywords

subcollection

years
2017, 2024

2024-11-13

schematics agent deploying, deploying agent, agent deploy, command-line, api, ui

schematics

Deploying agents

{: #deploy-agent-overview}

Create an agent registration in the selected {{site.data.keyword.bplong}} region to work directly in your cloud infrastructure on private network or isolated network zones. {: shortdesc}

Follow the steps to create and deploy an agent.

Create an agent definition to manage the agent deployment. This step initializes {{site.data.keyword.bpshort}} with the agent configuration that is used to deploy your agent to its target location.
Deploy the agent by using the ibmcloud schematics agent validate and ibmcloud schematics agent deploy CLI commands or the corresponding APIs.

Before you begin

{: #deploy-prereq}

Review and complete the steps that are described in preparing for agent deployment. After creation of the cluster, the {{site.data.keyword.cos_full_notm}} instance, and the {{site.data.keyword.cos_full_notm}} bucket, gather the following information as an input to deploy your agent to its target location. {: shortdesc}

The cluster, {{site.data.keyword.cos_full_notm}} instance, and {{site.data.keyword.cos_full_notm}} bucket are created in the same resource group.
Record the cluster ID, cluster resource group, and region of the {{site.data.keyword.containershort}} cluster the agent deploys.
The {{site.data.keyword.cos_full}} instance name, {{site.data.keyword.cos_full_notm}} bucket name of the {{site.data.keyword.objectstorageshort}} bucket is used for agent temporary data storage. The resource group and region of the {{site.data.keyword.cos_full_notm}} instance and bucket must be the same as the cluster.
Optional - if you need to update the proxy server to an Agent microservices, refer to configuring {{site.data.keyword.bpshort}} agents to a proxy server.
Optional - if you are using a private Git instance, you need to establish the connection with an agent through certificate. For more information, see steps to associate an agent with private Git instance.

You need to see that the Cluster, and the {{site.data.keyword.cos_full_notm}} instance are in the same resource group. {: important}

Creating an agent definition

{: #create-agent-ui} {: ui}

Log in to {{site.data.keyword.cloud_notm}} console{: external}.
Click the Menu icon > Platform Automation > Schematics > Extensions > Create Agent{: external}.
- In Define agent details section:
  - Enter a 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 {{site.data.keyword.containerlong_notm}} or the {{site.data.keyword.redhat_openshift_notm}} 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
Click Define.
Click Validate to validate the cluster and {{site.data.keyword.cos_full_notm}} configuration.
Click Deploy to deploy an agent.

Creating an agent definition through CLI

{: #create-agent-cli} {: cli}

As the first step, you must create an agent definition in your {{site.data.keyword.cloud_notm}} account, with the configuration that is used to deploy the agent. For a complete list of an agent create options, see ibmcloud schematics agent create command. {: shortdesc}

Select the {{site.data.keyword.cloud_notm}} region where you want to define and manage your agent from. Set the CLI region command by running ibmcloud target -r <region>. The region must be the same region as the location specified on the agent create command. The {{site.data.keyword.cos_full_notm}} 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>

{: pre}

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]

{: screen}

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

{: pre}

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]

{: screen}

Verifying prerequisites for agent deployment through CLI

{: #verify-agent-cli} {: cli}

You can verify the agent definition and cluster availability by using the agent validate command. The validate does 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 validates 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

{: pre}

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

{: screen}

Example

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

{: pre}

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

{: screen}

Deploying an agent through CLI

{: #apply-agent-cli} {: 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. {: shortdesc}

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

{: pre}

Output

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

{: screen}

Example

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

{: pre}

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

{: screen}

Verifying the agent deployment through CLI

{: #d-agent-cli} {: 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

{: pre}

Output

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

{: screen}

Example

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

{: pre}

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

{: screen}

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 through API

{: #create-agent-api} {: api}

Follow the steps to create an IAM access token and authenticate with {{site.data.keyword.bpshort}} 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"
    }
}

{: codeblock}

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. {: shortdesc}

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

{: screen}

Now, run the agent deploy API with the agent ID to create the {{site.data.keyword.bpshort}} 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

{: codeblock}

Example

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

{: codeblock}

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

{: screen}

Next steps

{: #agent-create-nextsteps}

Deploying and configuration of an agent are complete.

If you are using a private Git instance, then establish the connection with an agent through certificate. For more information, see steps to associate an agent to connect.
For configuring and provisioning your infrastructure by using, refer to agent policies. The agent policy is used by {{site.data.keyword.bpshort}} to dynamically route the Git repo download jobs, Workspace or Terraform jobs, and Action or Ansible jobs to an agent.
Manage your agent and Kubernetes cluster.
You can check out the agent FAQ for any common questions that are related to agents.
When the agent is no longer in need, it can be removed following the steps in delete an agent.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

sc-agentb1-deploy.md

sc-agentb1-deploy.md

Deploying agents

Before you begin

Creating an agent definition

Creating an agent definition through CLI

Verifying prerequisites for agent deployment through CLI

Deploying an agent through CLI

Verifying the agent deployment through CLI

Creating an agent through API

Next steps

Files

sc-agentb1-deploy.md

Latest commit

History

sc-agentb1-deploy.md

File metadata and controls

Deploying agents

Before you begin

Creating an agent definition

Creating an agent definition through CLI

Verifying prerequisites for agent deployment through CLI

Deploying an agent through CLI

Verifying the agent deployment through CLI

Creating an agent through API

Next steps