### Apply OpenStack Resource Controller Managed Network Example

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/quickstart.md

This example shows how to apply the `managed-network` example resource using `kubectl apply` with Kustomize. It navigates to the specific example directory and applies the configuration server-side. Note that this command does not create the necessary `clouds.yaml` secret, which must be set up separately.

```bash
$ cd examples/apply/managed-network
$ kubectl apply -k . --server-side
network.openstack.k-orc.cloud/mbooth-orc-managed-network serverside-applied
```

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

### Example OpenStack Subnet Kubernetes API Object Structure

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/getting-started.md

Illustrates the complete YAML structure of an OpenStack Subnet custom resource as managed by Kubernetes. This example serves as an API reference, detailing the `metadata`, `spec` (desired configuration), and `status` (actual state, including OpenStack resource ID and conditions) of the `Subnet` object.

```APIDOC
apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Subnet
metadata:
  annotations:
  creationTimestamp: "2025-01-03T16:29:05Z"
  finalizers:
  - openstack.k-orc.cloud/port
  - openstack.k-orc.cloud/subnet
  generation: 1
  labels:
    app.kubernetes.io/instance: openstacksubnet-gettingstarted
    app.kubernetes.io/name: openstacksubnet
    app.kubernetes.io/part-of: gettingstarted
  name: subnet-1
  namespace: default
  resourceVersion: "2318"
  uid: cc132c51-990d-4b4e-be80-3b72822d1a88
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: managed
  networkRef: network-1
  resource:
    allocationPools:
    - end: 192.168.1.60
      start: 192.168.1.5
    cidr: 192.168.1.0/24
    description: |
      Example subnet
    ipVersion: 4
    tags:
    - gettingstarted
status:
  conditions:
  - lastTransitionTime: "2025-01-03T16:34:31Z"
    message: OpenStack resource is available
    observedGeneration: 1
    reason: Success
    status: "True"
    type: Available
  - lastTransitionTime: "2025-01-03T16:34:31Z"
    message: OpenStack resource is up to date
    observedGeneration: 1
    reason: Success
    status: "False"
    type: Progressing
  id: bb1f0b74-0e79-4f77-b518-6a05a61662f0
  resource:
    allocationPools:
    - end: 192.168.1.60
      start: 192.168.1.5
    cidr: 192.168.1.0/24
    description: |
      Example subnet
    dnsPublishFixedIP: false
    enableDHCP: true
    gatewayIP: 192.168.1.1
    ipVersion: 4
    ipv6AddressMode: ""
    ipv6RAMode: ""
    name: subnet-1
    projectID: c73b7097d07c46f78eb4b4dcfbac5ca8
    revisionNumber: 1
    tags:
    - gettingstarted
```

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

### Deploy OpenStack Resource Controller (ORC) to Kubernetes

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/getting-started.md

Installs the latest released version of the OpenStack Resource Controller (ORC) into a Kubernetes cluster. This command fetches the official `install.yaml` manifest and applies all necessary Kubernetes resources for ORC's operation.

```sh
export ORC_RELEASE="https://github.com/k-orc/openstack-resource-controller/releases/latest/download/install.yaml"
kubectl apply --server-side -f $ORC_RELEASE
```

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

### Cleanup OpenStack Resource Controller Managed Network Example

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/quickstart.md

This snippet provides the command to clean up the resources created by the `managed-network` example. It uses `kubectl delete -k .` to remove the applied Kustomize configuration and associated OpenStack resources.

```bash
$ kubectl delete -k .
```

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

### Run the OpenStack Resource Controller manager locally

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/quickstart.md

This command executes the ORC manager application directly from its Go source code. It starts the controller, which then begins managing OpenStack resources based on the defined CRDs, logging at a detailed level (zap-log-level 5). The output shows the manager starting various controllers and event sources.

