Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[WIP] add cdx:k8s taxonomy #61

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

[WIP] add cdx:k8s taxonomy #61

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
09433bc
add cds:k8s taxonomy
itaysk Jun 17, 2023
3c2a850
address pr comments
itaysk Jun 18, 2023
3424226
component name and type
itaysk Jun 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions cdx.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
| `cdx:composer` | Namespace for properties specific to the PHP Composer ecosystem. | CycloneDX PHP Maintainers | [cdx:composer taxonomy](cdx/composer.md) |
| `cdx:device` | Namespace for properties specific to hardware devices. | CycloneDX Core Working Group | [cdx:device taxonomy](cdx/device.md) |
| `cdx:gomod` | Namespace for properties specific to the Go Module ecosystem. | CycloneDX Go Maintainers | [cdx:gomod taxonomy](cdx/gomod.md) |
| `cdx:k8s` | Namespace for properties specific to the Kubernetes ecosystem. | CycloneDX Core Working Group | [cdx:k8s taxonomy](cdx/k8s.md) |
| `cdx:npm` | Namespace for properties specific to the Node NPM ecosystem. | CycloneDX JavaScript Maintainers | [cdx:npm taxonomy](cdx/npm.md) |
| `cdx:pipenv` | Namespace for properties specific to the Python Pipenv ecosystem. | CycloneDX Python Maintainers | [cdx:pipenv taxonomy](cdx/pipenv.md) |
| `cdx:poetry` | Namespace for properties specific to the Python Poetry ecosystem. | CycloneDX Python Maintainers | [cdx:poetry taxonomy](cdx/poetry.md) |
Expand Down
12 changes: 12 additions & 0 deletions cdx/k8s.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
## `cdx:k8s` Namespace Taxonomy

| Namespace | Description |
| --- | --- |
| `cdx:k8s:component` | Namespace for metadata of [Kubernetes components](https://kubernetes.io/docs/concepts/overview/components/). |

## `cdx:k8s:component` Namespace Taxonomy

| Property | Description |
| --- | --- |
| `cdx:k8s:component:type` | Type of the [Kubernetes component](https://kubernetes.io/docs/concepts/overview/components/). Well-known roles are "controlPlane", "node" |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to my understanding, "controlPlane" and "node" are not types of a component, but workers that are defined as such are able to run specific components.

why do you need to make this clear in the first place?
if i knew a components role (like "kubelet") i would know on which runner-type this should be running (like "node").
there is no need to announce directly implied data, right?

could you describe why this information is useful?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the use of this field is just for information management, so that a user can search the control plane components or ignore them, etc. yes we don't mind removing it in the initial PR.

about your comment: for node-level components I think you're right and in fact we represent this as a dependency in the SBOM we generate. for control plane, there isn't an entity to refer to, we actually has a version with a controlplan entiry in the sbom just for the hierarchy but eventually decided to use property instead.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @itaysk in that there is value in stating the component type explicitly. If the tool generating the KBOM is able to deduce the type, why should the receiving party have to do it again?

The distinction of control plane vs. node is most certainly something the receiving party is interested in.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The distinction of control plane vs. node is most certainly something the receiving party is interested in.

@nscuro Is there an improvement you want to suggest?

| `cdx:k8s:component:name` | Name of the [Kubernetes component](https://kubernetes.io/docs/concepts/overview/components/). Well-known names are "kube-apiserver", "kube-scheduler", kube-controller-manager", "cloud-controller-manager", "kubelet", "kube-proxy", "dashboard", "cni", "csi" |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you mentioned that the names are not the official ones but different.
The official ones do have documentation and I would recognize them. Your custom values have no documentation at all.
what is the benefit in custom values?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the long comment.
I think this document does not intend to be the source of truth for how to classify or name components and it's not comprehensive nor up to date. Also, it is written as an article and not a technical document and therefore I don't think the titles used there should be taken verbatim as canonical names. For example:

  1. some of the components like kube-apiserver or cloud-controller-manager are written in a technical standard, while some like Web UI (Dashboard) or Container Resource Monitoring are written in a human readable standard. Also some titles like "Logging" or "Monitoring" aren't grammatically fitting for a component role or type. I think offering the latter as well known is inconsistent and potentially confusing.
  2. "Network Plugins" is a good for a doc title in but the technical term generally used is CNI Plugin (container network interface). This is used in other parts of the k8s docs and in other k8s tools. The doc covers CNI but not CSI (container storage interface) which is a more recent addition. If we chose the doc title "Network Plugin" should we call the other one "Storage Plugin" to go with the theme? probably not.
  3. Web UI (dashboard) - again, decent title in an web page, but I don't think it's useful in a json document.
  4. Addons is an entire rabbit hole of inconsistency and ill defined concepts. Addons used to be a k8s feature (there was an "addon-manager" and a collection of addons) but this is no longer. Now addon is an abstract concept which has conflicting definitions: the k8s docs refer to addons as k8s components in kube-system namespace, but the addons listed in the same don't follow this definition. most kubernetes utilities today (that could have been "addons") are being distributed and installed by users however they want and aren't called addons anymore. so for us, we decided against trying to fix this problem and just ignore it.

IMO - besides the "very well known" components (apiserver, kubelet, etc) I think it will be very hard to map components to a common taxonomy (for example, is this app I found a k8s dashboard or just an admin tool you happen to have there) and it's also not a problem we're trying to solve right now.

I can restore my original version with the titles from doc, or keep just the "very well known" components, up to you.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, the naming scheme used by the linked document is inconsistent and there exist better, technical names that are widely used in the industry.

For cni and csi specifically though, I'd suggest to use cni-plugin and csi-plugin instead. CNI and CSI are just interfaces exposed by k8s, whereas what you'd list in a KBOM are implementations of it (e.g. Calico, Cilium).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so we really need a set of well-known values in the documentation, right?
Would you add one, so we can discuss it?

Copy link
Member

@jkowalleck jkowalleck Jul 2, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, the naming scheme used by the linked document is inconsistent and there exist better, technical names that are widely used in the industry.

Why is this? I mean, we are scoping for Kubernetes, right?
How comes the terms from the docs of Kubernetes are inconsistent, and why are there technical names that are widely used in the industry instead?
Could somebody explain and help me understand, whether we are still in the technical scope of Kubernetes, not in general container scope?