Policy Controller Operator

A Helm‑based operator for deploying and managing instances of the Sigstore Policy Controller on OpenShift/Kubernetes.

Getting Started

You’ll need access to a Kubernetes cluster (either OpenShift or Kubernetes) to install and run this operator.

Running on the cluster

1. Build and push the operator image:

IMG=<registry>/operator:tag make docker-build docker-push

2. Deploy the operator with the image you just pushed:

IMG=<registry>/operator:tag make deploy

3. Create the PolicyController custom resource:

Modify the sample manifest at config/samples/rhtas.charts_v1alpha1_policycontroller.yaml, then apply it:

kubectl apply -f config/samples/rhtas.charts_v1alpha1_policycontroller.yaml

NOTE:

• The resource must be installed in the policy-controller-operator namespace.
• TUF is disabled by default (disable-tuf: true) to prevent the policy controller from trusting the Sigstore public good instance, which could allow untrusted resources to be deployed.
• When deploying an unreleased version of the policy controller, run make dev-images to update the image registry coordinates to quay.io before building.

The Policy Controller should now be deployed to your cluster

Create a Trust Root

When using this operator, it is assumed you are using RHTAS (Red Hat Trusted Artifact Signer) as your Sigstore instance. In order to allow the policy controller to trust your instance, you need to create a TrustRoot. You will need two things to do this:

1. TUF mirror URL
2. Base64-encoded root.json

You can then create a simple TrustRoot like so:

apiVersion: policy.sigstore.dev/v1alpha1
kind: TrustRoot
metadata:
  name: trust-root
spec:
  remote:
    mirror: https://tuf.example.com
    root: |
      <BASE64_ENCODED_ROOT_JSON>

• Replace https://tuf.example.com with your actual TUF mirror URL.
• Replace <BASE64_ENCODED_ROOT_JSON> with the Base64-encoded contents of your root.json.

Create a Cluster Image Policy

In order to enforce policy on resources, you need to create a ClusterImagePolicy. A simple policy might look like the example below:

apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: cluster-image-policy
spec:
  images:
    - glob: "**"
  authorities:
    - keyless:
        url: https://fulcio.example.com
        trustRootRef: trust-root-ref
        identities:
          - issuer: https://oidc.example.com
            subject: oidc-issuer-subject
      ctlog:
        url: https://rekor.example.com
        trustRootRef: trust-root-ref

Replace the example URLs and trustRootRef values with your actual Fulcio, Rekor, and TrustRoot names. Once applied, this policy will only allow images that have been signed via your Sigstore setup (using Fulcio + Rekor) and match the specified OIDC identity.

By Default, the policy controller will enforce cluster image policies on namespaces that have the label policy.rhtas.com/include=true.

Uninstall CRDs

To delete the CRDs from the cluster:

make uninstall

Undeploy controller

Undeploy the controller from the cluster:

make undeploy

Development

Running the E2E test suite

The E2E test suite validates the Policy Controller operator against a OpenShift/Kubernetes cluster.

Prerequisites

• Kubernetes/OpenShift cluster.
• RHTAS Operator installed and running.

1. Build and deploy

Build and deploy the policy controller operator to your cluster.

2. Build a test image

Build a test image and define an env var for it.

export TEST_IMAGE=quay.io/<org>/policy-controller-test:latest
echo 'FROM scratch' | podman build -f - -t $TEST_IMAGE . && podman push $TEST_IMAGE

3. Define RHTAS ENV var

export RHTAS_INSTALL_NAMESPACE=openshift-rhtas-operator
source ./test/tas-env-variables.sh

(Optional)

If your cluster’s ingress uses a self-signed certificate, update your local trust store and tell the tests to inject the cluster CA:

oc -n openshift-ingress-operator get secret router-ca -o jsonpath='{.data.tls\.crt}' | base64 --decode > ingress-ca.crt
sudo cp ingress-ca.crt /etc/pki/ca-trust/source/anchors/ 
sudo update-ca-trust extract

export INJECT_CA=true

4. Run the E2E tests

make e2e-test 

NOTE: On subsequent runs of the end-to-end tests, you’ll need to rebuild and push your image so that the policy controller will not trust it.

Documentation

For more information on the Policy controller please visit the upstream documentation: https://docs.sigstore.dev/policy-controller/overview/