# v1 Do-Document 06 — Magnum Keystone Domain Setup

**Status:** First execution document of Batch C. Runs after `v1-do-doc-05-vault-init.md` (admin-openrc valid; all charms active/idle including magnum). Runs before `v1-do-doc-07-capi-bootstrap.md` (CAPI workload cluster).

**Replaces:** `runbooks/deprecated/04-magnum-domain.md` (TODO-only placeholder).

**Cross-references:**

- D-007 Layer A (Magnum bundle deploy — done by Batch B) and Layer B (Magnum driver graft — Batch C continuation)
- D-008 (DNS architecture — the magnum keystone trustee user is in admin_domain, not magnum domain)
- Charmed Magnum `domain-setup` action documentation

---


## 1. Purpose & scope

Magnum needs a dedicated Keystone domain (`magnum`) and a service-trust user inside it. Magnum uses this domain to create per-cluster "trust" users at cluster-create time — those trust users are what cluster-internal services use to call back to OpenStack (e.g., OCCM, Cinder CSI). The `magnum` domain is conceptually a sandbox; the trust users have no privileges outside of it.

**What this document does:**

- Runs the Charmed Magnum action `domain-setup` on `magnum/leader`.
- Verifies the `magnum` domain exists and is enabled.
- Verifies the `magnum_domain_admin` (or charm-named equivalent) user exists in the magnum domain.
- Verifies magnum unit is still active/idle after the action.

**What this document does NOT do:**

- Install the Magnum CAPI Helm driver — that's v1-do-doc-08 (Layer B, after CAPI bootstrap).
- Create the `capi-mgmt` Keystone project / `capo` user / app credential — those live in `admin_domain` and are created in v1-do-doc-07 (CAPI bootstrap consumes them).
- Create any tenant projects or cluster templates — those are tenant work (Batch D + ongoing).

---


## 2. Decisions captured

| Decision | Choice | Notes |
|---|---|---|
| Trustee domain | `magnum` (separate from `admin_domain`) | Charm default; per-cluster trust users go here |
| Trustee admin user name | Per charm — typically `magnum_domain_admin` | Verified in §4.3 |
| Action invocation | `juju run magnum/leader domain-setup --wait=10m` | Synchronous; 10-min timeout sufficient for testcloud |
| Verification | API-level (`openstack domain show magnum`, `openstack user show ...`) | Direct charm-state inspection optional |

---


## 3. Prerequisites

| Prereq | Verification |
|---|---|
| `v1-do-doc-05-vault-init.md` ✓ (Vault unsealed, all charms active/idle) | `juju status magnum` shows active/idle |
| admin-openrc points at Caracal cloud and works | `( source $HOME/admin-openrc; openstack token issue ) | head -3` returns a token |
| Keystone reachable on its public VIP | Already confirmed by `openstack token issue` |

**Shell context:**

```bash
export REPO="$HOME/openstack-caracal-ipv4"
cd "$REPO"
```

**Confirm starting state:**

```bash
echo "=== Magnum unit status ==="
juju status magnum -m openstack

echo ""
echo "=== Domains currently in Keystone (before domain-setup) ==="
( source "$HOME/admin-openrc"; openstack domain list )
# Expect: at least 'default' and 'admin_domain'. 'magnum' should NOT appear yet
# (unless this is a re-run, in which case it's already there — see §6 for re-run posture).
```

---


## 4. Run domain-setup action

### 4.1 Invoke

```bash
juju run magnum/leader domain-setup --wait=10m -m openstack
```

Expected output: the action returns within 1-3 minutes (well under the 10-min timeout). The result block should show `status: completed` and no error message.

### 4.2 Verify the action succeeded

```bash
echo "=== Action result inspection ==="
juju show-action-output --format yaml $(juju list-actions magnum -m openstack 2>/dev/null | tail -5 | awk '{print $1}' | head -1) 2>/dev/null || \
  echo "(Use 'juju run --wait' synchronous mode — action result was visible in §4.1 output)"
```

> **Note on Juju 3.x action output:** in Juju 3.x, `juju run` returns the action result synchronously to stdout. You don't generally need a follow-up query unless investigating a failure. If §4.1 output ended in `Running operation ... with 1 task` followed by `done`, the action succeeded.

### 4.3 Verify Keystone state

```bash
( source "$HOME/admin-openrc"

  echo "=== magnum domain exists and is enabled ==="
  openstack domain show magnum -f json | python3 -c "
import json, sys
d = json.load(sys.stdin)
print(f'  name:    {d.get(\"name\")}')
print(f'  enabled: {d.get(\"enabled\")}')
print(f'  id:      {d.get(\"id\")}')
print(f'  desc:    {d.get(\"description\")}')
"

  echo ""
  echo "=== Users in magnum domain ==="
  openstack user list --domain magnum

  echo ""
  echo "=== Projects in magnum domain (likely empty — trust projects are per-cluster) ==="
  openstack project list --domain magnum
)
```

**Expected:**

- `magnum` domain present, `enabled: True`.
- At least one user in the magnum domain. Charm default name is `magnum_domain_admin` (verify exact name in output).
- Projects list may be empty at this stage — Magnum creates per-cluster trust projects on demand at cluster-create time.

### 4.4 Verify charm state

```bash
echo "=== Magnum unit status after domain-setup ==="
juju status magnum -m openstack
# Expect: magnum/0 still active/idle. The domain-setup action should not have moved it out of active.

echo ""
echo "=== Action history for magnum (last 5) ==="
juju list-actions magnum -m openstack 2>/dev/null | tail -10
```

---


## 5. Acceptance criteria — go/no-go for v1-do-doc-07-capi-bootstrap

- [ ] `juju run magnum/leader domain-setup --wait=10m` completed without error
- [ ] `openstack domain show magnum` returns `enabled: True`
- [ ] `openstack user list --domain magnum` returns at least one user (the trustee admin)
- [ ] `juju status magnum` still shows magnum/0 in active/idle

If all checked, proceed to `v1-do-doc-07-capi-bootstrap.md`.

---


## 6. Re-run posture

The `domain-setup` action is idempotent at the charm level — re-running it does not duplicate the domain or create extra users. The most common reason to re-run is if the charm was reconfigured or upgraded; the action re-ensures the domain state matches what the charm expects.

If §4.3 shows the magnum domain already exists from a prior run, the action will report `completed` with no work performed — that's the expected behavior.

---


## 7. Roosevelt deltas (forward-look)

| Aspect | Testcloud (v1) | Roosevelt |
|---|---|---|
| Domain name | `magnum` (charm default) | Same |
| Trustee user creation | Charm action `domain-setup` | Same — but Roosevelt may layer Vault PKI for trustee credentials |
| Action invocation | Manual `juju run` | Can be wrapped in a deploy script with idempotency check |
| Verification depth | Domain + user check (this doc §4.3) | Plus Vault audit trail confirming the trustee was created with correct permissions |

---


## 8. Change log

| Date | Change | Reference |
|---|---|---|
| 2026-05-27 | Document created. Replaces placeholder runbook 04 (TODO-only). | Batch C drafting |