Fixed docs not being upto date (#94)

.github/workflows/docs.yaml

@@ -24,4 +24,7 @@ jobs:
         if: steps.changes.outputs.changed == 1
         run: |
           echo "Uncommited changes to POLICIES.md exist. Failing."
-          exit 1
+          exit 1
+
+      - name: Link checker
+        uses: gaurav-nelson/github-action-markdown-link-check@v1

README.md

@@ -4,7 +4,7 @@
 [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) policies collection.
 
 ## Policies
-For a full list of policies, see the auto-generated [POLICIES.md](/POLICIES.md)
+For a full list of policies, see the auto-generated [POLICIES.md](POLICIES.md)
 
 The naming of the policies follows the Gatekeeper format, as described [here.](https://github.com/plexsystems/konstraint#how-template-and-constraint-naming-works)
 

policy/combine/namespace-has-networkpolicy/src.rego

@@ -2,7 +2,13 @@ package combine.namespace_has_networkpolicy
 
 import data.lib.konstraint
 
-# violation: Check if a Namespace has a networking.k8s.io/v1:NetworkPolicy
+# @title Namespace has a NetworkPolicy
+#
+# Kubernetes network policies specify the access permissions for groups of pods,
+# much like security groups in the cloud are used to control access to VM instances.
+# In other words, it creates firewalls between pods running on a Kubernetes cluster.
+# See: Network policies -> https://learnk8s.io/production-best-practices#governance
+#
 # @kinds core/Namespace networking.k8s.io/NetworkPolicy
 violation[msg] {
   manifests := input[_]

policy/ocp/bestpractices/common-k8s-labels-notset/src.rego

@@ -3,7 +3,11 @@ package ocp.bestpractices.common_k8s_labels_notset
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check if all workload related kinds contain labels as suggested by https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels
+# @title Common k8s labels are set
+#
+# Check if all workload related kinds contain labels as suggested by k8s.
+# See: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet core/Service route.openshift.io/Route
 violation[msg] {
   openshift.is_all_kind

policy/ocp/bestpractices/container-env-maxmemory-notset/src.rego

@@ -3,7 +3,12 @@ package ocp.bestpractices.container_env_maxmemory_notset
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds have the CONTAINER_MAX_MEMORY env set using the downward api
+# @title Container env has CONTAINER_MAX_MEMORY set
+#
+# Red Hat OpenJDK image uses CONTAINER_MAX_MEMORY env via the downward API to set Java memory settings.
+# Instead of manually setting -Xmx, let the image automatically set it for you.
+# See: https://github.com/jboss-openshift/cct_module/blob/master/jboss/container/java/jvm/bash/artifacts/opt/jboss/container/java/jvm/java-default-options
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-image-latest/src.rego

@@ -3,7 +3,10 @@ package ocp.bestpractices.container_image_latest
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds are not using the latest tag for their image
+# @title Container image is not set as latest
+#
+# Images should use immutable tags. Today's latest is not tomorrows latest.
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-java-xmx-set/src.rego

@@ -3,7 +3,11 @@ package ocp.bestpractices.container_java_xmx_set
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds do not set the Java Xmx option
+# @title Container does not set Java Xmx option
+#
+# Red Hat OpenJDK image uses CONTAINER_MAX_MEMORY env via the downward API to set Java memory settings.
+# Instead of manually setting -Xmx, let the image automatically set it for you.
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-labelkey-inconsistent/src.rego

@@ -3,7 +3,10 @@ package ocp.bestpractices.container_labelkey_inconsistent
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds have consistent key names for their labels
+# @title Label key is consistent
+#
+# Label keys should be qualified by 'app.kubernetes.io' or 'company.com' to allow a consistent understanding.
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-liveness-readinessprobe-equal/src.rego

@@ -3,7 +3,13 @@ package ocp.bestpractices.container_liveness_readinessprobe_equal
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds have not set their probes to be the same
+# @title Container liveness and readiness probes are equal
+#
+# When Liveness and Readiness probes are pointing to the same endpoint, the effects of the probes are combined.
+# When the app signals that it's not ready or live, the kubelet detaches the container from the Service and delete it at the same time.
+# You might notice dropping connections because the container does not have enough time to drain the current connections or process the incoming ones.
+# See: Health checks -> https://learnk8s.io/production-best-practices#application-development
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-livenessprobe-notset/src.rego

@@ -3,7 +3,12 @@ package ocp.bestpractices.container_livenessprobe_notset
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds have their liveness prob set
+# @title Container liveness prob is not set
+#
+# A Liveness checks determines if the container in which it is scheduled is still running.
+# If the liveness probe fails due to a condition such as a deadlock, the kubelet kills the container.
+# See: https://docs.openshift.com/container-platform/4.4/applications/application-health.html
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-readinessprobe-notset/src.rego

@@ -3,7 +3,12 @@ package ocp.bestpractices.container_readinessprobe_notset
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds have their readiness prob set
+# @title Container readiness prob is not set
+#
+# A Readiness check determines if the container in which it is scheduled is ready to service requests.
+# If the readiness probe fails a container, the endpoints controller ensures the container has its IP address removed from the endpoints of all services.
+# See: https://docs.openshift.com/container-platform/4.4/applications/application-health.html
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-resources-limits-cpu-set/src.rego

@@ -3,7 +3,12 @@ package ocp.bestpractices.container_resources_limits_cpu_set
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds do not set limits for CPU
+# @title Container resource limits CPU not set
+#
+# If you're not sure about what's the best settings for your app, it's better not to set the CPU limits.
+# See: Resources utilisation -> https://learnk8s.io/production-best-practices#application-development
+# See: https://www.reddit.com/r/kubernetes/comments/all1vg/on_kubernetes_cpu_limits
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-resources-limits-memory-greater-than/src.rego

@@ -4,7 +4,12 @@ import data.lib.konstraint
 import data.lib.memory
 import data.lib.openshift
 
-# violation: Check workload kinds limits for memory is not greater than an upper bound
+# @title Container resource limits memory not greater than
+#
+# Setting a too high memory limit can cause under utilisation on a node.
+# It is better to run multiple pods which use smaller limits.
+# See: Resources utilisation -> https://learnk8s.io/production-best-practices#application-development
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-resources-limits-memory-notset/src.rego

@@ -3,7 +3,12 @@ package ocp.bestpractices.container_resources_limits_memory_notset
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds has set their limits for memory
+# @title Container resource limits memory not set
+#
+# A container without a memory limit has memory utilisation of zero — according to the scheduler.
+# An unlimited number of Pods if schedulable on any nodes leading to resource overcommitment and potential node (and kubelet) crashes.
+# See: Resources utilisation -> https://learnk8s.io/production-best-practices#application-development
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-resources-memoryunit-incorrect/src.rego

@@ -3,7 +3,13 @@ package ocp.bestpractices.container_resources_memoryunit_incorrect
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds memory limits and requests unit is valid
+# @title Container resources limit memory has incorrect unit
+#
+# Begininers can easily confuse the allowed memory unit, this policy enforces what is valid.
+# k8s also allows for millibyte as a unit for memory, which causes unintended consequences for the scheduler.
+# See: https://github.com/kubernetes/kubernetes/issues/28741
+# See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-resources-requests-cpuunit-incorrect/src.rego

@@ -3,7 +3,11 @@ package ocp.bestpractices.container_resources_requests_cpuunit_incorrect
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds cpu requests unit is valid
+# @title Container resources requests cpu has incorrect unit
+#
+# Beginners can easily confuse the allowed cpu unit, this policy enforces what is valid.
+# See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-resources-requests-memory-greater-than/src.rego

@@ -4,7 +4,12 @@ import data.lib.konstraint
 import data.lib.memory
 import data.lib.openshift
 
-# violation: Check workload kinds requests for memory is not greater than an upper bound
+# @title Container resource requests memory not greater than
+#
+# Setting a too high memory request can cause under utilisation on a node.
+# It is better to run multiple pods which use smaller requests.
+# See: Resources utilisation -> https://learnk8s.io/production-best-practices#application-development
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-secret-mounted-envs/src.rego

@@ -3,7 +3,13 @@ package ocp.bestpractices.container_secret_mounted_envs
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds do not have secrets mounted as envs
+# @title Container secret not mounted as envs
+#
+# The content of Secret resources should be mounted into containers as volumes rather than passed in as environment variables.
+# This is to prevent that the secret values appear in the command that was used to start the container, which may be inspected
+# by individuals that shouldn't have access to the secret values.
+# See: Configuration and secrets -> https://learnk8s.io/production-best-practices#application-development
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-volumemount-inconsistent-path/src.rego

@@ -3,7 +3,10 @@ package ocp.bestpractices.container_volumemount_inconsistent_path
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds have consistent paths for their volume mounts
+# @title Container volume mount path is consistent
+#
+# Mount paths should be mounted at '/var/run/company.com' to allow a consistent understanding.
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/container-volumemount-missing/src.rego

@@ -3,7 +3,10 @@ package ocp.bestpractices.container_volumemount_missing
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds does not specify a volume without a corresponding volume mount
+# @title Container volume mount not set
+#
+# A volume does not have a corresponding volume mount. There is probably a mistake in your definition.
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/deploymentconfig-triggers-notset/src.rego

@@ -3,7 +3,10 @@ package ocp.bestpractices.deploymentconfig_triggers_notset
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check if a DeploymentConfig has 'spec.triggers' set
+# @title DeploymentConfig triggers not set
+#
+# If you are using a DeploymentConfig without 'spec.triggers' set, you could probably just use the k8s Deployment.
+#
 # @kinds apps.openshift.io/DeploymentConfig
 violation[msg] {
   openshift.is_deploymentconfig

policy/ocp/bestpractices/pod-hostnetwork/src.rego

@@ -3,7 +3,10 @@ package ocp.bestpractices.pod_hostnetwork
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds has 'spec.hostNetwork' set
+# @title Pod hostnetwork not set
+#
+# Pods which require 'spec.hostNetwork' should be limited due to security concerns.
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/DaemonSet apps/Deployment apps/StatefulSet
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/pod-replicas-below-one/src.rego

@@ -3,7 +3,11 @@ package ocp.bestpractices.pod_replicas_below_one
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds has replicas <= 1
+# @title Pod replica below 1
+#
+# Never run a single Pod individually.
+# See: Fault tolerance -> https://learnk8s.io/production-best-practices#application-development
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/Deployment
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/pod-replicas-not-odd/src.rego

@@ -3,7 +3,11 @@ package ocp.bestpractices.pod_replicas_not_odd
 import data.lib.konstraint
 import data.lib.openshift
 
-# violation: Check workload kinds has replicas not odd
+# @title Pod replica is not odd
+#
+# Pods should be run with a replica which is odd, i.e.: 3, 5, 7, etc, for HA guarantees.
+# See: Fault tolerance -> https://learnk8s.io/production-best-practices#application-development
+#
 # @kinds apps.openshift.io/DeploymentConfig apps/Deployment
 violation[msg] {
   openshift.is_workload_kind

policy/ocp/bestpractices/rolebinding-roleref-apigroup-notset/src.rego

@@ -3,7 +3,10 @@ package ocp.bestpractices.rolebinding_roleref_apigroup_notset
 import data.lib.konstraint
 import data.lib.kubernetes
 
-# violation: Check if a RoleBinding has 'roleRef.apiGroup' set
+# @title RoleBinding has apiGroup set
+#
+# Migrating from 3.11 to 4.x requires the 'roleRef.apiGroup' to be set.
+#
 # @kinds rbac.authorization.k8s.io/RoleBinding
 violation[msg] {
   kubernetes.is_rolebinding

policy/ocp/bestpractices/rolebinding-roleref-kind-notset/src.rego

@@ -3,7 +3,10 @@ package ocp.bestpractices.rolebinding_roleref_kind_notset
 import data.lib.konstraint
 import data.lib.kubernetes
 
-# violation: Check if a RoleBinding has 'roleRef.kind' set
+# @title RoleBinding has kind set
+#
+# Migrating from 3.11 to 4.x requires the 'roleRef.kind' to be set.
+#
 # @kinds rbac.authorization.k8s.io/RoleBinding
 violation[msg] {
   kubernetes.is_rolebinding

policy/ocp/deprecated/3_11/buildconfig-v1/src.rego

@@ -2,7 +2,10 @@ package ocp.deprecated.ocp3_11.buildconfig_v1
 
 import data.lib.konstraint
 
-# violation: Check for deprecated v1 apiVersion. OCP4.x expects build.openshift.io/v1
+# @title BuildConfig no longer served by v1
+#
+# OCP4.x expects build.openshift.io/v1.
+#
 # @kinds v1/BuildConfig
 violation[msg] {
   obj := konstraint.object

policy/ocp/deprecated/3_11/deploymentconfig-v1/src.rego

@@ -2,7 +2,10 @@ package ocp.deprecated.ocp3_11.deploymentconfig_v1
 
 import data.lib.konstraint
 
-# violation: Check for deprecated v1 apiVersion. OCP4.x expects apps.openshift.io/v1
+# @title DeploymentConfig no longer served by v1
+#
+# OCP4.x expects apps.openshift.io/v1.
+#
 # @kinds v1/DeploymentConfig
 violation[msg] {
   obj := konstraint.object

policy/ocp/deprecated/3_11/imagestream-v1/src.rego

@@ -2,7 +2,10 @@ package ocp.deprecated.ocp3_11.imagestream_v1
 
 import data.lib.konstraint
 
-# violation: Check for deprecated v1 apiVersion. OCP4.x expects image.openshift.io/v1
+# @title ImageStream no longer served by v1
+#
+# OCP4.x expects image.openshift.io/v1.
+#
 # @kinds v1/ImageStream
 violation[msg] {
   obj := konstraint.object

policy/ocp/deprecated/3_11/projectrequest-v1/src.rego

@@ -2,7 +2,10 @@ package ocp.deprecated.ocp3_11.projectrequest_v1
 
 import data.lib.konstraint
 
-# violation: Check for deprecated v1 apiVersion. OCP4.x expects project.openshift.io/v1
+# @title ProjectRequest no longer served by v1
+#
+# OCP4.x expects project.openshift.io/v1.
+#
 # @kinds v1/ProjectRequest
 violation[msg] {
   obj := konstraint.object

policy/ocp/deprecated/3_11/rolebinding-v1/src.rego

@@ -2,7 +2,10 @@ package ocp.deprecated.ocp3_11.rolebinding_v1
 
 import data.lib.konstraint
 
-# violation: Check for deprecated v1 apiVersion. OCP4.x expects rbac.authorization.k8s.io/v1
+# @title RoleBinding no longer served by v1
+#
+# OCP4.x expects rbac.authorization.k8s.io/v1
+#
 # @kinds v1/RoleBinding
 violation[msg] {
   obj := konstraint.object