```go
go run ./cmd/manager -zap-log-level 5
2024-11-11T12:09:30Z	INFO	setup	starting manager
2024-11-11T12:09:30Z	INFO	starting server {"name": "health probe", "addr": "[::]:8081"}
2024-11-11T12:09:30Z	INFO	Starting EventSource	{"controller": "network", "controllerGroup": "openstack.k-orc.cloud", "controllerKind": "Network", "source": "kind source: *v1alpha1.Network"}
2024-11-11T12:09:30Z	INFO	Starting Controller	{"controller": "network", "controllerGroup": "openstack.k-orc.cloud", "controllerKind": "Network"}
2024-11-11T12:09:30Z	INFO	Starting EventSource	{"controller": "image", "controllerGroup": "openstack.k-orc.cloud", "controllerKind": "Image", "source": "kind source: *v1alpha1.Image"}
2024-11-11T12:09:30Z	INFO	Starting Controller	{"controller": "image", "controllerGroup": "openstack.k-orc.cloud", "controllerKind": "Image"}
2024-11-11T12:09:30Z	INFO	Starting workers	{"controller": "image", "controllerGroup": "openstack.k-orc.cloud", "controllerKind": "Image", "worker count": 1}
2024-11-11T12:09:30Z	INFO	Starting workers	{"controller": "network", "controllerGroup": "openstack.k-orc.cloud", "controllerKind": "Network", "worker count": 1}
```

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

### Define and Apply OpenStack Network Kubernetes Custom Resource

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/getting-started.md

Applies a Kubernetes custom resource definition for an OpenStack Network. This resource is a prerequisite for creating subnets and other network-dependent OpenStack resources managed by ORC.

```yaml
kubectl apply --server-side -f- <<EOF
apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Network
metadata:
  labels:
    app.kubernetes.io/name: openstacknetwork
    app.kubernetes.io/instance: openstacknetwork-gettingstarted
    app.kubernetes.io/part-of: gettingstarted
  name: network-1
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: managed
  resource:
    description: |
      Example network
    tags:
    - gettingstarted
EOF
```

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

### Create Kubernetes Secret for OpenStack Clouds.yaml Credentials

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/getting-started.md

Creates a Kubernetes generic secret named `openstack-clouds` from a local `clouds.yaml` file. This secret securely stores your OpenStack credentials, making them accessible to the OpenStack Resource Controller for authenticating with OpenStack.

```sh
kubectl create secret generic openstack-clouds \
    --from-file=clouds.yaml=${XDG_CONFIG_HOME:-~/.config}/openstack/clouds.yaml
```

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

### Create a local Kubernetes kind cluster

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/quickstart.md

This command initializes a new Kubernetes cluster using 'kind'. It sets up the control plane, CNI, and storage, making the cluster ready for use. The output confirms the cluster creation and provides instructions for setting the kubectl context.

```bash
kind create cluster
Creating cluster "kind" ...
 ✓ Ensuring node image (kindest/node:v1.30.0) 🖼️
 ✓ Preparing nodes 📦
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹️ 
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
Set kubectl context to "kind-kind"
You can now use your cluster with:

kubectl cluster-info --context kind-kind

Have a question, bug, or feature request? Let us know! https://kind.sigs.k8s.io/#community 🙂
```

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

### Initialize Kustomize Environment and Apply OpenStack Credentials

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/quickstart.md

This snippet demonstrates how to initialize the k-orc Kustomize environment and apply OpenStack credentials. The `make` command generates a `dev-settings` kustomize component to add a username prefix, preventing naming conflicts. It also initializes local configurations, including a `clouds.yaml` secret and OpenStack network/subnet objects.

```bash
$ make
echo "$KUSTOMIZATION" > components/dev-settings/kustomization.yaml
kubectl apply -k apply/local-config --server-side
secret/mbooth-cloud-config-g4ckbm986f serverside-applied
network.openstack.k-orc.cloud/mbooth-external-network serverside-applied
subnet.openstack.k-orc.cloud/mbooth-external-subnet-ipv4 serverside-applied
```

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

### Build Installer and Tag Git Release

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/RELEASE.md

This snippet details the initial steps for a new release: setting the version, building the `install.yaml` manifest using `make`, adding the generated `dist` directory to Git, committing the changes, creating a signed Git tag for the release version, and pushing both the main branch and the new tag to the remote repository.

```bash
export VERSION=vX.Y.Z
make build-installer IMG=quay.io/orc/openstack-resource-controller:$VERSION
git add dist
git commit -m "Release $VERSION"
git tag -s -a $VERSION -m $VERSION
git push origin
git push origin tag $VERSION
```

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

### Define and Apply OpenStack Subnet Kubernetes Custom Resource

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/getting-started.md

Applies a Kubernetes custom resource definition for an OpenStack Subnet. This YAML manifest specifies the desired state of an OpenStack subnet, including its CIDR, allocation pools, and a reference to the network it belongs to.

