Merge branch 'main' into sb-aws-finops

Author: AlexanderHodicke

app-dev/devops-and-containers/oke/oci-functions-operator/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.github
+.idea
+.vscode
+bin
+dist
+tmp
+
+*.test
+*.out
+coverage.*
+
+.DS_Store

app-dev/devops-and-containers/oke/oci-functions-operator/AGENTS.md

@@ -0,0 +1,52 @@
+# OCI Functions Operator for OKE
+
+## Goal
+
+Build a Kubernetes operator that lets OKE users manage and invoke OCI Functions through Kubernetes-native CRDs.
+
+## MVP
+
+The MVP has two CRDs:
+
+- Function
+- FunctionJob
+
+FunctionJob should support:
+- functionRef
+- inline JSON payloads
+- parallelism
+- retryLimit
+- Kubernetes status aggregation
+
+## Design principles
+
+- Do not pretend OCI Functions are Kubernetes Pods.
+- Do not support arbitrary PodTemplateSpec in v1alpha1.
+- Prefer explicit validation errors over silent behavior.
+- Keep OCI SDK access behind small interfaces.
+- Make controllers idempotent.
+- Make status useful from `kubectl get` and `kubectl describe`.
+- Prefer small, testable packages.
+
+## Out of scope for MVP
+
+- Cron scheduling
+- Event sources
+- Native Kubernetes Job compatibility
+- Volumes
+- Sidecars
+- Init containers
+- GPU
+- Privileged execution
+- Full OCI Function lifecycle management before invocation spike works
+
+## Build commands
+
+Use:
+- `make generate`
+- `make manifests`
+- `make test`
+
+## Language
+
+Go, Kubebuilder/controller-runtime.

app-dev/devops-and-containers/oke/oci-functions-operator/Dockerfile

@@ -0,0 +1,23 @@
+# Build the manager binary.
+ARG GO_VERSION=1.26.0
+FROM golang:${GO_VERSION} AS builder
+
+WORKDIR /workspace
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+ARG TARGETOS=linux
+ARG TARGETARCH=amd64
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -trimpath -ldflags="-s -w" -o manager ./cmd
+
+# Run as a non-root user in a minimal image.
+FROM gcr.io/distroless/static-debian12:nonroot
+
+WORKDIR /
+COPY --from=builder /workspace/manager /manager
+
+USER 65532:65532
+ENTRYPOINT ["/manager"]

app-dev/devops-and-containers/oke/oci-functions-operator/Makefile

@@ -0,0 +1,63 @@
+LOCALBIN ?= $(shell pwd)/bin
+CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
+CONTROLLER_TOOLS_VERSION ?= v0.21.0
+GENERATED_CRD_DIR ?= config/crd/bases
+CHART_CRD_DIR ?= charts/oci-functions-operator/crds
+
+.PHONY: all
+all: generate manifests test
+
+.PHONY: generate
+generate: controller-gen
+	$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."
+
+.PHONY: manifests
+manifests: controller-gen
+	$(CONTROLLER_GEN) rbac:roleName=manager-role crd paths="./..." output:crd:artifacts:config=config/crd/bases output:rbac:artifacts:config=config/rbac
+
+.PHONY: test
+test:
+	go test ./...
+
+.PHONY: helm-chart
+helm-chart: manifests
+	mkdir -p $(CHART_CRD_DIR)
+	cp $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functionapplications.yaml $(CHART_CRD_DIR)/functionapplications.functions.oci.oracle.com.yaml
+	cp $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functions.yaml $(CHART_CRD_DIR)/functions.functions.oci.oracle.com.yaml
+	cp $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functionjobs.yaml $(CHART_CRD_DIR)/functionjobs.functions.oci.oracle.com.yaml
+	cp $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functionevents.yaml $(CHART_CRD_DIR)/functionevents.functions.oci.oracle.com.yaml
+	cp $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functioneventtriggers.yaml $(CHART_CRD_DIR)/functioneventtriggers.functions.oci.oracle.com.yaml
+	$(MAKE) helm-crds-check
+
+.PHONY: helm-crds-check
+helm-crds-check:
+	test -f $(CHART_CRD_DIR)/functionapplications.functions.oci.oracle.com.yaml
+	test -f $(CHART_CRD_DIR)/functions.functions.oci.oracle.com.yaml
+	test -f $(CHART_CRD_DIR)/functionjobs.functions.oci.oracle.com.yaml
+	test -f $(CHART_CRD_DIR)/functioneventtriggers.functions.oci.oracle.com.yaml
+	test -f $(CHART_CRD_DIR)/functionevents.functions.oci.oracle.com.yaml
+	cmp -s $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functionapplications.yaml $(CHART_CRD_DIR)/functionapplications.functions.oci.oracle.com.yaml
+	cmp -s $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functions.yaml $(CHART_CRD_DIR)/functions.functions.oci.oracle.com.yaml
+	cmp -s $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functionjobs.yaml $(CHART_CRD_DIR)/functionjobs.functions.oci.oracle.com.yaml
+	cmp -s $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functioneventtriggers.yaml $(CHART_CRD_DIR)/functioneventtriggers.functions.oci.oracle.com.yaml
+	cmp -s $(GENERATED_CRD_DIR)/functions.oci.oracle.com_functionevents.yaml $(CHART_CRD_DIR)/functionevents.functions.oci.oracle.com.yaml
+
+.PHONY: helm-template
+helm-template: helm-chart
+	helm template oci-functions-operator charts/oci-functions-operator \
+		--namespace oci-functions-operator-system
+
+.PHONY: fmt
+fmt:
+	go fmt ./...
+
+.PHONY: vet
+vet:
+	go vet ./...
+
+.PHONY: controller-gen
+controller-gen: $(CONTROLLER_GEN)
+
+$(CONTROLLER_GEN):
+	mkdir -p $(LOCALBIN)
+	GOBIN=$(LOCALBIN) go install sigs.k8s.io/controller-tools/cmd/controller-gen@$(CONTROLLER_TOOLS_VERSION)

