mandre · Oct 14, 2026 · Oct 13, 2026
diff --git a/README.md b/README.md
@@ -64,7 +64,7 @@ kubectl delete -f $ORC_RELEASE
 
 ## Supported OpenStack resources
 
-| **controller**              | **1.x (EOL)** | **2.x** | **main** |
+| **controller**              | **1.x (EOL)** | **2.x** | **3.x (main)** |
 |:---------------------------:|:-------:|:-------:|:--------:|
 | addressscope                |         |    ✔    |     ✔    |
 | application credential      |         |    ◐    |     ◐    |

diff --git a/website/docs/changelog.md b/website/docs/changelog.md
@@ -1,5 +1,109 @@
 # Changelog
 
+## v3.0-pre1 - October 14, 2026
+
+This is the first pre-release of ORC v3. This release is safe to use in
+production, but additional backward-incompatible changes may land before
+v3.0.0. The Go module path has changed from `v2` to `v3`, and the release
+contains several backward-incompatible API changes. See the
+[upgrade guide](howto/upgrading.md#from-v2-to-v3) for migration instructions.
+
+### New controllers
+
+- **DNSZone**: Manage Designate DNS zones
+- **Limit**: Manage Keystone unified limits
+- **Region**: Manage Keystone regions
+- **RegisteredLimit**: Manage Keystone registered limits
+- **RoleAssignment**: Manage Keystone role assignments (relationship resource, no OpenStack ID)
+- **ShareNetwork**: Manage Manila share networks
+- **SubnetPool**: Manage Neutron subnet pools
+
+### New features
+
+- **Drift detection and resync**: Every resource now has an optional `spec.resyncPeriod` field
+  and a `status.lastSyncTime` timestamp. A new `--default-resync-period` manager flag sets the
+  global default. When enabled, ORC periodically re-reads the OpenStack resource and updates
+  status accordingly. External deletion of managed resources is detected and the resource is
+  re-created automatically. Drift detection is not yet enabled by default; see
+  [Enable Drift Detection](howto/drift-detection.md) for setup instructions and
+  [Drift Detection Explained](concepts/drift-detection.md) for how it works.
+- **Helm charts**: New `orc` and `orc-crds` Helm charts for installation.
+- **OLM bundle**: Enriched metadata for OperatorHub.io.
+- **RBAC aggregation**: ORC CRDs now contribute rules to the standard Kubernetes `view`, `edit`,
+  and `admin` [aggregated ClusterRoles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles).
+- **Server**: Boot-from-volume support via `spec.resource.bootVolume`. New
+  `spec.resource.schedulerHints` with support for server groups, affinity/anti-affinity hints,
+  cell targeting, and arbitrary additional properties.
+- **Flavor**: Mutable extra specs via `spec.resource.extraSpecs`.
+- **Router**: Static routes support via `spec.resource.routes`.
+- **RouterInterface**: Support attaching by port (new `portRef` field and `Port` type).
+- **Network**: Provider segments in spec (`spec.resource.segments`) and status.
+- **Port**: New fields: `trustedVIF`, `valueSpecs`, `propagateUplinkStatus`.
+- **Endpoint**: `regionRef` in spec, filter, and status.
+- **Image**: `firmwareType` hardware property.
+
+### Breaking changes
+
+For detailed migration instructions, see the [upgrade guide](howto/upgrading.md#from-v2-to-v3).
+
+- **Go module path**: Changed from
+  `github.com/k-orc/openstack-resource-controller/v2` to
+  `github.com/k-orc/openstack-resource-controller/v3`. All Go imports must be updated.
+
+- **Server: `imageRef` changed from required to optional**: The type changed from
+  `KubernetesNameRef` (value) to `*KubernetesNameRef` (pointer). A new CEL rule requires
+  exactly one of `imageRef` or `bootVolume` to be set. Existing manifests that already
+  specify `imageRef` are not affected, but Go code referencing this field must handle the
+  pointer.
+
+- **Server: `serverGroupRef` moved to `schedulerHints`**: The field
+  `spec.resource.serverGroupRef` has been removed. Use
+  `spec.resource.schedulerHints.serverGroupRef` instead.
+
+- **Network: `status.resource.provider` replaced by `status.resource.segments`**: The
+  single `provider` object in status has been replaced by a `segments` list that can
+  represent multi-segment provider networks. Any code or tooling reading
+  `status.resource.provider` must switch to `status.resource.segments`.
+
+- **Port: `securityGroupRefs` changed from `[]OpenStackName` to `[]KubernetesNameRef`**:
+  Values were previously raw OpenStack security group names. They are now references to ORC
+  SecurityGroup objects. Existing Port manifests must be updated to reference ORC
+  SecurityGroup object names. (Fixes [#438](https://github.com/k-orc/openstack-resource-controller/issues/438))
+
+- **Status `bool` fields changed to `*bool`**: Five status fields changed from bare `bool`
+  to `*bool` so that `false` is distinguishable from unset in JSON. The affected fields are:
+    - `ApplicationCredentialResourceStatus.Unrestricted`
+    - `ImageResourceStatus.Protected`
+    - `SecurityGroupResourceStatus.Stateful`
+    - `ServerResourceStatus.ConfigDrive`
+    - `UserResourceStatus.Enabled`
+
+    This affects Go code that reads these fields directly (must dereference the pointer).
+    Existing YAML manifests are not affected since these are status-only.
+
+### Bug fixes
+
+- Flavor/Domain: Relaxed import ID validation from UUID-only to a broader pattern, allowing
+  non-UUID identifiers used by some OpenStack deployments (Fixes [#869](https://github.com/k-orc/openstack-resource-controller/issues/869))
+- SecurityGroup: Fixed deliberately-empty rules list never reaching Available (Fixes [#960](https://github.com/k-orc/openstack-resource-controller/issues/960))
+- SecurityGroup: Fixed incorrect index used for PortRange when creating rules
+- Status: Fixed `CreatedAt`/`UpdatedAt` set to literal JSON null on a zero timestamp
+- RouterInterface: Fixed status conditions when Router is not Available (Fixes [#838](https://github.com/k-orc/openstack-resource-controller/issues/838))
+- Port: Fixed endless update loop when MAC is empty in AllowedAddressPairs (Fixes [#852](https://github.com/k-orc/openstack-resource-controller/issues/852))
+- Port/Volume: Poll for status transition after server attachment (port ACTIVE, volume in-use) (Fixes [#842](https://github.com/k-orc/openstack-resource-controller/issues/842))
+- Invalidate cached provider scope when an OpenStack endpoint is missing from the catalog (Fixes [#941](https://github.com/k-orc/openstack-resource-controller/issues/941))
+- Network transport errors are now retryable (Fixes [#879](https://github.com/k-orc/openstack-resource-controller/issues/879))
+
+### Infrastructure improvements
+
+- Go bumped to 1.25.13
+- gophercloud bumped to v2.15.0
+- kuttl bumped to v0.27.0
+- Website migrated from mkdocs to zensical, with ORC logo and branding
+- Various dependency bumps (controller-runtime, cel-go, grpc, otel, etc.)
+
+---
+
 ## v2.6 - June 10, 2026
 
 ### New features

diff --git a/website/docs/howto/upgrading.md b/website/docs/howto/upgrading.md
@@ -0,0 +1,121 @@
+# Upgrading
+
+When upgrading across any major version, CRDs **must** be upgraded before the
+controller.
+
+Using kubectl, the `install.yaml` manifest includes both CRDs and the
+controller:
+
+```bash
+export NEW_VERSION=<target_version>
+kubectl apply --server-side -f \
+    https://github.com/k-orc/openstack-resource-controller/releases/download/${NEW_VERSION}/install.yaml
+```
+
+Using Helm, upgrade the CRDs chart first, then the controller:
+
+```bash
+helm upgrade orc-crds oci://quay.io/orc/helm/orc-crds
+helm upgrade orc oci://quay.io/orc/helm/orc
+```
+
+## From v2 to v3
+
+This section covers the backward-incompatible changes in ORC v3 and how to
+migrate from v2. For the full list of changes, see the
+[changelog](../changelog.md#v30-pre1-october-14-2026).
+
+### Go module path
+
+The module path changed from `github.com/k-orc/openstack-resource-controller/v2`
+to `github.com/k-orc/openstack-resource-controller/v3`. Update all Go imports:
+
+```bash
+find . -name '*.go' -exec sed -i \
+  's|k-orc/openstack-resource-controller/v2|k-orc/openstack-resource-controller/v3|g' {} +
+```
+
+### Server: imageRef
+
+`imageRef` changed from a required value field (`KubernetesNameRef`) to an
+optional pointer (`*KubernetesNameRef`). A new CEL rule requires exactly one of
+`imageRef` or `bootVolume` to be set.
+
+No YAML changes are required if `imageRef` is already set. Go code referencing
+this field must handle the pointer (e.g. using `ptr.Deref`).
+
+### Server: serverGroupRef
+
+The field `spec.resource.serverGroupRef` has been removed. Use
+`spec.resource.schedulerHints.serverGroupRef` instead.
+
+```yaml
+# Before (v2)
+spec:
+  resource:
+    serverGroupRef: my-server-group
+
+# After (v3)
+spec:
+  resource:
+    schedulerHints:
+      serverGroupRef: my-server-group
+```
+
+### Network: provider to segments
+
+The single `status.resource.provider` object has been replaced by a
+`status.resource.segments` list that can represent multi-segment provider
+networks. Any code or tooling reading `status.resource.provider` must switch to
+`status.resource.segments`.
+
+```yaml
+# Before (v2)
+status:
+  resource:
+    provider:
+      networkType: vlan
+      physicalNetwork: provider-net
+      segmentationID: 100
+
+# After (v3)
+status:
+  resource:
+    segments:
+      - networkType: vlan
+        physicalNetwork: provider-net
+        segmentationID: 100
+```
+
+A new `spec.resource.segments` field allows setting provider segments at
+creation time.
+
+### Port: securityGroupRefs
+
+The Go type of `securityGroupRefs` changed from `[]OpenStackName` to
+`[]KubernetesNameRef`. The YAML representation is identical (a list of
+strings), so no manifest changes are needed. The values were always intended to
+be ORC SecurityGroup object names.
+
+Go code that references this field type must be updated accordingly.
+
+### Status bool fields (Go code only)
+
+Five status fields changed from bare `bool` to `*bool` so that `false` is
+distinguishable from unset in JSON:
+
+- `ApplicationCredentialResourceStatus.Unrestricted`
+- `ImageResourceStatus.Protected`
+- `SecurityGroupResourceStatus.Stateful`
+- `ServerResourceStatus.ConfigDrive`
+- `UserResourceStatus.Enabled`
+
+Existing YAML manifests are not affected since these are status-only fields.
+
+```go
+// Before (v2)
+if status.Resource.Protected {
+
+// After (v3)
+if ptr.Deref(status.Resource.Protected, false) {
+```
diff --git a/website/docs/installation.md b/website/docs/installation.md
@@ -84,7 +84,7 @@ The upgrade process:
 
 !!! note
 
-    Always check the [Changelog](changelog.md) for breaking changes before upgrading major versions.
+    Always check the [Changelog](changelog.md) for breaking changes before upgrading major versions. For major version upgrades, see the [Upgrading](howto/upgrading.md) guide.
 
 ## Uninstalling
 

diff --git a/website/mkdocs.yml b/website/mkdocs.yml
@@ -14,6 +14,7 @@ nav:
   - How-to Guides:
     - Set Up Cloud Credentials: howto/cloud-credentials.md
     - Enable Drift Detection: howto/drift-detection.md
+    - Upgrading: howto/upgrading.md
     - Troubleshooting: troubleshooting.md
   - Reference:
     - Controller Configuration: reference/configuration.md