```yaml
kubectl apply --server-side -f- <<EOF
apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Subnet
metadata:
  labels:
    app.kubernetes.io/name: openstacksubnet
    app.kubernetes.io/instance: openstacksubnet-gettingstarted
    app.kubernetes.io/part-of: gettingstarted
  name: subnet-1
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: managed
  networkRef: network-1
  resource:
    description: |
      Example subnet
    tags:
    - gettingstarted
    ipVersion: 4
    allocationPools:
    - start: 192.168.1.5
      end: 192.168.1.60
    cidr: 192.168.1.0/24
EOF
```

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

### Install ORC using kubectl

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/README.md

This command sequence sets an environment variable for the latest ORC release YAML and then applies it to a Kubernetes cluster using `kubectl` for server-side installation. This is the simplest way to install a released version of ORC.

```bash
export ORC_RELEASE="https://github.com/k-orc/openstack-resource-controller/releases/latest/download/install.yaml"
kubectl apply --server-side -f $ORC_RELEASE
```

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

### Verify kind cluster node status with kubectl

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/quickstart.md

This command checks the status of nodes within the currently configured 'kubectl' context. It confirms that the 'kind' cluster's control plane node is ready and displays its age and Kubernetes version.

```bash
kubectl get node
NAME                 STATUS   ROLES           AGE     VERSION
kind-control-plane   Ready    control-plane   4m22s   v1.30.0
```

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

### Run Specific Kuttl E2E Test with Environment Variables

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/writing-tests.md

Example of running a specific end-to-end Kuttl test (`import-dependency` for the `subnet` controller) by setting environment variables for the test directory (`E2E_KUTTL_DIR`) and test name (`E2E_KUTTL_TEST`) before executing `make test-e2e`.

```bash
E2E_KUTTL_DIR=internal/controllers/subnet/tests E2E_KUTTL_TEST=import-dependency make test-e2e
```

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

### Inspect OpenStack Subnet Kubernetes Resource Details

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/getting-started.md

Retrieves the full YAML representation of a specific OpenStack Subnet custom resource from Kubernetes. This command allows inspection of both the desired state (`spec`) and the actual state (`status`), including the OpenStack resource ID and conditions.

```sh
kubectl get subnet subnet-1 -o yaml
```

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

### Execute Kubectl Commands within Kuttl Tests

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/writing-tests.md

Shows how to run `kubectl` commands directly from a Kuttl test step using the `command` field, useful for interacting with Kubernetes resources during tests. This example retrieves Kubernetes ports within a namespaced context.

```yaml
apiVersion: kuttl.dev/v1beta1
kind: TestStep
commands:
  - command: kubectl get port
    namespaced: true
```

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

### Delete Openstack Resources and Undeploy ORC

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/getting-started.md

This shell script snippet outlines the commands required to delete specific Openstack resources (subnet, network, and secret) from a Kubernetes cluster and then undeploy the Openstack Resource Controller (ORC) release. This action effectively resets the environment to a clean state.

```sh
kubectl delete subnet subnet-1
kubectl delete network network-1
kubectl delete secret openstack-clouds
kubectl delete -f $ORC_RELEASE
```

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

### Load OpenStack Resource Controller CRDs into Kubernetes

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/quickstart.md

This command applies the Custom Resource Definitions (CRDs) for the OpenStack Resource Controller (ORC) to the Kubernetes cluster. It uses kustomize to manage the CRD configurations located in 'config/crd' and applies them server-side, confirming their successful application.

```bash
kubectl apply -k config/crd --server-side
customresourcedefinition.apiextensions.k8s.io/images.openstack.k-orc.cloud serverside-applied
customresourcedefinition.apiextensions.k8s.io/networks.openstack.k-orc.cloud serverside-applied
customresourcedefinition.apiextensions.k8s.io/subnets.openstack.k-orc.cloud serverside-applied
```

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

### Go Controller Interface Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/controller-init.md

Defines the `Controller` interface that all controllers must implement. This interface specifies the `SetupWithManager` method for integrating the controller with the manager and the `GetName` method for retrieving its unique identifier.

```golang
type Controller interface {
	SetupWithManager(context.Context, ctrl.Manager, controller.Options) error
	GetName() string
}
```

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

### Create GitHub Release and Upload Artifacts

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/RELEASE.md