app-dev/devops-and-containers/oke/oci-functions-operator/PROJECT

@@ -0,0 +1,34 @@
+domain: oci.oracle.com
+layout:
+- go.kubebuilder.io/v4
+projectName: oci-functions-operator
+repo: github.com/oracle/oci-functions-operator
+resources:
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: oci.oracle.com
+  group: functions
+  kind: FunctionApplication
+  path: github.com/oracle/oci-functions-operator/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: oci.oracle.com
+  group: functions
+  kind: Function
+  path: github.com/oracle/oci-functions-operator/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: oci.oracle.com
+  group: functions
+  kind: FunctionJob
+  path: github.com/oracle/oci-functions-operator/api/v1alpha1
+  version: v1alpha1
+version: "3"

app-dev/devops-and-containers/oke/oci-functions-operator/README.md

@@ -0,0 +1,136 @@
+# OCI Functions Operator
+
+Kubernetes-native APIs for managing and invoking OCI Functions from OKE.
+
+Current controller image:
+
+```text
+ghcr.io/ronsevetoci/oci-functions-operator/controller:v0.1.7
+```
+
+## What This Operator Provides
+
+The operator exposes five namespaced CRDs in `functions.oci.oracle.com/v1alpha1`:
+
+- `FunctionApplication`: maps to an OCI Functions Application. It owns app-level settings such as compartment, region, subnets, NSGs, application config, and invocation log settings.
+- `Function`: maps to an OCI Function. It can reference an existing OCI Function or manage one inside a `FunctionApplication`.
+- `FunctionJob`: invokes a referenced `Function` with one or more inline JSON payloads, parallelism, retry limits, and per-payload status.
+- `FunctionEventTrigger`: routes an OCI Events rule or a Kubernetes-native `functionevent.*` event type to a `Function`.
+- `FunctionEvent`: an in-cluster event envelope that the operator matches against `FunctionEventTrigger` resources.
+
+`FunctionJob` and `FunctionEvent` both end in a Function invocation, but they are not the same resource. Use `FunctionJob` when a user or system wants to submit explicit invocation work and track that work as a job. Use `FunctionEvent` when an application emits an event and wants the operator to route it through matching triggers.
+
+## Resource Flow
+
+```mermaid
+flowchart TB
+    APPCR[FunctionApplication CR]
+    APP[OCI Functions Application]
+    FNCR[Function CR]
+    FN[OCI Function]
+    INVOKE[Function Invocation]
+
+    APPCR --> APP
+    APP --> FNCR
+    FNCR --> FN
+    FN --> INVOKE
+
+    JOB[FunctionJob CR]
+    TRIGGER[FunctionEventTrigger CR]
+    EVENT[FunctionEvent CR]
+    OCIEVENT[OCI service event]
+    RULE[OCI Events Rule]
+
+    JOB --> INVOKE
+    EVENT --> TRIGGER
+    OCIEVENT --> RULE
+    RULE --> TRIGGER
+    TRIGGER --> INVOKE
+```
+
+Read it top to bottom: a `FunctionApplication` is the application wrapper, a `Function` lives inside it, and every invocation path eventually invokes that function. `FunctionJob` is direct work submission. `FunctionEventTrigger` routes either OCI service events through an OCI Events Rule or in-cluster `FunctionEvent` objects.
+
+The important boundary is that the operator does not turn OCI Functions into Pods. It keeps OCI Functions as OCI resources and gives Kubernetes users a clear control plane for application setup, function setup, invocation, event routing, status, and events.
+
+## Two Images
+
+The operator image and function runtime image are separate artifacts:
+
+- Operator/controller image: runs as a Kubernetes Deployment in OKE. It can be in GHCR, OCIR, or any registry OKE can pull from.
+- Function runtime image: runs in OCI Functions. It must be an OCI Functions-compatible Fn image in same-region OCIR, for example `jed.ocir.io/<TENANCY_NAMESPACE>/hello-function:fn-v1` for Jeddah.
+
+Do not use GHCR for the OCI Functions runtime image. OCI Functions pulls the runtime image from the Functions application network during invocation, so the application subnet and any attached NSGs must allow egress to Oracle Services Network/OCIR even when the OCIR repository is public.
+
+## Start Here
+
+- [Helm install](docs/helm-install.md): supported OKE installation and upgrade path.
+- [OKE deployment](docs/oke-deployment.md): Workload Identity, IAM, networking, and the core resource sequence.
+- [Function event triggers](docs/event-triggers.md): OCI Events and `functionevent.*` routing.
+- [Function events](docs/function-events.md): Kubernetes-native event emission.
+- [Debugging Functions](docs/debugging-functions.md): image, CRD, Workload Identity, NSG, and invocation failure checks.
+- [Design overview](docs/design.md): controller architecture, resource behavior, and current limitations.
+- [Sample function image](examples/hello-function/README.md): Fn-compatible Python function runtime image.
+
+Tracked files under `config/samples/` are generic examples with placeholders. Live walkthrough manifests with OCIDs, tenancy namespaces, bucket names, or temporary cleanup settings should live in the ignored `local/` directory, not in the repository history.
+
+## Helm CRDs
+
+The Helm chart includes CRDs for `FunctionApplication`, `Function`, `FunctionJob`, `FunctionEventTrigger`, and `FunctionEvent`.
+
+Fresh Helm installs install CRDs from `charts/oci-functions-operator/crds/`, but existing Helm upgrades do not add or update CRDs from that directory. Before installing or upgrading after API changes, apply the chart CRDs first:
+
+```sh
+kubectl apply -f charts/oci-functions-operator/crds/
+```
+
+Then run `helm upgrade --install`.
+
+## Modes
+
+`INVOKER_MODE=fake` is the default for local controller development and tests. It requires no OCI auth and creates no OCI resources.
+
+`INVOKER_MODE=oci` uses the OCI Go SDK:
+
+- On OKE, the Helm chart configures Workload Identity with `oci.authMode=workload`.
+- For local development only, use `OCI_AUTH_MODE=config` with `OCI_CONFIG_FILE` and `OCI_CONFIG_PROFILE`.
+
+The Helm chart is the supported way to deploy the operator on OKE. Kustomize under `config/` is kept for Kubebuilder-generated manifests and local development only. Do not mix Helm and Kustomize for the same cluster install.
+
+## Resource Model
+
+Preferred managed mode is explicit:
+
+1. Create a `FunctionApplication` for the shared OCI Functions Application.
+2. Create one or more managed `Function` resources with `spec.applicationRef.name`.
+3. Wait for `Function.status.functionId` and `Function.status.invokeEndpoint`.
+4. Invoke through `FunctionJob`, OCI Events-backed `FunctionEventTrigger`, or Kubernetes-native `FunctionEvent`.
+
+Legacy managed `Function` manifests that put app-level settings under `spec.config` still work for compatibility, but new manifests should use `FunctionApplication`.
+
+`Function.spec.deletionPolicy` defaults to `Retain`. Deleting a managed `Function` with `Retain` leaves OCI resources untouched. Set `deletionPolicy: Delete` only when Kubernetes deletion should also delete the managed OCI Function. `FunctionApplication.spec.deletionPolicy` controls OCI Application cleanup separately; `Delete` is honored only for managed applications and only when no functions remain. Existing-mode resources never delete OCI resources.
+
+## Local Development
+
+Install or refresh generated CRDs:
+
+```sh
+make generate
+make manifests
+kubectl apply -k config/crd
+```
+
+Run the manager in fake mode:
+
+```sh
+INVOKER_MODE=fake go run ./cmd
+```
+
+Apply the safe sample resources:
+
+```sh
+kubectl apply -k config/samples
+kubectl get functions,functionjobs
+kubectl describe functionjob hello-job
+```
+
+Fake mode proves only Kubernetes reconciliation and status behavior. It does not prove OCI auth, OCI Functions network egress, OCIR image access, or function image compatibility.