IBM Cloud Docs
Agent

Agent

Answers to common questions about the Agent for IBM Cloud Schematics.

What are the updates in the GA agent release?

The following are the features in the agent release.

  • Improvements to the agent deployment experience through CLI and UI.
  • Support to run Ansible playbooks on the agent.
  • Dynamic assignment of workspace or action jobs to the agent.

What are the costs of installing and using agents?

The following is the cost break-down for deploying and using a Schematics agent.

The prerequisite infrastructure required to deploy and run an agent is chargeable:

  • Cost of VPC infrastructure elements such as subnet, public gateways.
  • Cost of IBM Cloud Kubernetes Service (cluster) on VPC, with three-node worker pool.
  • Cost of IBM Cloud Object Storage

Agent service execution:

  • There is no cost to running jobs on agents.
  • The Schematics version 1 agent capability is a non-chargeable feature. Future versions may be chargeable.

Is it possible to install more than one Agent on a cluster?

You can install only one agent on the IBM Cloud Kubernetes Service cluster. Additional clusters are required to deploy additional agents. If you attempt to install more than one agent on a cluster, the deploy job fails with a namespace conflict error.

What Terraform versions are supported with agents?

Only the two most recent versions of Terraform supported by Schematics are supported with agents, for example, Terraform v1.4 and Terraform v1.5. Older versions of Terraform are not supported. Workspaces using older versions of Terraform must be updated to one of the supported versions before using agents. See the instructions Upgrading to a new Terraform version to upgrade before using agents.

Why does workspace execution fail with terraformx.x: executable file not found in $PATH

The version of Terraform used by the workspace is not supported with agents. Agent supports the workspace using Terraform v1.4, and v1.5 or the two most recent versions of Terraform supported by Schematics. Workspaces with older versions of Terraform must be updated to one of the supported versions to support by an agent. For more information, see the deprecation schedule and user actions to upgrade.

What type of jobs can be run in an agent?

You can run Schematics workspace Terraform and Actions jobs on an agent.

How can I see the Schematics job results and logs for the jobs running on an agent?

The workspace job or action job logs are available in the Schematics UI console. You can also access the job logs by using the Schematics workspace API, or CLI.

What is the minimum cluster configuration required in Agent release?

The agent needs IBM Cloud Kubernetes Service service with a minimum three worker nodes, with a type of b4x16 or higher.

How many workspaces can be assigned to an agent?

Currently, you can assign any number of workspaces to an agent. The workspace jobs are queued to run on the agent, based on the agent assignment policy. The agent periodically polls Schematics for jobs to run, with a polling interval of one minute. By default, the agent runs only three jobs in parallel. The remaining jobs are queued.

How many jobs can run in parallel on an agent?

Schematics Agent can perform three Git downloads, workspace jobs (Terraform commands), and action jobs (Ansible playbooks) in parallel. Any additional jobs are queued and runs when prior jobs completes execution.

What is the default polling interval for agents?

Schematics maintains a queue of jobs for an agent. By default every one minute the agent polls the jobs.

Are there execution timeout limits when working with agents?

Schematics Agent relax the timeout limitation for local-exec, remote-exec and Ansible playbook execution. These are limited to 60 minutes in the multi-tenant service to ensure fair service utilization by all users. No duration is applied for jobs executed on agents. Long job execution times needs more user cluster capacity and worker nodes to ensure timely execution of all cluster jobs.

It is recommended to use a service such as Continuous Delivery for long running jobs performing software installation tasks.

What is the difference between agent-location and location flag in agent service?

The --agent-location parameter is a variable that specifies the region of the cluster where an agent service is deployed. For example, us-south. This must match the cluster region.

The --location parameter is a variable that specifies the region that is supported by the Schematics service such as us-south, us-east, eu-de, eu-gb. The agent polls Schematics service instance from this location, for workspace or action jobs for processing.

Can an agent run workspace jobs that are associated with different resource groups?

Yes, an agent can run workspace or actions jobs associated with any resource group, in an account. Agent (assignment) policies are used to assign the execution of jobs, based on resource group, region, and user tags to a specific agent.

Can an agent work with workspaces and actions belonging to different Schematics regions?

