docs(secureguard): accuracy pass, feature coverage, launch unhide, OpenBao 0.3.0#2209
Open
scheeles wants to merge 12 commits into
Open
docs(secureguard): accuracy pass, feature coverage, launch unhide, OpenBao 0.3.0#2209scheeles wants to merge 12 commits into
scheeles wants to merge 12 commits into
Conversation
- Getting Started: document auto-generated Dex admin password retrieval (chart never uses a hardcoded password) and add the missing RBAC binding step required before the dashboard shows anything - Installation: rewrite proxy RBAC section to the impersonation model (no standing read access); document the Reloader sub-chart; clarify Bring-Your-Own-ESO scope - Advanced Configuration: replace the outdated 'no metrics' monitoring section with the real Prometheus metrics, ServiceMonitor/PodMonitor values and health endpoints; complete the proxy env-var table (SESSION_SECRET, OIDC_*, LOG_LEVEL, COOKIE_SECURE, ...); pin the manual ESO install example to a supported 2.x release - ESO Basics: correct ReloaderConfig ownership (Reloader companion project, reloader.external-secrets.io/v1alpha1, bundled sub-chart) - Troubleshooting: document LOG_LEVEL debug knob; replace the orphaned 'init container mode' note with informer-based Secret discovery; precise auto-unseal anchor - Federation: pin fedclient image tag; drop internal test-suite jargon - Fix four provider links to point at ESO's provider support matrix Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
…rence - New API Reference page: proxy REST endpoints, CSRF contract, method- aware route allowlist, redaction, cluster discovery, error semantics; all GitHub links to the internal api-reference.md now point here - User Guide: stale-secret detection heuristic (2x refreshInterval), Sync Error Drawer with remediation hints, event-stream controls (filters, pause/resume, clear, polling/buffer), visualization graph + list views, ?cluster= URL param, ESODeployment create/edit form (version catalog picker, form<->YAML toggle, reloader toggle, cron image updates), conflict pre-validation, Discovered/external mode, Add Cluster wizard steps, Test Connection and Delete Cluster - Advanced Configuration: conflict detection semantics (severities, Conflict condition) and external-ESO discovery (eso-ext-*, managementMode: external) - Installation: component enable matrix incl. opt-in sgAgent/federation defaults, chart auto-wiring (session secret, Dex->OpenBao OIDC job, Kubernetes auth job, openbao-backend ClusterSecretStore, projected token lifetime), ingress trio, values-production.yaml Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
- Troubleshooting: new Federation section (401/403/404 broker outcomes mapped to fedclient exit codes, OIDC discovery/caBundle failures, mandatory TLS), ESODeployment & SG Agent failure modes (agent disabled by default, Conflict condition, stuck Deploying, eso-ext-* discovery, stale heartbeats), kubeconfig-rejected-at-registration entry, and static-admin password recovery - Upgrade Guides: OpenBao Raft snapshot restore procedure, helm rollback step, post-upgrade verification checklist, release-notes pointer, and a version-specific-notes section Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
- Replace all links into the source repository with in-site content or Hugo refs (RBAC templates, dev manifests, sample catalogs, fedclient example) - Swap ESO Basics / OpenBao Basics nav weights to match the recommended reading order on the landing page - De-duplicate ingress TLS and resource-limit blocks between Installation and Security Hardening (canonical home + cross-links); link Installation's Production Hardening and Network Policies to the Security Hardening guide - Reconcile the two multi-tenancy stories (OpenBao namespaces vs per-tenant instances) with mutual cross-links; document disabling the OpenBao UI in production - Glossary: add ESOVersion, correct the Reloader attribution, complete the CRD example list; align front-matter dates; note on self-hosting fonts for strict CSP Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
SecureGuard is publicly launched, so remove the pre-launch front-matter flags (private / sitemapexclude / searchexclude) from all pages and drop the preview/under-development banners from the landing pages. New work now targets main directly. Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
…art 0.3.0) Reflect the chart 0.3.0 change where the bundled OpenBao now deploys as a 3-node integrated-Raft HA cluster and is automatically initialized and unsealed by a post-install/upgrade hook Job. - Installation: Raft HA is the managed default; new self-initialization section (init Job weight 0 -> unseal all nodes -> K8s auth + chart admin role -> revoke root; Shamir key shares in <release>-openbao-keys, back it up; restart-reseal caveat + unsealCronJob); KMS auto-unseal documented as the restart-resilient opt-out (init.enabled=false + seal stanza); fix the stale standalone/manual-unseal dev-mode text and add the single-node file-backend opt-out; update the chart auto-wiring list with hook weights (0/5/10) and chart-admin-role auth - OpenBao Basics: add the automated Shamir self-init path alongside manual and KMS unsealing; note 3-node Raft is the bundled default - Upgrade Guides: back up the unseal-keys Secret with the Raft snapshot; break-glass via operator generate-root (root token revoked); rewrite the OpenBao restart/unseal notes; add a 0.3.0 breaking-change entry - Troubleshooting: sealed-OpenBao resolution for the self-init default (retrieve shares from the Secret, re-unseal via upgrade/CronJob, KMS) - Advanced Configuration: Storage Backends now notes Raft HA as default - Glossary: broaden Sealing/Unsealing and Raft entries Refs kubermatic/secureguard#241 Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
kubermatic-bot
added
dco-signoff: yes
Contributor
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
…ons) The External Secrets Reloader is an event-driven trigger, not just a workload restarter. Fix every mention to describe the real model: - Notification sources: Kubernetes Secret/ConfigMap changes, cloud events (GCP Pub/Sub, AWS SQS, Azure Event Grid), Vault audit logs, generic webhook, TCP socket - Trigger destinations: Deployment rollout, or reconcile an ExternalSecret / PushSecret / WorkflowRunTemplate Removes the inaccurate 'restart Deployments/StatefulSets/DaemonSets' and 'reload strategy' details, adds the source/destination model and a link to the upstream External Secrets Reloader docs. Touches eso-basics, user-guide, glossary, installation, and the landing page. Ref https://external-secrets.github.io/reloader/ Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
Expand the Installation prerequisites beyond "Kubernetes + helm" to the platform pieces a real (non-local) install needs: - Private-registry pull credentials — SecureGuard images live in a private Quay repo, so pods ImagePullBackOff with 401 until an imagePullSecrets / global.imagePullSecrets is set (kubectl create secret docker-registry + the chart values, incl. per-sub-chart dex/reloader keys for mirrored registries). - Ingress controller + an existing IngressClass; cert-manager + a ClusterIssuer (or a pre-created TLS Secret); wildcard DNS pointed at the ingress LB. - A default StorageClass for OpenBao Raft HA PVCs, with a sizing note: EBS gp2/gp3 may not support online volume expansion, so size dataStorage up front or use allowVolumeExpansion. Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
Document the real first-install sequence for cloud clusters where the ingress load-balancer address only exists after install and cert-manager can only issue once DNS resolves: install -> read the LB address -> create wildcard DNS -> cert-manager issues secureguard-tls -> log in. Note that no restart is needed between steps: the proxy retries OIDC discovery with back-off and self-heals once the cert is issued and Dex is reachable over HTTPS. Also add a node-sizing tip covering dev-mode vs full Raft HA expectations. Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
…luster Add a prominent warning to the Multi-Cluster Deployments section: because the proxy impersonates the user on whichever cluster a request targets, a user bound only on the management cluster gets 403 on target clusters. Equivalent Role/ClusterRole bindings must exist for the user/groups on every target cluster; the management-cluster binding does not carry over. Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
…ials Flesh out Adding Clusters to the Dashboard: - Registration is stored as a Secret labeled secureguard.io/cluster-kubeconfig=true and discovered by the proxy via an informer (no restart); show how to list them. - The management/local cluster must be registered too, or its local views come up empty. - Credential constraints: the proxy mints a short-lived remote-SA token and never stores the uploaded credential as-is; bearer and exec-plugin creds work, but OIDC auth-provider kubeconfigs are rejected (no server-side plugin), and the uploaded credential must be able to create SAs/ClusterRoles/bindings. Cross-link the matching troubleshooting entry. Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
- Add a Custom Identity Providers subsection showing how to skip the Dex consent screen for the first-party dashboard via dex.config.oauth2.skipApprovalScreen (passes through the chart's dex.config verbatim), with a scope caveat. - Reinforce the OpenBao key-backup warning: back up <release>-openbao-keys as a day-one step, escrow it outside the cluster, verify readback, and note the generate-root break-glass path (root token is revoked after init). The related true caveats (openbao-backend needs ESO+OpenBao both enabled; managed ESODeployment needs sgAgent.enabled) are already stated in the docs. Signed-off-by: Sebastian Scheele <sebastian@loodse.com>
kubermatic-bot
added
size/XXL
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR does a broad accuracy + coverage pass on the SecureGuard user docs ahead of launch.
ReloaderConfigownership; pinned fedclient/ESO versions; provider links → ESO support matrix.sgAgent/federationdefaults,values-production.yaml, ingress trio.private/sitemapexclude/searchexcludefront-matter flags and the preview banners.unsealCronJob), KMS auto-unseal opt-out,bao operator generate-rootbreak-glass, and a 0.3.0 breaking-change upgrade note.ImagePullBackOff/401untilimagePullSecrets/global.imagePullSecretsis set), an ingress controller +IngressClass, cert-manager + aClusterIssuer, wildcard DNS → ingress LB, and a defaultStorageClasswith a sizing note (EBSgp2/gp3may not support online volume expansion).secureguard-tls→ log in, with a note that the proxy retries OIDC discovery and self-heals (no restart needed). Plus a node-sizing tip (dev-mode vs full Raft HA).secureguard.io/cluster-kubeconfig=true) + informer discovery, the management/local cluster must be registered too, and credential constraints (bearer/exec supported; OIDCauth-providerkubeconfigs rejected).dex.config.oauth2.skipApprovalScreenfor the first-party dashboard client, and a reinforced day-one<release>-openbao-keysbackup +generate-rootbreak-glass step.