(docs): Update plain bundle docs #642
Conversation
everettraven
force-pushed
the
docs/build-plain-bundle
branch
from
fb11ae6
to
b1eec41
Compare
|
/lgtm |
docs/bundles/plain.md
Outdated
| * An [upload](../sources/upload.md) | ||
| * A `.tgz` file returned by a [http endpoint](../sources/http.md) | ||
|
|
||
| Additional source types (such as a local volume or a generic URI-based resource) are on the roadmap. These source types all present the same content: a directory containing static Kubernetes YAML manifests |
There was a problem hiding this comment.
I would drop this line. There's nothing on the immediate roadmap at this point AFAIK.
There was a problem hiding this comment.
Removed in 56cfbae
docs/bundles/plain.md
Outdated
| @@ -29,16 +58,123 @@ manifests | |||
| └── deployment.yaml | |||
| ``` | |||
|
|
|||
| For a bundle `git` repo, any directory that contains only static Kubernetes manifests checked into a `git` repository | |||
There was a problem hiding this comment.
I don't think this is quite true. A plain bundle must have a manifests directory (yes, specifically named manifests) at its root. So it can't be any directory. The bundle root directory has to contain a manifests directory.
There was a problem hiding this comment.
TBH, I don't think I'd talk about the source types here though. The bundle format and the sourcing mechanism are completely decoupled in the rukpak design.
There was a problem hiding this comment.
Removed it in 56cfbae
docs/bundles/plain.md
Outdated
| * The static manifests must be located in the root-level `/manifests` directory in a bundle image for the bundle to be a | ||
| valid `plain+v0` bundle that the provisioner can unpack. A plain bundle image without a `/manifests` directory is | ||
| invalid and will not be successfully unpacked onto the cluster. | ||
| * For a bundle `git` repo, the manifests directory can be anywhere in the repository, not just at the root-level. The | ||
| location can be specified via `spec.source.git.directory`. There must be a flat directory consisting of Kubernetes YAML manifests at the provided location in order to have a valid bundle git repo. If a specific directory is not provided, it is assumed to be `./manifests` in a bundle git repo. | ||
| * The manifests directory should be flat: all manifests should be at the top-level with no subdirectories. | ||
| * Including any content in the /manifests directory of a plain bundle that is not static manifests will result in | ||
| a failure when creating content on-cluster from that bundle. Essentially, any file that would not | ||
| successfully `kubectl apply` will result in an error, but multi-object YAML files, or JSON files, are fine. There will | ||
| be validation tooling provided that can determine whether a given artifact is a valid bundle. No newline at end of file | ||
| * The plain bundle image can be built from any base image, but `scratch` is recommended as it keeps the resulting bundle | ||
| image a minimal size. | ||
| * It is required that `kubectl apply` is able to process all .yaml files in the directory that make up a plain bundle. For example, multi-object YAML files are acceptable, but Ansible playbooks would not be. |
There was a problem hiding this comment.
I would try to rewrite these to be focused on the contents of a plain bundle root directory, and not at all aware of the source implementation. Then the source docs should talk about the specifics of handing a bundle root off to a provisioner.
There was a problem hiding this comment.
Let me know if 56cfbae suffices
|
New changes are detected. LGTM label has been removed. |
Codecov Report
@@ Coverage Diff @@
## main #642 +/- ##
=======================================
Coverage ? 31.94%
=======================================
Files ? 10
Lines ? 479
Branches ? 0
=======================================
Hits ? 153
Misses ? 304
Partials ? 22 |
Signed-off-by: Bryce Palmer <[email protected]>
everettraven
force-pushed
the
docs/build-plain-bundle
branch
from
9108f8b
to
dc82bb6
Compare
Description
docs/concepts/plain-bundle-spec.mdin favor of moving its contents todocs/bundles/plain.md(IMO a more intuitive location to find information on plain bundles)docs/concepts/plain-bundle-spec.mdwith a section titleBuilding a plain bundlethat includes information about how to build a plain bundle for use with all the various source types that rukpak supportsMotivation