mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-05-17 18:25:26 +00:00
Merge pull request #3924 from monopole/architecture
Add ARCHITECTURE.md
This commit is contained in:
Kubernetes Prow Robot
299
ARCHITECTURE.md
Normal file
299
ARCHITECTURE.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# Architecture
|
||||
|
||||
* _Updated: December 2021_
|
||||
|
||||
This document describes the repository organization and the kustomize
|
||||
build process. It's meant to lower the barrier to learning and
|
||||
contributing to the code base.
|
||||
|
||||
If not kept up to date, it will just be a historical snapshot.
|
||||
|
||||
|
||||
## Repository layout
|
||||
|
||||
[human-edited docs]: https://github.com/kubernetes-sigs/cli-experimental/tree/master/site
|
||||
[generated docs]: https://github.com/kubernetes-sigs/cli-experimental/tree/master/docs
|
||||
[rendered docs]: https://kubectl.docs.kubernetes.io
|
||||
[openapi]: https://kubernetes.io/blog/2016/12/kubernetes-supports-openapi
|
||||
|
||||
[`api` module]: https://github.com/kubernetes-sigs/kustomize/blob/master/api/go.mod
|
||||
[`api`]: #the-api-module
|
||||
[`cmd/config` module]: https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/go.mod
|
||||
[`cmd/config`]: #the-cmdconfig-module
|
||||
[`kustomize` module]: https://github.com/kubernetes-sigs/kustomize/blob/master/kustomize/go.mod
|
||||
[`kustomize`]: #the-kustomize-module
|
||||
[`kyaml` module]: https://github.com/kubernetes-sigs/kustomize/blob/master/kyaml/go.mod
|
||||
[`kyaml`]: #the-kyaml-module
|
||||
[`kyaml/kio.Filter`]: https://github.com/Kubernetes-sigs/kustomize/blob/master/kyaml/kio/kio.go
|
||||
[`go-yaml`]: https://github.com/go-yaml/yaml/tree/v3
|
||||
|
||||
|
||||
[3922]: https://github.com/kubernetes-sigs/kustomize/issues/3922
|
||||
|
||||
|
||||
|
||||
| directory | purpose |
|
||||
| ---------: | :---------- |
|
||||
| `api` | The [`api`] module, holding high level kustomize code, suitable for import by other programs. |
|
||||
| `cmd` | Various Go programs aiding repo management. See also `hack`. As an outlier, includes the special [`cmd/config`] module. |
|
||||
| `docs` | Old home of documentation; contains pointers to new homes: [human-edited docs], [generated docs] and [rendered docs]. |
|
||||
| `examples` | Full kustomization examples that run as pre-merge tests. |
|
||||
| `functions` | Examples of plugins in KRM function form. TODO([3922]): Move under `plugin`. |
|
||||
| `hack` | Various shell scripts to help with code management. |
|
||||
| `kustomize` | The [`kustomize`] module holds the `main.go` for kustomize. |
|
||||
| `kyaml` | The [`kyaml`] module, holding Kubernetes-specific YAML editing packages used by the [`api`] module. Wraps [`go-yaml`] v3.|
|
||||
| `plugin` | Examples of Kustomize plugins. |
|
||||
| `releasing` | Instructions for releasing the various modules. |
|
||||
| `site` | Old generated documentation, kept to provide redirection links to the new docs. |
|
||||
|
||||
|
||||
## Modules
|
||||
|
||||
[semantically versioned]: https://semver.org
|
||||
[Go modules]: https://github.com/golang/go/wiki/Modules
|
||||
|
||||
The [Go modules] in the kustomize repository are [semantically versioned].
|
||||
|
||||
|
||||
### `kustomize`
|
||||
|
||||
> _Depends on [`api`], [`cmd/config`], [`kyaml`]_
|
||||
|
||||
The [`kustomize` module] contains the `main.go` for `kustomize`, buildable with
|
||||
|
||||
```
|
||||
(cd kustomize; go install .)
|
||||
```
|
||||
|
||||
[appears in kubectl]: https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/kubectl/pkg/cmd/kustomize/kustomize.go
|
||||
|
||||
Below this are packages containing
|
||||
[cobra](http://github.com/spf13/cobra) commands implementing `build`,
|
||||
`edit`, `fix`, etc., packages linked together by `main.go`.
|
||||
|
||||
These command packages are intentionally public, semantically
|
||||
versioned, and can be used in other programs. Specifically, the
|
||||
`kustomize build` command [appears in kubectl] as `kubectl kustomize`.
|
||||
|
||||
The code in the `build` package is dominated by flag validation,
|
||||
with minimal business logic. The critical lines are something
|
||||
like
|
||||
|
||||
```
|
||||
# Make a kustomizer.
|
||||
k := krusty.MakeKustomizer(
|
||||
HonorKustomizeFlags(krusty.MakeDefaultOptions()),
|
||||
)
|
||||
|
||||
# Run the kustomizer, sending location of kustomization.yaml
|
||||
m := k.Run(fSys, "/path/to/dir")
|
||||
|
||||
# Write the result as YAML.
|
||||
writer.Write(m.AsYaml())
|
||||
```
|
||||
|
||||
The `krusty` package is in the [`api`] module.
|
||||
|
||||
### `api`
|
||||
|
||||
> _Depends on [`kyaml`] and code generated from builtin plugin modules_
|
||||
|
||||
The [`api` module] is used by CLI programs like `kustomize` and `kubectl`
|
||||
to read and honor `kustomization.yaml` files and all that implies.
|
||||
|
||||
The main public packages in the [`api` module] are
|
||||
|
||||
| package | |
|
||||
| --------: | :---------- |
|
||||
| `filters` | Implementations of [`kyaml/kio.Filter`] used by kustomize to transform Kubernetes objects. |
|
||||
| `konfig` | Configuration methods and constants in the kustomize API. |
|
||||
| `krusty` | Primary API entry point. Holds the kustomizer and hundreds of tests for it. |
|
||||
| `loader` | Loads kustomization files and the files they refer to, enforcing security rules. |
|
||||
| `resmap` | The primary internal data structure over which the kustomizer and filters work. |
|
||||
| `types` | The `Kustomization` object and ancillary structs. |
|
||||
|
||||
### `cmd/config`
|
||||
|
||||
> _Depends on [`kyaml`]_
|
||||
|
||||
This module contains cobra commands and kyaml-based functionality to
|
||||
provide unix-like file manipulation commands to kustomize like `grep`
|
||||
and `tree`. These commands may be included in any program that
|
||||
manipulates k8s YAML (e.g. kustomize).
|
||||
|
||||
### `kyaml`
|
||||
|
||||
> _Has no in-repo dependence_
|
||||
|
||||
The [`kyaml` module] is a kubernetes-focussed enhancement of [go-yaml].
|
||||
|
||||
The YAML manipulation performed by a kustomize is based on these libraries.
|
||||
|
||||
These libraries evolve independently of kustomize, and other programs depend on them.
|
||||
|
||||
The key public packages in the [`kyaml` module] include
|
||||
|
||||
| package | |
|
||||
| --------: | :---------- |
|
||||
| `errors` | Wrapper for the go-errors/errors lib |
|
||||
| `filesys` | A kustomize-specific file system abstraction, to ease writing tests |
|
||||
| `fn/framework` | An SDK for writing KRM Functions in Go |
|
||||
| `fn/runtime` | Implements the runtime for KRM Function extensions |
|
||||
| `kio` | Libraries for reading and writing collections of Kubernetes resources as RNodes |
|
||||
| `openapi` | Loads and accesses openapi schemas for schema-aware resource manipultaion |
|
||||
| `resid` | Representations to aid in unique identification of Kubernetes resources |
|
||||
| `yaml` | A Kubernetes-focused wrapper of [go-yaml], notably including the RNode object |
|
||||
|
||||
|
||||
-------
|
||||
|
||||
## How _kustomize build_ works
|
||||
|
||||
The command `kustomize build` accepts a single string argument,
|
||||
which must resolve to a directory, possibly in a git repository,
|
||||
called the _kustomization root_.
|
||||
|
||||
This directory must contain a file called `kustomization.yaml`, with
|
||||
YAML that marshals into a single instance of a `Kustomization` object.
|
||||
|
||||
For the remainder of this document, the word _kustomization_ refers to
|
||||
either of these things.
|
||||
|
||||
This kustomization is the access point to a directed, acyclic graph of
|
||||
Kubernetes objects, including other kustomizations, to include in a
|
||||
build.
|
||||
|
||||
Execution of `build` starts and ends in the [`api`] module,
|
||||
frequently dipping into the [`kyaml`] module for lower level
|
||||
YAML manipulation.
|
||||
|
||||
### The `build` flow
|
||||
|
||||
- Validate command lines arguments and flags.
|
||||
|
||||
- Make a `Kustomizer` as a function of those arguments.
|
||||
|
||||
- Call `Run` on the kustomizer, passing it the path to the
|
||||
kustomization.
|
||||
|
||||
`Run` returns an instance of `ResMap`, the `api` package's
|
||||
representation of a set of kubernetes `Resource` objects.
|
||||
|
||||
This structure offers resource lookup methods (map behavior),
|
||||
but also retains the resources in the order they were
|
||||
specified in kustomization files (list behavior).
|
||||
|
||||
Post-run, the objects are fully hydrated, per the
|
||||
instructions in the kustomization.
|
||||
|
||||
- Marshal the objects as YAML to a file or `stdout`.
|
||||
|
||||
|
||||
### The `Run` function
|
||||
|
||||
- Create various objects
|
||||
|
||||
- A `ResMap` factory.
|
||||
|
||||
Makes `ResMaps` from byte streams, other `ResMaps`, etc.
|
||||
|
||||
- A file `loader.Loader`.
|
||||
|
||||
It's fed an appropriate set of restrictions, and the path to the kustomization.
|
||||
|
||||
- A plugin loader.
|
||||
|
||||
It finds plugins (transformers, generators or validators)
|
||||
and prepares them for running.
|
||||
|
||||
- A `KustTarget` encapsulating all of the above.
|
||||
|
||||
A KustTarget contains one `Kustomization` and represents
|
||||
everything that kustomization can reach. This will include
|
||||
other `KustTarget` instances, each having a smaller purview than
|
||||
the one referencing it.
|
||||
|
||||
- Call `KustTarget.Load` to load its kustomization.
|
||||
|
||||
This step deals with deprecations and field changes.
|
||||
|
||||
- Load [openapi] data specified by the kustomization.
|
||||
|
||||
This is needed to recognize k8s kinds and their special
|
||||
properties, e.g. which kinds are cluster-scoped, which kinds
|
||||
refer to others, etc.
|
||||
|
||||
- Call `KustTarget.makeCustomizedResmap` to create the `ResMap` result.
|
||||
|
||||
This visits everything referenced by the kustomization,
|
||||
performing all generation, transformation and validation.
|
||||
|
||||
- Finish the `Run` with
|
||||
|
||||
- Optional reordering of objects in `ResMap`, overriding the
|
||||
FIFO rule.
|
||||
|
||||
- Optional addition of _kustomize build annotations_ to the
|
||||
resources. E.g. from which repo and file the resource was
|
||||
read, the fact that kustomize touched the resource, etc.
|
||||
These kustomize-specific annotations are intended for
|
||||
server-side data analytics, file structure traceability and
|
||||
reconstruction, etc.
|
||||
|
||||
### The `makeCustomizedResmap` function
|
||||
|
||||
This function starts the process of object transformation,
|
||||
as well as accumulation of recursively referenced data.
|
||||
|
||||
- Call `ra := KustTarget.AccumulateTarget`.
|
||||
|
||||
The result, `ra`, is a resource accumulator that contains
|
||||
everything referred to by the current kustomization, now fully
|
||||
hydrated.
|
||||
|
||||
- Uniquify names of generated objects by appending content hashes.
|
||||
|
||||
This cannot be done until the objects are complete.
|
||||
|
||||
- Fix all name references (given that names may have changed).
|
||||
|
||||
E.g. if a ConfigMaps was given a generated name, all objects that
|
||||
refer to that ConfigMap must be given its name.
|
||||
|
||||
- Resolve vars, replacing them with whatever they refer to (a legacy feature).
|
||||
|
||||
### The `AccumulateTarget` function
|
||||
|
||||
- Call `AccumulateResources` over the `resources` field (this can recurse).
|
||||
- Call `AccumulateComponents` over the `components` field (this can recurse),
|
||||
- Load legacy (pre-plugin) global kustomize configuration,
|
||||
- Load legacy (pre-openapi) _Custom Resource Definition_ data.
|
||||
- In the context of the data loaded above, run the kustomization's
|
||||
- generators,
|
||||
- transformers,
|
||||
- and validators.
|
||||
- Accumulate `vars` (make note of them for later replacement).
|
||||
|
||||
### `AccumulateResources` and component accumulation
|
||||
|
||||
- If the path is a file:
|
||||
- Accumulate the objects in the file (treating them
|
||||
as opaque kubernetes objects).
|
||||
|
||||
- If the path is a directory:
|
||||
- Create a new `KustTarget` referring to that directory's kustomization.
|
||||
- Call `subRa := KustTarget.AccumulateTarget`.
|
||||
- Call `ra.MergeAccumulator(subRa)`
|
||||
This completes a recursion.
|
||||
|
||||
- If the path is a git URL:
|
||||
- Clone the repository to a temporary directory.
|
||||
- Process the path optionally specified in the URL
|
||||
as a path in the clone.
|
||||
- If no path specified, work from the repository root.
|
||||
|
||||
|
||||
That's as deep as this discussion will go.
|
||||
|
||||
The deeper this document goes into the details, the faster
|
||||
it will get out of date.
|
||||
Reference in New Issue
Block a user