Skip to content

Commit

Permalink
update of CRI API readme file
Browse files Browse the repository at this point in the history 
Kubernetes-commit: 9ac25f1d9ed148c7baddc9b5377d2899ec9f285f
  • Loading branch information
@SergeyKanzhelev @k8s-publishing-bot
SergeyKanzhelev authored and k8s-publishing-bot committed Jan 23, 2025
1 parent a2aeca5 commit 2cf5e70
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 91 deletions.
12 changes: 10 additions & 2 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,15 @@
# Contributing guidelines

Do not open pull requests directly against this repository, they will be ignored. Instead, please open pull requests against [kubernetes/kubernetes](https://git.k8s.io/kubernetes/). Please follow the same [contributing guide](https://git.k8s.io/kubernetes/CONTRIBUTING.md) you would follow for any other pull request made to kubernetes/kubernetes.
Do not open pull requests directly against this repository, they will be ignored.
Instead, please open pull requests against [kubernetes/kubernetes](https://git.k8s.io/kubernetes/).
Please follow the same [contributing guide](https://git.k8s.io/kubernetes/CONTRIBUTING.md)
you would follow for any other pull request made to kubernetes/kubernetes.

This repository is published from [kubernetes/kubernetes/staging/src/k8s.io/cri-api](https://git.k8s.io/kubernetes/staging/src/k8s.io/cri-api) by the [kubernetes publishing-bot](https://git.k8s.io/publishing-bot).
Issues related to CRI API can be filed at [kubernetes/kubernetes repository](https://github.com/kubernetes/kubernetes/issues).
For issues in specific implementations of CRI API (e.g. container runtime) - follow processes of the specific runtime.
For support, ask your Kubernetes vendor or ask at the [forum](https://discuss.kubernetes.io/).

This repository is published from [kubernetes/kubernetes/staging/src/k8s.io/cri-api](https://git.k8s.io/kubernetes/staging/src/k8s.io/cri-api)
by the [kubernetes publishing-bot](https://git.k8s.io/publishing-bot).

Please see [Staging Directory and Publishing](https://git.k8s.io/community/contributors/devel/sig-architecture/staging.md) for more information.
115 changes: 26 additions & 89 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,89 +17,40 @@ to be Kubernetes-centric. We try to avoid it, but there may be logic within a co
runtime that optimizes for the order or specific parameters of call(s) that the kubelet
makes.

## Version skew policy
## Version skew policy and feature development

On a single Node there may be installed multiple components implementing
different versions of CRI API.
Please read about:

For example, on a single node there might be:
- [CRI API version skew policy](https://kubernetes.dev/docs/code/cri-api-version-skew-policy/)
- [Kubernetes feature development and container runtimes](https://kubernetes.dev/docs/code/cri-api-dev-policies/)

- _Kubelet_ may call into _Container Runtime_ (e.g. [containerd](https://containerd.io))
and _Image Service Proxy_ (e.g. [stargz-snapshotter](https://github.com/containerd/stargz-snapshotter)).
_Container Runtime_ may be versioned with the OS Image, _Kubelet_ is installed
by system administrator and _Image Service proxy_ is versioned by the third party vendor.
- _Image Service Proxy_ calls into _Container Runtime_.
- _CRI tools_ (e.g. [crictl](https://kubernetes.io/docs/tasks/debug/debug-cluster/crictl/))
may be installed by end user to troubleshoot, same as a third party daemonsets.
All of them are used to call into the _Container Runtime_ to collect container information.

So on a single node it may happen that _Container Runtime_ is serving a newer
version'd kubelet and older versioned crictl. This is a supported scenario within
the version skew policy.

### Version Skew Policy for CRI API

CRI API has two versions:
- Major semantic version (known versions are `v1alpha2` ([removed in 1.26](https://kubernetes.io/blog/2022/12/09/kubernetes-v1-26-release/#cri-v1alpha2-removed)), `v1`).
- Kubernetes version (for example: `@1.23`). Note, the `cri-api` Golang library is versioned as `0.23` as it doesn't guarantee Go types backward compatibility.

Major semantic version (e.g. `v1`) is used to introduce breaking changes
and major new features that are incompatible with the current API.

Kubernetes version is used to indicate a specific feature set implemented
on top of the major semantic version. All changes made without the change
of a major semantic version API must be backward and forward compatible.

- _Kubelet_ must work with the older _Container Runtime_ if it implements
the same semantic version of CRI API (e.g. `v1`) of up to three Kubernetes minor
versions back. New features implemented in CRI API must be gracefully degraded.
For example, _Kubelet_ of version 1.26 must work with _Container Runtime_
implementing `k8s.io/cri-api@v0.23.0`+.
- _Kubelet_ must work with _Container Runtime_ if it implements
the same semantic version of CRI API (e.g. `v1`) of up to
three minor versions up. New features implemented in CRI API must not change
behavior of old method calls and response values. For example, _Kubelet_ of
version 1.22 must work with _Container Runtime_ implementing `k8s.io/cri-api@v0.25.5`.


## Versioning
## Community, discussion, contribution, and support

This library contains go classes generated from the CRI API protocol buffers and gRPC API.
Learn how to engage with the Kubernetes community on the [community
page](https://www.k8s.dev/community/).

The library versioned as `0.XX` as Kubernetes doesn't provide any guarantees
on backward compatibility of Go wrappers between versions. However CRI API itself
(protocol buffers and gRPC API) is marked as stable `v1` version and it is
backward compatible between versions.
You can reach the maintainers of this repository at:

Versions like `v0.<minor>.<patch>` (e.g. `v0.25.5`) are considered stable.
It is discouraged to introduce CRI API changes in patch releases and recommended
to use versions like `v0.<minor>.0`.
- Slack: #sig-node (on https://kubernetes.slack.com -- get an
invite at [slack.kubernetes.io](https://slack.kubernetes.io))
- Mailing List:
https://groups.google.com/forum/#!forum/kubernetes-sig-node

All alpha and beta versions (e.g. `k8s.io/cri-api@v0.26.0-beta.0`) should be
backward and forward compatible.
Issues can be filed at https://github.com/kubernetes/kubernetes/issues. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Feature development
### Code of Conduct

Some features development requires changes in CRI API and corresponding changes
in _Container Runtime_. Coordinating between Kubernetes branches and release
versions and _Container Runtime_ versions is not always trivial.
Participation in the Kubernetes community is governed by the [Kubernetes
Code of Conduct](code-of-conduct.md).

The recommended feature development flow is following:
### Contribution Guidelines

- Review proposed CRI API changes during the KEP review stage.
Some field names and types may not be spelled out exactly at this stage.
- Locally implement a prototype that implement changes in both - Kubernetes and Container Runtime.
- Submit a Pull Request for Kubernetes implementing CRI API changes alongside the feature code.
Feature must be developed to degrade gracefully when used with older Container Runtime
according to the Version Skew policy.
- Once PR is merged, wait for the next Kubernetes release tag being produced.
Find the corresponding CRI API tag (e.g. `k8s.io/cri-api@v0.26.0-beta.0`).
- This tag can be used to implement the feature in Container Runtime. It is recommended
to switch to the stable tag like (`k8s.io/cri-api@v0.26.0`) once available.
See [CONTRIBUTING.md](CONTRIBUTING.md) for more information. Please note that [kubernetes/cri-api](https://github.com/kubernetes/cri-api)
is a readonly mirror repository, all development is done at [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).

## Change history

Here is the change history of the Container Runtime Interface protocol:
Here is the change history of the Container Runtime Interface protocol. The change history is maintained manually:

### v1.20

Expand Down Expand Up @@ -263,25 +214,11 @@ No changes
- [[KEP-4639] Add OCI VolumeSource CRI API](https://github.com/kubernetes/kubernetes/pull/125659)
- Added `image` field to the type `Mount` to represent the OCI VolumeSource

### v1.32

## Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the [community
page](http://kubernetes.io/community/).

You can reach the maintainers of this repository at:

- Slack: #sig-node (on https://kubernetes.slack.com -- get an
invite at [slack.kubernetes.io](https://slack.kubernetes.io))
- Mailing List:
https://groups.google.com/forum/#!forum/kubernetes-sig-node

### Code of Conduct

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

### Contribution Guidelines
`git diff v1.31.0 v1.32.0 -- staging/src/k8s.io/cri-api/pkg/apis/runtime/v1/api.proto`

See [CONTRIBUTING.md](CONTRIBUTING.md) for more information. Please note that [kubernetes/cri-api](https://github.com/kubernetes/cri-api)
is a readonly mirror repository, all development is done at [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
- [CRI: Add field to support CPU affinity on Windows](https://github.com/kubernetes/kubernetes/pull/124285)
- CRI field `affinity_cpus` to `WindowsContainerResources` struct to support CPU affinity on Windows.
This field will be used by Windows CPU manager to set the logical processors to affinitize
for a particular container down to containerd/hcsshim.

0 comments on commit 2cf5e70

Please sign in to comment.