Run Common Operations with aa

Every Access Analyzer service runs as a pod on the server's Kubernetes cluster. Day-to-day tasks such as checking that the services are up, opening a database shell, or restarting a service would otherwise need kubectl commands that name the access-analyzer namespace, the pod, the container, and the cluster credentials every time. The aa command fills those in for you.

The installer adds aa to the server when it installs Access Analyzer, and each time dspm-installer upgrade deploys a release. It's a link at /usr/local/bin/aa to dspm-installer, so it always matches the installer version on the server. dspm-installer --uninstall removes it.

Before You Begin

• Sign in to the Access Analyzer server with an account that can run sudo.
• You don't need to type sudo. The cluster credentials in /etc/rancher/k3s/k3s.yaml are readable only by root, so aa runs itself again with sudo when you start it as another user. sudo asks for your password the first time, as it does for any command.
• Every aa command acts with full administrator rights on the cluster. A query you run in a database shell or a service you restart takes effect at once.

Command Summary

Task	Command
Show application and pod status	aa status
Open a PostgreSQL shell on the access_analyzer database	aa psql
Run one PostgreSQL statement	aa psql -c "<statement>"
Open a ClickHouse shell	aa ch
Run one ClickHouse query	aa ch --query "<query>"
Open a Redis shell	aa redis
Restart a service	aa restart <service>
Pick services to restart from a list	aa restart
Open a shell in a service	aa sh <service>
Run one command in a service	aa sh <service> -- <command>
List connector scan and sync jobs	aa scans
Run any kubectl command in the Access Analyzer namespace	aa k <kubectl arguments>
Show or follow a service's logs	aa logs <service>
Write a support bundle	aa export-logs
Show help for a command	aa <command> --help

Check the Status of Access Analyzer

aa status lists the Argo CD applications that deploy Access Analyzer, with their sync and health status, and then every pod in the access-analyzer namespace.

aa status

Read the output this way:

• An application that isn't Synced and Healthy is still deploying, or one of its resources has a problem.
• A pod is ready when both numbers in its READY column match, such as 1/1. Pods whose STATUS is Completed are one-time jobs that have finished, and 0/1 is normal for them.
• A RESTARTS count that keeps growing points to a service that crashes. Read the logs from before the last restart with aa logs <service> --previous, as View and Export Logs describes.

Open a Database Shell

aa psql, aa ch, and aa redis open the database's own client inside its pod. The client signs in with the credentials the pod already holds, so you never type or see a database password.

Command	Opens	Signed in as
aa psql	psql on the access_analyzer PostgreSQL database	postgres
aa ch	clickhouse-client on ClickHouse	The ClickHouse service user
aa redis	redis-cli on Redis	No sign-in needed

aa psql

Type \q to leave psql, exit to leave clickhouse-client, and quit to leave redis-cli. Ctrl+C cancels the running query and keeps the session open.

Everything you type after the command goes to the client, so you can run one statement and return to the prompt:

aa ch --query "SELECT name FROM system.databases ORDER BY name"
aa redis ping

To run a file of statements, redirect it into the command, for example aa psql < cleanup.sql.

warning

Changes you make in a database shell are permanent. Before you change or delete data, confirm that a recent backup exists, as Backups describes, and change data only when Netwrix Support asks you to.

Restart a Service

aa restart performs a rolling restart of one or more services: Kubernetes starts a new pod, and stops the old one when the new pod is ready. Name each service by its Deployment or StatefulSet name, such as core-api, webapp, or clickhouse. The pod names in aa status start with these names.

aa restart webapp
aa k rollout status deployment/webapp

aa k rollout status waits until the restart finishes. With no service name, aa restart lists the services so you can pick one or more with the Space key and confirm with Enter. A name that doesn't match a service prints the list of valid names.

Open a Shell in a Service

aa sh <service> opens a shell in the service's pod, which helps you check files, disk usage, or network access from inside the cluster. Type exit to leave the shell.

aa sh clickhouse

• To run one command instead of a shell, put it after --, for example aa sh postgres -- df -h. Without --, aa sh reads the extra words as more service names and stops with an error.
• In a pod with more than one container, the shell opens in the main container. Pick another one with -c <container>.
• To reach a pod that isn't a Deployment or StatefulSet, such as a scan job, pass its type and name, for example aa sh pod/<pod-name>.

The Access Analyzer application services, such as core-api and connector-api, run in minimal images that contain no shell, so aa sh fails for them with executable file not found. Read their logs with aa logs instead.

List Scan Jobs

Each scan and sync that a connector runs is a Kubernetes job. aa scans lists these jobs, oldest first, with the connector, job type, and how the run was started.

aa scans

Add -w to keep the list open and print each change as jobs start and finish. Press Ctrl+C to stop. When no scan has run recently, the command prints No resources found in access-analyzer namespace.

Run Any kubectl Command

aa k runs kubectl with the cluster credentials and the access-analyzer namespace already set. Everything after k goes to kubectl unchanged.

aa k get pvc

To work in another namespace, add -n <namespace> or -A after k, for example aa k -n argocd get applications. Your namespace takes the place of access-analyzer.

Read Logs

aa logs and aa export-logs are the same commands as dspm-installer logs and dspm-installer export-logs. For targets, flags, and support bundles, see View and Export Logs.

Turn On Tab Completion

The installer writes a Bash completion script for aa to /etc/bash_completion.d/aa. With it, the Tab key completes command names, service names for aa restart and aa sh, and the kubectl arguments after aa k.

Completion needs the bash-completion package. Most Ubuntu Server installs include it. To add it:

• Ubuntu: sudo apt install bash-completion
• Red Hat Enterprise Linux (RHEL): sudo dnf install bash-completion

Sign out and back in, or open a new shell, for completion to start working.

Service names and kubectl arguments come from the cluster, which needs root. For an account other than root, they complete only while sudo remembers your password, such as within a few minutes after you run another aa command. Pressing Tab never asks for a password. Command names and flags always complete.

Troubleshooting

Problem	Cause and fix
aa: command not found	The installer on the server predates aa. Download the current installer to /usr/local/bin/dspm-installer, as Download the Installer describes, and run sudo dspm-installer again. A run with a newer installer goes through every install step, adds aa, and keeps your settings and data.
The installer prints Warning: the aa command could not be installed: /usr/local/bin/aa is not a link this installer created; leaving it in place	Another program already uses /usr/local/bin/aa. Run the commands as sudo dspm-installer instead, or move the other program and re-run the installer.
The installer prints Warning: the aa command could not be installed: not linking aa to <path>	The installer ran from a temporary directory, or from a file that root doesn't own. aa runs the installer as root, so it links only to a root-owned copy. Install the installer at /usr/local/bin/dspm-installer, as Download the Installer describes, and run it again from there.
Warning: aa needs root and could not re-run itself with sudo	sudo isn't installed, or isn't on your PATH. Run aa as root.
<user> is not in the sudoers file	Your account can't use sudo. Ask your Linux administrator for sudo rights, or sign in as root.