feat: Add support for deploying K8s Agent as Helm Addon during cluster deployment

api/v1alpha1/addon_types.go

@@ -90,6 +90,9 @@ type NutanixAddons struct {
 
 	// +kubebuilder:validation:Optional
 	COSI *NutanixCOSI `json:"cosi,omitempty"`
+
+	// +kubebuilder:validation:Optional
+	KonnectorAgent *NutanixKonnectorAgent `json:"konnectorAgent,omitempty"`
 }
 
 type GenericAddons struct {
@@ -371,3 +374,15 @@ type Ingress struct {
 	// +kubebuilder:validation:Enum="aws-lb-controller"
 	Provider string `json:"provider"`
 }
+
+type NutanixKonnectorAgent struct {
+	// A reference to the Secret for credential information for the target Prism Central instance
+	// +kubebuilder:validation:Optional
+	Credentials *NutanixKonnectorAgentCredentials `json:"credentials,omitempty"`
+}
+
+type NutanixKonnectorAgentCredentials struct {
+	// A reference to the Secret containing the credentials used by the Konnector agent.
+	// +kubebuilder:validation:Required
+	SecretRef LocalObjectReference `json:"secretRef"`
+}

api/v1alpha1/constants.go

@@ -32,6 +32,8 @@ const (
 	ServiceLoadBalancerVariableName = "serviceLoadBalancer"
 	// RegistryAddonVariableName is the OCI registry config patch variable name.
 	RegistryAddonVariableName = "registry"
+	// KonnectorAgentVariableName is the Nutanix konnector-agent addon config patch variable name.
+	KonnectorAgentVariableName = "konnectorAgent"
 
 	// GlobalMirrorVariableName is the global image registry mirror patch variable name.
 	GlobalMirrorVariableName = "globalImageRegistryMirror"

api/v1alpha1/crds/caren.nutanix.com_nutanixclusterconfigs.yaml

@@ -235,6 +235,28 @@ spec:
                         - defaultStorage
                         - providers
                       type: object
+                    konnectorAgent:
+                      properties:
+                        credentials:
+                          description: A reference to the Secret for credential information for the target Prism Central instance
+                          properties:
+                            secretRef:
+                              description: A reference to the Secret containing the credentials used by the Konnector agent.
+                              properties:
+                                name:
+                                  description: |-
+                                    Name of the referent.
+                                    More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                                  maxLength: 253
+                                  minLength: 1
+                                  type: string
+                              required:
+                                - name
+                              type: object
+                          required:
+                            - secretRef
+                          type: object
+                      type: object
                     nfd:
                       description: NFD tells us to enable or disable the node feature discovery addon.
                       properties:

api/variables/aggregate_types.go

@@ -68,6 +68,12 @@ type Addons struct {
 	COSI *COSI `json:"cosi,omitempty"`
 
 	Ingress *Ingress `json:"ingress,omitempty"`
+
+	NutanixKonnectorAgent *NutanixKonnectorAgent `json:"konnectorAgent,omitempty"`
+}
+
+type NutanixKonnectorAgent struct {
+	carenv1.NutanixKonnectorAgent `json:",inline"`
 }
 
 type CSI struct {

charts/cluster-api-runtime-extensions-nutanix/README.md

@@ -90,6 +90,8 @@ A Helm chart for cluster-api-runtime-extensions-nutanix
 | hooks.csi.snapshot-controller.helmAddonStrategy.defaultValueTemplateConfigMap.name | string | `"default-snapshot-controller-helm-values-template"` |  |
 | hooks.ingress.awsLoadBalancerController.defaultValueTemplateConfigMap.create | bool | `true` |  |
 | hooks.ingress.awsLoadBalancerController.defaultValueTemplateConfigMap.name | string | `"default-aws-load-balancer-controller-helm-values-template"` |  |
+| hooks.konnectorAgent.helmAddonStrategy.defaultValueTemplateConfigMap.create | bool | `true` |  |
+| hooks.konnectorAgent.helmAddonStrategy.defaultValueTemplateConfigMap.name | string | `"default-konnector-agent-helm-values-template"` |  |
 | hooks.nfd.crsStrategy.defaultInstallationConfigMap.name | string | `"node-feature-discovery"` |  |
 | hooks.nfd.helmAddonStrategy.defaultValueTemplateConfigMap.create | bool | `true` |  |
 | hooks.nfd.helmAddonStrategy.defaultValueTemplateConfigMap.name | string | `"default-nfd-helm-values-template"` |  |

charts/cluster-api-runtime-extensions-nutanix/addons/konnector-agent/values-template.yaml

@@ -0,0 +1,12 @@
+agent:
+  name: {{ .AgentName }}
+  image:
+    repository: quay.io/karbon
+    name: k8s-agent
+pc:
+  port: {{ .PrismCentralPort }}
+  insecure: {{ .PrismCentralInsecure }} #set this to true if PC does not have https enabled
+  endpoint: {{ .PrismCentralHost }} # eg: ip or fqdn
+k8sClusterName: {{ .ClusterName }}
+k8sDistribution: NKP
+createSecret: false

charts/cluster-api-runtime-extensions-nutanix/templates/deployment.yaml

@@ -45,6 +45,7 @@ spec:
         - --csi.snapshot-controller.helm-addon.default-values-template-configmap-name={{ (index .Values.hooks.csi "snapshot-controller").helmAddonStrategy.defaultValueTemplateConfigMap.name }}
         - --ccm.aws.helm-addon.default-values-template-configmap-name={{ .Values.hooks.ccm.aws.helmAddonStrategy.defaultValueTemplateConfigMap.name }}
         - --cosi.controller.helm-addon.default-values-template-configmap-name={{ .Values.hooks.cosi.controller.helmAddonStrategy.defaultValueTemplateConfigMap.name }}
+        - --konnector-agent.helm-addon.default-values-template-configmap-name={{ .Values.hooks.konnectorAgent.helmAddonStrategy.defaultValueTemplateConfigMap.name }}
         {{- range $k, $v := .Values.hooks.ccm.aws.k8sMinorVersionToCCMVersion }}
         - --ccm.aws.aws-ccm-versions={{ $k }}={{ $v }}
         {{- end }}

charts/cluster-api-runtime-extensions-nutanix/templates/helm-config.yaml

@@ -35,6 +35,10 @@ data:
     ChartName: cosi
     ChartVersion: 0.0.1-alpha.5
     RepositoryURL: '{{ if .Values.helmRepository.enabled }}oci://helm-repository.{{ .Release.Namespace }}.svc/charts{{ else }}https://mesosphere.github.io/charts/stable/{{ end }}'
+  konnector-agent: |
+    ChartName: konnector-agent
+    ChartVersion: 1.3.0-rc.1
+    RepositoryURL: '{{ if .Values.helmRepository.enabled }}oci://helm-repository.{{ .Release.Namespace }}.svc/charts{{ else }}https://mesosphere.github.io/charts/stable{{ end }}'
   local-path-provisioner-csi: |
     ChartName: local-path-provisioner
     ChartVersion: 0.0.32

charts/cluster-api-runtime-extensions-nutanix/templates/konnector-agent/helm-addon-installation.yaml

@@ -0,0 +1,12 @@
+# Copyright 2025 Nutanix. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+{{- if .Values.hooks.konnectorAgent.helmAddonStrategy.defaultValueTemplateConfigMap.name }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: '{{ .Values.hooks.konnectorAgent.helmAddonStrategy.defaultValueTemplateConfigMap.name }}'
+data:
+  values.yaml: |-
+    {{- .Files.Get "addons/konnector-agent/values-template.yaml" | nindent 4 }}
+{{- end -}}

charts/cluster-api-runtime-extensions-nutanix/values.schema.json

@@ -520,6 +520,27 @@
                         }
                     }
                 },
