About image signature verification¶
Your VSatellite protects the cluster it runs in with image signature verification. Before any VSatellite workload (Deployments and Jobs) is allowed to start, its container image is checked to confirm that it was published and signed by a trusted source. Unsigned or tampered images are rejected.
Verification is enforced by Connaisseur, a Kubernetes admission controller that runs in its own connaisseur namespace alongside the VSatellite. You don't interact with Connaisseur directly, because it's managed for you.
In normal operation you don't need to do anything: verification is on by default, and the signing keys and certificates are managed automatically. This topic is for the rare case where you're asked to turn enforcement off temporarily, or you need to investigate why a workload didn't start.
What gets verified¶
Images pulled from the trusted VSatellite registries are verified:
public.ecr.aws/venafi-vsatellite/*registry.venafi.cloud/public/venafi-vsatellite/*
Images pulled from any other registry are admitted normally, without verification.
The keys and certificates used to check signatures are delivered and rotated automatically. They're internal to Venafi and you have no access to them, so there's nothing for you to manage or rotate.
Enforcement modes¶
Verification runs in one of two modes:
| Mode | What happens | When to use it |
|---|---|---|
| Enforcing (default) | Unsigned or invalid images are rejected, and their pods are denied. | Normal, secure operation. |
| Detection mode | Verification still runs and is logged, but pods are allowed to start regardless of the result. | Only as a temporary workaround, when advised to. |
Important
Leave enforcement on. Detection mode is a temporary workaround for use when something is wrong on the Venafi side, and it leaves the VSatellite without the protection that image signature verification provides. Turn enforcement back on as soon as the underlying problem is resolved.
Checking the current mode¶
Use the vsatctl img-verify command to check or change the mode at any time.
Note
You must run this command with root privileges because it connects to the VSatellite cluster using credentials from a file that only root users can access.
To show the current state, run:
sudo vsatctl img-verify
The command reports one of the following:
INFO Image verification is currently enabled (enforcing)
INFO Image verification is currently disabled (detection mode)
Turning enforcement off and on¶
During installation or recovery¶
New VSatellite installations have image signature verification enabled by default.
To install or recover a VSatellite without enforcing verification, use the --skip-img-verify flag:
sudo vsatctl install --skip-img-verify [other flags]
sudo vsatctl recover --skip-img-verify [other flags]
The VSatellite starts in detection mode. Verification still runs and is logged, but no pods are blocked.
After installation¶
To turn enforcement on, so that unsigned images are rejected, run:
sudo vsatctl img-verify true
To turn enforcement off and run in detection mode, run:
sudo vsatctl img-verify false
Changing the setting restarts the Connaisseur admission controller so that the new behavior takes effect immediately.
The mode persists across VSatellite updates. A VSatellite installed with --skip-img-verify, or switched to detection mode later, stays in detection mode until you turn enforcement back on.
Troubleshooting¶
Generally you shouldn't need to investigate image signature verification yourself, but on rare occasions Venafi support engineers may ask you to collect the Connaisseur logs.
Verification problems are recorded as error messages in the logs of the pod running in the connaisseur namespace. The pod name ends in a different suffix each time, so list the pods first:
sudo kubectl get pods -n connaisseur
Then show the logs for the pod name returned by that command:
sudo kubectl logs -n connaisseur <pod>
Note
On RHEL, Oracle, and Rocky Linux, sudo kubectl fails by default because of the secure_path setting in /etc/sudoers. For workarounds, see Sudo secure_path settings that prevent running sudo kubectl.
How Connaisseur is installed and updated¶
You don't install or remove Connaisseur yourself. Its lifecycle follows the VSatellite:
- New installations: Connaisseur is deployed automatically as part of VSatellite setup. The VSatellite waits for Connaisseur to become ready before it enables the admission webhook, so there's no window in which legitimate pods are blocked.
- Existing VSatellites: Connaisseur is added automatically during a VSatellite update if it isn't already present. If Connaisseur is already installed, nothing changes.