These commands utilize the GitHub CLI (`gh`) to finalize the release process. The first command creates a new draft release on GitHub, automatically generating release notes and verifying the Git tag. The second command uploads the previously generated `install.yaml` artifact to the newly created GitHub release.

```bash
gh release create -d --generate-notes --verify-tag -t "Release $VERSION" $VERSION
gh release upload $VERSION dist/install.yaml
```

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

### Generate Controller Scaffolding Files

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/scaffolding.md

This command initiates the generation of boilerplate code for a new controller. Before running, ensure the new resource is added to `allResources` in `cmd/resource-generator/main.go`. The command will create three Go files: an API definition, an internal adapter, and an internal controller, which form the foundation for the new controller.

```shell
make generate-resources
```

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

### Uninstall ORC using kubectl

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/README.md

This command uninstalls ORC from a Kubernetes cluster by deleting the resources defined in the `install.yaml` file. It relies on the `ORC_RELEASE` environment variable being previously set to the installation YAML path.

```bash
kubectl delete -f $ORC_RELEASE
```

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

### APIDOC: AllocationPool Object Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Defines a range of IP addresses within a subnet that can be used for allocation. This object specifies the starting and ending IP addresses of the pool. It is typically found within the specification of a Subnet resource.

```APIDOC
AllocationPool:
  Appears in: SubnetResourceSpec
  Fields:
    start:
      Type: IPvAny
      Description: start is the first IP address in the allocation pool.
      Validation: MaxLength: 45, MinLength: 1
    end:
      Type: IPvAny
      Description: end is the last IP address in the allocation pool.
      Validation: MaxLength: 45, MinLength: 1
```

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

### APIDOC: AllocationPoolStatus Object Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Represents the status of an IP allocation pool, providing the actual start and end IP addresses as strings. This object is part of the status section of a Subnet resource, reflecting the current state of the allocation pool.

```APIDOC
AllocationPoolStatus:
  Appears in: SubnetResourceStatus
  Fields:
    start:
      Type: string
      Description: start is the first IP address in the allocation pool.
      Validation: MaxLength: 1024
    end:
      Type: string
      Description: end is the last IP address in the allocation pool.
      Validation: MaxLength: 1024
```

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

### Go BaseResourceActuator Interface Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/godoc/generic-interfaces.md

Defines the BaseResourceActuator interface, which provides core functionalities for managing OpenStack resources. It includes methods for getting resource IDs, fetching resources by ID, and listing resources for adoption to prevent resource leaks.

```go
type BaseResourceActuator[
    orcObjectPT interface {
        *orcObjectT
        client.Object
        orcv1alpha1.ObjectWithConditions
    }, orcObjectT any,
    osResourceT any,
] interface {
    // GetResourceID returns a string identifier for the OpenStack resource
    // managed by this actuator, typically the object's uuid. This is the value
    // stored in status.id.
    GetResourceID(osResource *osResourceT) string

    // GetOSResourceByID fetches this actuator's OpenStack resource by id.
    GetOSResourceByID(ctx context.Context, id string) (*osResourceT, progress.ReconcileStatus)

    // ListOSResourcesForAdoption is used to prevent resource leaks in the event
    // that we create an OpenStack resource, but fail to write its ID to the
    // object's status. It returns a set of resources which match what the
    // actuator would have created for this object. Ideally it should attempt to
    // do this match as accurately as possible, remembering that OpenStack does
    // not prevent the creation of objects with duplicate names.
    //
    // It is called in the creation flow immediately before creating a resource,
    // and in the deletion flow when deleting an object which has a finalizer
    // but no status.id.
    //
    // It returns 2 values:
    // - an iterator over the matching OpenStack resources
    // - a boolean indicating whether adoption should be considered for this object
    //
    // For example, we must return false for an object with no resource spec.
    ListOSResourcesForAdoption(ctx context.Context, orcObject orcObjectPT) (iter.Seq2[*osResourceT, error], bool)
}
```

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

### Create 1MB Zeroed Raw Image File

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/internal/controllers/image/testdata/README.md

Generates a 1MB raw image file named 'raw.img' filled with zeroes. This file serves as a basic placeholder or input for subsequent compression tests.

```bash
dd if=/dev/zero of=raw.img bs=1M count=1
```

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

### ReconcileStatus and WaitingOnEvent API Reference

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/godoc/reconcile-status.md

