Project refactor (#125)

* Project refactor

Assisted-by: Cursor

* Fix issue with CRD spec - additionalProperties and properties are mutual exclusive. Refactor some other code

Author: ramperher

grout-operator/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased] -
 
+## [0.2.2] - 2025-08-13
+
+- No functional changes to operator logic.
+- Documentation improvements for CRD specification, Grout Ansible role and deployment details.
+
 ## [0.2.1] - 2025-08-05
 
 - Updated OperatorSDK to v1.41.1

grout-operator/Dockerfile

@@ -3,8 +3,8 @@ FROM quay.io/operator-framework/ansible-operator:v1.39.0
 LABEL name="NFV Example CNF Application Operator" \
       maintainer="telcoci" \
       vendor="fredco" \
-      version="v0.2.1" \
-      release="v0.2.1" \
+      version="v0.2.2" \
+      release="v0.2.2" \
       summary="An example CNF for platform validation" \
       description="An example CNF for platform validation"
 

grout-operator/Makefile

@@ -3,7 +3,7 @@
 # To re-generate a bundle for another specific version without changing the standard setup, you can:
 # - use the VERSION as arg of the bundle target (e.g make bundle VERSION=0.0.2)
 # - use environment variables to overwrite this value (e.g export VERSION=0.0.2)
-VERSION := 0.2.1
+VERSION := 0.2.2
 
 # Set the Operator SDK version to use. By default, what is installed on the system is used.
 # This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit.

grout-operator/config/crd/bases/examplecnf.openshift.io_grouts.yaml

@@ -32,6 +32,54 @@ spec:
           spec:
             description: Spec defines the desired state of Grout
             type: object
+            properties:
+              privileged:
+                description: Run the container in privileged mode
+                type: boolean
+              imagePullPolicy:
+                description: Image pull policy for the Grout container
+                type: string
+                enum:
+                - Always
+                - IfNotPresent
+                - Never
+              size:
+                description: Number of replicas for the Grout deployment
+                type: integer
+                minimum: 1
+              networks:
+                description: List of NetworkAttachmentDefinitions to attach to the pod
+                type: array
+                items:
+                  type: object
+                  properties:
+                    name:
+                      description: NetworkAttachmentDefinition name (namespace/name or name)
+                      type: string
+                    count:
+                      description: Number of interfaces to request from this network
+                      type: integer
+                      minimum: 1
+                      default: 1
+                    mac:
+                      description: Optional list of MAC addresses, one per interface
+                      type: array
+                      items:
+                        type: string
+                    ip:
+                      description: Optional list of IP addresses, one per interface
+                      type: array
+                      items:
+                        type: string
+              runDeployment:
+                description: Whether to run the deployment automation (0 to disable, 1 to enable)
+                type: integer
+                enum:
+                - 0
+                - 1
+              runtime_class_name:
+                description: Optional RuntimeClass to use for the pod
+                type: string
             x-kubernetes-preserve-unknown-fields: true
           status:
             description: Status defines the observed state of Grout

grout-operator/molecule/default/tasks/grout_test.yml

@@ -1,6 +1,6 @@
 ---
 - name: Create the examplecnf.openshift.io/v1.Grout
-  k8s:
+  kubernetes.core.k8s:
     state: present
     namespace: '{{ namespace }}'
     definition: "{{ lookup('template', '/'.join([samples_dir, cr_file])) | from_yaml }}"
@@ -13,6 +13,6 @@
     cr_file: 'examplecnf_v1_grout.yaml'
 
 - name: Add assertions here
-  assert:
+  ansible.builtin.assert:
     that: false
     fail_msg: FIXME Add real assertions for your operator

grout-operator/roles/grout/README.md

