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@corp not periscope-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.event with these fields:
- actor — the oidc subject (e.g. alice@corp)
- verb — the action taken
- target — the cluster, namespace, resource, name
- outcome — success / failure / denied
- request_id — for cross-referencing app logs
- reason — 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.

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.
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: payments
```
periscope 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).

common questions.

what problem does periscope solve?

can i use periscope on non-eks clusters?

how is identity audited?

pod identity vs irsa — which should i use?

does periscope store any aws keys?

what's the security model?

where is the audit log stored, and how long is it kept?

what audit backend ships in v1?

how do i add a new cluster?