From b7ec9db2bc84bdeaa20133b59dd3c122cc0daef8 Mon Sep 17 00:00:00 2001
From: Oracle Public Cloud User
 <opc@vm-admin.lbsub89a3e9ab0.telmexokecluste.oraclevcn.com>
Date: Tue, 1 Sep 2026 21:32:59 +0000
Subject: [PATCH] kagents, oci gen ai, oke, oci devops

---
 README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fbb501b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,121 @@
+# kagent DevOps Remediator Function
+
+OCI Function bridge used by OCI DevOps to ask kagent for post-deployment diagnosis, business degradation analysis, pod troubleshooting, or remediation recommendations.
+
+## Network prerequisite
+
+The function cannot resolve Kubernetes `svc.cluster.local` names. Expose the kagent controller through a private LoadBalancer:
+
+```bash
+kubectl apply -f k8s/kagent/kagent-controller-private-lb.yaml
+kubectl get svc kagent-controller-private-lb -n kagent
+```
+
+Set `KAGENT_MCP_URL` to:
+
+```text
+http://<private-kagent-lb-ip>:8083/mcp
+```
+
+The Function must run in a subnet that can reach that private LB.
+
+## Function config
+
+Required config:
+
+```text
+KAGENT_MCP_URL=http://<private-kagent-lb-ip>:8083/mcp
+KAGENT_AGENT_NAME=k8s-agent
+KAGENT_AGENT_NAMESPACE=kagent
+APP_NAMESPACE=kagent-demo
+ORDER_OBSERVABILITY_URL=http://<order-lb-ip>/api/observability
+OCI_REGION=mx-monterrey-1
+NOTIFICATION_TOPIC_OCID=<oci-notifications-topic-ocid>
+DEVOPS_APPROVAL_URL=https://cloud.oracle.com/devops/projects/<project-ocid>/deploy-pipelines/<remediation-pipeline-ocid>?region=mx-monterrey-1
+```
+
+`NOTIFICATION_TOPIC_OCID` is optional. If it is configured, the Function publishes an OCI Notifications message only when kagent reports an active failure or degradation. Healthy results do not send email.
+
+`DEVOPS_APPROVAL_URL` is optional but recommended for the demo. Use a stable remediation pipeline URL because deployment OCIDs change on every run:
+
+```text
+DEVOPS_APPROVAL_URL=https://cloud.oracle.com/devops/projects/<project-ocid>/deploy-pipelines/<remediation-pipeline-ocid>?region=mx-monterrey-1
+```
+
+If you later want to include a specific deployment URL, pass it in the Function payload as `devopsApprovalUrl`. Payload values override the environment variable.
+
+## Default diagnosis payload
+
+```json
+{
+  "appNamespace": "kagent-demo",
+  "agentNamespace": "kagent",
+  "agentName": "k8s-agent",
+  "observabilityUrl": "http://40.233.26.150/api/observability"
+}
+```
+
+If no `prompt` is provided, the Function uses the default business-remediation prompt for the `kagent-demo` application.
+
+## OCI DevOps parameterized payload
+
+For the Invoke Function stage, create a General artifact using `k8s/kagent-multi-error-payload.json` and enable parameter substitution.
+
+Recommended OCI DevOps deployment pipeline parameters:
+
+```text
+OCI_REGION=mx-monterrey-1
+APP_NAMESPACE=kagent-demo
+ORDER_OBSERVABILITY_URL=http://<order-lb-ip>/api/observability
+NOTIFICATION_TOPIC_OCID=<oci-notifications-topic-ocid>
+DEVOPS_APPROVAL_URL=https://cloud.oracle.com/devops/projects/<project-ocid>/deploy-pipelines/<default-remediation-pipeline-ocid>?region=mx-monterrey-1
+BUSINESS_REMEDIATION_PIPELINE_OCID=<business-remediation-pipeline-ocid>
+IMAGEPULL_REMEDIATION_PIPELINE_OCID=<imagepull-remediation-pipeline-ocid>
+HPA_REMEDIATION_PIPELINE_OCID=<hpa-remediation-pipeline-ocid>
+BUSINESS_REMEDIATION_PROJECT_OCID=<business-remediation-project-ocid>
+IMAGEPULL_REMEDIATION_PROJECT_OCID=<imagepull-remediation-project-ocid>
+HPA_REMEDIATION_PROJECT_OCID=<hpa-remediation-project-ocid>
+```
+
+The Function uses these payload values before falling back to `func.yaml` environment variables. This lets each OCI DevOps pipeline control its own topic, URLs, and remediation pipeline OCIDs.
+
+## Generic prompt payload
+
+Use this mode when OCI DevOps needs to ask a different question.
+
+```json
+{
+  "agentNamespace": "kagent",
+  "agentName": "k8s-agent",
+  "responseMode": "json",
+  "prompt": "Analiza el namespace kagent-demo. Identifica pods con ImagePullBackOff, causa raiz, imagen afectada y accion recomendada para OCI DevOps. Responde JSON valido con fields: status, failureType, rootCause, evidence, recommendedAction."
+}
+```
+
+For free-form answers:
+
+```json
+{
+  "agentNamespace": "kagent",
+  "agentName": "k8s-agent",
+  "responseMode": "text",
+  "prompt": "Resume el estado actual del namespace kagent-demo y separa eventos historicos de fallas activas."
+}
+```
+
+## Recommended generic JSON contract
+
+For OCI DevOps automation, prompts should request this kind of structure:
+
+```json
+{
+  "status": "HEALTHY|DEGRADED|FAILED",
+  "failureType": "OKE_PLATFORM_FAILURE|DEPENDENCY_FAILURE|DEPLOYMENT_FAILURE|BUSINESS_PROCESS_DEGRADATION|NO_ACTIVE_FAILURE",
+  "rootCause": "",
+  "evidence": [],
+  "recommendedAction": "CONTINUE|APPROVAL_REQUIRED|APPLY_CONFIGMAP_FIX|ROLLBACK|REDEPLOY",
+  "configMapPatchRequired": false,
+  "recommendedConfigMapData": {},
+  "deploymentsToRestart": []
+}
+```