--- name: schematics-sc-agent-infra-setup title: Deploying agent prerequisite infrastructure description: Agents for IBM Cloud® Schematics extend its ability to work directly to cloud infrastructure on the private network or in any isolated network zones. last-updated: 2025-10-30 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/schematics?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Deploying agent prerequisite infrastructure {: #agent-infrastructure-overview} Agents for IBM Cloud® Schematics extend its ability to work directly to cloud infrastructure on the private network or in any isolated network zones. {: shortdesc} ## Before you begin {: #agents-setup-prereq} The following prerequisites must be met before you begin deploying the agent infrastructure. - You must have an [IBM Cloud Pay-As-You-Go or Subscription](https://cloud.ibm.com/registration){: external} account to proceed. For more information about managing your IBM Cloud, see [Setting up your IBM Cloud account](https://cloud.ibm.com/docs/account?topic=account-account-getting-started&format=markdown). - Check whether you have the permissions to [provision a VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-managing-user-permissions-for-vpc-resources&format=markdown), a [IBM Cloud Kubernetes Service cluster](https://cloud.ibm.com/docs/containers?topic=containers-terraform-setup&format=markdown#terraform-cluster-IAM), and [logging service](https://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-atla&format=markdown) in the target resource group. - Check whether you have the [permission](https://cloud.ibm.com/docs/schematics?topic=schematics-access&format=markdown#workspace-permissions) to create a workspace. ## Provisioning agent infrastructure using Schematics {: #agents-infra-workspace} Schematics provides a [sample template](https://github.com/Cloud-Schematics/schematics-agents/tree/main/templates/infrastructure){: external} that you can use to provision the infrastructure needed by your agent. {: shortdesc} When installing an Agent in the `ca-mon` cluster, make sure both the `private` and `public` service endpoints are enabled. These endpoints are required only during installation or upgrade. After the successful installation or upgrade, you can disable the `public` service endpoint. However, you must re-enable the public service endpoint before performing any future Agent upgrades. {: note} The Agent infrastructure is composed of the following resources. - [VPC infrastructure](https://cloud.ibm.com/docs/vpc?topic=vpc-iam-getting-started&format=markdown) as `public_gateways`, `subnets`. - [IBM Cloud® Kubernetes Service](https://cloud.ibm.com/docs/containers?topic=containers-vpc-subnets&format=markdown) or [Red Hat OpenShift Kubernetes Service](https://cloud.ibm.com/docs/openshift?topic=openshift-learning-path-admin&format=markdown#admin_cluster) as `vpc_kubernetes_cluster`. 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 Network Security Groups rules and ACLs at VPC level before deploying an agent on the cluster. For more information, see [Terraform script to define security groups and ACLs on VPC](https://github.com/Cloud-Schematics/schematics-agents/blob/main/templates/infrastructure/vpc/network_acl.tf){: external}. {: note} 1. Log in to [IBM Cloud console](https://cloud.ibm.com/){: external}. 2. Click the **Menu** icon ![hamburger icon](images/icon_hamburger.svg) > **Platform Automation** > **Schematics** > **Terraform** > [**Create workspace**](https://cloud.ibm.com/schematics/workspaces/create){: external} with the following inputs to create an Agent infrastructure workspace. - In the **Specify Template** section: - **`GitHub`, `GitLab`, or `Bitbucket` repository URL** - `https://github.com/Cloud-Schematics/agent-infrastructure-sample/tree/main/templates/infrastructure`. - **Personal access token** - ``. You can click the `Open reference picker` to select a your Secrets Manager key reference. For more information, see [creating a Secrets Manager instance](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instance&format=markdown). - Terraform Version - `terraform_v1.5`. You need to select Terraform version 1.5 or greater than version. - Click `Next`. - In the **Workspace details** section enter - **Workspace name** as `schematics-agent-infrastructure`. - **Tags** as `agents-infra`. - **Resource group** as `default` or other resource group for this workspace. For more information, see [Creating a resource group](https://cloud.ibm.com/docs/account?topic=account-rgs&format=markdown). You must have the access permission for the resource group. - **Location** as `North America` or other [region](https://cloud.ibm.com/docs/schematics?topic=schematics-multi-region-deployment&format=markdown) for this workspace. If the location used for Agent infrastructure and Agent service does not match, then the logs are not sent to LogDNA. - Click `Next`. - Check the information that is entered are correct to create a workspace. - Click `Create`. 3. On successful creation of the `schematics-agent-infrastructure` Workspace, review and edit the `agent infrastructure` input variables in the workspace **Settings** page. The agent infrastructure and the workspace can be in different resource groups and locations. The agent infrastructure workspace can be defined in any Schematics supported region. {: note} | Input variable | Data type | Required/Optional | Description | |--|--|--|-- | | `agent_prefix` | String | `Required` | Provide the prefix for naming your agent VPC, cluster, and logging configuration. | `location`| String | `Required` | The region in the agent infrastructure VPC and cluster are created in. | | `resource_group_name` | String | `Required` | Name for the resource group used the agent infrastructure and agent are associated to. For example, **`test_agent`**. For more information, see [Creating a resource group](https://cloud.ibm.com/docs/account?topic=account-rgs&format=markdown). You must have the access permission for the resource group. | | `ibmcloud_api_key` | String | `Optional` | The IBM Cloud API key used to provision the Schematics Agent infrastructure resources. If not provided, resources provisions in currently logged in user credentials.| | `tags` | List(String) | `Optional` | A list of user tags to be applied to the deployed, VPC, and cluster. For example, `myproject:agent`, `test:agentinfra`. You can see the provisioned resources of an Agent faster by using Tag name. | {: caption="Schematics Agent infrastructure inputs" caption-side="bottom"} 4. Click **Apply plan** on the `schematics-agent-infrastructure` workspace to provision the agent infrastructure. It takes up to 45 - 90 minutes to provision all the resources. 5. View the **Jobs** logs and **Resources** page to monitor the resources are provisioned successfully and verify that the workspace status is now `ACTIVE`. Record the `cluster_id` and `logdna_name` from the `Outputs:` section of the Jobs log. This information is used when deploying the agent. If the job fails and you do not observe the `cluster_id` details in the Jobs log, you must have the IAM permissions to create `VPC Infrastructure`, and `Kubernetes cluster` services. Then, click **Apply plan** to redeploy the agent infrastructure. {: important} ### Expected outcome {: #agents-setup-infra-output} Follow the steps to view the Agent infrastructure workspace setup. 1. Navigate to the [Resources list](https://cloud.ibm.com/resources/){: external} page. 2. Verify that the following resources are provisioned from the resource list page. - **VPC > Search** `-vpc` the status as **Available**. - **Services and Software** > `-logdna` the status as **Active**. - **Clusters** > `-iks` the status as **Normal**. Optional: you can search the provisioned resources with the user tag you specified in the [Resources list](https://cloud.ibm.com/resources/){: external} page. {: note} ## Next steps {: #nextsteps-agent-infra} You have completed the Schematics Agent infrastructure set up. - Now, you need to [Deploy your Agent](https://cloud.ibm.com/docs/schematics?topic=schematics-deploy-agent-overview&format=markdown)