User Guide

This guide covers the core concepts and common usage patterns for ORC (openstack-resource-controller). It assumes you have already completed the Quick Start guide and have ORC deployed to your cluster.

Core Concepts

Management Policies

Every ORC resource has a managementPolicy that determines how ORC manages the OpenStack resource:

When to use managed:

• You want ORC to have full control over the resource lifecycle
• The resource doesn't exist yet and should be created
• You want changes to the Kubernetes object to be reflected in OpenStack

When to use unmanaged:

• The resource already exists and is managed by another system
• You need to reference shared infrastructure (external networks, public flavors)
• You want to prevent accidental deletion of critical resources

Import vs Create

ORC can either create new OpenStack resources or import existing ones:

Creating a new resource (managed):

apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Network
metadata:
  name: my-network
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: managed
  resource:
    description: My application network
    tags:
      - my-app

Importing an existing resource by ID (unmanaged):

apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Network
metadata:
  name: external-network
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: unmanaged
  import:
    id: "12345678-1234-1234-1234-123456789abc"

Importing an existing resource by filter (unmanaged):

apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Network
metadata:
  name: external-network
spec:
  cloudCredentialsRef:
    cloudName: openstack
    secretName: openstack-clouds
  managementPolicy: unmanaged
  import:
    filter:
      name: public
      external: true

Deletion Behavior

For managed resources, the managedOptions.onDelete field controls what happens when the Kubernetes object is deleted:

spec:
  managementPolicy: managed
  managedOptions:
    onDelete: detach  # Keep the OpenStack resource on deletion
  resource:
    # ...

Resource References

ORC resources reference each other using *Ref fields. These references:

• Are resolved by Kubernetes object name (in the same namespace)
• Create automatic dependencies - ORC waits for referenced resources to be ready
• Prevent deletion of resources that are still in use

For example, a Subnet references a Network:

apiVersion: openstack.k-orc.cloud/v1alpha1
kind: Subnet
metadata:
  name: my-subnet
spec:
  # ...
  resource:
    networkRef: my-network  # References the Network named "my-network"
    cidr: 192.168.1.0/24
    ipVersion: 4

Understanding Status and Conditions

Every ORC resource reports its status through two conditions: Available (whether the resource is ready for use) and Progressing (whether ORC is still working on it). For detailed information about conditions and their meanings, see Troubleshooting: Status Conditions Explained.

Check resource status with:

kubectl get networks
kubectl get network my-network -o yaml

The .status.resource field contains the observed state of the OpenStack resource, including fields set by OpenStack (like projectID, createdAt, etc.).

Cloud Credentials

All ORC resources require a cloudCredentialsRef that points to a Kubernetes Secret containing OpenStack credentials.

Creating the Credentials Secret

The secret must contain a clouds.yaml file:

kubectl create secret generic openstack-clouds \
    --from-file=clouds.yaml=/path/to/your/clouds.yaml

Example clouds.yaml:

clouds:
  openstack:
    auth:
      auth_url: https://keystone.example.com:5000/v3
      project_name: my-project
      username: my-user
      password: my-password
      user_domain_name: Default
      project_domain_name: Default
    region_name: RegionOne

Using Custom CA Certificates

If your OpenStack deployment uses a custom CA, include it in the secret:

kubectl create secret generic openstack-clouds \
    --from-file=clouds.yaml=/path/to/clouds.yaml \
    --from-file=cacert=/path/to/ca-bundle.crt

Referencing Credentials

Every ORC resource references credentials like this:

spec:
  cloudCredentialsRef:
    secretName: openstack-clouds  # Name of the secret
    cloudName: openstack          # Name of the cloud in clouds.yaml