# 1Password Connect migration plan (ESO)

This document outlines the migration from SOPS-managed application secrets to 1Password Connect with External Secrets Operator (ESO).


# Principles and constraints

- Keep a minimal SOPS-encrypted bootstrap for cluster bring-up and Flux decryption.
- Use ESO with a shared `ClusterSecretStore` named `onepassword`.
- Deploy ESO and 1Password Connect in `external-secrets` namespace.
- Use a push-style migration: load secrets into 1Password first, then switch workloads to `ExternalSecret`.
- Organize cutovers namespace-by-namespace to reduce coordination overhead.


# Phase 0: Discovery and design

- Inventory current SOPS secrets by namespace and classify shared vs app-specific values.
- Confirm 1Password vault strategy (default vault: `homelab`).
- Confirm naming conventions and field mapping.
- Prepare migration inputs: SOPS path -\> 1Password item title/field labels.


## Phase 0 outputs (current repository state)

| Namespace | App | SOPS file path | Notes |
|----|----|----|----|
| bootstrap | bootstrap | `kubernetes/bootstrap/age-key.sops.yaml` | Shared bootstrap (age key). |
| bootstrap | bootstrap | `kubernetes/bootstrap/github-deploy-key.sops.yaml` | Shared bootstrap (Flux deploy key). |
| cert-manager | cert-manager | `kubernetes/apps/cert-manager/cert-manager/issuers/secret.sops.yaml` | App-specific issuer credentials. |
| database | cloudnative-pg | `kubernetes/apps/database/cloudnative-pg/cluster/secrets.sops.yaml` | App-specific database credentials. |
| database | ext-postgres-operator | `kubernetes/apps/database/ext-postgres-operator/app/secret.sops.yaml` | Operator credentials. |
| database | pgadmin | `kubernetes/apps/database/pgadmin/app/secret.sops.yaml` | App-specific credentials. |
| datasci | cloudnative-pg | `kubernetes/apps/datasci/postgres/cloudnative-pg/cluster/secrets.sops.yaml` | App-specific database credentials. |
| datasci | ext-postgres-operator | `kubernetes/apps/datasci/postgres/ext-postgres-operator/app/secret.sops.yaml` | Operator credentials. |
| datasci | mlflow | `kubernetes/apps/datasci/mlflow/app/secret.sops.yaml` | App-specific credentials. |
| datasci | mlflow | `kubernetes/apps/datasci/mlflow/app/secret-gateway.sops.yaml` | Gateway-specific credentials. |
| datasci | mlflow | `kubernetes/apps/datasci/mlflow/app/secret-s3.sops.yaml` | Object storage credentials. |
| default | calibre-web-automated | `kubernetes/apps/default/calibre-web-automated/app/secret.sops.yaml` | App-specific credentials. |
| default | calibre-web-automated | `kubernetes/apps/default/calibre-web-automated/app/secret-oidc.sops.yaml` | OIDC client credentials. |
| default | homebox | `kubernetes/apps/default/homebox/app/secret.sops.yaml` | App-specific credentials. |
| default | homepage | `kubernetes/apps/default/homepage/app/secret.sops.yaml` | App-specific credentials. |
| default | jelu | `kubernetes/apps/default/jelu/app/secret-oidc.sops.yaml` | OIDC client credentials. |
| default | karakeep | `kubernetes/apps/default/karakeep/app/secret.sops.yaml` | App-specific credentials. |
| default | karakeep | `kubernetes/apps/default/karakeep/app/secret-oidc.sops.yaml` | OIDC client credentials. |
| default | mealie | `kubernetes/apps/default/mealie/app/secret.sops.yaml` | App-specific credentials. |
| default | mealie | `kubernetes/apps/default/mealie/app/secret-oidc.sops.yaml` | OIDC client credentials. |
| default | memos | `kubernetes/apps/default/memos/app/secret-oidc.sops.yaml` | OIDC client credentials. |
| default | miniflux | `kubernetes/apps/default/miniflux/app/secret.sops.yaml` | App-specific credentials. |
| default | miniflux | `kubernetes/apps/default/miniflux/app/secret-oidc.sops.yaml` | OIDC client credentials. |
| default | picoshare | `kubernetes/apps/default/picoshare/app/secret.sops.yaml` | App-specific credentials. |
| debug | whoami | `kubernetes/apps/debug/whoami/app/secret-oidc.sops.yaml` | OIDC client credentials. |
| flux | flux vars | `kubernetes/flux/vars/cluster-secrets.sops.yaml` | Shared bootstrap variables. |
| flux | flux vars | `kubernetes/flux/vars/custom-secrets.sops.yaml` | Shared customization variables. |
| flux-system | flux-system | `kubernetes/apps/flux-system/addons/webhooks/github/secret.sops.yaml` | GitHub webhook secret. |
| network | cloudflared | `kubernetes/apps/network/cloudflared/app/secret.sops.yaml` | Tunnel credentials. |
| network | external-dns | `kubernetes/apps/network/external-dns/app/secret.sops.yaml` | DNS provider credentials. |
| observability | grafana operator | `kubernetes/apps/observability/grafana/operator/secret.sops.yaml` | App-specific credentials. |
| observability | grafana operator | `kubernetes/apps/observability/grafana/operator/secret-oidc.sops.yaml` | OIDC client credentials. |
| observability | kube-prometheus-stack | `kubernetes/apps/observability/kube-prometheus-stack/app/secret-additionalScrapeConfigs.sops.yaml` | Additional scrape configs. |
| observability | kube-prometheus-stack | `kubernetes/apps/observability/kube-prometheus-stack/app/secret-alertmgrNotifiers.sops.yaml` | Alertmanager notifiers. |
| observability | nut-exporter | `kubernetes/apps/observability/nut-exporter/app/secret.sops.yaml` | App-specific credentials. |
| security | authelia | `kubernetes/apps/security/authelia/app/secret.sops.yaml` | App-specific credentials. |
| security | lldap | `kubernetes/apps/security/lldap/app/secret.sops.yaml` | Directory credentials. |
| blog | hugo | `kubernetes/apps/blog/hugo/app/secret.sops.yaml` | App-specific credentials. |

