### Install Project using kubectl

Source: https://github.com/nephio-project/nephio/blob/main/operators/focom-operator/README.md

Demonstrates how users can install the project by applying the generated 'install.yaml' file using kubectl. This file contains all necessary resources for installation.

```sh
kubectl apply -f https://raw.githubusercontent.com/<org>/focom-operator/<tag or branch>/dist/install.yaml
```

--------------------------------

### Build Installer Command

Source: https://github.com/nephio-project/nephio/blob/main/operators/focom-operator/README.md

This command is used to build the installer for the operator image, which includes Kustomize-built resources necessary for project installation.

```sh
make build-installer IMG=<some-registry>/focom-operator:tag
```

--------------------------------

### Detailed Reconcile Flow Example

Source: https://github.com/nephio-project/nephio/blob/main/operators/focom-operator/README.md

Provides a more granular example of the reconciliation flow, illustrating conditional logic and the role of helper methods like handleDeletion.

```text
Fetch CR → if not found, done.
If being deleted → handleDeletion(...) → done.
If no finalizer → add finalizer → requeue.
Validate → if invalid, set status → done.
Build remote → if fails, set status → done.
Ensure remote resource (create or poll) → set status → requeue if needed
```

--------------------------------

### Nephio Controller Manager Setup and Configuration (Go)

Source: https://context7.com/nephio-project/nephio/llms.txt

Sets up and configures the Nephio Controller Manager, initializing reconcilers, and integrating with IPAM/VLAN backends. It uses the controller-runtime library and supports various command-line flags for enabling specific reconcilers and configuring backend addresses.

```go
package main

import (
    "context"
    "os"
    "github.com/nephio-project/nephio/controllers/pkg/reconcilers/config"
    "github.com/nokia/k8s-ipam/pkg/proxy/clientproxy"
    "github.com/nokia/k8s-ipam/pkg/proxy/clientproxy/ipam"
    "github.com/nokia/k8s-ipam/pkg/proxy/clientproxy/vlan"
    ctrl "sigs.k8s.io/controller-runtime"
)

func main() {
    ctx := context.Background()

    // Configure controller manager with reconcilers
    mgr, _ := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
        Scheme: scheme,
        Metrics: server.Options{BindAddress: ":8080"},
        HealthProbeBindAddress: ":8081",
        LeaderElection: false,
        LeaderElectionID: "nephio-operators.nephio.org",
    })

    // Backend configuration for IPAM and VLAN
    backendAddress := os.Getenv("CLIENT_PROXY_ADDRESS")
    if backendAddress == "" {
        backendAddress = "127.0.0.1:9999"
    }

    // Controller configuration
    ctrlCfg := &config.ControllerConfig{
        Address: backendAddress,
        PorchClient: porchClient,
        PorchRESTClient: porchRESTClient,
        IpamClientProxy: ipam.New(ctx, clientproxy.Config{
            Address: backendAddress,
        }),
        VlanClientProxy: vlan.New(ctx, clientproxy.Config{
            Address: backendAddress,
        }),
        ApprovalRequeueDuration: 15,
    }

    // Start with enabled reconcilers
    mgr.Start(ctx)
}

// Command line usage:
// # Enable all reconcilers
// ./controller-manager --reconcilers=* --metrics-bind-address=:8080
//
// # Enable specific reconcilers
// ./controller-manager --reconcilers=approval,network,repository
//
// # Configure IPAM backend
// export CLIENT_PROXY_ADDRESS="ipam-service.nephio-system:9999"
// ./controller-manager --reconcilers=*
//
// Available reconcilers:
// - approval: Auto-approves package revisions
// - bootstrap-packages: Bootstraps initial packages
// - bootstrap-secret: Manages bootstrap secrets
// - generic-specializer: Runs KRM functions on packages
// - network: Manages network resources
// - repository: Manages Porch repositories
// - spire-bootstrap: Manages SPIRE security
// - token: Manages authentication tokens

```

--------------------------------

### Example Environment Variables for Gitea Connection

Source: https://github.com/nephio-project/nephio/blob/main/controllers/pkg/reconcilers/token/README.md

This snippet shows example environment variables used to configure the token controller's connection to the Gitea server. It includes the mandatory GIT_URL and optionally GIT_SECRET_NAME and GIT_NAMESPACE for custom secret configurations.

```yaml
- name: "GIT_URL"
  value: "https://172.18.0.200:3000"
```

--------------------------------

### Example Token CRD with Application Annotation

Source: https://github.com/nephio-project/nephio/blob/main/controllers/pkg/reconcilers/token/README.md

This YAML example illustrates the creation of a Token CRD with an annotation specifying the associated application. This particular instance is for 'mgmt-access-token-configsync' and is linked to the 'configsync' application.

```yaml
cat <<EOF | kubectl apply -f - 
    apiVersion: infra.nephio.org/v1alpha1
    kind: Token
    metadata:
      name: mgmt-access-token-configsync
      annotations:
        nephio.org/app: configsync
    spec:
EOF
```

--------------------------------

### Example Token CRD for Management Access

Source: https://github.com/nephio-project/nephio/blob/main/controllers/pkg/reconcilers/token/README.md

This YAML example demonstrates how to create a Token Custom Resource Definition (CRD) in Kubernetes. This specific example is for a 'mgmt-access-token-porch', managing access tokens.

```yaml
cat <<EOF | kubectl apply -f - 
    apiVersion: infra.nephio.org/v1alpha1
    kind: Token
    metadata:
      name: mgmt-access-token-porch
    spec:
EOF
```