Comprehensive API documentation for the `ReconcileStatus` type and related functions/methods, detailing their purpose, parameters, return types, and usage for managing reconciliation flow, error handling, and various waiting states.

```APIDOC
ReconcileStatus Type:
  Description: Represents the status of the current reconcile. nil is a valid ReconcileStatus. It is safe to call all methods on a nil ReconcileStatus. You MUST use the return value of any method which returns ReconcileStatus: the returned object may not be equal to the receiver, for example when the receiver is nil.
  Definition: type ReconcileStatus = *reconcileStatus

  Functions:
    NeedsRefresh():
      Signature: func NeedsRefresh() ReconcileStatus
      Description: Convenience method which returns a new ReconcileStatus with NeedsRefresh.
      Returns: ReconcileStatus

    NewReconcileStatus():
      Signature: func NewReconcileStatus() ReconcileStatus
      Description: Returns an empty ReconcileStatus.
      Returns: ReconcileStatus

    WaitingOnFinalizer(finalizer string):
      Signature: func WaitingOnFinalizer(finalizer string) ReconcileStatus
      Description: Convenience method which returns a new ReconcileStatus with WaitingOnFinalizer.
      Parameters:
        finalizer: string
      Returns: ReconcileStatus

    WaitingOnObject(kind, name string, waitingOn WaitingOnEvent):
      Signature: func WaitingOnObject(kind, name string, waitingOn WaitingOnEvent) ReconcileStatus
      Description: Convenience method which returns a new ReconcileStatus with WaitingOnObject.
      Parameters:
        kind: string
        name: string
        waitingOn: WaitingOnEvent
      Returns: ReconcileStatus

    WaitingOnOpenStack(waitingOn WaitingOnEvent, pollingPeriod time.Duration):
      Signature: func WaitingOnOpenStack(waitingOn WaitingOnEvent, pollingPeriod time.Duration) ReconcileStatus
      Description: Convenience method which returns a new ReconcileStatus with WaitingOnOpenStack.
      Parameters:
        waitingOn: WaitingOnEvent
        pollingPeriod: time.Duration
      Returns: ReconcileStatus

    WrapError(err error):
      Signature: func WrapError(err error) ReconcileStatus
      Description: Returns a ReconcileStatus containing the given error.
      Parameters:
        err: error
      Returns: ReconcileStatus

  Methods:
    (r ReconcileStatus) GetError():
      Signature: func (r ReconcileStatus) GetError() error
      Description: (No explicit description provided in source, inferred from signature)
      Returns: error

    (r ReconcileStatus) GetProgressMessages():
      Signature: func (r ReconcileStatus) GetProgressMessages() []string
      Description: (No explicit description provided in source, inferred from signature)
      Returns: []string

    (r ReconcileStatus) GetRequeue():
      Signature: func (r ReconcileStatus) GetRequeue() time.Duration
      Description: (No explicit description provided in source, inferred from signature)
      Returns: time.Duration

    (r ReconcileStatus) NeedsRefresh():
      Signature: func (r ReconcileStatus) NeedsRefresh() ReconcileStatus
      Description: (No explicit description provided in source, inferred from signature)
      Returns: ReconcileStatus

    (r ReconcileStatus) NeedsReschedule():
      Signature: func (r ReconcileStatus) NeedsReschedule() (bool, error)
      Description: (No explicit description provided in source, inferred from signature)
      Returns: (bool, error)

    (r ReconcileStatus) Return(log logr.Logger):
      Signature: func (r ReconcileStatus) Return(log logr.Logger) (ctrl.Result, error)
      Description: (No explicit description provided in source, inferred from signature)
      Parameters:
        log: logr.Logger
      Returns: (ctrl.Result, error)

    (r ReconcileStatus) WaitingOnFinalizer(finalizer string):
      Signature: func (r ReconcileStatus) WaitingOnFinalizer(finalizer string) ReconcileStatus
      Description: (No explicit description provided in source, inferred from signature)
      Parameters:
        finalizer: string
      Returns: ReconcileStatus

    (r ReconcileStatus) WaitingOnObject(kind, name string, waitingOn WaitingOnEvent):
      Signature: func (r ReconcileStatus) WaitingOnObject(kind, name string, waitingOn WaitingOnEvent) ReconcileStatus
      Description: (No explicit description provided in source, inferred from signature)
      Parameters:
        kind: string
        name: string
        waitingOn: WaitingOnEvent
      Returns: ReconcileStatus

    (r ReconcileStatus) WaitingOnOpenStack(waitingOn WaitingOnEvent, pollingPeriod time.Duration):
      Signature: func (r ReconcileStatus) WaitingOnOpenStack(waitingOn WaitingOnEvent, pollingPeriod time.Duration) ReconcileStatus
      Description: (No explicit description provided in source, inferred from signature)
      Parameters:
        waitingOn: WaitingOnEvent
        pollingPeriod: time.Duration
      Returns: ReconcileStatus

    (r ReconcileStatus) WithError(err error):
      Signature: func (r ReconcileStatus) WithError(err error) ReconcileStatus
      Description: (No explicit description provided in source, inferred from signature)
      Parameters:
        err: error
      Returns: ReconcileStatus

    (r ReconcileStatus) WithProgressMessage(msgs ...string):
      Signature: func (r ReconcileStatus) WithProgressMessage(msgs ...string) ReconcileStatus
      Description: (No explicit description provided in source, inferred from signature)
      Parameters:
        msgs: ...string
      Returns: ReconcileStatus

    (r ReconcileStatus) WithReconcileStatus(o ReconcileStatus):
      Signature: func (r ReconcileStatus) WithReconcileStatus(o ReconcileStatus) ReconcileStatus
      Description: (No explicit description provided in source, inferred from signature)
      Parameters:
        o: ReconcileStatus
      Returns: ReconcileStatus

    (r ReconcileStatus) WithRequeue(requeue time.Duration):
      Signature: func (r ReconcileStatus) WithRequeue(requeue time.Duration) ReconcileStatus
      Description: (No explicit description provided in source, inferred from signature)
      Parameters:
        requeue: time.Duration
      Returns: ReconcileStatus

WaitingOnEvent Type:
  Description: (No explicit description provided in source, inferred from index)
```

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

