focom-operator

FOCOM SMO Service

Starting point implementation of FOCOM SMO Service, which reconciles FOCOM provisioning requests into oran provisioning requests.

Description

Reconciling FOCOM provisioning requests into oran provisioning requests, will look for correct TemplateInfo referenced in the request. Current validation only checks if the referenced TemplateInfo exists, with given name and version. Template parameters are not validated yet, it will be done in the future. Once the referenced template is validated, reconcile will proceed to find OCloudId referenced in the request and make sure it exists. From the OCloudId it will read the secret referenced in the OCloud.

In this early stage, secret contains kubeconfig for the OCloud cluster, which will be used to build client to interact with the remote cluster. Using this client reconciler will produce Oran provisioning requests on the remote cluster.

Later, this is planned to be changed to support REST-like interface on the remote cluster, rather then using kubeconfig. Secret in this phase should be endpoint and bearer token,

Project contains few test samples, using testenv, and there is usual e2e test from the operator-sdk that can validate operator deployment. This code is at the POC level, and needs more work to be production ready.

ORAN provisioning request CRD is located inside oran-provisioning-crd folder. Focom CRDS are generated by operator-sdk/kubebuilder from go structs in the api folder. Generated yaml files are located in config/crd/bases.

Current code does not cater for more then one-shot operations, and patching of ORAN provisioning requests is not supported yet. Validation of the TemplateInfo parameters is not implemented yet, potentially this can be done by validating webhook, making them immutable for a start.

Getting Started

To build the code simply run the make command. Makefile provided, contains various targets to build, test and deploy the code. Building code:

make

To build the docker image, run the following command:

make docker-build docker-push IMG=your-docker-repository/focom-operator:2.0.0

Kpt packages are included in the folder kpt-package, focom-operator.yaml file (is generated)/can be generaated by running make, where IMG is the image built previously:

make build-k8s-deployment IMG=your-docker-repository/focom-operator:2.0.0

To deploy the FOCOM SMO Service on the cluster, run the following command:

make deploy IMG=your-docker-repository/focom-operator:2.0.0

Prerequisites

• go version v1.22.0+
• docker version 17.03+.
• kubectl version v1.11.3+.
• Access to a Kubernetes v1.11.3+ cluster.
• oapi-codegen installed with: go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
• setup-env test: go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest

To run the tests locally

Set up the setup-envtest from the root folder of the project.

# For example, to use envtest 1.31 on macOS with an ARM processor, run:
setup-envtest use 1.31 --bin-dir=./testbin
export KUBEBUILDER_ASSETS="$(pwd)/testbin/k8s/1.31.0-darwin-arm64"
go test -v ./internal/controller/...

To run e2e tests inside the test folder, set up a kind cluster, for example:

kind create cluster
make test-e2e

To Deploy on the cluster

Build and push your image to the location specified by IMG:

make docker-build docker-push IMG=<some-registry>/focom-operator:<tag>

NOTE: This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment. Make sure you have the proper permission to the registry if the above commands don’t work.

Install the CRDs into the cluster:

make install

Deploy the Manager to the cluster with the image specified by IMG:

make deploy IMG=<some-registry>/focom-operator:<tag>

NOTE: If you encounter RBAC errors, you may need to grant yourself cluster-admin privileges or be logged in as admin.

Create instances of your solution You can apply the samples (examples) from the config/sample:

kubectl apply -k config/samples/

NOTE: Ensure that the samples has default values to test it out.

To Uninstall

Delete the instances (CRs) from the cluster:

kubectl delete -k config/samples/

Delete the APIs(CRDs) from the cluster:

make uninstall

UnDeploy the controller from the cluster:

make undeploy

Current reconcilation method

1. The Reconcile method as is now, reads like a high-level “table of contents”:

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

2.All the details of how finalizers or remote creation works are delegated to smaller helper methods that do one job. 3. Example Reconcile Flow

Example flow:
```
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

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `NBI_PORT` | `8080` | HTTP server port for the NBI API |
| `NBI_STORAGE_BACKEND` | `memory` | Storage backend (`memory` or `porch`) |
| `NBI_STAGE` | `1` | Implementation stage (1, 2, or 3) |
| `FOCOM_NAMESPACE` | `focom-system` | Default namespace for FOCOM resources |
| `FOCOM_EARLY_SCHEMA_VALIDATION` | `false` | When set to `true`, validates FPR `templateParameters` against the referenced TemplateInfo `templateParameterSchema` during CreateDraft and UpdateDraft operations. When disabled (default), schema validation only runs during the ValidateDraft step. |

## Notes
 - Code needs testcases and better refactoring of certain parts.
 - Code needs to ensure that templateParameters are immutable, this could be done with validating webhook.
 - Code needs to ensure template validation is performed, not just check for template existence.
 - Possibly wrong group for the TemplateInfo?


## Project Distribution

Following are the steps to build the installer and distribute this project to users.

1. Build the installer for the image built and published in the registry:

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

NOTE: The makefile target mentioned above generates an 'install.yaml' file in the dist directory. This file contains all the resources built with Kustomize, which are necessary to install this project without its dependencies.

1. Using the installer

Users can just run kubectl apply -f to install the project, i.e.:

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

Contributing

// TODO(user): Add detailed information on how you would like others to contribute to this project

NOTE: Run make help for more information on all potential make targets

More information can be found via the Kubebuilder Documentation

License

Copyright 2025.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.