- Kubernetes Cluster (>= v1.20)
- Flux (>= v0.36.0)
- kubectl
- Cert Manager (>= v1.5.0)
- WeaveGitOps UI(Optional)
If you are not using flux, you need to have both Helm and Kustomize installed on your cluster
By default, the policy agent is configured to enforce policies using kubernetes admisson controller, and publish the violation events to Kubernetes Events. For advanced configurations, please check here.
To install Weave Policy Agent, you can use Flux and HelmRelease as part of GitOps ecosystem, or you can directly install the agent using just Helm.
Create policy-system namespace to install the chart in
kubectl create ns policy-systemIn your flux repo in the cluster's directory, create the following HelmRepository and HelmRelease manifests that reference the policy helm chart, push the new files to your repository.
Note: You can create these manifests in another directory, just make sure the directory is getting reconciled by flux.
The repository tree should be something like the following:
Repository tree - Click to expand ..
.
└── clusters
└── my-cluster
├── flux-system
│ ├── gotk-components.yaml
│ ├── gotk-sync.yaml
│ └── kustomization.yaml
├── wpa-helmrelease.yaml
└── wpa-helmrepo.yamlwpa-helmrepo.yaml - Click to expand ..
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
creationTimestamp: null
name: policy-agent
namespace: flux-system
spec:
interval: 1m0s
timeout: 1m0s
url: https://weaveworks.github.io/policy-agent/
status: {}wpa-helmrelease.yaml - Click to expand ..
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: policy-agent
namespace: flux-system
spec:
chart:
spec:
chart: policy-agent
sourceRef:
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
name: policy-agent
namespace: flux-system
version: 2.3.0
interval: 10m0s
targetNamespace: policy-system
values:
caCertificate: ""
certificate: ""
config:
accountId: ""
admission:
enabled: true
sinks:
k8sEventsSink:
enabled: true
audit:
enabled: false
clusterId: ""
excludeNamespaces:
- kube-system
failurePolicy: Fail
image: weaveworks/policy-agent
key: ""
persistence:
enabled: false
useCertManager: true
status: {}Once the HelmRepository and HelmRelease are reconciled by Flux, you should find the Policy Agent installed on your cluster.
Check installation status using the below commands, you should expect to see the success of HelmRelease installation and the pod of the agent running.
flux get helmrelease -A
kubectl get pods -n policy-systemCreate policy-system namespace to install the chart in.
kubectl create ns policy-systemAdd the Weave Policy Agent helm chart.
helm repo add policy-agent https://weaveworks.github.io/policy-agent/Install the helm chart.
helm install policy-agent policy-agent/policy-agent -n policy-systemCheck the installation status using the below command, you should expect the pod of the agent to be running.
kubectl get pods -n policy-systemWeave Policy Agent uses policies custom resources to validate resources compliance. Policy custom resource follows this definition (Policy CRD), and it consists of policy code and policy meta data. Policy code is written in OPA Rego Language.
To get started, you can use the default policies found here, which covers some kubernetes and flux best practices.
In flux repo, beside the policy agent helm repo and helm release files, create the following mainfest file to reference the default policies from the policy agent repository and push it to your cluster.
policies.yaml - Click to expand ..
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: policies
namespace: flux-system
spec:
interval: 5m
url: https://github.com/weaveworks/policy-agent/
ref:
branch: master
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: policies
namespace: flux-system
spec:
interval: 10m
targetNamespace: default
sourceRef:
kind: GitRepository
name: policies
path: "./policies"
prune: true
timeout: 1mCreate policies directory and create the following kustomization.yaml file, then from the parent directory apply it to your Kubernetes cluster using the command below.
kubectl apply -k policieskustomization.yaml - Click to expand ..
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- github.com/weaveworks/policy-agent/policiesYou can verify the installation by running the following command. If the installation is successful, the output will show a list of all the default policies.
kubectl get policiesIf you have WeaveGitOps UI installed on your cluster, you can use it to explore the policies installed on the cluster, as well as, explore the details on each policy.
With the agent and policies installed, Weave Policy Agent will prevent any resource that violate the relevant polices from being created or updated.
When using flux, flux reconcilation will fail if one of your application resources is violating any of the policies.
You should be able to see an error like this:
Admission controller violation error - Click to expand ..
```bash
Error from server (==================================================================
==================================================================
Policy : weave.policies.containers-minimum-replica-count
Entity : deployment/nginx-deployment in namespace: default
Occurrences:
- Replica count must be greater than or equal to '2'; found '1'.
): error when creating "deployment.yaml": admission webhook "admission.agent.weaveworks" denied the request:
==================================================================
Policy : weave.policies.containers-minimum-replica-count
Entity : deployment/nginx-deployment in namespace: default
Occurrences:
- Replica count must be greater than or equal to '2'; found '1'.
```
If you don't have a violating application/resource on your cluster, you can use the following Deployment as an example to try the agent out.
This deployment is violating Containers Minimum Replica Count policy by having 1 replicas instead of min. 2 replicas.
If you are using flux, try adding the deployment to your flux repo root directory. Or you can simply apply it directly to your cluster using kubectl apply.
violating-deployment.yaml - Click to expand ..
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
namespace: default
labels:
app: nginx
spec:
replicas: 1
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.14.2
ports:
- containerPort: 80Since Kubernetes events are configured as a sink for the admission mode, you can use the following command to list policy violatons.
kubectl get events --field-selector type=Warning,reason=PolicyViolation -AIf you have WeaveGitOps UI installed, you can find each policy violations listed in Violations tab inside each policy.
Your next step is to start fix policy violations, for that you can follow the remediation steps listed in each policy, apply them to the violating resources, and re-apply the resource or let flux sync the updated manifest.
Remediation steps are aavailable in the policy custom resource yaml, under the how_to_resolve section.
The remediation steps also are viewable using WeaveGitOps UI in each policy page.
To fix the violation on the deployment example, simply update the replicas count from 1 to 2, then apply or sync the deployment. It should pass the violation and the new manifest gets applied.
Usually, you will have certain namespaces that you need to be excluded from policy evaluation, because they are vital to how your cluster operate and you don't want them affected by policy violations, for example kube-system and flux-system.
To prevent the agent from scanning certain namespaces and stop deployments, you can add these namespaces to excludeNamespaces in the Policy Agent helm chart values file.
To prevent a certain policy from running in a specific namespace, you can add these namespaces to the policy's exclude_namespaces parameter, either by a direct modification to the policy file or by using kustomize overlays.