### Import progress package

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/godoc/reconcile-status.md

Imports the `progress` package from the OpenStack resource controller, providing access to reconciliation status management utilities.

```go
import "github.com/k-orc/openstack-resource-controller/v2/internal/controllers/generic/progress"
```

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

### Compress Raw Image with XZ

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/internal/controllers/image/testdata/README.md

Compresses the 'raw.img' file using the xz utility, creating a 'raw.img.gz' file. Note: The output file extension 'gz' for xz compression might be a typo in the source, typically xz creates '.xz' files.

```bash
xz < raw.img > raw.img.gz
```

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

### Compress Raw Image with Gzip

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/internal/controllers/image/testdata/README.md

Compresses the 'raw.img' file using the gzip utility, resulting in a 'raw.img.gz' file. This provides an alternative common compression format for testing purposes.

```bash
gzip < raw.img > raw.img.gz
```

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

### Define Minimal OpenStack Network Resource for Testing

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/writing-tests.md

This YAML snippet defines a minimal OpenStack Network resource used in 'create-minimal' tests. It specifies the API version, kind, metadata, and a spec including cloud credentials, management policy, and an empty resource object, demonstrating the basic required fields for resource creation.

```yaml
apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Network
metadata:
  name: network-create-minimal
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: managed
  resource: {}
```

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

### Execute OpenStack Commands within Kuttl Tests

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/writing-tests.md

Demonstrates how to run `openstack` CLI commands from within a Kuttl test step using the `script` command, allowing interaction with OpenStack resources during E2E tests. It navigates to the E2E Kuttl OSClouds directory and lists OpenStack ports.

```yaml
apiVersion: kuttl.dev/v1beta1
kind: TestStep
commands:
  - script: |
      cd $(dirname ${E2E_KUTTL_OSCLOUDS})
      export OS_CLOUD=openstack
      openstack port list
```

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

### Verify Released Container Image Pull

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/RELEASE.md

After the release image build workflow completes, this command verifies the successful creation and availability of the new container image. It attempts to pull the image from the specified Quay.io registry using `podman`, ensuring it's accessible for deployment.

```bash
podman pull quay.io/orc/openstack-resource-controller:$VERSION
```

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

### Go Package Import for Generic Interfaces

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/godoc/generic-interfaces.md

Imports the necessary Go package containing the generic interfaces for the OpenStack Resource Controller.

```go
import "github.com/k-orc/openstack-resource-controller/v2/internal/controllers/generic/interfaces"
```

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

