docs - c7n_kube and c7n-kates documentation (cloud-custodian#7883)

docs/source/index.rst

@@ -82,6 +82,14 @@ Navigate below to your cloud provider and get started with Cloud Custodian!
    awscc/resources/index
 
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Kubernetes
+
+   kubernetes/gettingstarted
+   kubernetes/controllermode
+   kubernetes/examples/index
+
 .. toctree::
    :maxdepth: 2
    :caption: Tools
@@ -107,4 +115,3 @@ Navigate below to your cloud provider and get started with Cloud Custodian!
    developer/tests.rst
    developer/documentation.rst
    developer/packaging.rst
-

docs/source/kubernetes/examples/deny-pod-exec-attach.rst

@@ -0,0 +1,60 @@
+Denying Pod Exec or Attach
+==========================
+
+Custodian can deny users from connecting to a pod based on the event which includes
+metadata such as their groups:
+
+.. code-block:: yaml
+
+  policies:
+    - name: test-deny-pod-exec-based-on-group
+      resource: k8s.pod
+      mode:
+        type: k8s-admission
+        subresource: ['exec', 'attach']
+        on-match: deny
+        operations:
+        - CONNECT
+      filters:
+      - type: event
+        key: request.userInfo.groups
+        value: allow-exec
+        op: not-in
+        value_type: swap
+
+
+Alternatively, you can also deny based on the namespace or pod name the user is trying
+to attach or exec to:
+
+.. code-block:: yaml
+
+  policies:
+    - name: test-deny-pod-exec-based-on-namespace
+      resource: k8s.pod
+      mode:
+        type: k8s-admission
+        subresource: ['exec', 'attach']
+        on-match: deny
+        operations:
+        - CONNECT
+      filters:
+      - type: event
+        key: request.namespace
+        value: 
+          - default
+          - database
+        op: in
+
+    - name: test-deny-pod-exec-based-on-pod-name
+      resource: k8s.pod
+      mode:
+        type: k8s-admission
+        subresource: ['exec', 'attach']
+        on-match: deny
+        operations:
+        - CONNECT
+      filters:
+      - type: event
+        key: request.name
+        value: .*production-db.*
+        op: regex

docs/source/kubernetes/examples/index.rst

@@ -0,0 +1,12 @@
+.. _kubernetes_examples:
+
+Examples
+=========
+
+These use cases provide examples of specific policies.
+
+.. toctree::
+  :titlesonly:
+  :glob:
+
+  ./*

docs/source/kubernetes/examples/require-label-on-event.rst

@@ -0,0 +1,37 @@
+Require Labels on Resources on Creation or Update
+=================================================
+
+Custodian can deny resources from being created or updated unless the resource
+has the required labels. In the example below, we require that all pods
+contain the recommended labels.
+
+.. code-block:: yaml
+
+  policies:
+    - name: missing-recommended-labels
+      mode:
+        type: k8s-admission
+        on-match: deny
+        operations:
+          - CREATE
+          - UPDATE
+      description: |
+        Kubernetes recommmended the following labels from its docs:
+
+        app.kubernetes.io/name
+        app.kubernetes.io/instance
+        app.kubernetes.io/version
+        app.kubernetes.io/component
+        app.kubernetes.io/part-of
+        app.kubernetes.io/managed-by
+
+        https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/
+      resource: k8s.pod
+      filters:
+        - or:
+          - metadata.labels."app.kubernetes.io/name": absent
+          - metadata.labels."app.kubernetes.io/instance": absent
+          - metadata.labels."app.kubernetes.io/version": absent
+          - metadata.labels."app.kubernetes.io/component": absent
+          - metadata.labels."app.kubernetes.io/part-of": absent
+          - metadata.labels."app.kubernetes.io/managed-by": absent

docs/source/kubernetes/examples/require-replicas.rst

@@ -0,0 +1,22 @@
+Require Replicas on Deployments
+================================
+
+Require deployments to have at least 3 replicas
+
+
+.. code-block:: yaml
+
+  policies:
+    - name: require-at-least-3-replicas
+      resource: k8s.deployment
+      mode:
+        type: k8s-admission
+        on-match: deny
+        operations:
+          - CREATE
+          - UPDATE
+      filters:
+        - type: value
+          key: spec.replicas
+          value: 3
+          op: gte

docs/source/kubernetes/examples/restrict-service-account-usage.rst

@@ -0,0 +1,21 @@
+Restrict Service Account Usage
+==============================
+
+Custodian can restrict creation or updating of resources that specify
+certain service accounts in their spec:
+
+.. code-block:: yaml
+
+  policies:
+    - name: restrict-service-account-usage
+      mode:
+        type: k8s-admission
+        on-match: deny
+        operations:
+          - CREATE
+          - UPDATE
+      resource: k8s.pod
+      filters:
+        - type: value
+          key: spec.serviceAccountName
+          value: "ClusterAdmin"