@@ -0,0 +1,101 @@
+# Grout Ansible Role
+
+This Ansible role (`grout`) is designed to deploy and manage the Grout application in a Kubernetes/OpenShift environment. It automates the creation of necessary Kubernetes resources, parses network definitions, and configures the Grout deployment according to user-specified parameters.
+
+## Default Variables
+
+The following variables are defined in [`defaults/main.yml`](defaults/main.yml):
+
+| Variable              | Default Value                                                                                                    | Description                                                                                                 |
+|-----------------------|------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| `image_grout`         | quay.io/rh-nfv-int/grout-container-app-cnfapp@sha256:112bed772707280de16a64eb4fb3c3c0ec027fa030372dff05927d105bc822fd | Container image for the Grout application.                                                                  |
+| `size`                | 1                                                                                                                | Number of replicas for the Grout deployment.                                                                |
+| `skip_annot`          | false                                                                                                            | Whether to skip annotation steps.                                                                           |
+| `networks`            | []                                                                                                               | List of network definitions (see below for structure).                                                      |
+| `image_pull_policy`   | IfNotPresent                                                                                                     | Image pull policy for the Grout container (`Always`, `IfNotPresent`, or `Never`).                           |
+| `privileged`          | false                                                                                                            | Whether to run the container in privileged mode.                                                            |
+| `hugepage_1gb_count`  | 4Gi                                                                                                              | Amount of 1Gi hugepages to allocate.                                                                        |
+| `memory`              | 1000Mi                                                                                                           | Memory request for the Grout container.                                                                     |
+| `cpu`                 | 4                                                                                                                | CPU request for the Grout container.                                                                        |
+| `network_resources`   | {}                                                                                                               | Internal variable for tracking network resource usage.                                                      |
+| `resources`           | []                                                                                                               | List of additional resources to be used.                                                                    |
+| `environments`        | {}                                                                                                               | Environment variables to set in the container.                                                              |
+| `rx_queues`           | 2                                                                                                                | Number of RX queues.                                                                                        |
+
+### Example `networks` Variable Structure
+
+The `networks` variable is a list of dictionaries, each describing a network attachment. Example:
+
+```
+"networks": [
+    {
+        "count": 1,
+        "ip": [
+            "192.168.36.60/26"
+        ],
+        "mac": [
+            "80:03:0f:f1:89:01"
+        ],
+        "name": "example-cnf-net1"
+    },
+    {
+        "count": 1,
+        "ip": [
+            "192.168.36.100/26"
+        ],
+        "mac": [
+            "80:03:0f:f1:89:02"
+        ],
+        "name": "example-cnf-net2"
+    }
+]
+```
+
+## How the Ansible Tasks Work
+
+The Grout role uses a series of Ansible tasks (see [`tasks/main.yml`](tasks/main.yml)) to automate the deployment and configuration of the Grout application. Here is an overview of the main steps:
+
+1. **Initialization**:  
+   The role initializes internal variables such as `network_resources` (to track network resource usage) and `network_name_list` (to keep a list of network names).
+
+2. **Input Validation**:  
+   The role checks that at least one of the `networks` or `resources` variables is provided. If both are empty, the playbook fails with an error.
+
+3. **Network Parsing**:  
+   If the `networks` variable is defined and not empty, the role loops through each network entry and includes the `network-parse.yaml` task file. This subtask:
+   - Extracts the network name and details.
+   - Looks up the corresponding `NetworkAttachmentDefinition` in the cluster.
+   - Gathers resource names, counts, and updates the `network_resources` dictionary accordingly.
+   - Handles duplicate resources by incrementing their counts.
+   - Collects a list of all network names used.
+
+4. **Resource Parsing**:  
+   If `resources` are defined and `networks` is empty, the role populates `network_resources` directly from the `resources` list.
+
+5. **Debugging and Output**:  
+   Throughout the process, the role prints debug information for variables like `networks`, `resources`, `network_resources`, and `network_name_list` to aid troubleshooting.
+
+6. **Kubernetes Resource Creation**:  
+   The role then creates the necessary Kubernetes resources for the Grout application:
+   - **ServiceAccount**: For the Grout pod to interact with the cluster.
+   - **Role and RoleBinding**: To grant the required permissions.
+   - **Deployment**: To launch the Grout application pods using the specified configuration.
+   - **PodDisruptionBudget**: To ensure high availability during node maintenance or upgrades.
+
+These tasks ensure that the Grout application is deployed with the correct network attachments, resource allocations, and permissions, based on the variables you provide to the role.
+
+## Deployment Details
+
+The Grout role creates a Kubernetes `Deployment` resource to manage the lifecycle of the Grout application pods. This deployment is defined using a Jinja2 template (`deployment.yml`) and is rendered with the variables you provide to the role. The deployment includes the following key features:
+
+- **Replica Count**: The number of pod replicas is controlled by the `size` variable.
+- **Container Image**: The Grout container image is specified by the `image_grout` variable, with the pull policy set by `image_pull_policy`.
+- **Network Attachments**: The deployment attaches the specified networks to the pods using the `networks` variable, enabling SR-IOV or other CNI-based networking as required.
+- **Resource Requests and Limits**: CPU, memory, and hugepage resources are set according to the role defaults or your overrides.
+- **Security Context**: The pod can be run in privileged mode if `privileged` is set to `true`.
+- **RuntimeClass**: If a high-performance runtime is specified (via `runtime_class_name`), it is set on the pod for advanced scheduling or isolation.
+- **Environment Variables**: Any custom environment variables can be injected using the `environments` variable.
+- **Service Account**: The deployment uses a dedicated ServiceAccount created by the role to ensure proper permissions.
+- **PodDisruptionBudget**: A PodDisruptionBudget is also created to help maintain pod availability during node drains or upgrades.
+
+This deployment ensures that the Grout application is robustly managed by Kubernetes, with flexible configuration for networking, resources, and security to suit a variety of CNF (Cloud-Native Network Function) scenarios.