--------------------------------

### FOCOM Operator Provisioning Request Controller Setup (Go)

Source: https://context7.com/nephio-project/nephio/llms.txt

Initializes and runs the FOCOM Operator's provisioning request controller. This Go code demonstrates creating a FocomProvisioningRequest object and configuring the controller-runtime manager for its lifecycle management. It also outlines command-line usage and health check endpoints.

```go
package main

import (
    "context"
    focomv1alpha1 "github.com/nephio-project/nephio/operators/focom-operator/api/focom/v1alpha1"
    provisioningv1alpha1 "github.com/nephio-project/nephio/operators/focom-operator/api/provisioning/v1alpha1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
)

func main() {
    // Create provisioning request
    provReq := &focomv1alpha1.FocomProvisioningRequest{
        TypeMeta: metav1.TypeMeta{
            APIVersion: "focom.nephio.org/v1alpha1",
            Kind:       "FocomProvisioningRequest",
        },
        ObjectMeta: metav1.ObjectMeta{
            Name:      "upf-provisioning",
            Namespace: "default",
        },
        Spec: focomv1alpha1.FocomProvisioningRequestSpec{
            // Provisioning specifications
        },
    }

    // Controller reconciles provisioning requests
    // Manages lifecycle of network function deployments

    // Start FOCOM operator
    mgr, _ := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
        Scheme: scheme,
        Metrics: metricsserver.Options{
            BindAddress: ":8443",
            SecureServing: true,
        },
        HealthProbeBindAddress: ":8081",
        LeaderElection: false,
        LeaderElectionID: "7ad7da43.nephio.org",
    })

    mgr.Start(ctrl.SetupSignalHandler())
}

// Command line usage:
// # Start with secure metrics (default)
// ./focom-operator --metrics-bind-address=:8443 --metrics-secure=true
//
// # Start with HTTP/2 disabled (recommended for production)
// ./focom-operator --enable-http2=false
//
// # Enable leader election for HA
// ./focom-operator --leader-elect=true
//
// Health endpoints:
// - GET /healthz (health check)
// - GET /readyz (readiness check)
// - GET /metrics (Prometheus metrics - requires authentication)

```

--------------------------------

### Example 'for' Resource Filter Definition in Go

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

This Go code illustrates a specific example of defining a 'for' KRM resource filter. It sets the APIVersion to 'example.com/v1alpha1' and the Kind to 'A'. This configuration allows the SDK to identify and process all KRM resource instances of Kind 'A' within the specified API group and version.

```go
For: corev1.ObjectReference{
    APIVersion: "example.com/v1alpha1",
    Kind:       "A",
}
```

--------------------------------

### Example Secret for Bootstrap Secret Controller (YAML)

Source: https://github.com/nephio-project/nephio/blob/main/controllers/pkg/reconcilers/bootstrap-secret/README.md

This example demonstrates a Kubernetes Secret manifest configured for the Bootstrap Secret Controller. It includes annotations that specify the target cluster and namespace for installation, along with the application identifier.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: example-site-name-access-token-configsync
  namespace: default
  annotations:
    nephio.org/gitops: configsync
    nephio.org/app: tobeinstalledonremotecluster
    nephio.org/remote-namespace: config-management-system
    nephio.org/cluster-name: edge01
