Skip to content

Commit 95ae2f8

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #161 from astoycos/add-blog
setup mkdocs blog scaffolding
2 parents 85f553d + f17f85e commit 95ae2f8

9 files changed

+379
-5
lines changed

‎mkdocs.yml

+10
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,13 @@ plugins:
2424
- macros:
2525
#include_dir: examples
2626
j2_line_comment_prefix: "#$"
27+
- blog:
28+
# NOTE: configuration options can be found at
29+
# https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/
30+
blog_dir: blog
31+
blog_toc: true
32+
#post_excerpt: required
33+
post_excerpt_max_authors: 2
2734
markdown_extensions:
2835
- admonition
2936
- meta
@@ -57,8 +64,11 @@ nav:
5764
- Template: npeps/npep-95.md
5865
- Provisional:
5966
- npeps/npep-126-egress-traffic-control.md
67+
- npeps/npep-122.md
6068
- Implementable:
6169
- npeps/npep-137-conformance-profiles.md
6270
# - Experimental:
6371
# - Standard:
6472
# - Declined:
73+
- Blog:
74+
- blog/index.md

‎requirements.txt

+4-4
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ MarkupSafe==2.1.3
88
mkdocs==1.5.2
99
mkdocs-awesome-pages-plugin==2.7.0
1010
mkdocs-macros-plugin==0.6.0
11-
mkdocs-material==7.3.3
12-
mkdocs-material-extensions==1.0.1
11+
mkdocs-material==9.2.0b3
12+
mkdocs-material-extensions==1.1.1
1313
pep562==1.0
14-
Pygments==2.5.2
15-
pymdown-extensions==9.0
14+
Pygments==2.14.0
15+
pymdown-extensions==9.9.1
1616
PyYAML==5.3
1717
six==1.14.0
1818
tornado==6.0.3

‎site-src/blog/.authors.yml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
astoycos:
2+
name: Alex Stoycos
3+
description: Senior Software Engineer at Red Hat. network-policy-api co-lead.
4+
avatar: https://github.com/astoycos.png
5+

‎site-src/blog/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Network Policy API Subgroup Blog

‎site-src/blog/posts/fake-post.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
date: 2023-09-07
3+
authors:
4+
- astoycos
5+
---
6+
7+
# Replace with blog post
8+
9+
This is a temporary blog to be replaced with a real one :) .