grout-operator/roles/grout/defaults/main.yml

@@ -4,22 +4,32 @@
 # https://github.com/openshift-kni/example-cnf/blob/main/grout-operator/Makefile - See "ensure_digests" task
 image_grout: "quay.io/rh-nfv-int/grout-container-app-cnfapp@sha256:112bed772707280de16a64eb4fb3c3c0ec027fa030372dff05927d105bc822fd" # v0.2.0
 
+# Number of replicas for the Grout deployment.
 size: 1
+# Whether to skip annotation steps.
 skip_annot: false
 
 # PCI devices to be used during execution should be obtained from these networks
 # Grout application entrypoint script should get PCI and then run Grout execution
 networks: []
 
+# Image pull policy for the Grout container (Always, IfNotPresent, or Never).
 image_pull_policy: IfNotPresent
+# Whether to run the container in privileged mode.
 privileged: false
+# Amount of 1Gi hugepages to allocate.
 hugepage_1gb_count: 4Gi
+# Memory request for the Grout container.
 memory: 1000Mi
+# CPU request for the Grout container.
 cpu: 4
 
+# Internal variable for tracking network resource usage.
 network_resources: {}
+# List of additional resources to be used.
 resources: []
-ethpeer_maclist: []
+# Environment variables to set in the container.
 environments: {}
 
+# Number of RX queues.
 rx_queues: 2

grout-operator/roles/grout/tasks/main.yml

@@ -1,49 +1,49 @@
 ---
 # tasks file for Grout
-- set_fact:
+- ansible.builtin.set_fact:
     network_resources: {}
     network_name_list: []
 
 - name: print network list
-  debug:
+  ansible.builtin.debug:
     var: networks
 
 - name: print resource list
-  debug:
+  ansible.builtin.debug:
     var: resources
 
 - name: Check if networks parameter is empty
-  fail:
+  ansible.builtin.fail:
     msg: "networks or resources parameter is required"
   when:
     - networks|length == 0
     - resources|length == 0
 
 - name: "Parse network"
