Preparing for agent deployment

Schematics Agent extends the ability to work directly on your private network or any isolated network zones. Agents put users in control of the network configuration and access that they give to an agent to run workspace and action jobs. Agents are designed without inbound access from Schematics and the opening of inbound firewall or network access ports. All communication between the agent and Schematics is outbound from the agent and under user control.

Schematics Agent is a collection of microservices that runs on the Kubernetes clusters in your account. Also they use an Object Storage bucket as an intermediate or temporary data store for the log files and state-files generated by workspace or action jobs.

Review and complete the listed tasks to prepare your IBM Cloud® environment to deploy a new agent.

Account and networks

An agent provides Schematics the ability to run workspace and action jobs within a target account and the accounts private network. Network policies must be configured to allow the cluster that the agent is deployed on to communicate back to Schematics, also to the IBM Cloud APIs, services and, for instance, to a user private Git or Vault instances. For more information, see the section on Planning agent network access and configuration.

• Record information about the allowed network zones and infrastructure accessible to the agent.

Cluster

A Schematics Agent can be deployed on existing private or public IBM Cloud Kubernetes Service and Red Hat OpenShift Kubernetes Service clusters. You can use an existing cluster or provision a new cluster with the following minimum configuration.

• For the IBM Cloud Kubernetes Service v1.28 and later cluster versions. You need to update the network path so that images are pulled through a VPE gateway instead of a private service endpoint or enhance the Schematics agent template.
• Minimum configuration: Three worker nodes with b4x16 flavor. This configuration can be used to run four workspace or action jobs in parallel.
• Record information about the cluster such as cluster ID, cluster resource group, and region for the later use.

To support agents on the Red Hat OpenShift Kubernetes Service based on the requirement, You can control egress traffic through security groups and network access control lists (ACLs). You need to define any security group rules and ACLs at the VPC level before deploying an agent on the cluster. For more information, see the Terraform script to define security groups and ACLs on a VPC.

IBM Cloud Object Storage

The Schematics Agent uses a Object Storage bucket to store temporary data. The IBM Cloud Object Storage instance must be in the same resource group as the cluster. Also the new bucket must be in the same region as the cluster.

• To deploy an agent, you must have the necessary privileges to create the HMAC credentials for the Object Storage bucket and store the credential as a Kubernetes secret.
• The IBM Cloud Object Storage instance and bucket must be created for the successful deployment.
• Record information about the IBM Cloud Object Storage resources such as COS instance name, COS bucket name, and bucket region for the later use.

IAM access permission

At a minimum you must have access permissions for the Kubernetes service, Resource Group, Object Storage, and the Schematics service to deploy an agent.

• To deploy an agent in another account by using a ServiceID or APIKey, you must see that the account administrator gives permission for all the services enlisted in permission to deploy an agent.

IBM Cloud CLI

Use the recent version of IBM Cloud CLI and the Schematics CLI v1.12.12 or higher plug-in to install an agent. For more information about plug-in installation, see installing Schematics CLI plug-in.

Terraform version support

Agent supports the workspace by using Terraform v1.5, and v1.6. 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.

You can deploy only one agent instance on a Kubernetes cluster. To deploy multiple agents in a single IBM Cloud account, they must be deployed to different Kubernetes clusters. Each agent and cluster can cater to different network isolation zones in your Cloud environment.

An agent can be associated with and run jobs for one IBM Cloud account and geographic region. Agents cannot be shared with other accounts or run jobs for multiple accounts. The diagram represents the association of agents with a Schematics geographic region. Here multiple agents with access to local private resources in remote locations are associated with different Schematics geographic instances.

This image is an artistic representation and does not reflect actual political or geographic boundaries.

Planning agent network access and configuration

Schematics Agent enables workspace and action jobs to be ran on your private network with direct access to work with resources on your private network and data centers. The following diagram illustrates a possible agent deployment model on a cluster environment with multiple VPCs connected through a transit gateway.

To work with private resources, your private cloud environment must be configured to allow the cluster to run on your agent. And has access to the APIs, services and resources to enable workspace and actions jobs to run. Typically Terraform uses HTTPS to configure service over port 443. Whereas Ansible uses SSH through port 22 to perform post-provisioning VSI configuration. These HTTPS and SSH network paths are illustrated in the diagram.

VPC Security Group or Access Control List policies must be configured to allow the agent cluster to access IBM Cloud APIs by using HTTPS and any target VSIs by using SSH.

Access to data center resources can be configured by using Direct Link or a VPN connection.

With agents, you need to do the network security policies for the Kubernetes cluster, and any VPC Security Group or Access Control List policies for the running agent. Therefore, determining the ability of workspace and action jobs to access private cloud resources and the IBM Cloud APIs for the service provisioning and configuration.