Need help with portieris?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

246 Stars 47 Forks Apache License 2.0 227 Commits 39 Opened issues


A Kubernetes Admission Controller for verifying image trust with Notary.

Services available


Need anything else?

Contributors list

Portieris logo

Travis badge

Portieris is a Kubernetes admission controller for the enforcment of image security policies. You can create image security policies for each Kubernetes namespace, or at the cluster level, and enforce different rules for different images.

How it works

Portieris uses a Kubernetes Mutating Admission Webhook to modify your Kubernetes resources, at the point of creation, to ensure that Kubernetes runs only policy compliant images. When configured to do so, it can enforce Docker Content Trust with optional trust pinning, or can verify signatures created using RedHat's simple signing model and will prevent the creation of resources using untrusted or unverified images.

If your cloud provider provides a Notary server (sometimes referred to as Content Trust), Portieris accesses trust data in that Notary server that corresponds to the image that you are deploying. In order to verify RedHat simple signatures they must be accessible via registry extension APIs or a configured signature store.

When you create or edit a workload, the Kubernetes API server sends a request to Portieris. The AdmissionRequest contains the content of your workload. For each image in your workload, Portieris finds a matching security policy.

If trust enforcement is enabled in the policy, Portieris pulls signature information for your image from the corresponding Notary server and, if a signed version of the image exists, creates a JSON patch to edit the image name in the workload to the signed image by digest. If a signer is defined in the policy, Portieris additionally checks that the image is signed by the specified role, and verifies that the specified key was used to sign the image.

If simple signing is specified by the policy, Portieris will verify the signature using using the public key and identity rules supplied in the policy and if verified similarly mutates the image name to a digest reference to ensure that concurrent tag changes cannot influence the image being pulled.

While it is possible to require both Notary trust and simple signing, the two methods must agree on the signed digest for the image. If the two methods return different signed digests, the image is denied. It is not possible to allow alternative signing methods.

If any image in your workload does not satisfy the policy the entire workload is prevented from deploying.

Portieris receives AdmissionRequests for creation of or edits to all types of workload. To prevent Portieris from impacting auto-recovery, it approves requests where a parent exists.

Portieris' Admission Webhook is configured to fail closed. Three instances of Portieris make sure that it is able to approve its own upgrades and auto-recovery. If all instance of Portieris are unavailable, Kubernetes will not auto-recover it, and you must delete the MutatingAdmissionWebhook to allow Portieris to recover.

Portieris Metrics

Portieris exposes two metrics for monitoring the policy decisions made for workload images, these metrics are available on port 8080, and are exposed via annotations to prometheus. The metrics are

and are counters that increment each time a decision is made. To locally view these metrics, they are available on the
path for each pod running.

Installing Portieris

Portieris is installed using a Helm chart. Before you begin, make sure that you have Kubernetes 1.16 or above on your cluster and Helm 3.0 or above installed on your workstation.

To install Portieris in the default namespace (portieris):

  • Find the release you want to run in releases and download the helm chart package.
  • Unpack the charts, for example
    tar xzvf portieris-0.9.4.tgz
  • Run
    sh ./portieris/gencerts
    . The
    script generates new SSL certificates and keys for Portieris. Portieris presents this certificates to the Kubernetes API server when the API server makes admission requests. If you do not generate new certificates, it could be possible for an attacker to spoof Portieris in your cluster.
  • Run
    helm install portieris --create-namespace --namespace portieris ./portieris

You can use a different namespace if you choose, including an existing one if you omit the

option, but note that the namespace forms part of the webhook certificate common name so you need to generate the certificate for the target namespace.
  • Run
    sh portieris/gencerts 
  • Run
    helm install portieris --create-namespace --namespace  ./portieris

To manage certificates through an installed cert-manager, you do not need to unpack the charts in this case:

  • Run
    helm install portieris --set UseCertManager=true portieris-0.9.4.tgz

By default, Portieris' admission webhook runs in all namespaces including its own install namespace, so that Portieris is able to review all the pods in the cluster. However, this can prevent the cluster from self healing in the event where Portieris becomes unavailable. Portieris also supports skipping namespaces with a certain label set. You can enable this by adding

--set AllowAdmissionSkip=true
to your install command, but make sure to control who can add labels to namespaces and who can access namespaces with this label so that a malicious party cannot use this label to bypass Portieris.

Another way to avoid update deadlock is to specify

--set webHooks.failurePolicy=Ignore

Uninstalling Portieris

You can uninstall Portieris, at any time, by running

helm delete portieris --namespace 

Uninstall Notes: 1. All your image security policies are deleted when you uninstall Portieris. 1. If you no longer need the namespace it will have to be manually deleted. i.e.

kubectl delete namespace/
1. If you have issues uninstalling portieris, via helm, try running the cleanup script:
helm/ portieris 

Image security policies

Image security policies define Portieris' behavior in your cluster. You must configure your own policies in order for Portieris to enforce your desired security posture. Policies are described separately.

Configuring access controls for your security policies

You can configure Kubernetes RBAC rules to define which users and applications have the ability to modify your security policies. For more information, see the IBM Cloud docs.

If Portieris is installed with

, you can prevent Portieris' admission webhook from being called in specific namespaces by labelling the namespace with skip
. Doing so would allow pods in that namespace to recover when the admission webhook is down, but note that no policies are applied in that namespace. For example, the Portieris install namespace is configured with this label to allow Portieris itself to recover when it is down. Make sure to control who can add labels to namespaces and who can access namespaces with this label so that a malicious party cannot use this label to bypass Portieris.

Reporting security issues

To report a security issue, DO NOT open an issue. Instead, send your report via email to [email protected] privately.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.