kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-14 10:30:59 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

update docs site

Browse Source
This commit is contained in:
Phillip Wittrock
2020-11-11 08:30:00 -08:00
parent 71b763888c
commit afff3ce5ab
49 changed files with 197 additions and 7846 deletions
Download Patch File Download Diff File Expand all files Collapse all files

358
docs/api-reference/glossary/index.html
View File

@@ -702,37 +702,6 @@
<nav id="TableOfContents">
<ul>
<li><a href="#application">application</a></li>
<li><a href="#apply">apply</a></li>
<li><a href="#base">base</a></li>
<li><a href="#bespoke-configuration">bespoke configuration</a></li>
<li><a href="#custom-resource-definition">custom resource definition</a></li>
<li><a href="#declarative-application-management">declarative application management</a></li>
<li><a href="#generator">generator</a></li>
<li><a href="#gitops">gitops</a></li>
<li><a href="#kustomization">kustomization</a></li>
<li><a href="#kustomization-root">kustomization root</a></li>
<li><a href="#kubernetes">kubernetes</a></li>
<li><a href="#kubernetes-style-object">kubernetes-style object</a></li>
<li><a href="#kustomize">kustomize</a></li>
<li><a href="#off-the-shelf-configuration">off-the-shelf configuration</a></li>
<li><a href="#overlay">overlay</a></li>
<li><a href="#package">package</a></li>
<li><a href="#patch">patch</a></li>
<li><a href="#patchstrategicmerge">patchStrategicMerge</a></li>
<li><a href="#patchjson6902">patchJson6902</a></li>
<li><a href="#plugin">plugin</a></li>
<li><a href="#resource">resource</a></li>
<li><a href="#root">root</a></li>
<li><a href="#sub-target--sub-application--sub-package">sub-target / sub-application / sub-package</a></li>
<li><a href="#target">target</a></li>
<li><a href="#transformer">transformer</a></li>
<li><a href="#variant">variant</a></li>
</ul>
</nav>
</div>
@@ -769,331 +738,6 @@
<h1>Glossary</h1>
<div class="lead">Glossary of terms</div>
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/references/kustomize/glossary/" />
<h1 id="glossary">Glossary</h1>
<h2 id="application">application</h2>
<p>An <em>application</em> 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.
<a href="#resource">Resource</a> labelling, naming and metadata schemes have
historically served to group resources together for
collective operations like <em>list</em> and <em>remove</em>.</p>
<p>This <a href="https://github.com/kubernetes/community/pull/1629">proposal</a> describes a new k8s resource called
<em>application</em> to more formally describe this idea and
provide support for application-level operations and
dashboards.</p>
<p><a href="#kustomize">kustomize</a> configures k8s resources, and the proposed
application resource is just another resource.</p>
<h2 id="apply">apply</h2>
<p>The verb <em>apply</em> in the context of k8s refers to a
kubectl command and an in-progress <a href="https://goo.gl/UbCRuf">API
endpoint</a> for mutating a
cluster.</p>
<p>One <em>applies</em> a statement of what one wants to a
cluster in the form of a complete resource list.</p>
<p>The cluster merges this with the previously applied
state and the actual state to arrive at a new desired
state, which the cluster&rsquo;s reconciliation loop attempts
to create. This is the foundation of level-based state
management in k8s.</p>
<h2 id="base">base</h2>
<p>A <em>base</em> is a <a href="#kustomization">kustomization</a> referred to
by some other <a href="#kustomization">kustomization</a>.</p>
<p>Any kustomization, including an <a href="#overlay">overlay</a>, can be a base to
another kustomization.</p>
<p>A base has no knowledge of the overlays that refer to it.</p>
<p>For simple <a href="#gitops">gitops</a> management, a base configuration
could be the <em>sole content of a git repository
dedicated to that purpose</em>. Same with <a href="#overlay">overlays</a>.
Changes in a repo could generate a build, test and
deploy cycle.</p>
<h2 id="bespoke-configuration">bespoke configuration</h2>
<p>A <em>bespoke</em> configuration is a <a href="#kustomization">kustomization</a> and some
<a href="#resource">resources</a> created and maintained internally by some
organization for their own purposes.</p>
<p>The <a href="/kustomize/guides">workflow</a> associated with a <em>bespoke</em> config is
simpler than the workflow associated with an
<a href="#off-the-shelf-configuration">off-the-shelf</a> config, because there&rsquo;s no notion of
periodically capturing someone else&rsquo;s upgrades to the
<a href="#off-the-shelf-configuration">off-the-shelf</a> config.</p>
<h2 id="custom-resource-definition">custom resource definition</h2>
<p>One can extend the k8s API by making a
Custom Resource Definition (<a href="https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/">CRD spec</a>).</p>
<p>This defines a custom <a href="#resource">resource</a> (CD), an entirely
new resource that can be used alongside <em>native</em>
resources like ConfigMaps, Deployments, etc.</p>
<p>Kustomize can customize a CD, but to do so
kustomize must also be given the corresponding CRD
so that it can interpret the structure correctly.</p>
<h2 id="declarative-application-management">declarative application management</h2>
<p>Kustomize aspires to support <a href="https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md">Declarative Application Management</a>,
a set of best practices around managing k8s clusters.</p>
<p>In brief, kustomize should</p>
<ul>
<li>Work with any configuration, be it bespoke,
off-the-shelf, stateless, stateful, etc.</li>
<li>Support common customizations, and creation of
<a href="#variant">variants</a> (e.g. <em>development</em> vs.
<em>staging</em> vs. <em>production</em>).</li>
<li>Expose and teach native k8s APIs, rather than
hide them.</li>
<li>Add no friction to version control integration to
support reviews and audit trails.</li>
<li>Compose with other tools in a unix sense.</li>
<li>Eschew crossing the line into templating, domain
specific languages, etc., frustrating the other
goals.</li>
</ul>
<h2 id="generator">generator</h2>
<p>A generator makes resources that can be used as is,
or fed into a <a href="#transformer">transformer</a>.</p>
<h2 id="gitops">gitops</h2>
<p>Devops or CICD workflows that use a git repository as a
single source of truth and take action (e.g., build,
test or deploy) when that truth changes.</p>
<h2 id="kustomization">kustomization</h2>
<p>The term <em>kustomization</em> refers to a
<code>kustomization.yaml</code> file, or more generally to a
directory (the <a href="#kustomization-root">root</a>) containing the
<code>kustomization.yaml</code> file and all the relative file
paths that it immediately references (all the local
data that doesn&rsquo;t require a URL specification).</p>
<p>I.e. if someone gives you a <em>kustomization</em> for use
with <a href="#kustomize">kustomize</a>, it could be in the form of</p>
<ul>
<li>one file called <code>kustomization.yaml</code>,</li>
<li>a tarball (containing that YAML file plus what it references),</li>
<li>a git archive (ditto),</li>
<li>a URL to a git repo (ditto), etc.</li>
</ul>
<p>A kustomization file contains <a href="fields.md">fields</a>
falling into four categories:</p>
<ul>
<li>
<p><em>resources</em> - what existing <a href="#resource">resources</a> are to be customized.
Example fields: <em>resources</em>, <em>crds</em>.</p>
</li>
<li>
<p><em>generators</em> - what <em>new</em> resources should be created.
Example fields: <em>configMapGenerator</em> (legacy),
<em>secretGenerator</em> (legacy), <em>generators</em> (v2.1).</p>
</li>
<li>
<p><em>transformers</em> - what to <em>do</em> to the aforementioned resources.
Example fields: <em>namePrefix</em>, <em>nameSuffix</em>, <em>images</em>,
<em>commonLabels</em>, <em>patchesJson6902</em>, etc. and the more
general <em>transformers</em> (v2.1) field.</p>
</li>
<li>
<p><em>meta</em> - fields which may influence all or some of
the above. Example fields: <em>vars</em>, <em>namespace</em>,
<em>apiVersion</em>, <em>kind</em>, etc.</p>
</li>
</ul>
<h2 id="kustomization-root">kustomization root</h2>
<p>The directory that immediately contains a
<code>kustomization.yaml</code> file.</p>
<p>When a kustomization file is processed, it may or may
not be able to access files outside its root.</p>
<p>Data files like resource YAML files, or text files
containing <em>name=value</em> pairs intended for a ConfigMap
or Secret, or files representing a patch to be used in
a patch transformation, must live <em>within or below</em> the
root, and as such are specified via <em>relative
paths</em> exclusively.</p>
<p>A special flag (in v2.1), <code>--load_restrictions none</code>,
is provided to relax this security feature, to, say,
allow a patch file to be shared by more than one
kustomization.</p>
<p>Other kustomizations (other directories containing a
<code>kustomization.yaml</code> file) may be referred to by URL, by
absolute path, or by relative path.</p>
<p>If kustomization <strong>A</strong> depends on kustomization <strong>B</strong>, then</p>
<ul>
<li><strong>B</strong> may not <em>contain</em> <strong>A</strong>.</li>
<li><strong>B</strong> may not <em>depend on</em> <strong>A</strong>, even transitively.</li>
</ul>
<p><strong>A</strong> may contain <strong>B</strong>, but in this case it might be
simplest to have <strong>A</strong> directly depend on <strong>B</strong>&rsquo;s
resources and eliminate <strong>B</strong>&rsquo;s kustomization.yaml file
(i.e. absorb <strong>B</strong> into <strong>A</strong>).</p>
<p>Conventionally, <strong>B</strong> is in a directory that&rsquo;s sibling
to <strong>A</strong>, or <strong>B</strong> is off in a completely independent
git repository, referencable from any kustomization.</p>
<p>A common layout is</p>
<blockquote>
<pre><code>├── base
│   ├── deployment.yaml
│   ├── kustomization.yaml
│   └── service.yaml
└── overlays
├── dev
│   ├── kustomization.yaml
│   └── patch.yaml
├── prod
│   ├── kustomization.yaml
│   └── patch.yaml
└── staging
├── kustomization.yaml
└── patch.yaml
</code></pre></blockquote>
<p>The three roots <code>dev</code>, <code>prod</code> and <code>staging</code>
(presumably) all refer to the <code>base</code> root. One would
have to inspect the <code>kustomization.yaml</code> files to be
sure.</p>
<h2 id="kubernetes">kubernetes</h2>
<p><a href="https://kubernetes.io">Kubernetes</a> is an open-source
system for automating deployment, scaling, and
management of containerized applications.</p>
<p>It&rsquo;s often abbreviated as <em>k8s</em>.</p>
<h2 id="kubernetes-style-object">kubernetes-style object</h2>
<p>An object, expressed in a YAML or JSON file, with the
<a href="https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields">fields required</a> by kubernetes. Basically just a
<em>kind</em> field to identify the type, a <em>metadata/name</em>
field to identify the particular instance, and an
<em>apiVersion</em> field to identify the version (if there&rsquo;s
more than one version).</p>
<h2 id="kustomize">kustomize</h2>
<p><em>kustomize</em> is a command line tool supporting
template-free, structured customization of declarative
configuration targeted to k8s-style objects.</p>
<p><em>Targeted to k8s means</em> that kustomize has some
understanding of API resources, k8s concepts like
names, labels, namespaces, etc. and the semantics of
resource patching.</p>
<p>kustomize is an implementation of <a href="#declarative-application-management">DAM</a>.</p>
<h2 id="off-the-shelf-configuration">off-the-shelf configuration</h2>
<p>An <em>off-the-shelf</em> configuration is a kustomization and
resources intentionally published somewhere for others
to use.</p>
<p>E.g. one might create a github repository like this:</p>
<blockquote>
<pre><code>github.com/username/someapp/
kustomization.yaml
deployment.yaml
configmap.yaml
README.md
</code></pre></blockquote>
<p>Someone could then <em>fork</em> this repo (on github) and
<em>clone</em> their fork to their local disk for
customization.</p>
<p>This clone could act as a <a href="#base">base</a> for the user&rsquo;s
own <a href="#overlay">overlays</a> to do further customization.</p>
<h2 id="overlay">overlay</h2>
<p>An <em>overlay</em> is a kustomization that depends on
another kustomization.</p>
<p>The <a href="#kustomization">kustomizations</a> an overlay refers to (via file
path, URI or other method) are called <a href="#base">bases</a>.</p>
<p>An overlay is unusable without its bases.</p>
<p>An overlay may act as a base to another overlay.</p>
<p>Overlays make the most sense when there is <em>more than
one</em>, because they create different <a href="#variant">variants</a> of a
common base - e.g. <em>development</em>, <em>QA</em>, <em>staging</em> and
<em>production</em> environment variants.</p>
<p>These variants use the same overall resources, and vary
in relatively simple ways, e.g. the number of replicas
in a deployment, the CPU to a particular pod, the data
source used in a ConfigMap, etc.</p>
<p>One configures a cluster like this:</p>
<blockquote>
<pre><code> kustomize build someapp/overlays/staging |\
kubectl apply -f -
kustomize build someapp/overlays/production |\
kubectl apply -f -
</code></pre></blockquote>
<p>Usage of the base is implicit - the overlay&rsquo;s
kustomization points to the base.</p>
<p>See also <a href="#kustomization-root">root</a>.</p>
<h2 id="package">package</h2>
<p>The word <em>package</em> has no meaning in kustomize, as
kustomize is not to be confused with a package
management tool in the tradition of, say, <a href="https://en.wikipedia.org/wiki/APT_(Debian)">apt</a> or
<a href="https://en.wikipedia.org/wiki/Rpm_(software)">rpm</a>.</p>
<h2 id="patch">patch</h2>
<p>General instructions to modify a resource.</p>
<p>There are two alternative techniques with similar
power but different notation - the
<a href="#patchstrategicmerge">strategic merge patch</a>
and the <a href="#patchjson6902">JSON patch</a>.</p>
<h2 id="patchstrategicmerge">patchStrategicMerge</h2>
<p>A <em>patchStrategicMerge</em> is <a href="https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md">strategic-merge</a>-style patch (SMP).</p>
<p>An SMP looks like an incomplete YAML specification of
a k8s resource. The SMP includes <code>TypeMeta</code>
fields to establish the group/version/kind/name of the
<a href="#resource">resource</a> to patch, then just enough remaining fields
to step into a nested structure to specify a new field
value, e.g. an image tag.</p>
<p>By default, an SMP <em>replaces</em> values. This is
usually desired when the target value is a simple
string, but may not be desired when the target
value is a list.</p>
<p>To change this
default behavior, add a <em>directive</em>. Recognized
directives in YAML patches are <em>replace</em> (the default)
and <em>delete</em> (see <a href="https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md">these notes</a>).</p>
<p>Note that for custom resources, SMPs are treated as
<a href="https://tools.ietf.org/html/rfc7386">json merge patches</a>.</p>
<p>Fun fact - any resource file can be used as
an SMP, overwriting matching fields in another
resource with the same group/version/kind/name,
but leaving all other fields as they were.</p>
<p>TODO(monopole): add ptr to example.</p>
<h2 id="patchjson6902">patchJson6902</h2>
<p>A <em>patchJson6902</em> refers to a kubernetes <a href="#resource">resource</a> and
a <a href="https://tools.ietf.org/html/rfc6902">JSONPatch</a> specifying how to change the resource.</p>
<p>A <em>patchJson6902</em> can do almost everything a
<em>patchStrategicMerge</em> can do, but with a briefer
syntax. See this <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/examples/jsonpatch.md">example</a>.</p>
<h2 id="plugin">plugin</h2>
<p>A chunk of code used by kustomize, but not necessarily
compiled into kustomize, to generate and/or transform a
kubernetes resource as part of a kustomization.</p>
<p>Details <a href="../../guides/plugins">here</a>.</p>
<h2 id="resource">resource</h2>
<p>A <em>resource</em> in the context of a REST-ful API is the
target object of an HTTP operation like <em>GET</em>, <em>PUT</em> or
<em>POST</em>. k8s offers a REST-ful API surface to interact
with clients.</p>
<p>A <em>resource</em>, in the context of a kustomization, is a
<a href="#kustomization-root">root</a> relative path to a <a href="http://www.yaml.org/start.html">YAML</a> or <a href="https://www.json.org/">JSON</a> file
describing a k8s API object, like a Deployment or a
ConfigMap, or it&rsquo;s a path to a kustomization, or a URL
that resolves to a kustomization.</p>
<p>More generally, a resource can be any correct YAML file
that <a href="https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields">defines an object</a>
with a <em>kind</em> and a <em>metadata/name</em> field.</p>
<h2 id="root">root</h2>
<p>See <a href="#kustomization-root">kustomization root</a>.</p>
<h2 id="sub-target--sub-application--sub-package">sub-target / sub-application / sub-package</h2>
<p>A <em>sub-whatever</em> is not a thing. There are only
<a href="#base">bases</a> and <a href="#overlay">overlays</a>.</p>
<h2 id="target">target</h2>
<p>The <em>target</em> is the argument to <code>kustomize build</code>, e.g.:</p>
<blockquote>
<pre><code> kustomize build $target
</code></pre></blockquote>
<p><code>$target</code> must be a path or a url to a <a href="#kustomization">kustomization</a>.</p>
<p>The target contains, or refers to, all the information
needed to create customized resources to send to the
<a href="#apply">apply</a> operation.</p>
<p>A target can be a <a href="#base">base</a> or an <a href="#overlay">overlay</a>.</p>
<h2 id="transformer">transformer</h2>
<p>A transformer can modify a resource, or merely
visit it and collect information about it in the
course of a <code>kustomize build</code>.</p>
<h2 id="variant">variant</h2>
<p>A <em>variant</em> is the outcome, in a cluster, of applying
an <a href="#overlay">overlay</a> to a <a href="#base">base</a>.</p>
<p>E.g., a <em>staging</em> and <em>production</em> overlay both modify
some common base to create distinct variants.</p>
<p>The <em>staging</em> variant is the set of resources exposed
to quality assurance testing, or to some external users
who&rsquo;d like to see what the next version of production
will look like.</p>
<p>The <em>production</em> variant 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.</p>
<div class="section-index">
@@ -1149,7 +793,7 @@ cpu and memory requests.</p>
<div class="text-muted mt-5 pt-3 border-top">Last modified November 4, 2020: <a href="https://github.com/kubernetes-sigs/kustomize/commit/0834e152b203ffeccfbbf1ddd3c1f49debdac341">Redirect kustomize docs to the new unified site. (0834e152)</a>
<div class="text-muted mt-5 pt-3 border-top">Last modified November 11, 2020: <a href="https://github.com/kubernetes-sigs/kustomize/commit/71b763888cad614abb44b3086e291fe72d601080">Remove duplicate kustomize docs content (71b76388)</a>
</div>
</div>