Add a readme

README.md

@@ -0,0 +1,112 @@
+# Tape is for packaging applications
+
+## What is Tape?
+
+Tape is a tool that can package an entire application as a self-contained (taped) OCI image that can be deployed to a
+Kubernetes cluster. A taped OCI image contains all application components and Kubernetes resources required to run all
+of the components together.
+
+## What problem does it solve?
+
+> TL;DR - Tape reduces complexity of building and deploying applications to Kubernetes with entire applications
+> distributed as OCI images.
+
+The process of building and deploying an application to Kubernetes is highly fragmented. There are many choices that
+one has to navigate, starting with the design of a CI pipeline, Dockerfiles, use of OCI registry, mapping of revisions
+to image tags, rules of deployment based around tags, promotion between environments, as well as various kinds of ways
+to manage Kubernetes configs and how these configs get deployed to any particular cluster.
+Even with an assumption that some of these steps are of essential complexity, like assuming that all CI pipelines will
+be different and everyone wants to use their favourite tool, the fragmented view of the world doesn't cater well for
+collaboration between organisations that have made different choices, despite all using OCI images and Kubernetes APIs.
+To illustrate this, let's ask ourselves - "Why should there be any difference in the mechanics of how my application is
+deployed to a Kubernetes cluster vs. someone else's application being deployed to the same cluster?".
+Of course, it comes down to Kubernetes API resources, but there is often a lot that happens in between. Sometimes Helm
+is used, sometimes it's Kustomize, and some folks prefer to use plain manifests and create bespoke automation around
+their configs stored in Git, some folks do an entirely different thing. There are indeed many choices here. The problem
+is that the knowledge of what the choices are exactly and how some well-known tools might be used is not trivial or
+automatically transferable.
+
+Tape addresses the complexity by using OCI for the distribution of runnable code as well configuration required to run it
+correctly on Kubernetes. More specifically, it introduces a notion of application artifact without introducing any particular
+model of how components are composed into an artifact. This model aims to be a layer of interoperability between different
+tools and provide a logical supply chain entry point and location for storing metadata.
+
+The best analogy is flatpack furniture. Presently, deployment of an application is as if flatpack hasn't been invented, so
+when someone orders a wooden cabinet, all that arrives in a box is just the pieces of wood, they have to shop for nuts,
+bolts and tools. Of course, that might be desirable for some, as they have a well-stocked workshop with the best tools and
+a decent selection of nuts and bolts. But did the box even include assembly instructions with the list of nuts and bolts
+one has to buy?
+That model doesn't scale to the consumer market. Of course, some consumers might have a toolbox, but very few will be able
+to find the right nuts and bolts or even bother looking for any, they might just send the whole box back instead.
+A taped image is like a flatpack package, it has everything needed as well as assembly instructions, without introducing
+new complexity elsewhere and allows users to keep using their favourite tools.
+
+## How does Tape work?
+
+> NB: this describes current implementation that is very minimal and doesn't achieve all of the abitious goals as
+> described above, namely it works only with plain YAML and JSON manifests and doesn't yet have key integrations,
+> e.g. with Helm or other tools.
+
+Tape can parse a directory with Kubernetes configuration and find all canonical references to application images.
+Namely, it looks for paths like `spec.containers[].image`.
+If an image reference contains a digest, Tape will use it, otherwise it resolves it by making a registry API call.
+For each of the images, Tape searches of all well-known related tags, such as external signatures, attestations and
+SBOMs. Tape will make a copy of every application image and any tags related to it to a registry the user has specified.
+Once images are copied, it updates manifests with new references and bundles the result in an OCI artifact pushed to
+the same repo in the registry.
+
+Copying of all application images and referencing by digest is performed to ensure the application and its configuration
+are tightly coupled together to provide a single link in the supply chain as well as a single point of distribution
+and access control for the whole application.
+
+Tape also checks VCS provenance of manifests, so if any manifest files are checked in Git, Tape will attest to what
+Git repository each file came from, all of the revision metadata and whether it's been modified or not.
+Additionally, Tape attests to all key steps that it performs, e.g. original image references it detects and manifest
+checksums. It stores the attestations using in-toto format in an OCI artifact.
+
+## Usage
+
+Tape has the following commands:
+
+- `tape images` - examine a given set of manifests before packaging them
+- `tape package`- package the application and push the resulting self-contained image to a registry
+
+## Roadmap & FAQ
+
+### What configuration formats does Tape support, does it support any kind of templating?
+
+Presently, it supports plain JSON and YAML manifest. In the future, the goal is to accommodate a variety of popular
+templating options, e.g. CUE, Helm and scripting languages, so that environment-specific parameters can be specified.
+It may also support basic runtime overrides with or without templating e.g. for namespaces and labels.
+It should also offer flexibility around templating at buildtime, runtime or done partially buildtime/runtime.
+
+### How does Tape relate to existing tools?
+
+Many existing tools in this space help with some aspects of handling Kubernetes resources. These tools operate on
+either loosely coupled collections of resouces (like Kustomize), or opinionated application package formats (most
+notably Helm). One of the goals of Tape is to abstract the use of any tools that already exist while paving the way
+for innovation. Tape will attempt to integrate with most of the popular tools, and enable anyone to deploy applications
+from taped images without having to know if under the hood it will use Kustomize, Helm, just plain manifest or something
+else entirely. The other goal is that users won't need to know about Tape either, perhaps someday `kubectl apply` could
+support OCI artifacts and there could be different ways of building the artifacts.
+
+### What kind of applications can Tape package?
+
+Tape doesn't infer an opinion of how the application is structured, namely what it consists of or doesn't consist of. It doesn't
+present any application definition format, it operates on plain Kubernetes manifests found in a directory.
+
+### Does Tape provide SBOMs?
+
+It doesn't create new SBOMs at the moment, but it may cater to this use case in the future.
+
+## Acknowledgments & Prior Art
+
+What Tape does is very much in the spirit of Docker images, but it extends the idea by shifting the perspective to configuration
+as an entry point to a map of dependencies, as opposed to forced separation of app images and configuration.
+
+It's not a novelty to package configuration in OCI, there exist many examples of this practice, but there is no interoperability.
+Tape's ambition is to commoditise the model and abstract configuration tooling, so that end-users don't need to think whether a
+particular app needs to be deployed with Helm, Kustomize or something else.
+
+Tape was directly inspired by [flux push artifact](https://fluxcd.io/flux/cheatsheets/oci-artifacts/). Incidentally, it also resembles
+some of the aspects of CNAB, but it is much smaller in scope.