### Go Controller Interface Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/godoc/generic-interfaces.md

Defines the Controller interface, which specifies methods for setting up the controller with a manager and retrieving its name.

```go
type Controller interface {
    SetupWithManager(context.Context, ctrl.Manager, controller.Options) error
    GetName() string
}
```

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

### FloatingIPList API Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Describes the structure for a list of FloatingIP resources, adhering to Kubernetes API list conventions. It includes standard API versioning, kind, metadata, and an array of FloatingIP items.

```APIDOC
FloatingIPList:
  description: Contains a list of FloatingIP.
  fields:
    apiVersion (string): openstack.k-orc.cloud/v1alpha1
    kind (string): FloatingIPList
    metadata (ListMeta): Refer to Kubernetes API documentation for fields of metadata.
    items (FloatingIP array): items contains a list of FloatingIP.
```

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

### Go Interface: ResourceHelperFactory

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/development/godoc/generic-interfaces.md

An interface for constructing helper objects required by the generic controller. It includes methods for creating API object adapters, and actuators for both resource creation and deletion, handling potential reconciliation statuses or errors during their instantiation. This factory ensures proper initialization of controller dependencies.

```Go
type ResourceHelperFactory[
    orcObjectPT interface {
        *orcObjectT
        client.Object
        orcv1alpha1.ObjectWithConditions
    }, orcObjectT any,
    resourceSpecT any, filterT any,
    osResourceT any,
] interface {
    // NewAPIObjectAdapter returns an APIObjectAdapter wrapping orcObject
    NewAPIObjectAdapter(orcObject orcObjectPT) APIObjectAdapter[orcObjectPT, resourceSpecT, filterT]

    // NewCreateActuator returns a CreateResourceActuator for the given
    // orcObject. If it is not able to return an actuator, it MUST return either
    // one or more ProgressStatuses, or an error. If returning ProgressStatuses,
    // these MUST ensure that the object will be reconciled again at an
    // appropriate time.
    NewCreateActuator(ctx context.Context, orcObject orcObjectPT, controller ResourceController) (CreateResourceActuator[orcObjectPT, orcObjectT, filterT, osResourceT], progress.ReconcileStatus)

    // NewDeleteActuator returns a DeleteResourceActuator for the given
    // orcObject. If it is not able to return an actuator, it MUST return either
    // one or more ProgressStatuses, or an error. If returning ProgressStatuses,
    // these MUST ensure that the object will be reconciled again at an
    // appropriate time.
    //
    // Consider carefully whether a DeleteResourceActuator needs all the same
    // initialisation dependencies as a CreateResourceActuator. Consider that we
    // may want to delete a resource that is partially or not initialised, or
    // whose creation dependencies may no longer be in a healthy state.
    NewDeleteActuator(ctx context.Context, orcObject orcObjectPT, controller ResourceController) (DeleteResourceActuator[orcObjectPT, orcObjectT, osResourceT], progress.ReconcileStatus)
}
```

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

### ImageList API Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Defines the structure for a list of Image resources, following standard Kubernetes API conventions. It includes fields for API version, kind, metadata, and an array containing the Image items.

```APIDOC
ImageList:
  Description: ImageList contains a list of Image.
  apiVersion: string
    Description: openstack.k-orc.cloud/v1alpha1
    Default: openstack.k-orc.cloud/v1alpha1
  kind: string
    Description: ImageList
    Default: ImageList
  metadata: ListMeta
    Description: Refer to Kubernetes API documentation for fields of metadata.
    Reference: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#listmeta-v1-meta
  items: Image array
    Description: items contains a list of Image.
```

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

### ImageContainerFormat API Schema

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Defines the supported container formats for images, including bare, compressed, and various virtualization formats.

```APIDOC
ImageContainerFormat:
  Underlying type: string
  Validation: Enum: [ami ari aki bare ovf ova docker compressed]
  Appears in: ImageContent
  Enum Values:
    - aki
    - ami
    - ari
    - bare
    - compressed
    - docker
    - ova
    - ovf
```

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

### APIDOC: ProjectList Kubernetes API Type

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Contains a list of Project resources, including standard Kubernetes API version, kind, metadata for the list, and the array of Project items.