+                "konnectorAgent": {
+                    "type": "object",
+                    "properties": {
+                        "helmAddonStrategy": {
+                            "type": "object",
+                            "properties": {
+                                "defaultValueTemplateConfigMap": {
+                                    "type": "object",
+                                    "properties": {
+                                        "create": {
+                                            "type": "boolean"
+                                        },
+                                        "name": {
+                                            "type": "string"
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
                 "nfd": {
                     "type": "object",
                     "properties": {

charts/cluster-api-runtime-extensions-nutanix/values.yaml

@@ -102,6 +102,11 @@ hooks:
       defaultValueTemplateConfigMap:
         create: true
         name: default-metallb-helm-values-template
+  konnectorAgent:
+    helmAddonStrategy:
+      defaultValueTemplateConfigMap:
+        create: true
+        name: default-konnector-agent-helm-values-template
   cosi:
     controller:
       helmAddonStrategy:

docs/content/addons/konnector-agent.md

@@ -0,0 +1,162 @@
++++
+title = "Konnector Agent Addon"
+icon = "fa-solid fa-plug"
++++
+
+The Konnector Agent addon enables automatic registration of Kubernetes clusters with Nutanix Prism Central. This addon leverages Cluster API lifecycle hooks to deploy the [Konnector Agent](https://portal.nutanix.com/page/documents/details?targetId=Prism-Central-Guide-vpc_7_3:mul-cluster-kubernetes-clusters-manage-pc-c.html) on the new clusters.
+
+## Overview
+
+Konnector Agent's addon management via CAREN(Cluster API Runtime Extensions - Nutanix) provides:
+
+- **Automatic cluster registration** with Nutanix Prism Central
+- **Lifecycle management** through Cluster API hooks
+- **Credential management** for secure Prism Central connectivity
+
+## Lifecycle Hooks
+
+The addon implements the following Cluster API lifecycle hooks:
+
+### AfterControlPlaneInitialized
+
+- **Purpose**: Deploys the Konnector Agent after the control plane is ready
+- **Timing**: Executes when the cluster control plane is fully initialized
+- **Actions**:
+  - Creates credentials secret on the target cluster
+  - Deploys the Konnector Agent using the specified strategy
+  - Configures Prism Central connectivity
+
+### BeforeClusterUpgrade
+
+- **Purpose**: Ensures the agent is properly configured before cluster upgrades
+- **Timing**: Executes before cluster upgrade operations
+- **Actions**: Re-applies the agent configuration if needed
+
+### BeforeClusterDelete
+
+- **Purpose**: Gracefully removes the Konnector Agent before cluster deletion
+- **Timing**: Executes before cluster deletion begins
+- **Actions**:
+  - Initiates graceful helm uninstall
+  - Waits for cleanup completion
+  - Ensures proper cleanup order
+
+## Configuration
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Cluster
+metadata:
+  name: my-cluster
+spec:
+  topology:
+    variables:
+      - name: clusterConfig
+        value:
+          addons:
+            konnectorAgent:
+              strategy: HelmAddon
+              credentials:
+                secretRef:
+                  name: cluster-name-pc-credentials-for-konnector-agent
+```
+
+## Configuration Reference
+
+### NutanixKonnectorAgent
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `strategy` | string | No | `HelmAddon` | Deployment strategy (`HelmAddon`) |
+| `credentials` | object | No | - | Prism Central credentials configuration |
+
+### NutanixKonnectorAgentCredentials
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `secretRef.name` | string | Yes | Name of the Secret containing Prism Central credentials |
+
+## Prerequisites
+
+### 1. Prism Central Credentials Secret
+
+Create a secret containing Prism Central credentials:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: cluster-name-pc-credentials-for-konnector-agent
+  namespace: default
+type: Opaque
+stringData:
+  username: admin
+  password: password
+```
+
+### Example Configuration
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Cluster
+metadata:
+  name: custom-credentials-cluster
+spec:
+  topology:
+    variables:
+      - name: clusterConfig
+        value:
+          addons:
+            konnectorAgent:
+              strategy: HelmAddon
+              credentials:
+                secretRef:
+                  name: cluster-name-pc-credentials-for-konnector-agent
+```
+
+## Default Values
+
+The addon uses the following default values:
+
+- **Helm Release Name**: `konnector-agent`
+- **Namespace**: `ntnx-system`
+- **Agent Name**: `konnector-agent`
+- **Strategy**: `HelmAddon`
+- **Chart**: `konnector-agent`
+- **Version**: `1.3.0-rc.1`
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Missing Credentials Secret**
+   - Ensure the secret exists in the management cluster
+   - Verify the secret name matches the configuration
+
+2. **Prism Central Connectivity**
+   - Check network connectivity between the cluster and Prism Central
+   - Verify the Prism Central endpoint is correct
+   - Ensure credentials are valid
+
+3. **Helm Chart Issues**
+   - Check the Helm repository is accessible
+   - Verify the chart version exists
+   - Review HelmChartProxy status
+
+### Monitoring
+
+Monitor the Konnector Agent deployment:
+
+```bash
+# Check HelmChartProxy status
+kubectl get hcp -A
+
+# Check agent logs
+kubectl logs hook-preinstall -n ntnx-system
+```
+
+## References
+
+- [Konnector Agent](https://portal.nutanix.com/page/documents/details?targetId=Prism-Central-Guide-vpc_7_3:mul-cluster-kubernetes-clusters-manage-pc-c.html)
+- [Cluster API Add-on Provider for Helm](https://github.com/kubernetes-sigs/cluster-api-addon-provider-helm)
+- [Cluster API Runtime Hooks](https://cluster-api.sigs.k8s.io/tasks/experimental-features/runtime-sdk/hooks.html)

examples/capi-quick-start/nutanix-cluster-calico-crs.yaml

@@ -90,6 +90,10 @@ spec:
                 strategy: HelmAddon
             snapshotController:
               strategy: HelmAddon
+          konnectorAgent:
+            credentials:
+              secretRef:
+                name: ${CLUSTER_NAME}-pc-creds-for-konnector-agent
           nfd:
             strategy: ClusterResourceSet
           serviceLoadBalancer: