common questions.

identity & auth

• how is identity audited?

  #

  every privileged action — apply, delete, scale, secret reveal, exec into a pod, opening a cluster-wide shell, 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.

• what does the aws access surface do?

  #

  three surfaces shipped in v1.1.

  • cluster access page. reconciles eks Access Entries with the legacy kube-system/aws-auth ConfigMap, builds a unified ServiceAccount → IAM Role index across IRSA annotations and Pod Identity associations, surfaces the Pod Identity view by role, and rolls migration health into one chip ( aws-auth-only / entries-only / both).
  • aws access tab. every Pod / SA / Deployment / StatefulSet / DaemonSet detail pane resolves the identity chain server-side, fetches every inline + managed IAM policy attached to the bound roles, groups by AWS service, and chips against an 18-action sensitive-permissions catalog.
  • reverse lookup. answers which workloads can perform action X? in one query — one row per matched pod, with binding source attribution (IRSA / Pod Identity).

  the iam grant the server needs (plus the optional iam:SimulatePrincipalPolicy probe for the locked-feature pane) is documented at cluster-rbac; the operator walkthrough lives at aws-access.

• what's the sensitive-permissions catalog?

  #

  an embedded, versioned list of iam actions periscope chips as sensitive on the aws access tab. 17 named actions plus the literal * wildcard, in six categories:

  • privilege-escalation — e.g. iam:PassRole, iam:CreatePolicyVersion.
  • data — e.g. secretsmanager:GetSecretValue on a broad resource scope.
  • cross-account — e.g. sts:AssumeRole with a wildcard target.
  • destructive — e.g. s3:DeleteBucket, ec2:TerminateInstances.
  • cluster — control-plane reads worth flagging when granted broadly.
  • wildcard — any statement granting *:* or Service:*.

  the catalog lives at internal/awseks/iam/sensitive.yaml in the periscope repo, catalogVersion: 1.0.0 on every wire response so operators can trace why is this flagged? back to a specific catalog version. cluster-agnostic — mcp / ai tools fetch the same shape at GET /api/identity/sensitive-catalog.

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?

  #

  two paths, depending on whether the cluster is in your aws account or not.

  direct backend (eks / kubeconfig / in-cluster) — edit clusters.yaml (mounted via configmap, path /etc/periscope/clusters.yaml) and add an entry:

  - name: prod-eu-west-1
    backend: eks               # or: kubeconfig, in-cluster
    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. needs aws iam (pod identity / irsa) and an eks access entry per cluster.

  agent backend — for clusters where iam trust is impractical (other aws accounts, other clouds, on-prem). add a registry entry with backend: agent on the central server, then on the managed cluster click + onboard cluster in the fleet view, copy the bootstrap token, and run helm install periscope-agent. the agent dials out to the server, no inbound network needed. full walkthrough at agent onboarding.

  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).