Follow the README to clone the repository and create .env before running repository commands. Complete the prerequisites below and configure .env, then return to the README deployment steps.
Install AAP with its controller enabled, and create a Write-scope token as described in the README requirements. Set AAP_TOKEN and AAP_NAMESPACE in .env. The token's user needs permission to create and update projects and credentials, create/copy/update job templates, use the selected inventory and credentials, and execute jobs. ACM authentication also creates a custom credential type, which requires an AAP administrator.
-
In AAP, open Automation Execution → Projects → Create project. Use these values, then save and wait for a successful project sync:
Field Value Name ai-driven-network-remediationOrganization Your automation organization Source control type GitSource control URL https://github.com/rh-ai-quickstart/ai-driven-network-remediation.gitSource control branch/tag/commit main, or the revision you deployOptions Enable Update revision on launch See AAP project configuration for UI details.
-
Open Automation Execution → Templates → Create template → Create job template. Set:
Field Value Name lightspeed-runnerJob type RunInventory Your inventory for remediation jobs Project ai-driven-network-remediationPlaybook hub/helm/charts/network/files/playbooks/restart-nginx.yamlas the initial selectionVariables Enable Prompt on launch Execution environment An environment containing the Ansible modules required by your playbooks Save the template. The initial playbook satisfies AAP's required field; generated templates select their own playbook. See AAP job templates.
-
The bootstrap uses organization ID
1. If you selected another organization, add--set network.aapCredential.organizationId=YOUR_ORGANIZATION_IDto the existingHELM_EXTRA_ARGSassignment in.env, replacing the placeholder with its numeric ID.
Deployment creates the lightspeed-generated project against the bundled Gitea repository. It uploads the Network playbooks from hub/helm/charts/network/files/playbooks/ and creates matching templates by copying lightspeed-runner, including its inventory and credentials. Generated playbooks use the same Gitea project. AAP must be able to reach the internal Gitea service; external Gitea is not fully supported by the current bootstrap.
Create working playbooks and the matching ran-* job templates from the RAN remediation guide, including the fallback ran-generic-remediation. Configure each template's inventory, execution environment, target-system credentials, and Prompt on launch for variables. Deployment does not install these templates or attach their credentials on a real controller.
The Network workflow uses the Ansible Lightspeed intelligent assistant to generate remediation playbooks. Follow the Lightspeed installation procedure for the chatbot's model configuration secret and enable spec.lightspeed.disabled: false in the AAP resource. Set spec.lightspeed.chatbot_config_secret_name to that secret's name.
The linked AAP 2.5 guide now marks that intelligent assistant version as deprecated and directs users to AAP 2.6 or later for supported functionality. This repository has no verified Lightspeed compatibility matrix; use the installation documentation matching your AAP release.
Set these values in .env:
ENABLE_LIGHTSPEED=true
LIGHTSPEED_VERIFY_SSL=trueLeave LIGHTSPEED_URL and LIGHTSPEED_TOKEN unset to use discovery. Make selects the first Service whose name contains lightspeed-chatbot-api, constructs its internal HTTPS URL, and reads the api_key entry from aap-lightspeed-chatbot-api-key in AAP_NAMESPACE. Your logged-in user must be able to list those Services and read that Secret.
If there are multiple installations, the Secret has another name, or the internal certificate is not trusted by the agent, set LIGHTSPEED_URL to the intended API endpoint with a certificate trusted by the agent and LIGHTSPEED_TOKEN to its API key. Discovery does not establish certificate trust. This key is separate from AAP_TOKEN, which authorizes controller operations. The deployment prerequisite check still requires a lightspeed-chatbot-api Service on the cluster when you provide an explicit endpoint. For Lightspeed outside namespace aap, also add --set-string network.agentService.lightspeed.namespace=YOUR_LIGHTSPEED_NAMESPACE to HELM_EXTRA_ARGS so the chart's network policy targets the correct namespace.
For example, use the chatbot API Route supplied by your AAP administrator, with a certificate chain trusted by the agent, and replace these placeholders in .env. Use the API endpoint, rather than the AAP console URL:
LIGHTSPEED_URL=https://your-lightspeed-api.apps.example.com
LIGHTSPEED_TOKEN=replace-with-your-chatbot-api-keyThe AAP API token authorizes controller operations. Playbooks also need credentials for the cluster or equipment being repaired. The Network bootstrap attaches cluster credentials to lightspeed-runner; copied templates inherit them.
With real AAP, deployment automatically creates the aap-remediation ServiceAccount and registers its token as the AAP credential hub-remediation. Its Kubernetes API address defaults to https://kubernetes.default.svc, so the AAP execution environment must run on or reach that cluster.
The current chart grants cluster-wide get, list, and patch access to all resources in the core, apps, batch, and networking API groups. It stores a ServiceAccount token in a Secret and creates the AAP credential with certificate verification disabled. The original README and chart identify this permission profile as development-only; the quickstart does not provide a hardened production credential profile. Assess these existing permissions before connecting operational workloads.
For AAP jobs targeting managed clusters, follow the hub identity and addon setup in Red Hat's multicluster authentication guide. Ensure ManagedServiceAccount and cluster-proxy addons are enabled and the hub identity has proxy access. The chart expects the identity aap-integration-serviceaccount in namespace aap.
Find the proxy endpoint and obtain a token for that identity:
oc get route cluster-proxy-addon-user -n multicluster-engine -o jsonpath='https://{.spec.host}{"\n"}'
oc create token aap-integration-serviceaccount -n aapPut the returned URL and token in .env:
ENABLE_MULTICLUSTER=true
CLUSTER_PROXY_URL=https://your-cluster-proxy.example.com
RHACM_HUB_TOKEN=replace-with-the-hub-service-account-tokenRenew RHACM_HUB_TOKEN before its issued lifetime ends and redeploy to update the AAP credential. The bootstrap creates the RHACM Cluster Proxy credential type and rhacm-hub credential, which supplies hub_url and token_acm to playbooks. The incident's edge_site_id selects the managed-cluster path under the proxy URL.
ENABLE_MULTICLUSTER configures AAP authentication independently of CLUSTER_COUNT. In hub-spoke topology, the chart grants the expected hub identity the edit role on each configured spoke. If using another identity, add both network.aapCredential.multicluster.hubServiceAccountNamespace and network.aapCredential.multicluster.hubServiceAccountName overrides to HELM_EXTRA_ARGS; the token must belong to that identity. Other topology modes do not create these spoke bindings. See the multi-cluster deployment guide for topology prerequisites.
Use the real-integration AAP_URL example in .env.example and replace the endpoint before loading .env.
| Integration | Configuration behavior |
|---|---|
| Network AAP | Make sets AAP_URL to the namespace-local mock when enabled, or http://aap.aap.svc otherwise. |
| RAN AAP | Uses the same Make AAP_URL value as Network. |
| AAP namespace | AAP_NAMESPACE controls the prerequisite check and Lightspeed token lookup; it does not change controller URLs. The prerequisite check requires a controller Service named aap in that namespace. |
| ServiceNow escalation | Set ENABLE_SERVICENOW_MOCK=false with SERVICENOW_INSTANCE_URL and SERVICENOW_API_KEY (preferred), or SERVICENOW_USERNAME + SERVICENOW_PASSWORD (Basic-auth fallback). make helm-install wires the noc-servicenow MCP server and the chatbot dashboard probe from these; no manual Helm overrides needed. |
| ServiceNow dashboard | Uses the same SERVICENOW_INSTANCE_URL and noc-servicenow-secret credentials as the MCP server for open-incident counts and reachability. |
| Incident links | SERVICENOW_INSTANCE_URL sets the base URL for incident links. |
AAP_URL is a Make variable shared by both services. Its default is the namespace-local mock when ENABLE_AAP_MOCK=true and http://aap.aap.svc otherwise. Set AAP_URL on the Make command line or in the environment to override both URLs. Direct Helm installs retain the chart defaults. The AAP controller API prefix defaults to /api/controller/v2. SERVICENOW_USERNAME and SERVICENOW_PASSWORD provision the local bootstrap account and, when ENABLE_SERVICENOW_MOCK=false, serve as the Basic-auth fallback the Makefile forwards to the noc-servicenow MCP server. See the ServiceNow setup guide for account provisioning.
Ready pods confirm deployment health. To validate incident response, connect the sources your team operates:
- Network: Single-cluster deployment leaves log forwarding disabled. Configure the OpenShift Logging operator, Kafka client certificates,
KAFKA_EXTERNAL_HOST, andCLUSTER_LOG_FORWARDER_ENABLED=trueusing the single-cluster topology instructions. - RAN: Supply a measurement producer for the
ran-combined-metricsKafka topic. Each message contains akpi_windowof 128 timesteps × 18 KPI channels withincident_id,zone, andapplicationmetadata. Follow the detector guide and detection workflow. Deployment does not connect radio equipment automatically.
For an incident from your monitored environment, follow its diagnosis in the dashboard, confirm any launched AAP job, and verify the workload or radio condition recovered. Confirm escalated Network incidents in ServiceNow.
Load the deployment's .env before using namespace variables. If a diagnosis or remediation does not appear, inspect the relevant service:
set -a && source .env && set +a
oc logs deployment/hub-agent-service -n "$NAMESPACE" --tail=100
oc logs deployment/hub-ran-anomaly-detector -n "$NAMESPACE" --tail=100
oc logs deployment/hub-ran-rca-service -n "$NAMESPACE" --tail=100
oc logs deployment/hub-ran-remediation-service -n "$NAMESPACE" --tail=100| Symptom | Check |
|---|---|
| No Network incidents | Log-forwarding configuration and connectivity to the hub Kafka endpoint. |
| No RAN diagnosis | Measurement format, predictor endpoint ending in /v1/detect, and model endpoint credentials. |
| Lightspeed discovery fails | Installed chatbot Service, AAP_NAMESPACE, API-key Secret, and permissions to read them. |
| Lightspeed certificate error | The configured endpoint's certificate chain and hostname are trusted by the agent. |
| AAP authorization error | AAP_TOKEN validity and the user's project, template, inventory, and credential permissions. |
| AAP bootstrap cannot create templates | lightspeed-runner exists, its project synced, the organization ID matches, and AAP can reach Gitea. |
| Playbook cannot reach a target | Template credentials, target API access rules, ACM identity/token, and the incident's managed-cluster name. |
| ServiceNow counts are unavailable | The current dashboard credential limitation described under Integration endpoints; inspect escalation in ServiceNow directly. |