Small fixes to website and adding contributing info

- Added section to contributing doc explaining requirements to locally
  test docs.
- Fixed broken links
- Added diagram to API explanation
- Cross-linked example API objects to user stories

Author: rahulkjoshi

CONTRIBUTING.md

@@ -21,6 +21,22 @@ If your repo has certain guidelines for contribution, put them here ahead of the
 1) Clone the repo: `git clone https://github.com/kubernetes-sigs/network-policy-api.git`
 2) Run `cd network-policy-api` && `make install`
 
+## Developing the Website
+
+The site documentation is written in Markdown and compiled with
+[mkdocs](https://www.mkdocs.org/).
+
+### Setting up local development
+
+1.  Install mkdocs and required plugins:
+
+    ```
+    pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin mkdocs-macros-plugin
+    ```
+
+2.  To build the docs, run `make docs`.
+3.  To deploy the docs locally, run `make local-docs`
+
 ## Mentorship
 
 - [Mentoring Initiatives](https://git.k8s.io/community/mentoring) - We have a diverse set of mentorship programs available that are always looking for volunteers!

mkdocs.yml

@@ -13,7 +13,7 @@ theme:
     - search.highlight
     - navigation.tabs
     - navigation.top
-edit_uri: edit/main/site-src/
+edit_uri: edit/master/site-src/
 plugins:
   - search
   - awesome-pages
@@ -26,10 +26,13 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.details
   - pymdownx.highlight
   - pymdownx.inlinehilite
   - pymdownx.superfences
-  - pymdownx.snippets
+  - pymdownx.snippets:
+      base_path: site-src
+      check_paths: true
   - toc:
       permalink: true
 nav:

site-src/api-overview.md

@@ -33,6 +33,11 @@ Currently, there are two main objects in the Network Policy API resource model:
 
 - **BaselineAdminNetworkPolicy (BANP)**
 
+The diagram below demonstrates how these new API objects interact with
+each-other and existing NetworkPolicy Objects:
+
+![Alt text](./images/ANP-api-model.png?raw=true "Admin Network Policy API Model")
+
 ## General Notes
 
 - Any well defined AdminNetworkPolicy rules should
@@ -116,7 +121,7 @@ The BaselineAdminNetworkPolicy (BANP) resource will allow administrators to
 set baseline security rules that describes default connectivity for cluster workloads, 
 which CAN be overridden by developer NetworkPolicies if needed. The major use case 
 BANPs solve is the ability to flip the [default security stance of the 
-cluster](../index.md#story-5-cluster-wide-default-guardrails).
+cluster](user-stories.md#story-5-cluster-wide-default-guardrails).
 
 ### BaselineAdminNetworkPolicy Rule Actions 
 

site-src/docs/index.md

@@ -1,6 +1,7 @@
 # Network Policy API Working Group
  👋 Welcome to the Network Policy API Project - we are happy to have you here! Before you get started here are some useful links:
 
+- [Bi-Weekly Meeting Agenda](https://docs.google.com/document/d/1AtWQy2fNa4qXRag9cCp5_HsefD7bxKe3ea2RPn8jnSs/edit#heading=h.ajvcztp6cza)
 - [NetworkPolicy v1 Docs](https://kubernetes.io/docs/concepts/services-networking/network-policies/)
 - [API reference spec](/reference/spec/)
 
@@ -47,4 +48,4 @@ Time (16:00 UTC):
 To get started contributing please take time to read over the [contributing guidelines](https://github.com/kubernetes-sigs/network-policy-api/blob/master/CONTRIBUTING.md) as well as the [developer guide](https://github.com/kubernetes/community/blob/master/contributors/devel/README.md). You can then take a look at the open issues labelled 'good-first-issue' [here](https://github.com/kubernetes-sigs/network-policy-api/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
 
 ### Code of conduct
-Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
+Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](https://github.com/kubernetes/community/blob/master/code-of-conduct.md).

site-src/index.md

@@ -6,155 +6,51 @@ Network Policy API.
 ## Sample AdminNetworkPolicy and BaseLineAdminNetworkPolicy Resources
 
 These examples will start with the object yaml defintions used to implement the
-[core use cases](../intro.md#adminnetworkpolicy-api-user-stories). Please feel
+[core use cases](../user-stories.md). Please feel
 free to contribute more examples that may seem relevant to other users :-).
 
 ### Sample Spec for Story 1: Deny traffic at a cluster level
 
-![Alt text](../../images/explicit_deny.png?raw=true "Explicit Deny")
+![Alt text](../images/explicit_deny.png?raw=true "Explicit Deny")
 
 ```yaml
-apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
-metadata:
-  name: cluster-wide-deny-example
-spec:
-  priority: 10
-  subject:
-    namespaces:
-      matchLabels:
-        kubernetes.io/metadata.name: sensitive-ns
-  ingress:
-    - action: Deny
-      from:
-      - namespaces:
-         namespaceSelector: {}
-      name: select-all-deny-all
+--8<-- "user-story-examples/user-story-1.yaml"
 ```
 
 ### Sample Spec for Story 2: Allow traffic at a cluster level
 
-![Alt text](../../images/explicit_allow.png?raw=true "Explicit Allow")
+![Alt text](../images/explicit_allow.png?raw=true "Explicit Allow")
 
 ```yaml
-apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
-metadata:
-  name: cluster-wide-allow-example
-spec:
-  priority: 30
-  subject:
-    namespaces: {}
-  ingress:
-    - action: Allow
-      from:
-      - namespaces:
-          namespaceSelector:
-            matchLabels:
-              kubernetes.io/metadata.name: monitoring-ns
-  egress:
-    - action: Allow
-      to:
-      - namespaces:
-          namespaceSelector:
-            matchlabels:
-              kubernetes.io/metadata.name: kube-system
-        pods:   
-          podSelector:
-            matchlabels:
-              app: kube-dns
+--8<-- "user-story-examples/user-story-2.yaml"
 ```
 
 ### Sample Spec for Story 3: Explicitly Delegate traffic to existing K8s Network Policy
 
-![Alt text](../../images/delegation.png?raw=true "Delegate")
+![Alt text](../images/delegation.png?raw=true "Delegate")
 
 ```yaml
-apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
-metadata:
-  name: pub-svc-delegate-example
-spec:
-  priority: 20
-  subject:
-    namespaces: {}
-  egress:
-  - action: Pass
-    to:
-    - pods:
-        namespaceSelector:
-          matchLabels:
-            kubernetes.io/metadata.name: bar-ns-1
-        podSelector:
-          matchLabels:
-            app: svc-pub
-    ports:
-    - portNumber:
-        protocol: TCP
-        port: 8080
+--8<-- "user-story-examples/user-story-3.yaml"
 ```
 
-### Sample Spec for Story 4: Create and Isolate multiple tenants in a cluster  
+### Sample Spec for Story 4: Create and Isolate multiple tenants in a cluster
 
-![Alt text](../../images/tenants.png?raw=true "Tenants")
+![Alt text](../images/tenants.png?raw=true "Tenants")
 
 ```yaml
-apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
-metadata:
-  name: tenant-creation-example
-spec:
-  priority: 50
-  subject:
-    namespaces:
-      matchExpressions: {key: "tenant"; operator: Exists}
-  ingress:
-    - action: Deny
-      from:
-      - namespaces:
-          notSameLabels:
-          - tenant
+--8<-- "user-story-examples/user-story-4-v1.yaml"
 ```
 
 This can also be expressed in the following way:
 
 ```yaml
-apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
-metadata:
-  name: tenant-creation-example
-spec:
-  priority: 50
-  subject:
-    namespaces:
-      matchExpressions: {key: "tenant"; operator: Exists}
-  ingress:
-    - action: Pass # Pass inter-tenant traffic to any defined NetworkPolicies
-      from:
-      - namespaces:
-          sameLabels:
-          - tenant
-    - action: Deny   # Deny everything else other than same tenant traffic
-      from:
-      - namespaces:
-          namespaceSelector: {}
+--8<-- "user-story-examples/user-story-4-v2.yaml"
 ```
 
 ### Sample Spec for Story 5: Cluster Wide Default Guardrails
 
-![Alt text](../../images/baseline.png?raw=true "Default Rules")
+![Alt text](../images/baseline.png?raw=true "Default Rules")
 
 ```yaml
-apiVersion: policy.networking.k8s.io/v1alpha1
-kind: BaselineAdminNetworkPolicy
-metadata:
-  name: baseline-rule-example
-spec:
-  subject:
-    namespaces: {}
-  ingress:
-    - action: Deny   # zero-trust cluster default security posture
-      from:
-      - namespaces:
-          namespaceSelector: {}
+--8<-- "user-story-examples/user-story-5.yaml"
 ```

site-src/reference/examples.md

@@ -24,6 +24,11 @@ ports and protocols.
 
 ![Alt text](./images/explicit_deny.png?raw=true "Explicit Deny")
 
+??? success "Equivalent API Object"
+    ```yaml
+    --8<-- "user-story-examples/user-story-1.yaml"
+    ```
+
 #### Story 2: Allow traffic at a cluster level
 
 As a cluster admin, I want to apply non-overridable allow rules to  
@@ -36,6 +41,11 @@ traffic from pods in `monitoring-ns` for all ports and protocols.
 
 ![Alt text](./images/explicit_allow.png?raw=true "Explicit Allow")
 
+??? success "Equivalent API Object"
+    ```yaml
+    --8<-- "user-story-examples/user-story-2.yaml"
+    ```
+
 #### Story 3: Explicitly Delegate traffic to existing K8s Network Policy
 
 As a cluster admin, I want to explicitly delegate traffic so that it
@@ -49,6 +59,11 @@ delegated traffic the traffic will be allowed.
 
 ![Alt text](./images/delegation.png?raw=true "Delegate")
 
+??? success "Equivalent API Object"
+    ```yaml
+    --8<-- "user-story-examples/user-story-3.yaml"
+    ```
+
 #### Story 4: Create and Isolate multiple tenants in a cluster
 
 As a cluster admin, I want to build tenants in my cluster that are isolated from
@@ -60,6 +75,17 @@ all ingress traffic is denied to either tenant.
 
 ![Alt text](./images/tenants.png?raw=true "Tenants")
 
+??? success "Equivalent API Object"
+    ```yaml
+    --8<-- "user-story-examples/user-story-4-v1.yaml"
+    ```
+
+    This can also be expressed in the following way:
+
+    ```yaml
+    --8<-- "user-story-examples/user-story-4-v2.yaml"
+    ```
+
 #### Story 5: Cluster Wide Default Guardrails
 
 As a cluster admin I want to change the default security model for my cluster,
@@ -73,3 +99,8 @@ For Example: In the following diagram all Ingress traffic to every cluster
 resource is denied by a baseline deny rule.
 
 ![Alt text](./images/baseline.png?raw=true "Default Rules")
+
+??? success "Equivalent API Object"
+    ```yaml
+    --8<-- "user-story-examples/user-story-5.yaml"
+    ```

site-src/user-stories.md

@@ -0,0 +1,16 @@
+apiVersion: policy.networking.k8s.io/v1alpha1
+kind: AdminNetworkPolicy
+metadata:
+  name: cluster-wide-deny-example
+spec:
+  priority: 10
+  subject:
+    namespaces:
+      matchLabels:
+        kubernetes.io/metadata.name: sensitive-ns
+  ingress:
+    - action: Deny
+      from:
+      - namespaces:
+         namespaceSelector: {}
+      name: select-all-deny-all

site-src/user-story-examples/user-story-1.yaml

@@ -0,0 +1,26 @@
+apiVersion: policy.networking.k8s.io/v1alpha1
+kind: AdminNetworkPolicy
+metadata:
+  name: cluster-wide-allow-example
+spec:
+  priority: 30
+  subject:
+    namespaces: {}
+  ingress:
+    - action: Allow
+      from:
+      - namespaces:
+          namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: monitoring-ns
+  egress:
+    - action: Allow
+      to:
+      - namespaces:
+          namespaceSelector:
+            matchlabels:
+              kubernetes.io/metadata.name: kube-system
+        pods:
+          podSelector:
+            matchlabels:
+              app: kube-dns

site-src/user-story-examples/user-story-2.yaml

@@ -0,0 +1,22 @@
+apiVersion: policy.networking.k8s.io/v1alpha1
+kind: AdminNetworkPolicy
+metadata:
+  name: pub-svc-delegate-example
+spec:
+  priority: 20
+  subject:
+    namespaces: {}
+  egress:
+  - action: Pass
+    to:
+    - pods:
+        namespaceSelector:
+          matchLabels:
+            kubernetes.io/metadata.name: bar-ns-1
+        podSelector:
+          matchLabels:
+            app: svc-pub
+    ports:
+    - portNumber:
+        protocol: TCP
+        port: 8080