‎site-src/enhancements.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ To start NPEP process, create a PR adding `npep-<issue number>.md` file in the
5656
[npep folder](https://github.com/kubernetes-sigs/network-policy-api/tree/master/npep)
5757
using the [template NPEP](https://github.com/kubernetes-sigs/network-policy-api/blob/master/npep/npep-95.md) as a
5858
starting point. Make sure to also add your new NPEP to the website, this can be done within
59-
the `index.md` file at the root of the repo.
59+
the `mkdocs.yml` file at the root of the repo.
6060

6161
### 4. Provisional: Agree on the Goals and applicable User-Stories
6262

‎site-src/npeps/npep-126-egress-traffic-control.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# NPEP-126: Add northbound traffic support in (B)ANP API
2+
3+
* Issue: [#126](https://github.com/kubernetes-sigs/network-policy-api/issues/126)
4+
* Status: Provisional
5+
6+
## TLDR
7+
8+
This NPEP proposes adding support for cluster egress (northbound) traffic control
9+
in the `AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` API objects.
10+
11+
## Goals
12+
13+
* Implement egress traffic control towards external destinations (outside the cluster)
14+
* Implement egress traffic control towards cluster nodes
15+
- Currently the behaviour for policies defined around traffic from cluster
16+
workloads (non-hostNetworked pods) towards nodes in the
17+
cluster is undefined. See https://github.com/kubernetes-sigs/network-policy-api/issues/73.
18+
- ANP currently supports only east-west traffic and this traffic flow cuts from
19+
overlay to underlay which makes this part of the egress (northbound) use case.
20+
- Let's provide a defined behaviour in ANP to explicitly achieve the use case.
21+
- NOTE: Traffic towards nodes here includes traffic towards host-networked pods on that node
22+
because a "node" resource encompasses all objects that share the host-networking resources
23+
* Implement egress traffic control towards k8s-apiservers
24+
- An apiserver endpoint in this context is special in the sense that it can be any entity
25+
including but not limited to a host-networked pod within the cluster OR external VMs OR
26+
infrastructure nodes running outside the cluster. This is why its a separate category goal.
27+
28+
## Non-Goals
29+
30+
* Implementing southbound (ingress) traffic use cases is outside the scope of this NPEP
31+
* Implementing egress traffic control towards arbitrary hostNetworked pods is outside the scope of this NPEP
32+
- Currently the behaviour for policies defined around traffic from cluster
33+
workloads (non-hostNetworked pods) towards hostNetworked pods in the
34+
cluster is undefined. See https://github.com/kubernetes-sigs/network-policy-api/issues/73.
35+
- ANP currently supports only east-west traffic and this traffic flow cuts from
36+
overlay to underlay which makes this part of the egress (northbound) use case.
37+
- NOTE: Currently there are no user stories for `CNI pod to arbitrarily chosen hostNetworked pods`.
38+
Let's provide a defined behaviour in ANP to explicitly achieve the use case in the future if we have
39+
user stories for this outside of the k8s-apiserver usecase which is already covered in the goals.
40+
If that happens, this can be moved to goals.
41+
42+
## Introduction
43+
44+
### User Stories for egress traffic control towards external destinations
45+
46+
1. **As a** cluster administrator **I want** to restrict traffic from
47+
specific cluster workloads to all or specific destinations outside the
48+
cluster **so that** I can enforce security for northbound traffic.
49+
Example: Pods in namespaceA and namespaceB should not be able to talk
50+
to the internet but they should be able to access company's intranet.
51+
52+
2. **As a** cluster administrator **I want** to to ensure that pods can
53+
reach my cluster-external DNS server even if namespace admins create
54+
NetworkPolicies that block cluster-external egress.
55+
Example: As an owner of namespaceA I define policies that deny all
56+
northbound egress traffic for that namespace. However the cluster-admin
57+
can decide all namespaces in the cluster must be able to talk to the
58+
EXTERNAL_DNS_SERVER_IP on port 53.
59+
60+
### User Stories for egress traffic control towards cluster nodes
61+
62+
1. **As a** cluster administrator **I want** to easily block access from
63+
cluster workloads to specific ports on cluster nodes without having to block
64+
access to those ports on external hosts, without having to manually list
65+
the IP address of every node, and without having to change the policy when
66+
new nodes are added to the cluster.
67+
68+
### User Stories for egress traffic control towards k8s-apiservers
69+
70+
1. **As a** cluster administrator **I want** to easily allow access to
71+
k8s-apiservers from cluster workloads when there are other deny rules in place
72+
for these workloads.
73+
74+
2. **As a** cluster administrator **I want** to easily block access from
75+
selected cluster workloads to k8s-apiservers for securing the server.
76+
77+
## API
78+
79+
(... details, can point to PR with changes)
80+
81+
82+
## Alternatives
83+
84+
(List other design alternatives and why we did not go in that
85+
direction)
86+
87+
## References
88+
89+
* https://github.com/danwinship/enhancements/blob/cluster-egress-firewall/keps/sig-network/20190917-cluster-egress-firewall.md#blocking-access-to-services-used-by-the-node
90+
* https://github.com/kubernetes-sigs/network-policy-api/pull/86

‎site-src/npeps/npep-137-conformance-profiles.md

+189
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# NPEP-137: Conformance Profiles
2+
3+
* Issue: [#137](https://github.com/kubernetes-sigs/network-policy-api/issues/137)
4+
* Status: Implementable
5+
6+
## TLDR
7+
8+
Add conformance profiles for existing conformance tests which implementations
9+
can leverage when running the conformance test suite in their downstream repos
10+
to report the results of the tests back to the Network Policy API project and
11+
receive recognition (eg. "conformance badge")
12+
13+
* NOTE: Adapted with love from https://gateway-api.sigs.k8s.io/geps/gep-1709/ (Then
14+
a question may arise, why do we need our own NPEP? Answer: Gateway API Project has
15+
lots of resources and features and it gets very complicated to adopt their same API.
16+
We need to tune the profiles to be compatible with what works for Network Policy API
17+
project, thus the need for this NPEP). Our profiles are much simpler than what GatewayAPI
18+
supports.
19+
20+
## Goals
21+
22+
* Add conformance profiles for existing tests that downstream implementations
23+
can subscribe to to run tests associated to the supported API feature sets
24+
25+
* Add a reporting mechanism via a new CRD where conformance results can be
26+
reported back to the Network Policy API project and provide "conformance badges"
27+
via Network Policy official website to recognize these implementations.
28+
29+
* Expand existing conformance testing framework to account for profiles
30+
31+
## Non-Goals
32+
33+
* The first iteration will just have a simple repo under which the report
34+
results will be stored, no automated reporting infrastructure will be built for this now.
35+
Implementations will need to open PRs against network-policy-api repo to upload
36+
the results.
37+
38+
## Introduction
39+
40+
Currently, the conformance tests are grouped into `CoreFeatures` and
41+
`ExtendedFeatures`. The support for features that fall under the `CoreFeatures`
42+
are a requirement for conformant implementations, while the support for features that fall
43+
under `ExtendedFeatures` are optional and do not gate API conformance for implementations.
44+
45+
In this NPEP, we will add a concept called `named profiles` which will indicate a
46+
"level of conformance" for a given resource. We are picking profiles on a resource
47+
level because that is what makes sense for the project as of today. The initial decision
48+
to report conformance profiles on a per-resource level is a choice which may be re-evaluated
49+
by the NetworkPolicy API working group in the future. Using these `named profiles`,
50+
implementations can run the conformance tests, prove they satisfy the requirements for each profile,
51+
and receive conformance badges from the Network Policy API project.
52+
53+
This NPEP aims to provide an API (CRD) for reporting results from these conformance
54+
tests. CLI tooling will also be provided for invoking the conformance tests with
55+
the profile names so that the results can be easily submitted back upstream.
56+
57+
## User-Stories/Use-Cases
58+
59+
Story 1: Receive an API conformance badge
60+
61+
As a CNI maintainer, I want to receive recognition from Network Policy API subgroup
62+
that my plugin implements the `AdminNetworkPolicy` API. This badge will enable us
63+
to advertise upstream feature support in our plugin easily to our users.
64+
65+
Story 2: Track Implementations for each API resource
66+
67+
As a Network Policy project maintainer, I would like to easily track which
68+
implementations are using the defined API resources in our project so that it
69+
paves way for easier collaboration and feedback loops when changes are introduced
70+
to the API in each release.
71+
72+
## API
73+
74+
We will add a new API resource called `ConformanceReport` which will be at
75+
the center of our test result reporting workflow. The implementors running
76+
the tests can then:
77+
78+
1. Choose a `named profile`
79+
2. Integrate the tests required by a given profile in their downstream project
80+
3. Report the results to Network Policy API project using this new API resource
81+
4. Get a conformance badge recognition via our official website
82+
83+
## Profiles
84+
85+
Named Profiles for Network Policy API project will be tied to each API resource.
86+
We will start with two named profiles and expand this as the project evolves.
87+
88+
1. AdminNetworkPolicy
89+
2. BaselineAdminNetworkPolicy
90+
91+
Each of these profiles may have a combination of conformance tests that fall under
92+
`CoreFeatures` and `ExtendedFeatures`. Example; if you pick the profile
93+
`AdminNetworkPolicy`, all tests like `AdminNetworkPolicyEgressSCTP` and
94+
`AdminNetworkPolicyPriorityField` fall under the `SupportAdminNetworkPolicy` feature
95+
which is under the `CoreFeatures` subset. So these tests must pass for the
96+
`AdminNetworkPolicy` profile conformance. Whereas tests (we don't have any today)
97+
that fall under `AdminNetworkPolicySameLabels` feature which is under the
98+
`ExtendedFeatures` subset are not mandatory for `AdminNetworkPolicy`
99+
profile conformance.
100+
101+
## Integration
102+
103+
The conformance profile test suite can be integrated, invoked and run from your implementation
104+
using two methods:
105+
106+
* The `go test` CLI commands specifying the required information need to generate
107+
a conformance test report. Sample:
108+
```
109+
go test -v ./conformance -run TestConformanceProfiles -args --conformance-profiles=AdminNetworkPolicy,BaselineAdminNetworkPolicy --organization=ovn-org -project=ovn-kubernetes -url=<project-url> -version=0.1.1 -contact=<> -additional-info=<link-to-implementation>
110+
```
111+
* Using the conformance profile test suite `TestConformanceProfiles` by directly customizing it by providing
112+
the correct arguments. Sample:
113+
```
114+
cpSuite := suite.NewConformanceProfileTestSuite(
115+
suite.ConformanceProfileOptions{
116+
suite.Options: cSuiteDefaultOptions,
117+
Implementation: confv1alpha1.Implementation{
118+
Organization: "ovn-org",
119+
Project: "OVN-Kubernetes CNI",
120+
URL: "https://github.com/ovn-org/ovn-kubernetes",
121+
Version: "0.1.1",
122+
Contact: []string{"@tssurya"},
123+
AdditionalInformation: "https://github.com/ovn-org/ovn-kubernetes/blob/1c9f73dc8a755c07b22858c7404a7884970d1989/test/conformance/network_policy_v2_test.go"
124+
},
125+
ConformanceProfiles: sets.New(
126+
suite.ANPConformanceProfileName,
127+
suite.BANPConformanceProfileName,
128+
),
129+
})
130+
```
131+
132+
## Reporting process and certification
133+
134+
The reporting process is related to a specific API's version and channel (core and experimental).
135+
There are fields in the ConformanceReport CRD that includes such information. Any implementation
136+
can run the existing conformance test suite specifying the profiles they support and that will
137+
generate an output that looks like this:
138+
139+
```
140+
Conformance report:
141+
apiVersion: policy.networking.k8s.io/v1alpha1
142+
date: "2023-10-03T08:15:25+02:00"
143+
implementation:
144+
contact:
145+
- "@tssurya"
146+
organization: ovn-org
147+
project: OVN-Kubernetes CNI
148+
url: "https://github.com/ovn-org/ovn-kubernetes"
149+
version: 0.1.1
150+
additionalInformation: "https://github.com/ovn-org/ovn-kubernetes/blob/1c9f73dc8a755c07b22858c7404a7884970d1989/test/conformance/network_policy_v2_test.go"
151+
kind: ConformanceReport
152+
networkPolicyV2APIVersion: v0.1.1
153+
profiles:
154+
- core:
155+
failedTests:
156+
- AdminNetworkPolicyIngressSCTP
157+
- AdminNetworkPolicyEgressUDP
158+
result: failure
159+
statistics:
160+
Failed: 2
161+
Passed: 5
162+
Skipped: 0
163+
summary: ""
164+
name: AdminNetworkPolicy
165+
- core:
166+
result: success
167+
statistics:
168+
Failed: 0
169+
Passed: 7
170+
Skipped: 0
171+
summary: ""
172+
name: BaselineAdminNetworkPolicy
173+
```
174+
175+
This can then be uploaded to network-policy-api/conformance/reports/v.x.x/cni-name.yaml by
176+
opening a PR. That will then be reviewed and approved by maintainers thus recognizing the
177+
implementations that are conformant. It is recommended for the implementations to use the
178+
`additionalInformation` field to provide links to the implementation or github actions or
179+
jenkins or any other CI/CD job definitions that helped generate this report. This will
180+
help maintainers make an informed decision on merging the report PR.
181+
182+
## Alternatives
183+
184+
N/A - We just went with what Gateway API project already has implemented without
185+
having to reinvent the wheel.
186+
187+
## References
188+
189+
1. https://github.com/kubernetes-sigs/network-policy-api/pull/142

0 commit comments

Comments
 (0)