Troubleshoot secrets managers

Each secrets manager failure in Astralis carries an error class that names the step that failed: reaching the manager, authenticating, reading the secret, or validating its contents.

Find where it fails

The common trap: a manager reads Healthy while integrations fail. The manager test proves only authentication. Run Check on the integration's secret to test the read permission.

AWS Secrets Manager errors

If a test reports that this deployment's own AWS identity failed, the problem is the Astralis deployment, not your account; the manager's health is unchanged. The classes are MissingSourceCredentials, CredentialRetrievalError, InvalidClientTokenId, SignatureDoesNotMatch, and UnrecognizedClientException.

On an Ethyca-hosted deployment, contact Ethyca support. On a deployment you run, check the AWS identity of the web server and every worker:

HashiCorp Vault errors

Errors on any manager

Common situations

A rotated credential is not picked up. Astralis uses its cached value for up to 15 minutes. A failed connection makes it fetch again immediately, so the next attempt after the target rejects the old credential uses the new one.

The manager is unreachable and integrations still work. Astralis is serving cached values; the manager reads Serving cached credentials. Integrations start failing 45 minutes after the last successful read.

A Jira ticket integration refuses the secret. A manager supplies only domain, username, and api_key to a Jira ticket integration. OAuth keys such as access_token, refresh_token, and client_secret are refused; remove them from the secret.

A Jira ticket integration has no Manage credentials button. It follows a linked Jira integration onto that integration's manager. Unlink it in its Credentials tab first; see Jira ticket integrations.

Revoke access

Revoke access in your manager. Deleting the manager in Astralis revokes nothing in your account, and Astralis refuses to delete a manager while integrations read from it.

• AWS: remove the role's secretsmanager:GetSecretValue permission on the secrets, and any resource policy on the secrets that grants the role access. Reads fail once the change propagates, usually within minutes. To cut off issued sessions at once, use Revoke active sessions on the role in IAM. Removing the trust policy statement stops new role sessions, but a session AWS already issued keeps working until it expires, by default after one hour.

• Vault: remove the read grant first. Vault checks policies on every request, so this also stops tokens Astralis already holds. Then destroy the secret IDs to prevent new logins, and revoke the tokens in use:

  # Immediate: the role's policy grants nothing
  vault policy delete astralis-read
   
  # No new logins
  vault list auth/approle/role/astralis/secret-id
  vault write auth/approle/role/astralis/secret-id-accessor/destroy secret_id_accessor=<accessor>
   
  # Tokens in use. -mode=path revokes every token issued through this login path,
  # which covers every AppRole on the mount, not only the Astralis role.
  # Requires sudo on sys/leases/revoke-prefix/auth/approle/login.
  vault token revoke -mode=path auth/approle/login

A denied read is a permanent failure: Astralis clears its cached value and never serves it from the stale window. Each Astralis process can still use a value it read in the last 15 minutes until that cached copy expires, and an operation already in progress finishes.

To stop sooner, rotate the credential at the target system, such as the database password or API key. The next connection fails, Astralis reads the secret again, and the read is refused. To stop one integration without touching your manager, switch it to credentials entered in Astralis.

Rotating the secret's value in your manager is not a revocation: Astralis reads the new value.