Agents deployments are associated with a Schematics home region for job execution. They can only execute workspace or action jobs defined in the same region such as, North America, or Europe.

The Agent periodically polls its home Schematics region to fetch and run jobs. It can only execute workspace or action jobs defined for the region containing its home region. For example, an agent is deployed on a user cluster in Sydney is configured to with eu-de as it’s home location. The agent polls for jobs in the Europe region, containing both the eu-de and eu-gb regions. To deploy resources using the Sydney agent, workspaces or actions must be created in the eu-de or eu-gb regions.

Is it possible to use an agent to execute jobs for multiple accounts?

No, agents are associated with a single parent Schematics account and can only execute jobs for workspaces or actions belonging to this account.

Can an existing workspace run jobs on an agent?

Yes. Workspaces and actions are selected by policy to execute on agents. A Schematics agent-selection-policy assigns existing (or new) workspaces or actions to run on an target agent, if they match the policy attributes for tags, resource-group, location.

For example, if you have an existing workspace: wks-0120 with tag=dev, and you want the workspace to run on Agent-1. Create an agent-selection-policy with the rules to pick Agent-1 when the tag == dev. Later, the workspace job such as plan, apply, update are dynamically routed to run on Agent-1.

What IAM permissions is needed to deploy an agent?

For information about access permissions, see agent permissions.

Can I inject self-signed or TLS certificates in IBM Cloud Kubernetes Service pod or container's trusted CA root certificate store during agent runtime?

Yes, follow these steps to inject the certificates into an agent runtime.

In the four .cer extension file names ensure that you modify to replace the space with underscore.

  1. Create a config map by using .cer file as shown in the kubectrl command.

    kubectl -n schematics-runtime create configmap bnpp-root —-from-file 2014-2044_BNPP_Root.cer

    kubectl -n schematics-runtime create configmap bnpp-authentication —-from-file 2014-2029 BNPP_Users_Authentication.cer

    kubectl -n schematics-runtime create configmap bnpp-infrastructure —-from-file 2014-2029 BNPP_Infrastructure.cer

  2. Mount config map file as a volume in a directory /etc/ssl/certs/ as file agent-runtime-deployment-certs.yaml in a shared bnpp_agent_deployment_files directory.

The Shared directory bnpp_agent_deployment_files has two yaml files named - agent-runtime-deployment-certs.yaml and - agent-runtime-deployment.yaml.

The agent-runtime-deployment-certs.yaml file updates the certificates and appends the agent-runtime-deployment.yaml file that provides you with the desired deployment details to inject the certificates without any additional changes.

What attributes of workspaces or actions are used to dynamically select a target agent for execution

The following attributes of a Schematics workspace or action are used to dynamically select the agent instance.

  • Resource group
  • Location (region)
  • Tags

The Agent assignment policy for an agent instance determines which agent is selected to run a workspace or action job.

Here is a sample scenario for the usage of tags.

If your organization has three different network isolation zones (such as Dev, HR-Stage, and HR-Prod) and you have installed three agents (one each, for the three network isolation zones). You have defined an agent-assignment-policy for the agent running in Dev, with the selector as tags=dev. All workspaces that have tags=dev automatically are bound to the Dev agent. In other words, the Dev agent is used to download Terraform templates (from the Git repository) and run Terraform jobs. Similarly, the agent-assignment-policy can include other attributes of the workspaces to define the agent for job execution.

How can I enable debug mode in an agent?

You can follow these steps to enable or disable the debug mode of an agent.

  1. Log in to IBM Cloud.
  2. Click Kubernetes from the left navigator window, then click Clusters
  3. On the Kubernetes Clusters page, click your cluster > Kubernetes dashboard.
    • Click the default drop down to view the list of Namespaces:
      • In the drop down, type the Schematics-job-runtime namespaces.
      • Click Config Map from the Config and Storage.
      • From the Config Maps page. Click the three dots against schematics-jobrunner-config.
      • Click Edit to view the Edit a resource page with the YAML, and JSON tabs.
      • You can now edit the JR_LOGGERLEVEL parameter for job-runner microservice logging. By default the value is -1 that indicated disable debug to enable you need to edit JR_LOGGERLEVEL as 0.
      • Click Update to apply your edits.

