Skip to content

Commit 7ac5178

Browse files
astoycosastoycos
committed
Finish website first draft
Finish the website homepage, adding user stories and a brief introduction. Add Api overview Add Example yamls for user stories Signed-off-by: astoycos <[email protected]>
1 parent 62685e7 commit 7ac5178

File tree

11 files changed

+379
-122
lines changed

11 files changed

+379
-122
lines changed

‎bin/controller-gen

19.3 MB
Binary file not shown.

‎mkdocs.yml

Lines changed: 9 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ plugins:
1818
- search
1919
- awesome-pages
2020
- macros:
21-
include_dir: examples
21+
#include_dir: examples
2222
j2_line_comment_prefix: "#$"
2323
markdown_extensions:
2424
- admonition
@@ -33,40 +33,19 @@ markdown_extensions:
3333
- toc:
3434
permalink: true
3535
nav:
36-
- Overview:
37-
- Introduction: index.md
38-
- Concepts:
39-
API overview: concepts/api-overview.md
40-
Security Model: concepts/security-model.md
41-
Implementation Guidelines: concepts/guidelines.md
42-
Versioning: concepts/versioning.md
43-
- Implementations: implementations.md
44-
- FAQ: faq.md
36+
- Introduction: index.md
37+
- API overview: guides/api-overview.md
38+
- Examples: guides/examples.md
39+
# (TODO)
40+
# - Implementation Guidelines: concepts/guidelines.md
41+
# - Versioning: concepts/versioning.md
42+
# - Implementations: implementations.md
43+
# - FAQ: faq.md
4544
# - Guides:
4645
# - Getting started: guides/getting-started.md
47-
# - Simple Gateway: guides/simple-gateway.md
48-
# - HTTP routing: guides/http-routing.md
49-
# - HTTP redirects and rewrites: guides/http-redirect-rewrite.md
50-
# - HTTP traffic splitting: guides/traffic-splitting.md
51-
# - Cross-Namespace routing: guides/multiple-ns.md
52-
# - TLS: guides/tls.md
53-
# - TCP routing: guides/tcp.md
54-
# # - Reference:
55-
# - API Types:
56-
# GatewayClass: api-types/gatewayclass.md
57-
# Gateway: api-types/gateway.md
58-
# HTTPRoute: api-types/httproute.md
59-
# ReferenceGrant: api-types/referencegrant.md
60-
# - API specification: references/spec.md
61-
# - Policy Attachment: references/policy-attachment.md
62-
# - Enhancement Proposals:
63-
# - Overview: contributing/gep.md
64-
# - ... | geps/gep-*.md
6546
# - Contributing:
6647
# - Developer guide: contributing/devguide.md
6748
# - Enhancement Tracking and Backlog: contributing/enhancement-requests.md
6849
# - Community: contributing/community.md
6950
# - Blog:
7051
# - Index: blog/index.md
71-
# - 2021:
72-
# - blog/2021/introducing-v1alpha2.md