Notes:

- Bootstrap SOPS files remain encrypted after cutover for bootstrap/Flux workflows.
- Namespace inventories should drive `ExternalSecret` mappings during Phase 3.


# Phase 1: GitOps foundation in `kubernetes/apps/external-secrets`

Status checklist:

Deploy ESO via `external-secrets-operator` Flux Kustomization.

Deploy 1Password Connect + `ClusterSecretStore/onepassword` via `onepassword` Flux Kustomization.

Configure shared `ClusterExternalSecret` for `cluster-secrets` fan-out.

Provide example `ExternalSecret` and `ClusterExternalSecret` manifests.


## Phase 1 outputs (current repository state)

- Namespace + app root kustomization: `kubernetes/apps/external-secrets/`.
- ESO app: `kubernetes/apps/external-secrets/external-secrets-operator/`.
- 1Password app: `kubernetes/apps/external-secrets/onepassword/`.
- `ClusterSecretStore`: `onepassword`.
- Bootstrap secret expected in `external-secrets` namespace: `onepassword-secret` with keys:
  - `1password-credentials.json`
  - `token`


# Phase 2: Migration tooling and documentation

Inventory crawler: `scripts/onepassword/crawl.py`.

Push helper (SOPS -\> 1Password via `op`): `scripts/onepassword/push.py`.

ExternalSecret generator: `scripts/onepassword/externalsecrets.py`.

Tooling guide: see [1Password ESO migration tooling](onepassword-eso-migration-tooling.md).


# Phase 3: Namespace-by-namespace cutover

For each namespace:

- Create/adjust `ExternalSecret` resources mapping K8s keys to 1Password fields.
- Update namespace app manifests to consume ESO-managed secrets.
- Validate reconciliation (`ExternalSecret`/`ClusterSecretStore` Ready conditions).
- Remove direct SOPS consumption once cutover is verified.


# Phase 4: Cleanup and legacy handling

Keep minimal SOPS bootstrap only.

Remove unused SOPS app secrets after successful namespace cutovers.

Add monitoring/alerting for ESO sync errors and store readiness.


# Additional recommended milestones

- RBAC hardening: minimize ESO permissions and limit `ClusterExternalSecret` use where possible.
- Reliability: set/verify resource requests and disruption budgets for ESO + Connect.
- Observability: add dashboards/alerts for ESO reconciliation failures.
- Resilience drills: practice 1Password credential rotation and ESO recovery.


# Naming conventions (1Password + ESO)

- 1Password vault: `homelab` (use consistently for ESO and `op` references).
- `op` reference pattern: `op://homelab/<namespace>.<appname>/[section]/<field>`.
- 1Password item title: `{namespace}.{appname}` (example: `default.ghost`).
- Use `section` for grouping by purpose (for example `app`, `oidc`, `db`) when needed.
- Separator preference between namespace and app name: `.`, then `_`, then `-`.
- ESO's 1Password provider matches by field label and ignores section names, so field labels must be unique per item.
- Shared item titles: `shared.{purpose}`.
- Secret fields: `username`, `password`, `apiKey`, `token`, `certificate`, `privateKey`.
- Kubernetes Secret names: `app` or `app-<purpose>` in the app namespace.
- ExternalSecret resource names: `{namespace}-{app}-{source}` (example: `default-ghost`).
- ClusterSecretStore name: `onepassword`.
- `remoteRef.key` maps to item title; `remoteRef.property` maps to field label.