```APIDOC
ProjectList:
  description: ProjectList contains a list of Project.
  fields:
    apiVersion:
      type: string
      value: openstack.k-orc.cloud/v1alpha1
    kind:
      type: string
      value: ProjectList
    metadata:
      type: ListMeta (https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#listmeta-v1-meta)
      description: Refer to Kubernetes API documentation for fields of metadata.
    items:
      type: array of Project
      description: items contains a list of Project.
```

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

### ProjectSpec API Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Defines the desired state for an ORC (OpenStack Resource Controller) object, including options for importing existing resources, specifying the desired resource state, and defining the management policy. It also includes references to managed options and cloud credentials.

```APIDOC
ProjectSpec:
  description: defines the desired state of an ORC object.
  appears_in:
    - Project
  properties:
    import:
      type: ProjectImport
      description: refers to an existing OpenStack resource which will be imported instead of creating a new one.
      validation: MaxProperties: 1, MinProperties: 1
    resource:
      type: ProjectResourceSpec
      description: resource specifies the desired state of the resource. resource may not be specified if the management policy is `unmanaged`. resource must be specified if the management policy is `managed`.
    managementPolicy:
      type: ManagementPolicy
      description: defines how ORC will treat the object. Valid values are `managed`: ORC will create, update, and delete the resource; `unmanaged`: ORC will import an existing resource, and will not apply updates to it or delete it.
      default: managed
      validation: Enum: [managed, unmanaged]
    managedOptions:
      type: ManagedOptions
      description: specifies options which may be applied to managed objects.
    cloudCredentialsRef:
      type: CloudCredentialsReference
      description: points to a secret containing OpenStack credentials
```

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

### ServerGroupList API Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Describes the structure for a list of ServerGroup resources, including standard Kubernetes API list metadata and an array of ServerGroup items.

```APIDOC
ServerGroupList:
  description: Contains a list of ServerGroup.
  fields:
    apiVersion:
      type: string
      value: openstack.k-orc.cloud/v1alpha1
    kind:
      type: string
      value: ServerGroupList
    metadata:
      type: ListMeta
      reference: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#listmeta-v1-meta
      description: Refer to Kubernetes API documentation for fields of `metadata`.
    items:
      type: array<ServerGroup>
      description: items contains a list of ServerGroup.
```

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

### ImageCompression API Schema

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Defines the supported compression formats for image files, such as xz, gz, and bz2.

```APIDOC
ImageCompression:
  Underlying type: string
  Validation: Enum: [xz gz bz2]
  Appears in: ImageContentSourceDownload
  Enum Values:
    - xz
    - gz
    - bz2
```

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

### ImageProperties Schema Definition

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/website/docs/crd-reference.md

Defines the structure and validation rules for image properties used in OpenStack resource management, including CPU architecture, hypervisor type, minimum resource requirements, and hardware/OS configurations. This schema appears within the ImageResourceSpec.

```APIDOC
ImageProperties:
  Appears in: ImageResourceSpec
  Fields:
    architecture:
      type: string
      description: architecture is the CPU architecture that must be supported by the hypervisor.
      validation: Enum: [aarch64 alpha armv7l cris i686 ia64 lm32 m68k microblaze microblazeel mips mipsel mips64 mips64el openrisc parisc parisc64 ppc ppc64 ppcemb s390 s390x sh4 sh4eb sparc sparc64 unicore32 x86_64 xtensa xtensaeb]
    hypervisorType:
      type: string
      description: hypervisorType is the hypervisor type
      validation: Enum: [hyperv ironic lxc qemu uml vmware xen]
    minDiskGB:
      type: integer
      description: minDiskGB is the minimum amount of disk space in GB that is required to boot the image
      validation: Minimum: 1
    minMemoryMB:
      type: integer
      description: minMemoryMB is the minimum amount of RAM in MB that is required to boot the image.
      validation: Minimum: 1
    hardware:
      type: ImagePropertiesHardware
      description: hardware is a set of properties which control the virtual hardware created by Nova.
    operatingSystem:
      type: ImagePropertiesOperatingSystem
      description: operatingSystem is a set of properties that specify and influence the behavior of the operating system within the virtual machine.
```

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

### Compress Raw Image with Bzip2

Source: https://github.com/k-orc/openstack-resource-controller/blob/main/internal/controllers/image/testdata/README.md

Compresses the 'raw.img' file using the bzip2 utility, creating a new compressed file named 'raw.img.bz2'. This demonstrates one method of reducing file size for storage or transfer.

```bash
bzip2 < raw.img > raw.img.bz2
```