Namespace Policy

A QHxPolicy selects the QHx authority that issues identities to workloads in a namespace. The local QHx Manager resolves the selection and configures the SPIFFE CSI routing for that namespace.

Property	Value
API version	qhx.dev/v1
Kind	QHxPolicy
Scope	Namespaced
Authority resource	Cluster-scoped QHxAuthority

Prerequisites

You need a functioning QHx installation, an existing target namespace, and Kubernetes permission to manage policy in that namespace. A cluster administrator must create the target QHxAuthority before workloads can use it. Inspect the available authorities and cluster default:

kubectl get qhxauthorities -o yaml
kubectl get qhxclusters -o yaml

Check the intended authority’s status.trustDomain, status.effectiveConfig, and readiness conditions. Its configuration determines the PKI behavior; QHxPolicy selects the authority by name.

Select an authority

Manage one QHxPolicy per namespace. Check for an existing policy before creating one, and update that object if present:

kubectl get qhxpolicies -n production

For a namespace named production and an existing authority named production-authority, the policy is:

apiVersion: qhx.dev/v1
kind: QHxPolicy
metadata:
  name: qhx-policy
  namespace: production
spec:
  authority:
    name: production-authority

Save the manifest as namespace-policy.yaml and apply it:

kubectl apply -f namespace-policy.yaml
kubectl get qhxpolicy qhx-policy -n production -o yaml

spec.authority.name

This string names a cluster-scoped QHxAuthority. It is a Kubernetes object name, not a SPIFFE trust domain or an algorithm name. The manager routes the namespace’s workloads to that authority’s SPIRE agent.

An empty name or a reference to an authority that does not exist fails closed: workloads in the namespace receive no QHx SVID through that binding. An empty policy does not select the cluster default.

Namespace default

A namespace with no QHxPolicy uses the authority named by QHxCluster.spec.defaultAuthority. The default authority must be configured and available for workloads to receive identities. Deleting an explicit policy returns the namespace to that default; it does not disable QHx for the namespace.

Check the binding

The manager writes status.conditions on each policy. Inspect the policy:

kubectl describe qhxpolicy qhx-policy -n production

• Bound=True means the named authority exists.
• Bound=False with reason Unresolvable means the authority name is empty or the named authority does not exist. The condition message identifies the problem.

Bound=True does not prove that the authority is ready or that an application has obtained an SVID. Check the authority and the workload separately:

kubectl get qhxauthority production-authority -o yaml
kubectl get pods -n production
kubectl get pods -n qhx-system

Workloads that use SPIFFE CSI need the Workload API volume mounted in their pods. When changing an authority binding, plan the rollout of affected workloads and verify the identity they obtain through the mounted Workload API. Treat an authority change as a trust change: confirm that peers and application authorization rules accept the intended identity before moving production traffic.

Update or remove a policy

Edit the existing policy to select a different authority:

kubectl edit qhxpolicy qhx-policy -n production

After saving, check both the policy’s Bound condition and the selected authority’s readiness. Correct an unresolved name rather than relying on fallback to the cluster default.

Before removing a policy, inspect QHxCluster.spec.defaultAuthority and confirm that its authority is suitable for the namespace. Then remove the policy:

kubectl delete qhxpolicy qhx-policy -n production

Restrict policy and authority changes with Kubernetes RBAC, and monitor them through your organization’s Kubernetes audit process. Permission to change a namespace’s binding changes which authority supplies its workload identities.

Inspect a workload certificate

Use a SPIFFE Workload API client in the workload’s environment to obtain its current certificate. If you have exported it as svid.pem, a compatible OpenSSL installation can display its public-key and signature algorithms:

openssl x509 -in svid.pem -text -noout

Use a certificate tool that supports the certificate’s algorithms. The qhx CLI does not export SVIDs. Inspecting a certificate shows its contents; it does not by itself verify a live peer’s authorization.