Can I upgrade an agent beta version to an agent General Availability (GA) version?

No, you cannot upgrade agent beta setup to agent GA version.

Are Schematics Agent the same as Terraform cloud agents?

Schematics Agent performs a similar role to Terraform Cloud agents.

Do the agents run on IBM Cloud cloud resources?

Schematics Agent can run only workspace and action workloads. For the Beta, the agents are deployed in IBM Cloud IBM Cloud Kubernetes Service clusters in the user account.

What are the minimum cluster configurations needed to support 30 jobs on the Schematics agent?

For the IBM Cloud® Virtual Servers for Virtual Private Cloud or IBM Cloud® Kubernetes Service cluster. You need 9 minimum number of nodes, with a bx2.4x16 flavor, and edit the following agent microservices deployments to have the prescribed replica count.

agent microservice deployments
Microservice Number of replicas
jobrunner 4
sandbox 8
runtime-ws 16

How can a user identify the job is created by an agent?

You can identify that the workspace is created by an Agent through the workspace job logs.

Is it possible that a workspace is created by an agent, still do not have a reference in the workspace job log?

No, If a agent creates workspace you must see a reference in the workspace job log. If you don't see the reference, then you must check that your policy validation is failed.

Can Schematics Agent establish a connection with the private Git instance?

Yes, Schematics Agent establishes a connection with the private Git instance. However, you need to own an SSL certificate and follow these steps in agent micro-services.

  1. Establish a connection by configuring SSL certificate in Jobrunner, Sandbox, and Runtime-ws agent micro-services.
  2. Configuration should be done by using Kubernetes Service configmap mounting.

    • create a configmap with the required SSL certificate, for example,

      kubectl -n schematics-job-runtime create configmap mytestcert --from-file cert.pem

    • Use configmap as volume and mount as shared in the deployment file in Jobrunner, Sandbox, and Runtime-ws microservices.

         apiVersion: apps/v1
   kind: Deployment
   metadata:
   annotations:
   deployment.kubernetes.io/revision: "1"
   kubernetes.io/change-cause: job_runner_1.0
   creationTimestamp: "2023-09-14T12:18:07Z"
   generation: 1
   labels:
   app: jobrunner
   name: jobrunner
   namespace: schematics-job-runtime
   resourceVersion: "23425"
   uid: fa66583a-8bdb-40a1-9b05-df2c2bf56656
   spec:
   progressDeadlineSeconds: 600
   .....
   .....
   volumes:
   - hostPath:
           path: /var/log/at
           type: ""
           name: at-events
   - hostPath:
           path: /var/log/schematics
           type: ""
           name: ext-logs
   - name: mytestcert  #### added as a volume 
           configMap:
           name: mytestcert
           status:
           availableReplicas: 1
           conditions:
   - lastTransitionTime: "2023-09-14T12:18:42Z"
           lastUpdateTime: "2023-09-14T12:18:42Z"
           message: Deployment has minimum availability.
           reason: MinimumReplicasAvailable
           status: "True"
           type: Available
   - lastTransitionTime: "2023-09-14T12:18:07Z"
           lastUpdateTime: "2023-09-14T12:18:42Z"
           message: ReplicaSet "jobrunner-7f9ffdf959" has successfully progressed.
           reason: NewReplicaSetAvailable
           status: "True"
           type: Progressing
           observedGeneration: 1
           readyReplicas: 1
           replicas: 1
           updatedReplicas: 1

Can Schematics Agent update a connection with the private Git instance?

Yes, you can update the agent with the metadata to perform catalog on boarding with the private Git instance. Use the sample update API request for reference.

Perform this step only if an agent does not have metadata.

curl -X PUT 'https://schematics.cloud.ibm.com/v2/agents/<agent_id>'
    -H 'Authorization: Bearer <token>'
    -H 'X-Feature-Agents: true'
    -H 'refresh_token: <refresh_token>'
    -d '{
"agent_metadata": [
        {
            "name": "purpose",
            "value": ["git"] 
        },
        {
            "name": "git_endpoints",
            "value": ["https://myprivate-gitinstance/testrepo"] 
        }
      ]
    }'