8.0 KiB
Glossary
application
An application is a group of k8s resources related by some common purpose, e.g. a load balancer in front of a webserver backed by a database.
Resource labelling, naming and metadata schemes have historically served to group resources together for collective operations like list and remove.
This proposal describes a new k8s resource called application to more formally describe this idea and provide support for application-level operations and dashboards.
kinflate configures k8s resources, and the proposed
application resource is just another resource. There's
some conceptual overlap between the proposal’s
application resource and the kinflate manifest. The
application resource has a Components field that
serves a purpose similar to the resources field in
the kinflate manifest. This overlap can be resolved in
various ways, the simplest being that kinflate does
nothing special with the application resource.
apply
The verb apply in the context of k8s refers to a kubectl command and an in-progress API endpoint for mutating a cluster.
One applies a statement of what one wants to a cluster (in the form of a complete resource list), and the cluster merges this with the previously applied state and the actual state to arrive at a new desired state, which the cluster's reconcilation loop attempts to create. This is the foundation of level-based state management in k8s.
base
A base is a target that some overlay modifies.
Any target, including an overlay, can be a base to another target.
A base has no knowledge of the overlays that refer to it.
A base should be usable in isolation, i.e. one should be able to apply a base to a cluster directly.
bespoke configuration
A bespoke configuration is a manifest and some resources created and maintained internally by some organization for their own purposes.
The workflow associated with a bespoke config is simpler than the workflow associated with an off-the-shelf config, because there's no notion of periodically capturing someone else's upgrades to the off-the-shelf config.
declarative application management
Declarative Application Management (DAM) is a set of ideas aiming to ease management of k8s clusters.
- Works with any configuration, be it bespoke, off-the-shelf, stateless, stateful, etc.
- Supports common customizations, and creation of instance variants (dev vs, staging vs. production).
- Exposes and teaches native k8s APIs, rather than hiding them.
- No friction integration with version control to support reviews and audit trails.
- Composable with other tools in a unix sense.
- Eschews crossing the line into templating, domain specific languages, etc., frustrating the other goals.
instance
An instance is the outcome, in a cluster, of applying an overlay to a base.
Roughly synonymous with overlay.
For example, a staging and production overlay both modify some common base to create distinct instances.
The staging instance is the set of resources exposed to quality assurance testing, or to some external users who'd like to see what the next version of production will look like.
The production instance is the set of resources exposed to production traffic, and thus may employ deployments with a large number of replicas and higher cpu and memory requests.
kinflate
kinflate is a command line tool supporting template-free customization of declarative configuration targetted to k8s.
Targetted to k8s means that kinflate may need some limited understanding of API resources, k8s concepts like names, labels, namespaces, etc. and the semantics of resource patching.
kinflate is an implementation of DAM.
manifest
A manifest is a file called Kube-manifest.yaml that
describes a configuration consumable by kinflate.
A manifest contains fields falling into these categories:
- Immediate customization instructions - nameprefix, labelprefix, etc.
- Resource generators for configmaps and secrets.
- Cargo - names of external files in these categories:
- (TBD) Standard k8s API kind-version fields.
off-the-shelf configuration
An off-the-shelf configuration is a manifest and resources intentionally published somewhere for others to use.
E.g. one might create a github repository like this:
github.com/kinflate/ldap/ Kube-manifest.yaml deployment.yaml configmap.yaml README.md
Someone could then fork this repo (on github) and clone their fork to their local disk for customization.
This clone could act as a base for the user's own overlays to do further customization.
overlay
An overlay is a target that modifies (and thus depends on) another target.
The manifest in an overlay refers to (via file path, URI or other method) to some other manifest, known as its base. An overlay is unusable without its base.
An overlay supports the typical notion of a development, QA, staging and production environment instances.
The configuration of these environments is specified in individual overlays (one per environment) that all refer to a common base that holds common configuration. One configures the cluser like this:
kinflate inflate -f ldap/overlays/staging | kubectl apply -f - kinflate inflate -f ldap/overlays/production | kubectl apply -f -
Usage of the base is implicit (the overlay's manifest points to the base).
An overlay may act as a base to another overlay.
package
The word package has no meaning in kinflate, as kinflate is not to be confused with a package management tool in the tradition of, say, apt or rpm.
patch
A patch is a partially defined k8s resource with a name that must match a resource already known per traversal rules built into kinflate.
Patch is a field in the manifest, distinct from resources, because a patch file looks like a resource file, but has different semantics. A patch depends on (modifies) a resource, whereas a resourse has no dependencies. Since any resource file can be used as a patch, one cannot reliably distinguish a resource from a patch just by looking at the file's YAML.
resource
A resource is a path to a YAML or JSON file that completely defines a functional k8s API object.
sub-target / sub-application / sub-package
A sub-whatever is not a thing. There are only bases and overlays.
target
The target is the argument to inflate, e.g.:
kinflate inflate -f $target | kubectl apply -f -
$target must be
- a file path ending with
Kube-manifest.yaml(i.e. a manifest), - a directory that immediately contains a file with that name,
- a URI that resolves to some file or directory on the web (e.g. a github repo) meeting the aforemention conditions.
The target contains, or points to, all the information needed to create customized resources to send to the apply operation.