From 078c98f8472c6fa4e8f68e3a8e9a2a113b449215 Mon Sep 17 00:00:00 2001 From: Leonardo Grasso Date: Wed, 6 May 2020 12:20:46 +0200 Subject: [PATCH] docs(proposal): split artifacts scope proposal in 2 parts Still some TODOs Signed-off-by: Leonardo Grasso --- proposals/20200504-falco-artifacts-scope.md | 180 ------------------- proposals/20200506-artifacts-scope-part-1.md | 114 ++++++++++++ proposals/20200506-artifacts-scope-part-2.md | 135 ++++++++++++++ 3 files changed, 249 insertions(+), 180 deletions(-) delete mode 100644 proposals/20200504-falco-artifacts-scope.md create mode 100644 proposals/20200506-artifacts-scope-part-1.md create mode 100644 proposals/20200506-artifacts-scope-part-2.md diff --git a/proposals/20200504-falco-artifacts-scope.md b/proposals/20200504-falco-artifacts-scope.md deleted file mode 100644 index e1eca060..00000000 --- a/proposals/20200504-falco-artifacts-scope.md +++ /dev/null @@ -1,180 +0,0 @@ -# Falco Scope - -As a project we would like to support the following artifacts. - -Everything else will be moved to [contrib](https://github.com/falcosecurity/contrib). - -As a project we will build, change, rename, and move files, documents, scripts, configurations according to this new state of the world. - -Inspired from [#1114](https://github.com/falcosecurity/falco/issues/1114) and many of the weekly community calls. - -## Terms - -**falco** - -*Standalone Falco binary* - -**driver** - -*System call provider from the Linux kernel. Either (`bpf`, `module`, or `ptrace`)* - -**falco-driver-loader** - - -*The bash script found [here](https://github.com/falcosecurity/falco/blob/master/scripts/falco-driver-loader) that tries to compile else download the driver (kernel module or eBPF probe).* - -**package** - -*An installable artifact that is operating system specific. All packages MUST be hosted on bintray for X86_64.* - -**image** - -*OCI compliant container image hosted on dockerhub with tags for every release.* - - -# Packages - -Official packages for X86_64 only. All package names should contain a version which is not specified below. - -The following convention MUST be used for all packages. - - -_If a package installs the Falco kernel module it MUST contain `module`._ - -_If a package installs the Falco BPF probe it MUST contain `bpf`._ - - ---- - -### .deb - - Falco running in debian like systems that will default to the kernel module. - -- falco-x86.deb - - `falco` only (default depends on `falco-module`) - - falco-module-x86.deb - - `module` only - - falco-bpf-x86.deb - - `bpf` only - - falco-ptrace-x86.deb - - `ptrace` only - -### .rpm - - Falco running in rpm like systems that will default to the kernel module. - -- falco-x86.deb - - `falco` only (default depends on `falco-module`) - - falco-module-x86.deb - - `module` only - - falco-bpf-x86.deb - - `bpf` only - - falco-ptrace-x86.deb - - `ptrace` only - - -### .tar.gz - - - falco-src-x86.tar.gz - - No binaries - - `INSTALL` file - - falco-driver-src-x86.tar.gz - - `falco` and `/driver` with `Makefile` - - `INSTALL` file - - falco-driver-download-x86.tar.gz - - `falco` and `falco-driver-loader` download only - - falco-driver-full-x86.tar.gz - - `falco` and `falco-driver-loader` download else compile - - -# Images - -The following convention MUST be used for all container images. - - -_If a container image is for development purproses it MUST have the `dev-` prefix._ - -_If a container image is used to install something, then exit it MUST have the `-install` suffix.*_ - ---- - - - falcosecurity/falco:TAG - - Runs `falco` userspace only - - falcosecurity/falco-driver-loader:TAG - - Runs `falco-driver-loader` and exit - - falcosecurity/priviliged-driver-install-falco - - first runs `falco-driver-loader` then runs `falco` - - falcosecurity/dev-tester:TAG - - Runs the Falco integration test suite - - falcosecurity/dev-builder:TAG - - Contains falco tool chain - - -# Falco Project Evolution - -We will modeling a loosely defined adoption of the Kubernetes and CNCF incubator efforts. - -The criteria will remain loose, and tighten as needed at the discretion of the Falco open source community. - -### contrib - -"_Sandbox level_" - -This new [contrib](https://github.com/falcosecurity/contrib) repository will be equivalent to the `Falco Sandbox` and serves as a place for the community to `test-drive` ideas/projects/code. - -### repository - -"_Incubating level_" projects such as [falco-exporter](https://github.com/falco-exporter) can be promoted from `contrib` to their own repository. - -This is done as needed, and can best be measured by the need to cut a release and use the github release features. Again, this is at the discretion of the Falco open source community. - -### official support - -As the need for a project grows, it can ultimately achieve the highest and most coveted status within The Falco Project. "_Offical support_." - -These artifacts will be ammended to the ones listed above, and will become a part of the official Falco release process. - -# Action - -For each item, ask if this already exists. If so we need to rename, and update it to match this new convention. - - -### Action Items - -Here are SOME of the items that would need to be done for example: - - - Rename `stable` image to `privileged-driver-install-falco` - - Rename `bin` package to `falco-driver-full-x86.tar.gz` - - Rename `slim` image to `falco` - - Documentation in all packages with `INSTALL` file. - - Move everything else to contrib - - Move [/integrations](https://github.com/falcosecurity/falco/tree/master/integrations) to contrib - - Move [/examples](https://github.com/falcosecurity/falco/tree/master/examples) to contrib - - Old docker files - - Old documentation - -### Documentation - -Update documentation in [falco-website#184](https://github.com/falcosecurity/falco-website/pull/184) - -### Adjusting projects - - - Helm chart documentation to be moved to `contrib` - - YAML manifest documentation to be moved to `contrib` - - Minkube, Kind, Puppet, Ansible, etc documentation to be moved to `contrib` - -#### Note: - -This could break the current helm chart, and maybe other dependencies. - -We owe existing users of the Falco project some courtesy if we will break their usage of how Falco has traditionally been advertised. - -Some things we owe the community. - - - Announcement on Falco mailing list - - Issues/Pull Request to Helm chart - - Note: At the very least open an issue and document how to make the existing helm chart work with the new changes if needed. [Nova Volunteers] - - We should at least open a PR and update the helm chart with these new expectations if needed. [Nova Volunteers] - - We should revisit the helm chart OWNERS - - Twitter - - Documentation diff --git a/proposals/20200506-artifacts-scope-part-1.md b/proposals/20200506-artifacts-scope-part-1.md new file mode 100644 index 00000000..51140872 --- /dev/null +++ b/proposals/20200506-artifacts-scope-part-1.md @@ -0,0 +1,114 @@ +# Falco Artifacts Scope - Part 1 + +The **Falco Artifact Scope** proposal is divided in two parts: +1. the Part 1 - *this document*: to “capture” the state of recent changes +2. the [Part 2](./20200506-artifacts-scope-part-2.md): the intended state moving forward + +## Summary + +As a project we would like to support the following artifacts. + +Everything else will be moved to [contrib](https://github.com/falcosecurity/contrib). + +As a project we will build, change, rename, and move files, documents, scripts, configurations according to this new state of the world. + +Inspired from [#1114](https://github.com/falcosecurity/falco/issues/1114) and many of the weekly community calls. + +## Terms + +**falco** + +*Standalone Falco binary* + +**driver** + +*System call provider from the Linux kernel. Either (`bpf`, `module`, or `ptrace`)* + +**falco-driver-loader** + +*The bash script found [here](https://github.com/falcosecurity/falco/blob/master/scripts/falco-driver-loader) that tries to compile else download the driver (kernel module or eBPF probe).* + +**package** + +*An installable artifact that is operating system specific. All packages MUST be hosted on bintray.* + +**image** + +*OCI compliant container image hosted on dockerhub with tags for every release.* + + +# Packages + +List of currently official packages (for x86 64bits only): + +- `falco-x.y.z-x86_64.deb` for debian like systems, it installs the kernel module by default +- `falco-x.y.z-x86_64.rpm` for rpm like systems, it installs the kernel module by default +- `falco-x.y.z-x86_64.tar.gz` for binary installation, it contains `falco` binary, `falco-driver-loader` script and related dependencies + + +# Images + +List of currently official container images (for X86 64bits only): + +| Name | Directory | Description | +|---|---|---| +| [falcosecurity/falco:latest](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:_tag_](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:master](https://hub.docker.com/repository/docker/falcosecurity/falco) | docker/stable | Falco (DEB built from git tag or from the master) with all the building toolchain. | +| [falcosecurity/falco:latest-slim](https://hub.docker.com/repository/docker/falcosecurity/falco), [falcosecurity/falco:_tag_-slim](https://hub.docker.com/repository/docker/falcosecurity/falco),[falcosecurity/falco:master-slim](https://hub.docker.com/repository/docker/falcosecurity/falco) | docker/slim | Falco (DEB build from git tag or from the master) without the building toolchain. | +| [falcosecurity/falco-driver-loader:latest](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader), [falcosecurity/falco-driver-loader:_tag_](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader), [falcosecurity/falco-driver-loader:master](https://hub.docker.com/repository/docker/falcosecurity/falco-driver-loader) | docker/falco-driver-loader | `falco-driver-loader` as entrypoint with the building toolchain. | +| [falcosecurity/falco-builder:latest](https://hub.docker.com/repository/docker/falcosecurity/falco-builder) | docker/builder | The complete build tool chain for compiling Falco from source. See [the documentation](https://falco.org/docs/source/) for more details on building from source. Used to build Falco (CI). | +| [falcosecurity/falco-tester:latest](https://hub.docker.com/repository/docker/falcosecurity/falco-tester) | docker/tester | Container image for running the Falco test suite. Used to run Falco integration tests (CI). | +| _to not be published_ | docker/local | Built on-the-fly and used by falco-tester. | + +**Note**: `falco-builder`, `falco-tester` (and the `docker/local` image that it's built on the fly) are not integrated into the release process because they are development and CI tools that need to be manually pushed only when updated. + + +# Falco Project Evolution + +We will modeling a loosely defined adoption of the Kubernetes and CNCF incubator efforts. + +The criteria will remain loose, and tighten as needed at the discretion of the Falco open source community. + +### contrib + +"_Sandbox level_" + +This new [contrib](https://github.com/falcosecurity/contrib) repository will be equivalent to the `Falco Sandbox` and serves as a place for the community to `test-drive` ideas/projects/code. + +### repository + +"_Incubating level_" projects such as [falco-exporter](https://github.com/falco-exporter) can be promoted from `contrib` to their own repository. + +This is done as needed, and can best be measured by the need to cut a release and use the GitHub release features. Again, this is at the discretion of the Falco open source community. + +### official support + +As the need for a project grows, it can ultimately achieve the highest and most coveted status within The Falco Project. "_Offical support_." + +The artifacts listed above are part of the official Falco release process. These artifact will be refined and amended by the [Part 2](./20200506-artifacts-scope-part-2.md). + +# Action + +The *Part 1* is mainly intended as a cleanup process. +For each item not listed above, ask if it needs to be moved or deleted. +After the cleanup process, all items will match the *Part 1* of this proposal. + + +### Action Items + +Here are SOME of the items that would need to be done, for example: + + - Remove `minimal` from `falco` repository (it's almost similar to `slime`, we don't need two images for the same purpose) + - Rename `driverloader` image to `falco-driver-loader` (since it has not been release yet, we can rename it without breaking things) + - Move everything else to contrib + - Move [/integrations](https://github.com/falcosecurity/falco/tree/master/integrations) to contrib + - Move [/examples](https://github.com/falcosecurity/falco/tree/master/examples) to contrib + - Old documentation + +### Documentation + +Update documentation in [falco-website#184](https://github.com/falcosecurity/falco-website/pull/184). + +### Adjusting projects + + - YAML manifest documentation to be moved to `contrib` + - Minkube, Kind, Puppet, Ansible, etc documentation to be moved to `contrib` \ No newline at end of file diff --git a/proposals/20200506-artifacts-scope-part-2.md b/proposals/20200506-artifacts-scope-part-2.md new file mode 100644 index 00000000..233b01be --- /dev/null +++ b/proposals/20200506-artifacts-scope-part-2.md @@ -0,0 +1,135 @@ +# Falco Artifacts Scope - Part 2 + +The **Falco Artifact Scope** proposal is divided in two parts: +1. the [Part 1](./20200506-artifacts-scope-part-1.md): to “capture” the state of recent changes +2. the Part 2 - *this document*: the intended state moving forward + +## Summary + +See [Part 1](./20200506-artifacts-scope-part-1.md). + +## Terms + +See [Part 1](./20200506-artifacts-scope-part-1.md). + +## Packages + +Official packages for x86 64bits only. + +The following convention MUST be used for all packages. + +_All package names MUST contain a version._ + +_If a package installs the Falco kernel module it MUST contain `module`._ + +_If a package installs the Falco BPF probe it MUST contain `bpf`._ + +_In general, if a package install a Falco driver it MUST contain the driver name._ + + +### .deb + + Falco running in debian like systems that will default to the kernel module. + +- falco-*x.y.z*-x86.deb + - `falco` only (default depends on `falco-module`) + - falco-*x.y.z*-module-x86.deb + - `module` only + - falco-*x.y.z*-bpf-x86.deb + - `bpf` only + - falco-*x.y.z*-ptrace-x86.deb + - `ptrace` only + +N.B.: + +### .rpm + + Falco running in rpm like systems that will default to the kernel module. + +- falco-*x.y.z*-x86.deb + - `falco` only (default depends on `falco-module`) +- falco-*x.y.z*-module-x86.deb + - `module` only +- falco-*x.y.z*-bpf-x86.deb + - `bpf` only +- falco-*x.y.z*-ptrace-x86.deb + - `ptrace` only + + +### .tar.gz + +- falco-bin-x86.tar.gz + - `falco` binary, `falco-loader-script`, and related dependecies + - `INSTALL` file + - `Makefile` file +- falco-src-x86.tar.gz + - No binaries + - `INSTALL` file +- falco-module-src-x86.tar.gz + - `module` sources with `Makefile` + - `INSTALL` file +- falco-bpf-src-x86.tar.gz + - `bpf` sources with `Makefile` + - `INSTALL` file +- falco-ptrace-src-x86.tar.gz + - `ptrace` sources with `Makefile` + - `INSTALL` file + +## Images + +The following convention MUST be used for all container images. + +*TODO* image name conventions + + - falcosecurity/falco:TAG + - Runs `falco` userspace only + - falcosecurity/falco-driver-loader:TAG + - Runs `falco-driver-loader` and exit + - falcosecurity/*TBD** + - First runs `falco-driver-loader` then runs `falco` + - falcosecurity/tester:TAG + - Runs the Falco integration test suite + - falcosecurity/builder:TAG + - Contains falco tool chain + +The image usage MUST be documented in the Dockerfile and in the [website](https://falco.org/docs/). +If an image does not take any action by default, a command usage MUST printed out. + +## Official support + +These artifacts will be amended to the ones listed above, and will become a part of the official Falco release process. + +## Action + +For each item, ask if this already exists. If so we need to rename, and update it to match this new convention. If does not exist, add it. + + +### Action Items + +Here are SOME of the items that would need to be done for example: + + - Rename package accordingly + - Rename docker images accordingly + - Documentation in all packages with `INSTALL` file + - Add `Makefile` where needed + - Implement missing packages + +### Documentation + +Update documentation in [falco-website](https://github.com/falcosecurity/falco-website/) + +#### Note: + +This could break the current helm chart, and maybe other dependencies. + +We owe existing users of the Falco project some courtesy if we will break their usage of how Falco has traditionally been advertised. + +Some things we owe the community. + + - Announcement on Falco mailing list + - Issues/Pull Request to Helm chart + - Note: At the very least open an issue and document how to make the existing helm chart work with the new changes if needed. [Nova Volunteers] + - We should at least open a PR and update the helm chart with these new expectations if needed. [Nova Volunteers] + - We should revisit the helm chart OWNERS + - Twitter + - Documentation \ No newline at end of file