...
```

--------------------------------

### Provisioning Request CR Example (YAML)

Source: https://github.com/nephio-project/nephio/blob/main/operators/o2ims-operator/README.md

This YAML defines a sample ProvisioningRequest Custom Resource (CR) used by the Nephio O2IMS operator. It includes metadata such as annotations and timestamps, along with specifications for the desired cluster configuration, including template name, parameters, and version.

```yaml
apiVersion: o2ims.provisioning.oran.org/v1alpha1
kind: ProvisioningRequest
metadata:
  annotations:
    provisioningrequests.o2ims.provisioning.oran.org/kopf-managed: "yes"
    provisioningrequests.o2ims.provisioning.oran.org/last-ha-a.A3qw: |
      {"spec":{"description":"Provisioning request for setting up a test kind cluster.","name":"test-env-Provisioning","templateName":"nephio-workload-cluster","templateParameters":{"clusterName":"edge","labels":{"nephio.org/region":"europe-paris-west","nephio.org/site-type":"edge"},"templateVersion":"v3.0.0"}}
    provisioningrequests.o2ims.provisioning.oran.org/last-handled-configuration: |
      {"spec":{"description":"Provisioning request for setting up a test kind cluster.","name":"test-env-Provisioning","templateName":"nephio-workload-cluster","templateParameters":{"clusterName":"edge","labels":{"nephio.org/region":"europe-paris-west","nephio.org/site-type":"edge"},"templateVersion":"v3.0.0"}}
  creationTimestamp: "2025-01-31T13:50:46Z"
  generation: 1
  name: provisioning-request-sample
  resourceVersion: "12122"
  uid: e8377db2-5652-4bc6-9632-8ce0836c6afd
spec:
  description: Provisioning request for setting up a test kind cluster.
  name: test-env-Provisioning
  templateName: nephio-workload-cluster
  templateParameters:
    clusterName: edge
    labels:
      nephio.org/site-type: edge
      nephio.org/region: europe-paris-west
      nephio.org/owner: nephio-o2ims
  templateVersion: v3.0.0
status:
  provisionedResourceSet:
    oCloudInfrastructureResourceIds:
    - cb92ece1-7272-4e01-9d5c-11e47b2e2473
    oCloudNodeClusterId: 09470fe4-cff6-4362-a7d6-badc77dbf059
  provisioningStatus:
    provisioningMessage: Cluster resource created
    provisioningState: fulfilled
    provisioningUpdateTime: "2025-01-31T14:52:21Z"
```

--------------------------------

### Generated ConfigMap Example (YAML)

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/gen-configmap-fn/README.md

An example of a ConfigMap generated by the gen-configmap-fn based on the provided FunctionConfig. It includes both literal data and rendered template values.

```yaml
kind: ConfigMap
metadata:
  name: my-configmap
  labels:
    foo: bar
data:
  dburl: https://foo.example.com:8992/us-east1/db
  hello: there
```

--------------------------------

### Example Repository CRD Definition

Source: https://github.com/nephio-project/nephio/blob/main/controllers/pkg/reconcilers/repository/README.md

This snippet demonstrates the definition of a custom resource definition (CRD) for a 'Repository' in Nephio. It shows how to create a 'Repository' resource named 'mgmt' using kubectl apply.

```yaml
cat <<EOF | kubectl apply -f -
    apiVersion: infra.nephio.org/v1alpha1
    kind: Repository
    metadata:
      name: mgmt
    spec:
EOF
```

--------------------------------

### Example KRM Package with Multiple 'A' Resources

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

This YAML snippet shows a kpt package containing multiple instances of the KRM resource with Kind 'A' and APIVersion 'example.com/v1alpha1'. The condkptsdk will process each of these instances ('a1', 'a2', 'a3') as individual 'forKRMInstance' objects based on the defined 'for' filter.

```yaml
apiVersion: example.com/v1alpha1
kind: A
metadata:
  name: a1

apiVersion: example.com/v1alpha1
kind: A
metadata:
  name: a2

apiVersion: example.com/v1alpha1
kind: A
metadata:
  name: a3
```

--------------------------------

### Makefile Help Command

Source: https://github.com/nephio-project/nephio/blob/main/operators/focom-operator/README.md

Running 'make help' provides information on all available targets within the project's Makefile, which can be useful for development and build tasks.

```sh
make help
```

--------------------------------

### Provisioning Request Creation Controller (Python)

Source: https://github.com/nephio-project/nephio/blob/main/operators/o2ims-operator/README.md

This Python controller handles the creation of package variants for Porch, which are then applied to the cluster where Porch is running. It monitors the cluster creation process by querying the 'clusters.cluster.x-k8s.io' endpoint. Future enhancements will include querying packageRevisions, addressing current issues with Porch's request processing.

```python
from kopf import operator
from kubernetes import client, config
import time

@operator.on_create('provisioningrequests.o2ims.provisioning.oran.org')
def provisioning_request_creation_controller(meta: dict, spec: dict, logger):
    cluster_name = spec['templateParameters']['clusterName']
    package_variant_name = f"pkg-{cluster_name}"

    # Logic to create package variant for Porch would go here...
    logger.info(f"Creating package variant: {package_variant_name}")

    # Logic to apply package variant to the cluster...
    logger.info(f"Applying package variant to cluster: {cluster_name}")

    # Wait for cluster creation by querying clusters.cluster.x-k8s.io
    api = client.CustomObjectsApi()
    group = 'cluster.x-k8s.io'
    version = 'v1beta1'
    plural = 'clusters'

    while True:
        try:
            cluster = api.get_namespaced_custom_object(group=group, version=version, plural=plural, name=cluster_name)
            if cluster.get('status', {}).get('phase') == 'Provisioned':
                logger.info(f"Cluster {cluster_name} provisioned successfully.")
                break
        except client.ApiException as e:
            logger.error(f"Error querying cluster {cluster_name}: {e}")
        
        time.sleep(30) # Poll every 30 seconds

    # TODO: Add logic for querying packageRevisions once porch issues are resolved.
```

--------------------------------

### Setting up Controller Reconciler with Manager in Nephio

Source: https://github.com/nephio-project/nephio/blob/main/operators/nephio-controller-manager/README.md

This code illustrates the `SetupWithManager` method, which is implemented by all Nephio controller reconcilers. This method is responsible for registering the reconciler with the Nephio-controller-manager operator. It returns a map of GroupVersionKind to GenericEvent channels and an error, facilitating the integration of the reconciler into the manager's control loop.

```go
func (r *reconciler) SetupWithManager(mgr ctrl.Manager, i interface{}) (map[schema.GroupVersionKind]chan event.GenericEvent, error) {
  // Implementation details...
}
```

--------------------------------

### Update Kptfile with NAD Function Status Conditions

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/nad-fn/README.md

This example shows how the NAD function updates the Kptfile's status with conditions to indicate the fulfillment of NetworkAttachmentDefinition requests. It includes a condition detailing the status of a specific NAD resource associated with an Interface.

```yaml
apiVersion: kpt.dev/v1
kind: Kptfile
metadata:
    name: pkg-upf
    annotations:
        config.kubernetes.io/local-config: "true"
pipeline:
  mutators:
    - image: docker.io/nephio/interface-fn:v1
    - image: docker.io/nephio/dnn-fn:v1
    - image: docker.io/nephio/nad-fn:v1
    - .....
  status:
      conditions:
        - message: update done
          reason: req.nephio.org/v1alpha1.Interface.n3
          status: "True"
          type: k8s.cni.cncf.io/v1.NetworkAttachmentDefinition.n3

```

--------------------------------

### Build and Push Docker Image for ipam-fn

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/ipam-fn/README.md

Provides the make commands required to build the docker image for the ipam-fn and push it to a registry. These are essential for deployment.

```bash
make docker-build; make docker-push
```

--------------------------------

### Run NAD Reconciler - Go

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

Initializes and runs the Network Attachment Definition (NAD) reconciler. It sets up the SDK with necessary configurations, including watching for WorkloadCluster, IPClaim, VLANClaim, and Interface resources. The `PopulateOwnResourcesFn` is set to nil, indicating it doesn't own these resources. It returns an error if initialization fails or if the SDK run encounters an issue.

```Go
package main

import (
	"reflect"

	"github.com/nephio-project/nephio/apis/inv/v1alpha1"
	"github.com/nephio-project/nephio/pkg/oci"
	infrav1alpha1 "github.com/nephio-project/nephio/apis/inv/v1alpha1"
	ipamv1alpha1 "github.com/nephio-project/nephio/apis/ipam/v1alpha1"
	nephioreqv1alpha1 "github.com/nephio-project/nephio/apis/common/v1alpha1"
	vlanv1alpha1 "github.com/nephio-project/nephio/apis/vlan/v1alpha1"
	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime/schema"
	
	fn "github.com/GoogleContainerTools/kpt-functions-sdk/go/fn"
	ko "github.com/GoogleContainerTools/kpt-functions-sdk/go/fn/objectutil"
	nadv1 "github.com/nephio-project/nephio/apis/nad/v1alpha1"
	nadlibv1 "github.com/nephio-project/nephio/controllers/nad"
)

type nadFn struct {
	sdk             fn.KptCondSDK
	workloadCluster *infrav1alpha1.WorkloadCluster
}

func Run(rl *fn.ResourceList) (bool, error) {
	myFn := nadFn{}
	var err error
	myFn.sdk, err = fn.NewKptCondSDK(
		rl,
		&fn.Config{
			For: corev1.ObjectReference{
				APIVersion: nadv1.SchemeGroupVersion.Identifier(),
				Kind:       reflect.TypeOf(nadv1.NetworkAttachmentDefinition{}).Name(),
			},
			Watch: map[corev1.ObjectReference]fn.WatchCallbackFn{
				{
					APIVersion: infrav1alpha1.GroupVersion.Identifier(),
					Kind:       reflect.TypeOf(infrav1alpha1.WorkloadCluster{}).Name(),
				}: myFn.WorkloadClusterCallbackFn,
				{
					APIVersion: ipamv1alpha1.GroupVersion.Identifier(),
					Kind:       ipamv1alpha1.IPClaimKind,
				}: nil,
				{
					APIVersion: vlanv1alpha1.GroupVersion.Identifier(),
					Kind:       vlanv1alpha1.VLANClaimKind,
				}: nil,
				{
					APIVersion: nephioreqv1alpha1.GroupVersion.Identifier(),
					Kind:       nephioreqv1alpha1.InterfaceKind,
				}: nil,
			},
			PopulateOwnResourcesFn: nil,
			UpdateResourceFn:       myFn.updateResourceFn,
		},
	)
	if err != nil {
		rl.Results.ErrorE(err)
		return false, err
	}
	return myFn.sdk.Run()
}

// WorkloadClusterCallbackFn provides a callback for the workload cluster
// resources in the resourceList
func (f *nadFn) WorkloadClusterCallbackFn(o *fn.KubeObject) error {
	var err error

	if f.workloadCluster != nil {
		return fmt.Errorf("multiple WorkloadCluster objects found in the kpt package")
	}
	f.workloadCluster, err = ko.KubeObjectToStruct[infrav1alpha1.WorkloadCluster](o)
	if err != nil {
		return err
	}

	// validate check the specifics of the spec, like mandatory fields
	return f.workloadCluster.Spec.Validate()
}

func (f *nadFn) updateResourceFn(forObj *fn.KubeObject, objs fn.KubeObjects) (*fn.KubeObject, error) {
	if f.workloadCluster == nil {
		// no WorkloadCluster resource in the package
		return nil, fmt.Errorf("workload cluster is missing from the kpt package")
	}
	ipClaimObjs := objs.Where(fn.IsGroupVersionKind(schema.GroupVersionKind(ipamv1alpha1.IPClaimGroupVersionKind)))
	vlanClaimObjs := objs.Where(fn.IsGroupVersionKind(schema.GroupVersionKind(vlanv1alpha1.VLANClaimGroupVersionKind)))
	interfaceObjs := objs.Where(fn.IsGroupVersionKind(nephioreqv1alpha1.InterfaceGroupVersionKind))

	fn.Logf("nad updateResourceFn: ifObj: %d, ipClaimObj: %d, vlanClaimObj: %d\n", len(interfaceObjs), len(ipClaimObjs), len(vlanClaimObjs))
	// verify all needed objects exist
	if interfaceObjs.Len() == 0 {
		return nil, fmt.Errorf("expected %s object to generate the nad", nephioreqv1alpha1.InterfaceKind)
	}
	if ipClaimObjs.Len() == 0 && vlanClaimObjs.Len() == 0 {
		return nil, fmt.Errorf("expected one of %s or %s objects to generate the nad", ipamv1alpha1.IPClaimKind, vlanv1alpha1.VLANClaimKind)
	}

	// generate an empty nad struct
	nad, err := nadlibv1.NewFromGoStruct(&nadv1.NetworkAttachmentDefinition{
		TypeMeta: metav1.TypeMeta{
			APIVersion: nadv1.SchemeGroupVersion.Identifier(),
			Kind:       reflect.TypeOf(nadv1.NetworkAttachmentDefinition{}).Name(),
		},
		ObjectMeta: metav1.ObjectMeta{Name: interfaceObjs[0].GetName()},
	})
	if err != nil {
		return nil, err
	}

	if ipClaimObjs.Len() == 0 && vlanClaimObjs.Len() != 0 {
		nad.CniSpecType = nadlibv1.VlanClaimOnly
	}
	if nad.CniSpecType != nadlibv1.VlanClaimOnly {
		for _, itfce := range interfaceObjs {
			i, err := ko.NewFromKubeObject[nephioreqv1alpha1.Interface](itfce)
			if err != nil {
				return nil, err
			}

			itfceGoStruct, err := i.GetGoStruct()
			if err != nil {
				return nil, err
			}

			if !f.IsCNITypePresent(itfceGoStruct.Spec.CNIType) {
				return nil, fmt.Errorf("cniType not supported in workload cluster; workload cluster CNI(s): %v, interface cniType requested: %s", f.workloadCluster.Spec.CNIs, itfceGoStruct.Spec.CNIType)
			}

			if err := nad.SetCNIType(string(itfceGoStruct.Spec.CNIType)); err != nil {
				return nil, err
			}
			err = nad.SetNadMaster(*f.workloadCluster.Spec.MasterInterface) // since we validated the workload cluster before it is safe to do this
			if err != nil {
				return nil, err
			}
		}

		for _, ipClaim := range ipClaimObjs {
			claim, err := ko.NewFromKubeObject[ipamv1alpha1.IPClaim](ipClaim)
			if err != nil {
				return nil, err
			}

			ipclaimGoStruct, err := claim.GetGoStruct()
			if err != nil {
				return nil, err
			}
			address := ""
			gateway := ""
			if ipclaimGoStruct.Status.Prefix != nil {
				address = *ipclaimGoStruct.Status.Prefix
			}
			if ipclaimGoStruct.Status.Gateway != nil {
				gateway = *ipclaimGoStruct.Status.Gateway
			}
			err = nad.SetIpamAddress([]nadlibv1.Addresses{{ 
				Address: address,
				Gateway: gateway,
			}})
			if err != nil {
				return nil, err
			}
		}
	}

	for _, vlanClaim := range vlanClaimObjs {
		vlanID, _, _ := vlanClaim.NestedInt([]string{"status", "vlanID"}...)
		err = nad.SetVlan(vlanID)
		if err != nil {
			return nil, err
		}
	}
	return nad.GetKubeObject(), nil
}

func (f *nadFn) IsCNITypePresent(cniType string) bool {
	if f.workloadCluster == nil {
		return false
	}
	for _, cni := range f.workloadCluster.Spec.CNIs {
		if cni == cniType {
			return true
		}
	}
	return false
}

```

--------------------------------

### Configure and Run KRM Function with Conditional KPT SDK in Go

Source: https://context7.com/nephio-project/nephio/llms.txt

Demonstrates how to configure and run a KRM function using the conditional KPT SDK. It sets up resource ownership, watches for external resources, and defines callbacks for generating and updating resources. This function is designed for the Nephio project.

```go
package main

import (
    "github.com/kptdev/krm-functions-sdk/go/fn"
    "github.com/nephio-project/nephio/krm-functions/lib/condkptsdk"
    corev1 "k8s.io/api/core/v1"
)

func main() {
    // Configure KRM function with ownership and watch relationships
    config := &condkptsdk.Config{
        For: corev1.ObjectReference{
            APIVersion: "req.nephio.org/v1alpha1",
            Kind:       "Interface",
        },
        Owns: map[corev1.ObjectReference]condkptsdk.ResourceKind{
            {
                APIVersion: "ipam.resource.nephio.org/v1alpha1",
                Kind:       "IPClaim",
            }: condkptsdk.ChildRemote,
            {
                APIVersion: "vlan.resource.nephio.org/v1alpha1",
                Kind:       "VLANClaim",
            }: condkptsdk.ChildRemote,
        },
        Watch: map[corev1.ObjectReference]condkptsdk.WatchCallbackFn{
            {
                APIVersion: "infra.nephio.org/v1alpha1",
                Kind:       "WorkloadCluster",
            }: workloadClusterCallback,
        },
        PopulateOwnResourcesFn: generateChildResources,
        UpdateResourceFn: updateParentStatus,
    }

    // Run KRM function
    var rl *fn.ResourceList // Provided by KRM runtime
    sdk, err := condkptsdk.New(rl, config)
    if err != nil {
        rl.Results.ErrorE(err)
        return
    }

    changed, err := sdk.Run()
    if err != nil {
        rl.Results.ErrorE(err)
        return
    }
    // changed=true indicates resources were modified
}

// Callback functions
func workloadClusterCallback(o *fn.KubeObject) error {
    // Process WorkloadCluster resources
    return nil
}

func generateChildResources(parent *fn.KubeObject) (fn.KubeObjects, error) {
    // Generate owned child resources (IPClaim, VLANClaim)
    return fn.KubeObjects{}, nil
}

func updateParentStatus(parent *fn.KubeObject, children fn.KubeObjects) (fn.KubeObjects, error) {
    // Update parent status based on child resource states
    return fn.KubeObjects{parent}, nil
}

// ResourceKind types:
// - ChildLocal: Child resource stored in same package
// - ChildRemote: Child resource managed remotely (e.g., IPAM backend)
// - ChildRemoteCondition: Remote child with condition status tracking

```

--------------------------------

### Update Package Revision Approval - Go

Source: https://context7.com/nephio-project/nephio/llms.txt

Updates the lifecycle state of a Porch PackageRevision from 'Proposed' to 'Published' or 'DeletionProposed' using the approval subresource endpoint. It fetches the current revision, modifies its lifecycle state, and then updates it via the dedicated approval endpoint. Handles errors during the GET or PUT operations.

```go
package main

import (
    "context"
    "github.com/nephio-project/porch/api/porch/v1alpha1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/rest"
    "k8s.io/apimachinery/pkg/runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
)

func UpdatePackageRevisionApproval(ctx context.Context, restClient rest.Interface, key client.ObjectKey, newLifecycle v1alpha1.PackageRevisionLifecycle) error {
    scheme := runtime.NewScheme()
    v1alpha1.SchemeBuilder.AddToScheme(scheme)
    codec := runtime.NewParameterCodec(scheme)

    // Get current package revision
    var pr v1alpha1.PackageRevision
    err := restClient.Get().
        Namespace(key.Namespace).
        Resource("packagerevisions").
        Name(key.Name).
        VersionedParams(&metav1.GetOptions{}, codec).
        Do(ctx).
        Into(&pr)
    if err != nil {
        return err
    }

    // Change lifecycle to Published
    pr.Spec.Lifecycle = newLifecycle

    // Update via approval subresource
    result := &v1alpha1.PackageRevision{}
    return restClient.Put().
        Namespace(pr.Namespace).
        Resource("packagerevisions").
        Name(pr.Name).
        SubResource("approval").
        VersionedParams(&metav1.UpdateOptions{}, codec).
        Body(&pr).
        Do(ctx).
        Into(result)
}

// Example usage:
func main() {
    ctx := context.Background()
    restClient := getRESTClient() // Configured rest.Interface

    // Approve package for deployment
    err := UpdatePackageRevisionApproval(
        ctx,
        restClient,
        client.ObjectKey{
            Namespace: "default",
            Name:      "free5gc-upf-edge01-v1",
        },
        v1alpha1.PackageRevisionLifecyclePublished,
    )
    if err != nil {
        panic(err)
    }

    // Expected result: Package moves from Proposed -> Published
    // Error if lifecycle is not Proposed or already at target state
}

```

--------------------------------

### Setting Status and Returning Results in Go

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

This final Go snippet demonstrates how to set the status of an interface using an error-handling mechanism and return the updated Kubernetes object along with any potential errors. This is a standard pattern for completing operations in Go.

```go
// set the status
	err = itfceKOE.SetStatus(itfce)
	return &itfceKOE.KubeObject, err
}
```

--------------------------------

### Allocate IP Address with Nephio IPAM Function (Go)

Source: https://context7.com/nephio-project/nephio/llms.txt

Demonstrates how to use the Nephio IPAM function client to claim an IPv4 prefix for a network interface. It requires the kptdev/krm-functions-sdk and nokia/k8s-ipam libraries. The function takes a context and an IPClaim object, and returns an IPAM response containing the allocated prefix and gateway.

```go
package main

import (
    "context"
    "github.com/kptdev/krm-functions-sdk/go/fn"
    ipamv1alpha1 "github.com/nokia/k8s-ipam/apis/resource/ipam/v1alpha1"
    "github.com/nokia/k8s-ipam/pkg/proxy/clientproxy/ipam"
    resourcev1alpha1 "github.com/nokia/k8s-ipam/apis/resource/common/v1alpha1"
    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

func main() {
    // Create IPAM client proxy
    clientProxy := ipam.New(context.Background(), clientproxy.Config{
        Address: "127.0.0.1:9999",
    })

    // Create IP claim for network interface
    claim := ipamv1alpha1.BuildIPClaim(
        metav1.ObjectMeta{
            Name: "upf-n3-ipv4",
            Annotations: map[string]string{
                resourcev1alpha1.NephioClusterNameKey: "edge-cluster-01",
            },
        },
        ipamv1alpha1.IPClaimSpec{
            Kind: ipamv1alpha1.PrefixKindNetwork,
            NetworkInstance: corev1.ObjectReference{
                Name: "vpc-ran",
            },
            ClaimLabels: resourcev1alpha1.ClaimLabels{
                Selector: &metav1.LabelSelector{
                    MatchLabels: map[string]string{
                        resourcev1alpha1.NephioClusterNameKey:   "edge-cluster-01",
                        resourcev1alpha1.NephioAddressFamilyKey: "ipv4",
                        resourcev1alpha1.NephioNetworkNameKey:   "n3",
                    },
                },
            },
        },
        ipamv1alpha1.IPClaimStatus{},
    )

    // Claim IP address from IPAM backend
    resp, err := clientProxy.Claim(context.Background(), claim, nil)
    if err != nil {
        panic(err)
    }

    // Expected output: resp.Status.Prefix = "10.0.1.0/24"
    // Expected output: resp.Status.Gateway = "10.0.1.1"
}
```

--------------------------------

### Run Nephio Controller with Owns Configuration (Golang)

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

This Go function demonstrates the initialization and execution of a Nephio controller. It configures the controller with 'owns' rules for managing dependent resources like NetworkAttachmentDefinitions and IPClaims, and 'watch' rules for observing WorkloadCluster resources. The function utilizes the condkptsdk for Kubernetes dynamic control plane operations.

```golang
package main

import (
	"fmt"
	"reflect"

	"github.com/nephio-project/api/ipam/v1alpha1"
	"github.com/nephio-project/api/nephio/v1alpha1"
	"github.com/nephio-project/nephio/internal/ipclaim"
	"github.com/nephio-project/nephio/internal/ko"
	"github.com/nephio-project/nephio/internal/log"
	"github.com/nephio-project/nephio/internal/meta"
	"github.com/nephio-project/nephio/internal/networkattachmentdefinition"
	"github.com/nephio-project/nephio/internal/vlanclaim"
	infrav1alpha1 "github.com/nephio-project/nephio/internal/workloadcluster/api/v1alpha1"
	"github.com/nephio-project/nephio/pkg/condkptsdk"
	"github.com/nephio-project/nephio/pkg/fn"
	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

const defaultPODNetwork = "pod"

type itfceFn struct {
	sdk             condkptsdk.KptCondSDK
	workloadCluster *infrav1alpha1.WorkloadCluster
}

func Run(rl *fn.ResourceList) (bool, error) {
	myFn := itfceFn{}
	var err error
	myFn.sdk, err = condkptsdk.New(
		rl,
		&condkptsdk.Config{
			For: corev1.ObjectReference{
				APIVersion: nephioreqv1alpha1.GroupVersion.Identifier(),
				Kind:       nephioreqv1alpha1.InterfaceKind,
			},
			Owns: map[corev1.ObjectReference]condkptsdk.ResourceKind{
				{
					APIVersion: nadv1.SchemeGroupVersion.Identifier(),
					Kind:       reflect.TypeOf(nadv1.NetworkAttachmentDefinition{}).Name(),
				}: condkptsdk.ChildRemoteCondition,
				{
					APIVersion: ipamv1alpha1.GroupVersion.Identifier(),
					Kind:       ipamv1alpha1.IPClaimKind,
				}: condkptsdk.ChildRemote,
				{
					APIVersion: vlanv1alpha1.GroupVersion.Identifier(),
					Kind:       vlanv1alpha1.VLANClaimKind,
				}: condkptsdk.ChildRemote,
			},
			Watch: map[corev1.ObjectReference]condkptsdk.WatchCallbackFn{
				{
					APIVersion: infrav1alpha1.GroupVersion.Identifier(),
					Kind:       reflect.TypeOf(infrav1alpha1.WorkloadCluster{}).Name(),
				}: myFn.WorkloadClusterCallbackFn,
			},
			PopulateOwnResourcesFn: myFn.desiredOwnedResourceList,
			UpdateResourceFn:       myFn.updateItfceResource,
		},
	)
	if err != nil {
		rl.Results.ErrorE(err)
		return false, err
	}
	return myFn.sdk.Run()
}

// WorkloadClusterCallbackFn provides a callback for the workload cluster
// resources in the resourceList
func (f *itfceFn) WorkloadClusterCallbackFn(o *fn.KubeObject) error {
	var err error

	if f.workloadCluster != nil {
		return fmt.Errorf("multiple WorkloadCluster objects found in the kpt package")
	}
	f.workloadCluster, err = ko.KubeObjectToStruct[infrav1alpha1.WorkloadCluster](o)
	if err != nil {
		return err
	}

	// validate check the specifics of the spec, like mandatory fields
	return f.workloadCluster.Spec.Validate()
}

// desiredOwnedResourceList returns with the list of all child KubeObjects
// belonging to the parent Interface "for object"
func (f *itfceFn) desiredOwnedResourceList(o *fn.KubeObject) (fn.KubeObjects, error) {
	if f.workloadCluster == nil {
		// no WorkloadCluster resource in the package
		return nil, fmt.Errorf("workload cluster is missing from the kpt package")
	}
	// resources contain the list of child resources
	// belonging to the parent object
	resources := fn.KubeObjects{}

	itfceKOE, err := ko.NewFromKubeObject[nephioreqv1alpha1.Interface](o)
	if err != nil {
		return nil, err
	}

	itfce, err := itfceKOE.GetGoStruct()
	if err != nil {
		return nil, err
	}

	// Nothing to be done in case the interface is attached to
	// the default pod network since this is all handled in the
	// k8s cluster via the CNI.
	if itfce.Spec.NetworkInstance.Name == defaultPODNetwork {
		return fn.KubeObjects{}, nil
	}

	// meta is the generic object meta attached to all derived child objects
	meta := metav1.ObjectMeta{
		Name:        o.GetName(),
		Annotations: getAnnotations(o.GetAnnotations()),
	}

	afs := getAddressFamilies(itfce.Spec.IpFamilyPolicy)

	// When the CNIType is not set this is a loopback interface
	if itfce.Spec.CNIType != "" {
		if !f.IsCNITypePresent(itfce.Spec.CNIType) {
			return nil, fmt.Errorf("cniType not supported in workload cluster; workload cluster CNI(s): %v, interface cniType requested: %s", f.workloadCluster.Spec.CNIs, itfce.Spec.CNIType)
		}
		// add IPClaim of type network
		for _, af := range afs {
			meta := metav1.ObjectMeta{
				Name:        fmt.Sprintf("%s-%s", o.GetName(), string(af)),
				Annotations: getAnnotations(o.GetAnnotations()),
			}
			o, err := f.getIPClaim(meta, *itfce.Spec.NetworkInstance, ipamv1alpha1.PrefixKindNetwork, af)
			if err != nil {
				return nil, err
			}
			resources = append(resources, o)
		}

		if itfce.Spec.AttachmentType == nephioreqv1alpha1.AttachmentTypeVLAN {
			// add VLANClaim
			meta := metav1.ObjectMeta{
				Name:        o.GetName(),
				Annotations: f.getAnnotationsWithvlanClaimName(itfce),
			}
			o, err := f.getVLANClaim(meta)
			if err != nil {
				return nil, err
			}
			resources = append(resources, o)
		}

		// claim nad
		o, err = f.getNAD(meta)
		if err != nil {
			return nil, err
		}
		resources = append(resources, o)
	} else {
		// add IPClaim of type loopback
		for _, af := range afs {
			meta := metav1.ObjectMeta{
				Name:        fmt.Sprintf("%s-%s", o.GetName(), string(af)),
				Annotations: getAnnotations(o.GetAnnotations()),
			}
			o, err := f.getIPClaim(meta, *itfce.Spec.NetworkInstance, ipamv1alpha1.PrefixKindLoopback, af)
			if err != nil {
				return nil, err
			}
			resources = append(resources, o)
		}

	}
	return resources, nil
}

func (f *itfceFn) updateItfceResource(forObj *fn.KubeObject) (*fn.KubeObject, error) {
	if forObj == nil {
		return nil, fmt.Errorf("expected a for object but got nil")
	}
	itfceKOE, err := ko.NewFromKubeObject[nephioreqv1alpha1.Interface](forObj)

```

--------------------------------

### Kpt Eval Command for ipam-fn

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/ipam-fn/README.md

Shows how to use the kpt eval command to run the ipam-fn as a mutator. This command requires specifying the ipam-container-image.

```bash
kpt fn eval --type mutator <krm resource package>  -i <ipam-container-image>
```

--------------------------------

### Return Kubernetes Object in Go

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

This Go code snippet demonstrates how to return a Kubernetes object along with a potential error. It is typically used within functions that interact with Kubernetes resources.

```go
}
	}

	return &nad.K.KubeObject, nil
}
```

--------------------------------

### Processing VLAN Claims in Go

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

This Go code snippet iterates through VLAN claims, converts each to a Go struct, and updates the interface status with VLAN claim information. It demonstrates how to handle different types of claims within the same processing flow.

```go
vlanclaims := objs.Where(fn.IsGroupVersionKind(vlanv1alpha1.VLANClaimGroupVersionKind))
	for _, vlanclaim := range vlanclaims {
		claim, err := ko.NewFromKubeObject[vlanv1alpha1.VLANClaim](vlanclaim)
		if err != nil {
			return nil, err
		}
		claimGoStruct, err := claim.GetGoStruct()
		if err != nil {
			return nil, err
		}
		itfce.Status.VLANClaimStatus = &claimGoStruct.Status
	}
```

--------------------------------

### Reconcile Method Flowchart

Source: https://github.com/nephio-project/nephio/blob/main/operators/focom-operator/README.md

Describes the high-level steps involved in the reconciliation process. It details the sequence of operations from fetching resources to ensuring remote resource creation or polling.

```text
fetch → handle deletion → ensure finalizer → validate → build remote → ensure remote.
```

--------------------------------

### Error Handling and Data Retrieval in Go

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

This snippet demonstrates a common Go pattern for handling errors after an operation and retrieving a Go struct from a Kubernetes object. It's crucial for robust API interactions and data processing within the application.

```go
if err != nil {
		return nil, err
	}
	itfce, err := itfceKOE.GetGoStruct()
	if err != nil {
		return nil, err
	}
```

--------------------------------

### PackageVariant Configuration for upsert-kustomize-res

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/gen-kustomize-res/README.md

This YAML configuration illustrates how to use the `upsert-kustomize-res` function within a `PackageVariant` resource. It specifies the function's image and implies its inclusion in the mutation pipeline for downstream packages. Note the cautionary comment regarding potential prepend behavior affecting pipeline order.

```yaml
apiVersion: config.porch.kpt.dev/v1alpha1
kind: PackageVariant
metadata:
  name: example
spec:
  upstream:
    repo: catalog
    package: blueprint
    revision: v1
  downstream:
    repo: deployments
  pipeline:
    mutators:
    - image: docker.io/nephio/gen-kustomize-res:v1

```

--------------------------------

### Processing IP Claims and Sorting in Go

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/lib/condkptsdk/design.md

This Go code snippet processes IP claims, filters them by group version kind, and sorts them by name. It then iterates through the sorted claims, converting each to a Go struct and updating the interface status with IP allocation information.

```go
ipclaims := objs.Where(fn.IsGroupVersionKind(ipamv1alpha1.IPClaimGroupVersionKind))
sort.Slice(ipclaims, func(i, j int) bool {
		return ipclaims[i].GetName() < ipclaims[j].GetName()
	})
	for _, ipclaim := range ipclaims {
		// Don't care about the name since the condSDK sorts the data
		// based on owner reference
		claim, err := ko.NewFromKubeObject[ipamv1alpha1.IPClaim](ipclaim)
		if err != nil {
			return nil, err
		}
		claimGoStruct, err := claim.GetGoStruct()
		if err != nil {
			return nil, err
		}
		itfce.Status.UpsertIPAllocation(claimGoStruct.Status)
	}
```

--------------------------------

### Run dnn-fn with kpt fn source

Source: https://github.com/nephio-project/nephio/blob/main/krm-functions/dnn-fn/README.md

This command pipes the KRM resource package to the dnn-fn Go executable for processing. It's a common pattern for applying KRM functions directly.

```bash
kpt fn source <krm resource package> | go run main.go
```