faq
common questions.
questions we keep getting. ctrl-f for a phrase. link to a specific answer with the # anchor next to each question.
the pitch
what problem does periscope solve?
#periscope is a kubernetes dashboard for teams that run on aws and care about least-privilege. it removes the two operational pains that bite hardest in security-conscious orgs:
- no long-lived aws credentials.periscope uses eks pod identity (or irsa) — credentials it can't paste into slack, can't leak through config files, can't outlive an employee.
- no shared cluster identity.every k8s call carries the user's oidc identity via impersonation, so the audit log shows
alice@corpnotperiscope-bot.
the audience is devops / sre / platform engineers who manage eks clusters and care about audit, least-privilege, and not getting woken up at 3am because a credential rotated.
can i use periscope on non-eks clusters?
#the dashboard, audit log, and oidc-based user authentication work on any kubernetes cluster (1.27+). only the keyless aws-token story is eks-specific — pod identity is an eks feature, and irsa uses eks-flavored oidc.
for gke / aks / on-prem clusters, you'd use the cluster's own service account auth (or whatever your provider exposes). the user-identity-via-impersonation half of the model still applies — that's pure k8s rbac.
identity & auth
how is identity audited?
#every privileged action — apply, delete, scale, secret reveal, exec into a pod, log open, cronjob trigger — is recorded as a structured
audit.eventwith these fields:actor— the oidc subject (e.g.alice@corp)verb— the action takentarget— the cluster, namespace, resource, nameoutcome—success/failure/deniedrequest_id— for cross-referencing app logsreason— the rbac decision message, if any
the audit log is a first-class view in the app at /audit — searchable, time-filterable, and exportable.
pod identity vs irsa — which should i use?
#eks pod identityis the newer, simpler option. no iam trust policy juggling, no oidc provider associations, no webhook installation. recommended if your eks version supports it (1.27+) and your account isn't blocked from the feature.
irsaworks on older eks and clusters where pod identity isn't available. slightly more setup overhead — you configure an iam role with an oidc trust policy and annotate the service account.
see setup / deploy for both walkthroughs. tl;dr: pod identity if you can, irsa if you must.
does periscope store any aws keys?
#no. periscope never touches aws access keys. authentication to eks uses temporary tokens from pod identity or irsa — these expire on a short tttl and are auto-rotated by aws. periscope just consumes them via the aws sdk.
there is no
aws_access_key_idin any config file, env var, or secret. there is no place to put one. that's the whole point.what's the security model?
#three principles:
- zero shared cluster identity.every k8s call uses the user's oidc identity via
k8s.io/v1 impersonateheaders. the apiserver evaluates rbac under that identity — periscope can't grant access the user doesn't already have. - zero long-lived credentials. the cluster connection uses pod identity / irsa tokens. user authentication uses an oidc provider (okta, auth0, etc.) — short-lived id tokens, no passwords stored anywhere.
- full audit trail with real identities. the audit row is signed by the human, not by
periscope-bot. compliance reviews stop being a log-grep exercise.
the network surface is locked down via networkpolicy; the cluster rbac periscope itself needs is documented at cluster-rbac.
- zero shared cluster identity.every k8s call uses the user's oidc identity via
audit log
where is the audit log stored, and how long is it kept?
#two backends:
- sqlite — for single-replica installs. no extra infra, just a persistent volume mounted at
/var/lib/periscope/audit/audit.db.
defaults:
- retention: 30 days (
periscope_audit_retention_days) - size cap: 1024 mb (
periscope_audit_max_size_mb) - vacuum interval: 24h (
periscope_audit_vacuum_interval)
both bounds are pruned in the background on a vacuum tick. setting both retention and size cap to 0 is the unbounded-growth footgun — the startup validator will warn.
- sqlite — for single-replica installs. no extra infra, just a persistent volume mounted at
what audit backend ships in v1?
#sqlite only, in v1. single-replica install, file lives on a small pvc, queries are fast at any reasonable retention period. the file is also the source of the in-app audit view at
/audit.for compliance teams that need a multi-year tamper-evident record, ship the structured json events from stdout to your siem (cloudwatch / loki / opensearch / datadog) and treat that as the system of record. the sqlite db is a local cache for fast in-app queries.
an ha-friendly backend (postgres or similar) is a v1.x follow-up; not on the v1.0 release. see RFC 0003 for the audit log spec including the v1.x evolution path.
operations
how do i add a new cluster?
#edit
clusters.yaml(mounted via configmap, path/etc/periscope/clusters.yaml). add an entry:- name: prod-eu-west-1 region: eu-west-1 arn: arn:aws:eks:eu-west-1:123456789012:cluster/prod-eu-west-1 environment: prod # optional tags: # optional team: paymentsperiscope picks it up on next reload. the full configmap shape is documented at setup / deploy.
v1 doesn't expose a write api for cluster registration — the source of truth is the configmap. that's by design (every cluster addition is a reviewable git change).