Skip to content

Commit 69fb7ed

Browse files
mandremandre
committed
docs: refresh user and dev documentation
Reorganize the docs for better usability, and refresh content.
1 parent ec771ca commit 69fb7ed

26 files changed

Lines changed: 1529 additions & 647 deletions

‎website/docs/concepts/core-concepts.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Core Concepts
2+
3+
This page explains what ORC does and how its main features work. For the
4+
reasoning behind these choices, see [Design Principles](design-principles.md). For
5+
the full field-level API documentation, see the
6+
[CRD Reference](../crd-reference.md).
7+
8+
## Management Policies
9+
10+
Every ORC resource has a `managementPolicy` that determines how ORC treats the
11+
underlying OpenStack resource:
12+
13+
| Policy | Description |
14+
|--------|-------------|
15+
| `managed` | ORC creates, updates, and deletes the OpenStack resource. This is the default. |
16+
| `unmanaged` | ORC imports an existing OpenStack resource but will not modify or delete it. |
17+
18+
### When to use `managed`
19+
20+
- The resource should be created and owned by ORC
21+
- You want ORC to update the OpenStack resource when you change the spec
22+
- You want ORC to delete the OpenStack resource when you remove it from
23+
Kubernetes
24+
25+
### When to use `unmanaged`
26+
27+
- The resource is owned by another system (e.g. created by an admin or
28+
another tool)
29+
- You need to reference shared infrastructure that multiple projects use
30+
(external networks, public flavors)
31+
32+
The distinction matters most at deletion time. By default, when you delete a
33+
`managed` ORC object, ORC deletes the corresponding OpenStack resource. When you
34+
delete an `unmanaged` ORC object, the OpenStack resource is always left
35+
untouched. See [Deletion Behavior](#deletion-behavior) for how to change the
36+
default for managed resources.
37+
38+
### Create vs Import
39+
40+
A **managed** resource uses `spec.resource` to describe what should be created:
41+
42+
```yaml
43+
spec:
44+
managementPolicy: managed
45+
resource:
46+
description: My application network
47+
```
48+
49+
An **unmanaged** resource uses `spec.import` to find an existing OpenStack
50+
resource by UUID or by a filter query:
51+
52+
```yaml
53+
spec:
54+
managementPolicy: unmanaged
55+
import:
56+
filter:
57+
name: public
58+
external: true
59+
```
60+
61+
When importing by filter, the filter must match exactly **one** resource:
62+
63+
- **No matches**: ORC keeps retrying (the resource stays `Progressing: True`).
64+
This is useful when you expect another system to create the resource soon.
65+
- **Multiple matches**: ORC reports a terminal error. Make the filter more
66+
specific.
67+
68+
See [Troubleshooting](../troubleshooting.md#common-issues) for debugging
69+
import filter issues. The [Tutorial](../getting-started.md) walks through
70+
importing resources step by step.
71+
72+
## Resource References and Dependencies
73+
74+
ORC resources reference each other using `*Ref` fields (e.g. `networkRef`,
75+
`flavorRef`, `portRef`). These references serve three purposes:
76+
77+
1. **Name resolution**: References are resolved by Kubernetes object name
78+
within the same namespace. References to other OpenStack resources always
79+
go through an ORC object, never by raw OpenStack UUID. (A few spec fields
80+
do accept raw IDs for values that aren't references to other resources,
81+
such as setting a resource's own ID or a port's host ID.)
82+
83+
2. **Automatic ordering**: ORC waits for a referenced resource to exist and
84+
be `Available` before proceeding. You can apply all your resources at once
85+
in any order and ORC will sort out the sequencing.
86+
87+
3. **Deletion protection**: ORC prevents deletion of a resource while other
88+
resources still reference it. If you delete everything at once, ORC
89+
automatically deletes them in the correct reverse order.
90+
91+
See [Design Principles](design-principles.md#orc-objects-only-reference-orc-objects)
92+
for why ORC requires all references to go through ORC objects.
93+
94+
### Cross-namespace references
95+
96+
ORC does not allow cross-namespace references. All `*Ref` fields resolve within
97+
the same namespace. This applies to ORC objects, credential secrets, and any
98+
other referenced objects. See
99+
[Design Principles](design-principles.md#no-cross-namespace-references) for the
100+
rationale behind this choice.
101+
102+
## Deletion Behavior
103+
104+
For managed resources, the `managedOptions.onDelete` field controls what happens
105+
when the Kubernetes object is deleted:
106+
107+
| Value | Description |
108+
|-------|-------------|
109+
| `delete` | Delete the OpenStack resource. This is the default. |
110+
| `detach` | Keep the OpenStack resource; only remove the ORC object. |
111+
112+
```yaml
113+
spec:
114+
managementPolicy: managed
115+
managedOptions:
116+
onDelete: detach # Keep the OpenStack resource on deletion
117+
resource:
118+
# ...
119+
```
120+
121+
Use `detach` when you want to stop managing a resource through ORC without
122+
destroying the underlying infrastructure, for example during a migration.
123+
124+
## Name Reuse
125+
126+
Deleting an ORC object and creating a new one with the same name is safe. ORC's
127+
dependency management ensures that the old resource is fully cleaned up before
128+
the new one takes its place.
129+
130+
## Status and Conditions
131+
132+
Every ORC resource reports its state through two conditions: **Available** (is
133+
the resource ready?) and **Progressing** (is ORC still working on it?). A
134+
resource is healthy when `Available=True` and `Progressing=False`.
135+
136+
When something goes wrong, the condition's `reason` and `message` fields explain
137+
what happened. See [Status Conditions Reference](../reference/conditions.md)
138+
for the full list of condition states, reasons, and recommended actions.
139+
140+
ORC surfaces error messages, including potentially sensitive details from
141+
OpenStack, directly in status conditions.
142+
143+
The `.status.resource` field contains the observed state from OpenStack,
144+
including fields that OpenStack assigns (like `projectID`, `createdAt`, etc.).
145+
146+
## Cloud Credentials
147+
148+
Every ORC resource has its own `cloudCredentialsRef` that points to a Kubernetes
149+
Secret containing OpenStack credentials. The secret holds a standard OpenStack
150+
`clouds.yaml`, and each ORC resource specifies which cloud entry to use.
151+
Because credentials are per-resource, you can manage OpenStack resources across
152+
multiple clouds or projects from the same namespace.
153+
154+
ORC prevents deletion of credential secrets while they are still referenced by
155+
ORC resources, ensuring credentials aren't accidentally removed from under
156+
running infrastructure.
157+
158+
See [Set Up Cloud Credentials](../howto/cloud-credentials.md) for step-by-step
159+
instructions on creating the secret, adding custom CA certificates, and
160+
referencing credentials from ORC resources.
161+
162+
## Resource Naming
163+
164+
By default, ORC creates OpenStack resources with the same name as the Kubernetes
165+
object. You can override this using `spec.resource.name`. See
166+
[Design Principles](design-principles.md#resource-naming) for how ORC handles
167+
duplicate names safely.
168+
169+
## Deterministic Behavior
170+
171+
When OpenStack would create resources behind the scenes or make arbitrary
172+
choices, ORC requires the user to be explicit instead. See
173+
[Design Principles](design-principles.md#deterministic-behavior) for examples.

‎website/docs/concepts/design-principles.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Design Principles
2+
3+
This page explains why ORC is designed the way it is. It covers the principles
4+
and trade-offs that guide ORC's behavior. Understanding these principles helps
5+
you predict how ORC will behave in situations the documentation doesn't
6+
explicitly cover. For a practical introduction to ORC's features, see
7+
[Core Concepts](core-concepts.md).
8+
9+
## ORC objects only reference ORC objects
10+
11+
In order to fully manage dependencies, ORC only ever references other ORC
12+
objects in spec fields. You cannot put a raw OpenStack UUID in a `*Ref` field.
13+
Instead, you create an ORC object (even an `unmanaged` import) and reference
14+
that.
15+
16+
This may seem like extra work for simple cases, but it gives ORC a complete
17+
picture of the dependency graph. That's what makes automatic ordering and
18+
deletion protection possible: ORC knows what depends on what because every
19+
relationship goes through a Kubernetes object it can watch.
20+
21+
Status fields *do* contain OpenStack UUIDs. When reporting observed state, ORC
22+
directly reports what OpenStack returned, including resource IDs.
23+
24+
## No implicit resource creation
25+
26+
ORC avoids API options that would cause OpenStack to create resources behind the
27+
scenes. For example, OpenStack's server create API accepts networks by network
28+
ID, port ID, or fixed IP, all inline. Passing a network or IP address inline
29+
would cause OpenStack to create a port implicitly, invisible to ORC. ORC
30+
requires you to create a separate Port object and reference it via `portRef`,
31+
so every resource has a clear owner.
32+
33+
## Deterministic behavior
34+
35+
Given a spec, the resulting OpenStack state should be predictable. ORC honors
36+
OpenStack's default values, but where OpenStack would make an arbitrary choice,
37+
ORC requires the user to be explicit.
38+
39+
For example, creating a port on a network with multiple subnets would let
40+
OpenStack pick a subnet arbitrarily. ORC will not create IP addresses for ports
41+
unless the user specifies them in the spec.
42+
43+
## No cross-namespace references
44+
45+
ORC does not allow cross-namespace references. This applies to all references,
46+
including references to other ORC objects and to non-ORC objects such as
47+
credential secrets and user-data secrets.
48+
49+
This design principle:
50+
51+
- **Reduces security risk**: a bug in the controller cannot accidentally leak
52+
resources from other namespaces
53+
- **Enables namespace-scoped operation**: ORC can run in a single namespace
54+
without any ClusterRoles
55+
56+
## Resource naming
57+
58+
By default, ORC creates OpenStack resources with the same name as the Kubernetes
59+
object. Since Kubernetes enforces unique names within a namespace, OpenStack
60+
resources created by ORC will have distinct names by default.
61+
62+
ORC also allows overriding the OpenStack name via `spec.resource.name`, which
63+
makes it possible to create OpenStack resources with duplicate names. ORC
64+
handles this correctly because it always tracks resources by their OpenStack ID
65+
(stored in `status.id`), not by name.
66+
67+
## Error reporting
68+
69+
ORC considers itself an agent of the user: error messages, including
70+
potentially sensitive details from OpenStack, are surfaced directly in status
71+
conditions because the user would have received the same response calling the
72+
API directly.

‎website/docs/concepts/drift-detection.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Drift Detection and External Deletion
2+
3+
This page explains how ORC's periodic resync works, what happens when resources
4+
are changed or deleted outside of ORC, and how dependent resources are affected.
5+
For practical setup steps, see
6+
[How to Enable Drift Detection](../howto/drift-detection.md).
7+
8+
## How periodic resync works
9+
10+
After a resource reaches a stable state (`Progressing=False`), ORC schedules a
11+
reconciliation after the configured `resyncPeriod`. On each resync:
12+
13+
1. ORC fetches the current state of the OpenStack resource.
14+
2. For **managed** resources: if drift is detected, ORC updates the resource to
15+
match the Kubernetes spec.
16+
3. For **unmanaged** resources: ORC refreshes `status.resource` to reflect the
17+
current OpenStack state, but makes no changes.
18+
4. The next resync is scheduled.
19+
20+
A small random jitter ([0%, +20%]) is applied to `resyncPeriod` to spread
21+
reconciliations and avoid thundering-herd effects.
22+
23+
!!! note
24+
25+
Resources in a terminal error state (`Progressing=False` with reason
26+
`InvalidConfiguration` or `UnrecoverableError`) are **not** periodically
27+
resynced. Terminal errors require manual intervention to resolve.
28+
29+
### Restart behavior
30+
31+
ORC persists `status.lastSyncTime` in the Kubernetes status. After a controller
32+
restart, it uses this timestamp to determine when the next resync should occur,
33+
preventing a thundering herd of reconciliations on startup.
34+
35+
## External deletion handling
36+
37+
When a resource is deleted directly from OpenStack (bypassing ORC), the behavior
38+
depends on how ORC originally obtained the resource.
39+
40+
### Managed resources are recreated
41+
42+
If you created the resource through ORC's `spec.resource` field, ORC
43+
**recreates** it automatically:
44+
45+
1. ORC detects the resource is missing from OpenStack (the ID stored in
46+
`status.id` no longer exists).
47+
2. ORC clears `status.id`.
48+
3. On the next reconcile, ORC creates a new OpenStack resource.
49+
4. The new resource ID is stored in `status.id`.
50+
51+
The ORC object continues to exist and becomes `Available=True` again once the
52+
resource is recreated.
53+
54+
!!! warning
55+
56+
Recreation produces a new OpenStack resource with a **new ID**. Any
57+
OpenStack resources (outside ORC) that referenced the old ID will need to be
58+
updated manually.
59+
60+
### Imported resources enter terminal error
61+
62+
If you imported an existing resource using `spec.import`, ORC reports a
63+
**terminal error** when the resource is deleted from OpenStack:
64+
65+
- `Available=False`
66+
- `Progressing=False`
67+
- Condition reason: `UnrecoverableError`
68+
- Message: `resource has been deleted from OpenStack`
69+
70+
ORC does **not** recreate imported resources because it did not create them
71+
originally, and recreating a new empty resource would not restore what was lost.
72+
73+
To recover: delete and recreate the ORC object pointing at a new or restored
74+
OpenStack resource.
75+
76+
## Implications for dependent resources
77+
78+
OpenStack enforces referential integrity for most resource relationships. For
79+
example, a Network cannot be deleted while Subnets exist on it. This means
80+
externally deleting a parent resource is normally prevented by OpenStack itself.
81+
82+
!!! warning
83+
84+
If a parent resource is externally deleted in a way that bypasses
85+
OpenStack's referential integrity (e.g. direct database manipulation),
86+
manual cleanup of both the parent and dependent resources may be required.
87+
This is an unusual operational scenario.

0 commit comments

Comments
 (0)