-  include_tasks: network-parse.yaml
+  ansible.builtin.include_tasks: network-parse.yaml
   when: networks|default([])|length > 0
   loop: "{{ networks }}"
   loop_control:
     loop_var: network_item
 
 - name: print network_resources after parsing networks
-  debug:
+  ansible.builtin.debug:
     var: network_resources
 
 - name: print network_name_list after parsing networks
-  debug:
+  ansible.builtin.debug:
     var: network_name_list
 
 - name: "Parse resources if defined and when sriov network is not defined"
-  set_fact:
+  ansible.builtin.set_fact:
     network_resources: "{{ network_resources | combine({item.name: item.count}) }}"
   loop: "{{ resources }}"
   when:
     - networks|default([])|length == 0
     - resources|default([])|length > 0
 
 - name: print network resources map
-  debug:
+  ansible.builtin.debug:
     var: network_resources
 
 - name: Create ServiceAccount for Grout resource

grout-operator/roles/grout/tasks/network-parse.yaml

@@ -1,64 +1,64 @@
 ---
-- debug:
+- ansible.builtin.debug:
     msg: "Gather network info of network: {{ network_item.name }}"
 
 - name: Initialize variable that checks if resource name is already on the dict
-  set_fact:
+  ansible.builtin.set_fact:
     resource_exists: false
 
-- set_fact:
+- ansible.builtin.set_fact:
     net: "{{ network_item.name.split('/')[1] }}"
   when: "'/' in network_item.name"
 
-- set_fact:
+- ansible.builtin.set_fact:
     net: "{{ network_item.name }}"
   when: "'/' not in network_item.name"
 
 - name: print net
-  debug:
+  ansible.builtin.debug:
     var: net
 
-- set_fact:
+- ansible.builtin.set_fact:
     net_def: "{{ lookup('k8s', kind='NetworkAttachmentDefinition', namespace=ansible_operator_meta.namespace, resource_name=net) }}"
   failed_when: net_def|length == 0
 
 - name: print net_def
-  debug:
+  ansible.builtin.debug:
     var: net_def
 
-- set_fact:
+- ansible.builtin.set_fact:
     network_port_count: "{{ network_item.count|default(1) }}"
 
 - name: print network_port_count
-  debug:
+  ansible.builtin.debug:
     var: network_port_count
 
-- set_fact:
+- ansible.builtin.set_fact:
     network_resource_name: "{{ net_def['metadata']['annotations']['k8s.v1.cni.cncf.io/resourceName'] }}"
 
 - name: print network_resource_name
-  debug:
+  ansible.builtin.debug:
     var: network_resource_name
 
 - name: Update resource_exists if the resource is in the dict
-  set_fact:
+  ansible.builtin.set_fact:
     resource_exists: true
   with_dict: "{{ network_resources }}"
   when: "network_resource_name in item.key"
 
 - name: print resource_exists
-  debug:
+  ansible.builtin.debug:
     var: resource_exists
 
 - name: Include new network resource if it was not included before
-  set_fact:
+  ansible.builtin.set_fact:
     network_resources: "{{ network_resources | combine( {network_resource_name : network_port_count} ) }}"
   when: not resource_exists
 
 - name: Update network resource
   block:
     - name: Update count for network resource
-      set_fact:
+      ansible.builtin.set_fact:
         network_resources: "{{ network_resources | combine(new_item, recursive=true) }}"
       vars:
         new_item: "{ '{{ item.key }}': {{ item.value|int + network_port_count|int }} }"
@@ -67,12 +67,12 @@
   when: resource_exists
 
 - name: print network_resources
-  debug:
+  ansible.builtin.debug:
     var: network_resources
 
-- set_fact:
+- ansible.builtin.set_fact:
     network_name_list: "{{ network_name_list + [net] }}"
 
 - name: print network_name_list
-  debug:
+  ansible.builtin.debug:
     var: network_name_list