‎site-src/guides/api-overview.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
## API overview
2+
3+
Prior to the AdminNetworkPolicy API there was no native tooling for Cluster Admins
4+
to apply security rules in a cluster-wide manner, and in some cases Network Policies
5+
were being incorrectly used to do so, creating a complex web of objects to be
6+
maintained.
7+
8+
With the advent of the AdminNetworkPolicy API Cluster Admins will now have the
9+
ability to apply policy on in-cluster workloads with only a few simple policy
10+
objects that can be applied globally.
11+
12+
## Roles and personas
13+
14+
In this documentation we refer to three primary personas:
15+
16+
- Application Developer
17+
- Namespace Administrator
18+
- Cluster Administrator
19+
20+
## Resource Model
21+
22+
There are two main objects in the AdminNetworkPolicy API resource model
23+
24+
- **AdminNetworkPolicy (ANP)**
25+
26+
- **BaselineAdminNetworkPolicy (BANP)**
27+
28+
## General Notes
29+
30+
- Any well defined AdminNetworkPolicy rules should
31+
be read as-is, i.e. there will not be any implicit isolation effects for the Pods
32+
selected by the AdminNetworkPolicy, as opposed to what NetworkPolicy rules imply.
33+
34+
- As of `v1alpha1` of this API we focus primarily on E/W cluster traffic and
35+
do not address N/S (Ingress/Egress) use cases. However this is an issue the community
36+
would like to keep thinking about during further iterations, and a tracking issue
37+
can be found/ commented on here ---> [issue #28](https://github.com/kubernetes-sigs/network-policy-api/issues/28)
38+
39+
## The AdminNetworkPolicy Resource
40+
41+
The AdminNetworkPolicy (ANP) resource will help administrators set strict security
42+
rules for the cluster, i.e. a developer CANNOT override these rules by creating
43+
NetworkPolicies that apply to the same workloads as the AdminNetworkPolicy.
44+
45+
### AdminNetworkPolicy Actions
46+
47+
Unlike the NetworkPolicy resource in which each rule represents an allowed
48+
traffic, AdminNetworkPolicies will enable administrators to set `Pass`,
49+
`Deny` or `Allow` as the action of each rule. AdminNetworkPolicy rules should
50+
be read as-is, i.e. there will not be any implicit isolation effects for the Pods
51+
selected by the AdminNetworkPolicy, as opposed to implicit deny NetworkPolicy rules imply.
52+
53+
- **Pass**: Traffic that matches a `Pass` rule will skip all further rules from all
54+
numbered ANPs and instead be enforced by the K8s NetworkPolicies.
55+
If there is no K8s NetworkPolicy of BaselineAdminNetworkPolicy rule match
56+
match, traffic will be governed by the implementation. For most implementations,
57+
this means "allow", but there may be implementations which have their own policies
58+
outside of the standard Kubernetes APIs.
59+
- **Deny**: Traffic that matches a `Deny` rule will be dropped.
60+
- **Allow**: Traffic that matches an `Allow` rule will be allowed.
61+
62+
AdminNetworkPolicy `Deny` rules are useful for administrators to explicitly
63+
block traffic with malicious in-cluster clients, or workloads that pose security risks.
64+
Those traffic restrictions can only be lifted once the `Deny` rules are deleted,
65+
modified by the admin, or overridden by a higher priority rule.
66+
67+
On the other hand, the `Allow` rules can be used to call out traffic in the cluster
68+
that needs to be allowed for certain components to work as expected (egress to
69+
CoreDNS for example). Those traffic should not be blocked when developers apply
70+
NetworkPolicy to their Namespaces which isolates the workloads.
71+
72+
AdminNetworkPolicy `Pass` rules allows an admin to delegate security posture for
73+
certain traffic to the Namespace owners by overriding any lower precedence Allow
74+
or Deny rules. For example, intra-tenant traffic management can be delegated to tenant
75+
admins explicitly with the use of `Pass` rules. More specifically traffic selected
76+
by a `Pass` rule will skip any further ANP rule selection, be evaluated against
77+
any well defined NetworkPolicies, and if not terminated ultimately be evaluated against any
78+
BaselineAdminNetworkPolicies.
79+
80+
### AdminNetworkPolicy Priorities
81+
82+
Integer priority values were added to the AdminNetworkPolicy API to allow Cluster
83+
Admins to express direct and intentional ordering between various ANP Objects.
84+
The `Priority` field in the ANP spec is defined as an integer value
85+
within the range 0 to 1000 where rules with lower priority values have higher
86+
precedence. Regardless of priority value all ANPs have higher precedence than
87+
any defined NetworkPolicy or BaselineAdminNetworkPolicy objects.
88+
89+
### AdminNetworkPolicy Rules
90+
91+
Each ANP should define at least one `Ingress` or `Egress` relevant in-cluster traffic flows.
92+
and the Actions that should take place for those flows. In each `gress` rule the user
93+
should AT THE MINIMUM define an `Action`, and at least one `AdminNetworkPolicyPeer`.
94+
Optionally the user may also define select `Ports` to filter traffic on and also
95+
a name for each rule to make management/ reporting easier for Admins.
96+
97+
### AdminNetworkPolicy Status
98+
99+
For `v1alpha1` of this API the ANP status field is simply defined as a list of
100+
[`metav1.condition`](https://github.com/kubernetes/apimachinery/blob/v0.25.0/pkg/apis/meta/v1/types.go#L1464)s. Currently there are no rule as to what these conditions should display,
101+
and it is up to each implementation to report what they see fit. For further
102+
API iterations the community may consider standardizing these conditions based on
103+
the usefulness they provide for various implementors.
104+
105+
## The BaselineAdminNetworkPolicy Resource
106+
107+
The BaselineAdminNetworkPolicy (BANP) resource will allow administrators to
108+
set baseline security rules that describes default connectivity for cluster workloads,
109+
which CAN be overridden by developer NetworkPolicies if needed. The major use case
110+
BANPs solve is the ability to flip the [default security stance of the
111+
cluster](../index.md#story-5-cluster-wide-default-guardrails).
112+
113+
### BaselineAdminNetworkPolicy Rule Actions
114+
115+
BaselineAdminNetworkPolicies allow administrators to define two distinct actions
116+
for each well defined rule, `Allow` and `Deny`.
117+
118+
- **Deny**: Traffic that matches a `Deny` rule will be dropped.
119+
- **Allow**: Traffic that matches an `Allow` rule will be allowed.
120+
121+
### BaselineAdminNetworkPolicy Rules
122+
123+
BANP Rules are defined and behave the same (Except for the `Pass` action) as [ANP
124+
rules](#adminnetworkpolicy-rules).
125+
126+
### BaselineAdminNetworkPolicy Status
127+
128+
The BANP `status` field follows the same constructs as used by the
129+
[AdminNetworkPolicy.Status](#adminnetworkpolicy-status) field.

‎site-src/guides/examples.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
## Example AdminNetworkPolicy API Object Definitions
2+
3+
These examples will start with the object yaml defintions used to implement the
4+
[core use cases](../index.md#adminnetworkpolicy-api-user-stories). Please feel
5+
free to contribute more examples that may seem relevant to other users :-).
6+
7+
### Sample Spec for Story 1: Deny traffic at a cluster level
8+
9+
![Alt text](../images/explicit_deny.png?raw=true "Explicit Deny")
10+
11+
```yaml
12+
apiVersion: policy.networking.k8s.io/v1alpha1
13+
kind: AdminNetworkPolicy
14+
metadata:
15+
name: cluster-wide-deny-example
16+
spec:
17+
priority: 10
18+
subject:
19+
namespaces:
20+
matchLabels:
21+
kubernetes.io/metadata.name: sensitive-ns
22+
ingress:
23+
- action: Deny
24+
from:
25+
- namespaces:
26+
namespaceSelector: {}
27+
name: select-all-deny-all
28+
```
29+
30+
### Sample Spec for Story 2: Allow traffic at a cluster level
31+
32+
![Alt text](../images/explicit_allow.png?raw=true "Explicit Allow")
33+
34+
```yaml
35+
apiVersion: policy.networking.k8s.io/v1alpha1
36+
kind: AdminNetworkPolicy
37+
metadata:
38+
name: cluster-wide-allow-example
39+
spec:
40+
priority: 30
41+
subject:
42+
namespaces: {}
43+
ingress:
44+
- action: Allow
45+
from:
46+
- namespaces:
47+
namespaceSelector:
48+
matchLabels:
49+
kubernetes.io/metadata.name: monitoring-ns
50+
egress:
51+
- action: Allow
52+
to:
53+
- namespaces:
54+
namespaceSelector:
55+
matchlabels:
56+
kubernetes.io/metadata.name: kube-system
57+
pods:
58+
podSelector:
59+
matchlabels:
60+
app: kube-dns
61+
```
62+
63+
### Story 3: Explicitly Delegate traffic to existing K8s Network Policy
64+
65+
![Alt text](../images/delegation.png?raw=true "Delegate")
66+
67+
```yaml
68+
apiVersion: policy.networking.k8s.io/v1alpha1
69+
kind: AdminNetworkPolicy
70+
metadata:
71+
name: pub-svc-delegate-example
72+
spec:
73+
priority: 20
74+
subject:
75+
namespaces: {}
76+
egress:
77+
- action: Pass
78+
to:
79+
- namespaces:
80+
namespaceSelector:
81+
matchLabels:
82+
kubernetes.io/metadata.name: bar-ns-1
83+
pods:
84+
podSelector:
85+
matchLabels:
86+
app: svc-pub
87+
ports:
88+
- portNumber:
89+
protocol: TCP
90+
port: 8080
91+
```
92+
93+
### Story 4: Create and Isolate multiple tenants in a cluster
94+
95+
![Alt text](../images/tenants.png?raw=true "Tenants")
96+
97+
```yaml
98+
apiVersion: policy.networking.k8s.io/v1alpha1
99+
kind: AdminNetworkPolicy
100+
metadata:
101+
name: tenant-creation-example
102+
spec:
103+
priority: 50
104+
subject:
105+
namespaces:
106+
matchExpressions: {key: "tenant"; operator: Exists}
107+
ingress:
108+
- action: Deny
109+
from:
110+
- namespaces:
111+
notSameLabels:
112+
- tenant
113+
```
114+
115+
This can also be expressed in the following way:
116+
117+
```yaml
118+
apiVersion: policy.networking.k8s.io/v1alpha1
119+
kind: AdminNetworkPolicy
120+
metadata:
121+
name: tenant-creation-example
122+
spec:
123+
priority: 50
124+
subject:
125+
namespaces:
126+
matchExpressions: {key: "tenant"; operator: Exists}
127+
ingress:
128+
- action: Pass # Pass inter-tenant traffic to any defined NetworkPolicies
129+
from:
130+
- namespaces:
131+
sameLabels:
132+
- tenant
133+
- action: Deny # Deny everything else other than same tenant traffic
134+
from:
135+
- namespaces:
136+
namespaceSelector: {}
137+
```
138+
139+
### Story 5: Cluster Wide Default Guardrails
140+
141+
![Alt text](../images/baseline.png?raw=true "Default Rules")
142+
143+
```yaml
144+
apiVersion: policy.networking.k8s.io/v1alpha1
145+
kind: BaselineAdminNetworkPolicy
146+
metadata:
147+
name: baseline-rule-example
148+
spec:
149+
subject:
150+
namespaces: {}
151+
ingress:
152+
- action: Deny # zero-trust cluster default security posture
153+
from:
154+
- namespaces:
155+
namespaceSelector: {}
156+
```

‎site-src/images/ANP-api-model.png

37.5 KB
Loading

‎site-src/images/baseline.png

21.8 KB
Loading

‎site-src/images/delegation.png

22.7 KB
Loading

‎site-src/images/explicit_allow.png

32.3 KB
Loading

‎site-src/images/explicit_deny.png

31.5 KB
Loading

‎site-src/images/tenants.png

25.3 KB
Loading

0 commit comments

Comments
 (0)