Skip to content

Commit 7d1e131

Browse files
astoycosastoycos
committed
Fixup Website add Docs
Add docs around versioning and releasing of the API. Update the website adding some of the new docs and changing the landing page to not take users directly to the AdminNetworkPolicy API. Signed-off-by: Andrew Stoycos <[email protected]>
1 parent 2cc1bfb commit 7d1e131

File tree

11 files changed

+365
-127
lines changed

11 files changed

+365
-127
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<img src="https://github.com/kubernetes/kubernetes/raw/master/logo/logo.png" width="100">
22

33
# Network Policy API
4-
👋 Welcome to the Network Policy API Project - we are happy to have you here! Before you get started here are some useful links:
4+
Welcome to the Network Policy API Project - we are happy to have you here! Before you get started here are some useful links:
55
- [Our Website](https://network-policy-api.sigs.k8s.io/)
66
- [Agenda](https://docs.google.com/document/d/1AtWQy2fNa4qXRag9cCp5_HsefD7bxKe3ea2RPn8jnSs/edit#heading=h.ajvcztp6cza)
77
- [NetworkPolicy v1 Docs](https://kubernetes.io/docs/concepts/services-networking/network-policies/)

‎RELEASE.md

Lines changed: 92 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,95 @@
11
# Release Process
22

3-
The Kubernetes Template Project is released on an as-needed basis. The process is as follows:
3+
## Overview
44

5-
1. An issue is proposing a new release with a changelog since the last release
6-
1. All [OWNERS](OWNERS) must LGTM this release
7-
1. An OWNER runs `git tag -s $VERSION` and inserts the changelog and pushes the tag with `git push $VERSION`
8-
1. The release issue is closed
9-
1. An announcement email is sent to `[email protected]` with the subject `[ANNOUNCE] kubernetes-template-project $VERSION is released`
5+
The Network Policy API project is has the following two main release components:
6+
- Kubernetes Custom Resource Definitions (CRDs)
7+
- Corresponding Go API in the form of `sigs.k8s.io/network-policy-api` Go package
8+
9+
This repository is the home for both of the above components.
10+
11+
## Versioning strategy
12+
The versioning strategy for this project is covered in detail in [the release
13+
documentation].
14+
15+
[the release documentation]: site-src/versioning.md
16+
17+
## Releasing a new version
18+
19+
### Writing a Changelog
20+
21+
To simplify release notes generation, we recommend using the [Kubernetes release
22+
notes generator](https://github.com/kubernetes/release/blob/master/cmd/release-notes):
23+
24+
```
25+
go install k8s.io/release/cmd/release-notes@latest
26+
export GITHUB_TOKEN=your_token_here
27+
release-notes --start-sha EXAMPLE_COMMIT --end-sha EXAMPLE_COMMIT --branch main --repo network-policy-api --org kubernetes-sigs
28+
```
29+
30+
This output will likely need to be reorganized and cleaned up a bit, but it
31+
provides a good starting point. Once you're satisfied with the changelog, create
32+
a PR. This must go through the regular PR review process and get merged into the
33+
`main` branch. Approval of the PR indicates community consensus for a new
34+
release.
35+
36+
### Release Steps
37+
38+
The following steps must be done by one of the [network-policy API maintainers][network-policy-api-team]:
39+
40+
For a **PATCH** release:
41+
- Create a new branch in your fork named something like `<githubuser>/release-x.x.x`. Use the new branch
42+
in the upcoming steps.
43+
- Use `git` to cherry-pick all relevant PRs into your branch.
44+
- Update `pkg/generator/main.go` with the new semver tag and any updates to the API review URL.
45+
- Run the following command `BASE_REF=vmajor.minor.patch make generate` which
46+
will update generated docs and webhook with the correct version info. (Note
47+
that you can't test with these YAMLs yet as they contain references to
48+
elements which wont exist until the tag is cut and image is promoted to
49+
production registry.)
50+
- Create a pull request of the `<githubuser>/release-x.x.x` branch into the `release-x.x` branch upstream
51+
(which should already exist since this is a patch release). Add a hold on this PR waiting for at least
52+
one maintainer/codeowner to provide a `lgtm`.
53+
- Verify the CI tests pass and merge the PR into `release-x.x`.
54+
- Create a tag using the `HEAD` of the `release-x.x` branch. This can be done using the `git` CLI or
55+
Github's [release][release] page.
56+
- Run the `make build-install-yaml` command which will generate install files in the `release/` directory.
57+
Attach these files to the Github release.
58+
- Update the `README.md` and `site-src/guides/index.md` files to point links and examples to the new release.
59+
60+
For a **MAJOR** or **MINOR** release:
61+
62+
- Cut a `release-major.minor` branch that we can tag things in as needed.
63+
- Check out the `release-major.minor` release branch locally.
64+
- Update `pkg/generator/main.go` with the new semver tag and any updates to the API review URL.
65+
- Run the following command `BASE_REF=vmajor.minor.patch make generate` which
66+
will update generated docs and webhook with the correct version info. (Note
67+
that you can't test with these YAMLs yet as they contain references to
68+
elements which wont exist until the tag is cut and image is promoted to
69+
production registry.)
70+
- Verify the CI tests pass before continuing.
71+
- Create a tag using the `HEAD` of the `release-x.x` branch. This can be done using the `git` CLI or
72+
Github's [release][release] page.
73+
- Run the `make build-install-yaml` command which will generate install files in the `release/` directory.
74+
Attach these files to the Github release.
75+
- Update the `README.md` and `site-src/guides/index.md` files to point links and examples to the new release.
76+
77+
For an **RC** release:
78+
79+
- Update `pkg/generator/main.go` with the new semver tag and any updates to the API review URL.
80+
- Run the following command `BASE_REF=vmajor.minor.patch make generate` which
81+
will update generated docs and webhook with the correct version info. (Note
82+
that you can't test with these YAMLs yet as they contain references to
83+
elements which wont exist until the tag is cut and image is promoted to
84+
production registry.)
85+
- Include the changelog update in this PR.
86+
- Merge the update PR.
87+
- Tag the release using the commit on `main` where the changelog update merged.
88+
This can be done using the `git` CLI or Github's [release][release]
89+
page.
90+
- Run the `make build-install-yaml` command which will generate
91+
install files in the `release/` directory.
92+
- Attach these files to the Github release.
93+
94+
[release]: https://github.com/kubernetes-sigs/network-policy-api/releases
95+
[network-policy-api-team]: https://github.com/kubernetes/org/blob/main/config/kubernetes-sigs/sig-network/teams.yaml

‎hack/make-docs.sh

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,5 +37,5 @@ mkdocs build
3737
# Generate v1alpha2 API docs
3838
./hack/api-docs/generate.sh site/spec.html
3939
# Add them to spec page originally generated by mkdocs
40-
run::sed -e '/REPLACE_WITH_GENERATED_CONTENT/{r site/spec.html' -e 'd;}' site/references/spec/index.html
41-
run::sed -e '/REPLACE_WITH_GENERATED_CONTENT/{r site/spec.html' -e 'd;}' site/references/spec/index.html
40+
run::sed -e '/REPLACE_WITH_GENERATED_CONTENT/{r site/spec.html' -e 'd;}' site/reference/spec/index.html
41+
run::sed -e '/REPLACE_WITH_GENERATED_CONTENT/{r site/spec.html' -e 'd;}' site/reference/spec/index.html

‎mkdocs.yml

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
site_name: Kubernetes AdminNetworkPolicy API
1+
site_name: Network Policy API
22
repo_url: https://github.com/kubernetes-sigs/network-policy-api
33
repo_name: kubernetes-sigs/network-policy-api
44
site_dir: site
@@ -34,10 +34,16 @@ markdown_extensions:
3434
permalink: true
3535
nav:
3636
- Introduction: index.md
37-
- API overview: guides/api-overview.md
38-
- Examples: guides/examples.md
37+
- Overview:
38+
- User Stories: user-stories.md
39+
- Resources: api-overview.md
40+
- Versioning: versioning.md
41+
- Implementations: implementations.md
3942
- Reference:
40-
- API specification: references/spec.md
43+
- Examples: reference/examples.md
44+
- API Reference: reference/spec.md
45+
46+
4147
# (TODO)
4248
# - Implementation Guidelines: concepts/guidelines.md
4349
# - Versioning: concepts/versioning.md

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

Lines changed: 25 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
1-
## API overview
1+
# Api Object Overview
22

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.
3+
Prior to the Network Policy API the original NetworkPolicy Resource was the only
4+
way for k8s users to apply security rules to their kubernetes workloads. One of the
5+
main drawbacks to this API was that it was designed exclusively for use by the
6+
Application Developer, although in reality it is used by many different cluster
7+
personas, sometimes creating a complex web of objects to be maintained. In
8+
Contrast, each resource in the Network Policy API is designed to be used by a
9+
specific persona.
710

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+
With the advent of the AdminNetworkPolicy and BaselineAdminNetworkPolicy
12+
resources Cluster Admins will now have the ability to apply policy on in-cluster
13+
workloads with only a few simple policy objects that can be applied globally.
1114

1215
## Roles and personas
1316

@@ -17,9 +20,14 @@ In this documentation we refer to three primary personas:
1720
- Namespace Administrator
1821
- Cluster Administrator
1922

20-
## Resource Model
23+
## Resource Model
2124

22-
There are two main objects in the AdminNetworkPolicy API resource model
25+
!!! note
26+
Network Policy API resources are in the `policy.networking.k8s.io` API group as
27+
Custom Resource Definitions (CRDs). Unqualified resource names below will
28+
implicitly be in this API group.
29+
30+
Currently, there are two main objects in the Network Policy API resource model:
2331

2432
- **AdminNetworkPolicy (ANP)**
2533

@@ -31,18 +39,18 @@ There are two main objects in the AdminNetworkPolicy API resource model
3139
be read as-is, i.e. there will not be any implicit isolation effects for the Pods
3240
selected by the AdminNetworkPolicy, as opposed to what NetworkPolicy rules imply.
3341

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
42+
- As of `v1alpha1` of this API we focus primarily on E/W cluster traffic and
43+
do not address N/S (Ingress/Egress) use cases. However this is an issue the community
44+
would like to keep thinking about during further iterations, and a tracking issue
3745
can be found/ commented on here ---> [issue #28](https://github.com/kubernetes-sigs/network-policy-api/issues/28)
3846

39-
## The AdminNetworkPolicy Resource
47+
## The AdminNetworkPolicy Resource
4048

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
49+
The AdminNetworkPolicy (ANP) resource will help administrators set strict security
50+
rules for the cluster, i.e. a developer CANNOT override these rules by creating
4351
NetworkPolicies that apply to the same workloads as the AdminNetworkPolicy.
4452

45-
### AdminNetworkPolicy Actions
53+
### AdminNetworkPolicy Actions
4654

4755
Unlike the NetworkPolicy resource in which each rule represents an allowed
4856
traffic, AdminNetworkPolicies will enable administrators to set `Pass`,

‎site-src/implementations.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Implementations
2+
3+
This document tracks downstream(actual and planned) implementations of
4+
Network Policy API resources and provides status and resource references for them.
5+
6+
Implementors of Network Policy API resources are encouraged to update this document with status information about their
7+
implementations, the versions they cover, and documentation to help users get started.
8+
9+
## AdminNetworkPolicy and BaseLineAdminNetworkPolicy
10+
11+
Updated: 05-08-2023
12+
13+
- [Ovn-Kubernetes CNI](https://github.com/ovn-org/ovn-kubernetes/pull/3489) (work in progress)
14+
- [Antrea CNI](https://github.com/antrea-io/antrea/pull/4537) (work in progress)
15+
- [Cilium CNI](https://github.com/cilium/cilium/issues/23380) (tracking issue)
16+
- [Calico CNI](https://github.com/projectcalico/calico/issues/7578) (tracking issue)

‎site-src/index.md

Lines changed: 28 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,42 @@
1-
## What is the AdminNetworkPolicy API?
1+
# Network Policy API Working Group
2+
👋 Welcome to the Network Policy API Project - we are happy to have you here! Before you get started here are some useful links:
3+
- [Bi-Weekly Meeting Agenda](https://docs.google.com/document/d/1AtWQy2fNa4qXRag9cCp5_HsefD7bxKe3ea2RPn8jnSs/edit#heading=h.ajvcztp6cza)
4+
- [NetworkPolicy v1 Docs](https://kubernetes.io/docs/concepts/services-networking/network-policies/)
25

3-
The AdminNetworkPolicy API is an open source project managed by the [SIG-NETWORK][sig-network]
4-
community. It is a collection of resources, which aim to make securing Kubernetes
5-
clusters easier for Administrators.
6+
## What is the Network Policy API Project?
67

7-
![Gateway API Model](./images/ANP-api-model.png)
8+
The network policy API subgroup is a part of [SIG Network](https://github.com/kubernetes/community/tree/master/sig-network),
9+
formed to address further work involving Kubernetes network security beyond the core NetworkPolicy v1 resource.
10+
The [`network-policy-api`](https://github.com/kubernetes-sigs/network-policy-api/) repository contains APIs which are
11+
created and maintained by this subgroup.
812

9-
## Getting started
13+
## APIs
1014

11-
Whether you are a user interested in using the AdminNetworkPolicy API or an implementer
12-
interested in conforming to the API, the following resources will help give
13-
you the necessary background:
15+
We refer to "APIs" in the plural here because this project will house
16+
multiple K8s CRD resources geared towards different users and use cases.
1417

15-
- [API overview](/guides/api-overview)
16-
- [Examples](/guides/examples)
17-
- [API Source](https://github.com/kubernetes-sigs/network-policy-api/tree/master/apis/v1alpha1)
18+
### Active (APIs undergoing active development)
1819

20+
- [AdminNetworkPolicy](api-overview.md#the-adminnetworkpolicy-resource) and [BaselineAdminNetworkPolicy](api-overview.md#the-baselineadminnetworkpolicy-resource)
1921

20-
## AdminNetworkPolicy API User Stories
22+
### Future (Possible APIs to be created in the future)
2123

22-
The following user stories drive the concepts of the AdminNetworkPolicy API for the
23-
`v1alpha1` version of the api. More information on how the community ended up here
24-
can be found in the [API KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-network/2091-admin-network-policy)
25-
and in the accompanying [KEP PR](https://github.com/kubernetes/enhancements/pull/2522)
24+
- DeveloperNetworkPolicy
2625

27-
Future API developments should all start with a **well-defined** and **intentional**
28-
user story.
26+
## Outreach
2927

30-
### Story 1: Deny traffic at a cluster level
28+
- [Kubecon NA 2022 Contributors Summit](https://youtu.be/00nVssi2oPA)
29+
- [Kubecon NA 2022 SIG Network Deep Dive](https://www.youtube.com/watch?v=qn9bM5Cwvg0&t=752s)
30+
- [Kubecon NA 2023 SIG Network Deep Dive](https://www.youtube.com/watch?v=0uPEFcWn-_o)
3131

32-
As a cluster admin, I want to apply non-overridable deny rules
33-
to certain pod(s) and(or) Namespace(s) that isolate the selected
34-
resources from all other cluster internal traffic.
32+
## Community, discussion, contribution, and support
33+
Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
3534

36-
For Example: In this diagram there is a AdminNetworkPolicy applied to the
37-
`sensitive-ns` denying ingress from all other in-cluster resources for all
38-
ports and protocols.
35+
You can reach the maintainers of this project at:
36+
- [Slack](https://kubernetes.slack.com/messages/sig-network-policy-api)
37+
- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-network)
3938

40-
![Alt text](./images/explicit_deny.png?raw=true "Explicit Deny")
41-
42-
### Story 2: Allow traffic at a cluster level
43-
44-
As a cluster admin, I want to apply non-overridable allow rules to
45-
certain pods(s) and(or) Namespace(s) that enable the selected resources
46-
to communicate with all other cluster internal entities.
47-
48-
For Example: In this diagram there is a AdminNetworkPolicy applied to every
49-
namespace in the cluster allowing egress traffic to `kube-dns` pods, and ingress
50-
traffic from pods in `monitoring-ns` for all ports and protocols.
51-
52-
![Alt text](./images/explicit_allow.png?raw=true "Explicit Allow")
53-
54-
### Story 3: Explicitly Delegate traffic to existing K8s Network Policy
55-
56-
As a cluster admin, I want to explicitly delegate traffic so that it
57-
skips any remaining cluster network policies and is handled by standard
58-
namespace scoped network policies.
59-
60-
For Example: In the diagram below egress traffic destined for the service svc-pub
61-
in namespace bar-ns-1 on TCP port 8080 is delegated to the k8s network policies
62-
implemented in foo-ns-1 and foo-ns-2. If no k8s network policies touch the
63-
delegated traffic the traffic will be allowed.
64-
65-
![Alt text](./images/delegation.png?raw=true "Delegate")
66-
67-
### Story 4: Create and Isolate multiple tenants in a cluster
68-
69-
As a cluster admin, I want to build tenants in my cluster that are isolated from
70-
each other by default. Tenancy may be modeled as 1:1, where 1 tenant is mapped
71-
to a single Namespace, or 1:n, where a single tenant may own more than 1 Namespace.
72-
73-
For Example: In the diagram below two tenants (Foo and Bar) are defined such that
74-
all ingress traffic is denied to either tenant.
75-
76-
![Alt text](./images/tenants.png?raw=true "Tenants")
77-
78-
### Story 5: Cluster Wide Default Guardrails
79-
80-
As a cluster admin I want to change the default security model for my cluster,
81-
so that all intra-cluster traffic (except for certain essential traffic) is
82-
blocked by default. Namespace owners will need to use NetworkPolicies to
83-
explicitly allow known traffic. This follows a whitelist model which is
84-
familiar to many security administrators, and similar
85-
to how [kubernetes suggests network policy be used](https://kubernetes.io/docs/concepts/services-networking/network-policies/#default-policies).
86-
87-
For Example: In the following diagram all Ingress traffic to every cluster
88-
resource is denied by a baseline deny rule.
89-
90-
![Alt text](./images/baseline.png?raw=true "Default Rules")
91-
92-
## Who is working on AdminNetworkPolicy?
93-
94-
The AdminNetworkPolicy API is a
95-
[SIG-Network](https://github.com/kubernetes/community/tree/master/sig-network)
96-
project being built to improve and standardize cluster-wide security policy in k8s. In-progress implementations include Antrea (VMware) and Openshift (RedHat),
97-
If you are interested in contributing to or
98-
building an implementation using the AdminNetworkPolicy API then don’t hesitate to [get
99-
involved!](/contributing/community)
100-
101-
[sig-network]: https://github.com/kubernetes/community/tree/master/sig-network
39+
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).
10240

41+
### Code of conduct
42+
Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).

0 commit comments

Comments
 (0)