kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-13 01:50:55 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Convert docs to docsy

Browse Source
This commit is contained in:
Phillip Wittrock
2020-06-07 21:07:46 -07:00
parent 25a38ad2b6
commit 42497c664f
11469 changed files with 816051 additions and 4557 deletions
Download Patch File Download Diff File Expand all files Collapse all files

489
docs/faq/eschewedfeatures/index.html Normal file
View File

@@ -0,0 +1,489 @@
<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="generator" content="Hugo 0.73.0-DEV" />
<META NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW">
<link rel="alternate" type="application/rss&#43;xml" href="https://kubernetes-sigs.github.io/kustomize/faq/eschewedfeatures/index.xml">
<link rel="shortcut icon" href="/favicons/favicon.ico" >
<link rel="apple-touch-icon" href="/kustomize/favicons/apple-touch-icon-180x180.png" sizes="180x180">
<link rel="icon" type="image/png" href="/kustomize/favicons/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="/kustomize/favicons/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-36x36.png" sizes="36x36">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-48x48.png" sizes="48x48">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-72x72.png" sizes="72x72">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-96x96.png" sizes="96x96">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-144x144.png" sizes="144x144">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-192x192.png" sizes="192x192">
<title>Eschewed Features | Kustomize</title><meta property="og:title" content="Eschewed Features" />
<meta property="og:description" content="Eschewed Features
" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/faq/eschewedfeatures/" />
<meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="Eschewed Features">
<meta itemprop="description" content="Eschewed Features
"><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Eschewed Features"/>
<meta name="twitter:description" content="Eschewed Features
"/>
<link rel="preload" href="/kustomize/scss/main.min.818a933df0186c907f1faea6730835dd5fa01c3b53af36bb68396dc80a2d3c45.css" as="style">
<link href="/kustomize/scss/main.min.818a933df0186c907f1faea6730835dd5fa01c3b53af36bb68396dc80a2d3c45.css" rel="stylesheet" integrity="">
<script
src="https://code.jquery.com/jquery-3.3.1.min.js"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
crossorigin="anonymous"></script>
<link rel="stylesheet" type="text/css" href="https://kubernetes-sigs.github.io/kustomize//css/asciinema-player.css" />
<title>Eschewed Features | Kustomize</title>
</head>
<body class="td-section">
<header>
<nav class="js-navbar-scroll navbar navbar-expand navbar-dark flex-column flex-md-row td-navbar">
<a class="navbar-brand" href="/kustomize/">
<span class="navbar-logo"></span><span class="text-uppercase font-weight-bold">Kustomize</span>
</a>
<div class="td-navbar-nav-scroll ml-md-auto" id="main_navbar">
<ul class="navbar-nav mt-2 mt-lg-0">
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/installation/" ><span>Installation</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/guides/" ><span>Guides</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/api-reference/" ><span>API Reference</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link active" href="/kustomize/faq/" ><span class="active">FAQ</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/blog/" ><span>Blog</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/contributing/" ><span>Contributing</span></a>
</li>
</ul>
</div>
<div class="navbar-nav d-none d-lg-block">
</div>
</nav>
</header>
<div class="container-fluid td-outer">
<div class="td-main">
<div class="row flex-xl-nowrap">
<div class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
<div id="td-sidebar-menu" class="td-sidebar__inner">
<form class="td-sidebar__search d-flex align-items-center">
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-docs-nav" aria-expanded="false" aria-label="Toggle section navigation">
</button>
</form>
<nav class="collapse td-sidebar-nav pt-2 pl-4" id="td-section-nav">
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/faq/" class="align-left pl-0 pr-2 td-sidebar-link td-sidebar-link__section">FAQ</a>
</li>
<ul>
<li class="collapse show" id="kustomizefaq">
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/faq/eschewedfeatures/" class="align-left pl-0 pr-2 active td-sidebar-link td-sidebar-link__section">Eschewed Features</a>
</li>
<ul>
<li class="collapse show" id="kustomizefaqeschewedfeatures">
</li>
</ul>
</ul>
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizefaqversioningpolicy" href="/kustomize/faq/versioningpolicy/">Versioning Policy</a>
</li>
</ul>
</ul>
</nav>
</div>
</div>
<div class="d-none d-xl-block col-xl-2 td-toc d-print-none">
<div class="td-page-meta ml-2 pb-1 pt-2 mb-0">
<a href="https://github.com/kubernetes-sigs/kustomize/edit/master/site/content/en/faq/eschewedfeatures/_index.md" target="_blank"><i class="fa fa-edit fa-fw"></i> Edit this page</a>
<a href="https://github.com/kubernetes-sigs/kustomize/issues/new?title=Eschewed%20Features" target="_blank"><i class="fab fa-github fa-fw"></i> Create documentation issue</a>
<a href="https://github.com/kubernetes-sigs/kustomize/issues/new" target="_blank"><i class="fas fa-tasks fa-fw"></i> Create project issue</a>
</div>
<nav id="TableOfContents">
<ul>
<li><a href="#removal-directives">Removal directives</a></li>
<li><a href="#unstructured-edits">Unstructured edits</a></li>
<li><a href="#build-time-side-effects-from-cli-args-or-env-variables">Build-time side effects from CLI args or env variables</a></li>
<li><a href="#globs-in-kustomization-files">Globs in kustomization files</a></li>
</ul>
</nav>
</div>
<main class="col-12 col-md-9 col-xl-8 pl-md-5" role="main">
<nav aria-label="breadcrumb" class="d-none d-md-block d-print-none">
<ol class="breadcrumb spb-1">
<li class="breadcrumb-item" >
<a href="https://kubernetes-sigs.github.io/kustomize/faq/">FAQ</a>
</li>
<li class="breadcrumb-item active" aria-current="page">
<a href="https://kubernetes-sigs.github.io/kustomize/faq/eschewedfeatures/">Eschewed Features</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>Eschewed Features</h1>
<div class="lead">Eschewed Features</div>
<p>The maintainers established this list to
place bounds on the kustomize feature
set. The bounds can be changed with
a consensus on the risks.</p>
<p>For a bigger picture about why kustomize
does some things and not others, see the
glossary entry for <a href="/kustomize/api-reference/glossary#declarative-application-management">DAM</a>.</p>
<h2 id="removal-directives">Removal directives</h2>
<p><code>kustomize</code> supports configurations that can be reasoned about as
<em>compositions</em> or <em>mixins</em> - concepts that are widely accepted as
a best practice in various programming languages.</p>
<p>To this end, <code>kustomize</code> offers various <em>addition</em> directives.
One may add labels, annotations, patches, resources, bases, etc.
Corresponding <em>removal</em> directives are not offered.</p>
<p>Removal semantics would introduce many possibilities for
inconsistency, and the need to add code to detect, report and
reject it. It would also allow, and possibly encourage,
unnecessarily complex configuration layouts.</p>
<p>When faced with a situation where removal is desirable, it&rsquo;s
always possible to remove things from a base like labels and
annotations, and/or split multi-resource manifests into individual
resource files - then add things back as desired via the
<a href="/kustomize/api-reference/glossary#kustomization">kustomization</a>.</p>
<p>If the underlying base is outside of one&rsquo;s control, an <a href="/kustomize/api-reference/glossary#off-the-shelf-configuration">OTS
workflow</a> is the recommended best practice. Fork the base, remove
what you don&rsquo;t want and commit it to your private fork, then use
kustomize on your fork. As often as desired, use <em>git rebase</em> to
capture improvements from the upstream base.</p>
<h2 id="unstructured-edits">Unstructured edits</h2>
<p><em>Structured edits</em> are changes controlled by
knowledge of the k8s API, and YAML or JSON syntax.</p>
<p>Most edits performed by kustomize can be expressed as
<a href="/kustomize/api-reference/glossary#patchjson6902">JSON patches</a> or <a href="/kustomize/api-reference/glossary#patchstrategicmerge">SMP patches</a>.
Those can be verbose, so common patches,
like adding labels or annotatations, get dedicated
transformer plugins - <code>LabelTransformer</code>,
<code>AnnotationsTransformer</code>, etc.
These accept relatively simple YAML configuration
allowing easy targeting of any number of resources.</p>
<p>Another class of edits take data from one specific
object&rsquo;s field and use it in another (e.g. a service
object&rsquo;s name found and copied into a container&rsquo;s
command line). These reflection-style edits
are called <em>replacements</em>.</p>
<p>The above edits create valid output given valid input,
and can provide syntactically and semantically
informed error messages if inputs are invalid.</p>
<p><em>Unstructured edits</em>, edits that don&rsquo;t limit
themselves to a syntax or object structure,
come in many forms. A common one in the
configuration domain is the template or
parameterization approach.</p>
<p>In this technique, the source
material is sprinkled with strings of the
form <code>${VAR}</code>. A scanner replaces them
with a value taken from a map using <code>VAR</code>
as the map key. It&rsquo;s trivial to implement.</p>
<p>kustomize eschews parameterization, because</p>
<ul>
<li>The source yaml gets polluted with <code>$VARs</code>
and can no longed be applied as is
to the cluster (it <em>must</em> be processed).</li>
<li>The source material is no longer structured,
making it unusable with any YAML processor.
It&rsquo;s no longer <em>data</em>, it&rsquo;s now logic that
must be compiled.</li>
<li>Errors in the output are disconnected from
the edit that caused it.</li>
<li>The input becomes <a href="https://github.com/helm/charts/blob/e002378c13e91bef4a3b0ba718c191ec791ce3f9/stable/artifactory/templates/artifactory-deployment.yaml">unintelligible</a> as the project
scales in any number of dimensions (resource
count, cluster count, environment count, etc.)</li>
</ul>
<p>Kustomizations are meant to be sharable and stackable.
Imagine tracing down a problem rooted in a
clever set of stacked regexp replacements
performed by various overlays on some remote base.
We&rsquo;ve used such systems, and never want to again.</p>
<p>Other tools (sed, jinja, erb, envsubst, kafka, helm, ksonnet,
etc.) provide varying degrees of unstructured editting
and/or embedded languages, and can be used instead
of, or in a pipe with, kustomize. If you want to
go all-in on <em>configuration as a language</em>, consider <a href="https://cuelang.org/">cue</a>.</p>
<p>kustomize is going to stick to YAML in / YAML out.</p>
<h2 id="build-time-side-effects-from-cli-args-or-env-variables">Build-time side effects from CLI args or env variables</h2>
<p><code>kustomize</code> supports the best practice of storing one&rsquo;s
entire configuration in a version control system.</p>
<p>Changing <code>kustomize build</code> configuration output as a result
of additional arguments or flags to <code>build</code>, or by
consulting shell environment variable values in <code>build</code>
code, would frustrate that goal.</p>
<p><code>kustomize</code> insteads offers <a href="/kustomize/api-reference/glossary#kustomization">kustomization</a> file <code>edit</code>
commands. Like any shell command, they can accept
environment variable arguments.</p>
<p>For example, to set the tag used on an image to match an
environment variable, run</p>
<pre><code>kustomize edit set image nginx:$MY_NGINX_VERSION
</code></pre><p>as part of some encapsulating work flow executed before
<code>kustomize build</code>.</p>
<h2 id="globs-in-kustomization-files">Globs in kustomization files</h2>
<p><code>kustomize</code> supports the best practice of storing one&rsquo;s
entire configuration in a version control system.</p>
<p>Globbing the local file system for files not explicitly
declared in the <a href="/kustomize/api-reference/glossary#kustomization">kustomization</a> file at <code>kustomize build</code> time
would violate that goal.</p>
<p>Allowing globbing in a kustomization file would also introduce
the same problems as allowing globbing in <a href="https://www.codebyamir.com/blog/pitfalls-java-import-wildcards">java import</a>
declarations or BUILD/Makefile dependency rules.</p>
<p><code>kustomize</code> will instead provide kustomization file editting
commands that accept globbed arguments, expand them at <em>edit
time</em> relative to the local file system, and store the resulting
explicit names into the kustomization file.</p>
<div class="section-index">
<hr class="panel-line">
</div>
<div class="text-muted mt-5 pt-3 border-top">Last modified June 7, 2020: <a href="https://github.com/kubernetes-sigs/kustomize/commit/a2ea87d167bfd7a9dce16ff47d93b379f2a2d80d">Convert docs to docsy (a2ea87d1)</a>
</div>
</div>
</main>
</div>
</div>
<footer class="bg-dark py-5 row d-print-none">
<div class="container-fluid mx-sm-5">
<div class="row">
<div class="col-6 col-sm-4 text-xs-center order-sm-2">
<ul class="list-inline mb-0">
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="User mailing list" aria-label="User mailing list">
<a class="text-white" target="_blank" href="https://groups.google.com/forum/#!forum/kubernetes-sig-cli">
<i class="fa fa-envelope"></i>
</a>
</li>
</ul>
</div>
<div class="col-6 col-sm-4 text-right text-xs-center order-sm-3">
<ul class="list-inline mb-0">
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="GitHub" aria-label="GitHub">
<a class="text-white" target="_blank" href="https://github.com/kubernetes-sigs/kustomize">
<i class="fab fa-github"></i>
</a>
</li>
</ul>
</div>
<div class="col-12 col-sm-4 text-center py-2 order-sm-2">
<small class="text-white">&copy; 2020 Kubernetes Authors All Rights Reserved</small>
</div>
</div>
</div>
</footer>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
<script src="/kustomize/js/main.min.35b203b3c2114e187f6e4bbf0903c511aaaac5535186321e3b5e364656b6de0c.js" integrity="sha256-NbIDs8IRThh/bku/CQPFEaqqxVNRhjIeO142Rla23gw=" crossorigin="anonymous"></script>
<script src="https://kubernetes-sigs.github.io/kustomize//js/asciinema-player.js"></script>
</body>
</html>

17
docs/faq/eschewedfeatures/index.xml Normal file
View File

@@ -0,0 +1,17 @@
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>Kustomize – Eschewed Features</title>
<link>https://kubernetes-sigs.github.io/kustomize/faq/eschewedfeatures/</link>
<description>Recent content in Eschewed Features on Kustomize</description>
<generator>Hugo -- gohugo.io</generator>
<atom:link href="https://kubernetes-sigs.github.io/kustomize/faq/eschewedfeatures/index.xml" rel="self" type="application/rss+xml" />
</channel>
</rss>

415
docs/faq/index.html Normal file
View File

@@ -0,0 +1,415 @@
<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="generator" content="Hugo 0.73.0-DEV" />
<META NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW">
<link rel="alternate" type="application/rss&#43;xml" href="https://kubernetes-sigs.github.io/kustomize/faq/index.xml">
<link rel="shortcut icon" href="/favicons/favicon.ico" >
<link rel="apple-touch-icon" href="/kustomize/favicons/apple-touch-icon-180x180.png" sizes="180x180">
<link rel="icon" type="image/png" href="/kustomize/favicons/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="/kustomize/favicons/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-36x36.png" sizes="36x36">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-48x48.png" sizes="48x48">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-72x72.png" sizes="72x72">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-96x96.png" sizes="96x96">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-144x144.png" sizes="144x144">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-192x192.png" sizes="192x192">
<title>FAQ | Kustomize</title><meta property="og:title" content="FAQ" />
<meta property="og:description" content="Kubernetes Configuration Customization" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/faq/" />
<meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="FAQ">
<meta itemprop="description" content="Kubernetes Configuration Customization"><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="FAQ"/>
<meta name="twitter:description" content="Kubernetes Configuration Customization"/>
<link rel="preload" href="/kustomize/scss/main.min.818a933df0186c907f1faea6730835dd5fa01c3b53af36bb68396dc80a2d3c45.css" as="style">
<link href="/kustomize/scss/main.min.818a933df0186c907f1faea6730835dd5fa01c3b53af36bb68396dc80a2d3c45.css" rel="stylesheet" integrity="">
<script
src="https://code.jquery.com/jquery-3.3.1.min.js"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
crossorigin="anonymous"></script>
<link rel="stylesheet" type="text/css" href="https://kubernetes-sigs.github.io/kustomize//css/asciinema-player.css" />
<title>FAQ | Kustomize</title>
</head>
<body class="td-section">
<header>
<nav class="js-navbar-scroll navbar navbar-expand navbar-dark flex-column flex-md-row td-navbar">
<a class="navbar-brand" href="/kustomize/">
<span class="navbar-logo"></span><span class="text-uppercase font-weight-bold">Kustomize</span>
</a>
<div class="td-navbar-nav-scroll ml-md-auto" id="main_navbar">
<ul class="navbar-nav mt-2 mt-lg-0">
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/installation/" ><span>Installation</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/guides/" ><span>Guides</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/api-reference/" ><span>API Reference</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link active" href="/kustomize/faq/" ><span class="active">FAQ</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/blog/" ><span>Blog</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/contributing/" ><span>Contributing</span></a>
</li>
</ul>
</div>
<div class="navbar-nav d-none d-lg-block">
</div>
</nav>
</header>
<div class="container-fluid td-outer">
<div class="td-main">
<div class="row flex-xl-nowrap">
<div class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
<div id="td-sidebar-menu" class="td-sidebar__inner">
<form class="td-sidebar__search d-flex align-items-center">
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-docs-nav" aria-expanded="false" aria-label="Toggle section navigation">
</button>
</form>
<nav class="collapse td-sidebar-nav pt-2 pl-4" id="td-section-nav">
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/faq/" class="align-left pl-0 pr-2 active td-sidebar-link td-sidebar-link__section">FAQ</a>
</li>
<ul>
<li class="collapse show" id="kustomizefaq">
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/faq/eschewedfeatures/" class="align-left pl-0 pr-2 td-sidebar-link td-sidebar-link__section">Eschewed Features</a>
</li>
<ul>
<li class="collapse show" id="kustomizefaqeschewedfeatures">
</li>
</ul>
</ul>
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizefaqversioningpolicy" href="/kustomize/faq/versioningpolicy/">Versioning Policy</a>
</li>
</ul>
</ul>
</nav>
</div>
</div>
<div class="d-none d-xl-block col-xl-2 td-toc d-print-none">
<div class="td-page-meta ml-2 pb-1 pt-2 mb-0">
<a href="https://github.com/kubernetes-sigs/kustomize/edit/master/site/content/en/faq/_index.md" target="_blank"><i class="fa fa-edit fa-fw"></i> Edit this page</a>
<a href="https://github.com/kubernetes-sigs/kustomize/issues/new?title=FAQ" target="_blank"><i class="fab fa-github fa-fw"></i> Create documentation issue</a>
<a href="https://github.com/kubernetes-sigs/kustomize/issues/new" target="_blank"><i class="fas fa-tasks fa-fw"></i> Create project issue</a>
</div>
<nav id="TableOfContents">
<ul>
<li><a href="#security-file-foo-is-not-in-or-below-bar">security: file &lsquo;foo&rsquo; is not in or below &lsquo;bar&rsquo;</a></li>
<li><a href="#some-field-is-not-transformed-by-kustomize">Some field is not transformed by kustomize</a></li>
</ul>
</nav>
</div>
<main class="col-12 col-md-9 col-xl-8 pl-md-5" role="main">
<nav aria-label="breadcrumb" class="d-none d-md-block d-print-none">
<ol class="breadcrumb spb-1">
<li class="breadcrumb-item active" aria-current="page">
<a href="https://kubernetes-sigs.github.io/kustomize/faq/">FAQ</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>FAQ</h1>
<h2 id="security-file-foo-is-not-in-or-below-bar">security: file &lsquo;foo&rsquo; is not in or below &lsquo;bar&rsquo;</h2>
<p>v2.0 added a security check that prevents
kustomizations from reading files outside their own
directory root.</p>
<p>This was meant to help protect the person inclined to
download kustomization directories from the web and use
them without inspection to control their production
cluster
(see <a href="https://github.com/kubernetes-sigs/kustomize/issues/693">#693</a>,
<a href="https://github.com/kubernetes-sigs/kustomize/pull/700">#700</a>,
<a href="https://github.com/kubernetes-sigs/kustomize/pull/995">#995</a> and
<a href="https://github.com/kubernetes-sigs/kustomize/pull/998">#998</a>)</p>
<p>Resources (including configmap and secret generators)
can <em>still be shared</em> via the recommended best practice
of placing them in a directory with their own
kustomization file, and referring to this directory as a
<a href="/kustomize/api-reference/glossary#base"><code>base</code></a> from any kustomization that
wants to use it. This encourages modularity and
relocatability.</p>
<p>To disable this, use v3, and the <code>load_restrictor</code> flag:</p>
<pre><code>kustomize build --load_restrictor none $target
</code></pre><h2 id="some-field-is-not-transformed-by-kustomize">Some field is not transformed by kustomize</h2>
<p>Example: <a href="https://github.com/kubernetes-sigs/kustomize/issues/1319">#1319</a>, <a href="https://github.com/kubernetes-sigs/kustomize/issues/1322">#1322</a>, <a href="https://github.com/kubernetes-sigs/kustomize/issues/1347">#1347</a> and etc.</p>
<p>The fields transformed by kustomize is configured explicitly in <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/api/konfig/builtinpluginconsts/defaultconfig.go">defaultconfig</a>. The configuration itself can be customized by including <code>configurations</code> in <code>kustomization.yaml</code>, e.g.</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml"><span style="color:#204a87;font-weight:bold">apiVersion</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span>kustomize.config.k8s.io/v1beta1<span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">kind</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span>Kustomization<span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">configurations</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span>- kustomizeconfig.yaml<span style="color:#f8f8f8;text-decoration:underline">
</span></code></pre></div><p>The configuration directive allows customization of the following transformers:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml"><span style="color:#204a87;font-weight:bold">commonAnnotations</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000;font-weight:bold">[]</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">commonLabels</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000;font-weight:bold">[]</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">nameprefix</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000;font-weight:bold">[]</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">namespace</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000;font-weight:bold">[]</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">varreference</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000;font-weight:bold">[]</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">namereference</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000;font-weight:bold">[]</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">images</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000;font-weight:bold">[]</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">replicas</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#000;font-weight:bold">[]</span><span style="color:#f8f8f8;text-decoration:underline">
</span></code></pre></div><p>To persist the changes to default configuration, submit a PR like <a href="https://github.com/kubernetes-sigs/kustomize/pull/1338">#1338</a>, <a href="https://github.com/kubernetes-sigs/kustomize/pull/1348">#1348</a> and etc.</p>
<div class="section-index">
<hr class="panel-line">
<div class="entry">
<h5>
<a href="/kustomize/faq/eschewedfeatures/">Eschewed Features</a>
</h5>
<p>Eschewed Features</p>
</div>
<div class="entry">
<h5>
<a href="/kustomize/faq/versioningpolicy/">Versioning Policy</a>
</h5>
<p></p>
</div>
</div>
<div class="text-muted mt-5 pt-3 border-top">Last modified June 7, 2020: <a href="https://github.com/kubernetes-sigs/kustomize/commit/a2ea87d167bfd7a9dce16ff47d93b379f2a2d80d">Convert docs to docsy (a2ea87d1)</a>
</div>
</div>
</main>
</div>
</div>
<footer class="bg-dark py-5 row d-print-none">
<div class="container-fluid mx-sm-5">
<div class="row">
<div class="col-6 col-sm-4 text-xs-center order-sm-2">
<ul class="list-inline mb-0">
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="User mailing list" aria-label="User mailing list">
<a class="text-white" target="_blank" href="https://groups.google.com/forum/#!forum/kubernetes-sig-cli">
<i class="fa fa-envelope"></i>
</a>
</li>
</ul>
</div>
<div class="col-6 col-sm-4 text-right text-xs-center order-sm-3">
<ul class="list-inline mb-0">
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="GitHub" aria-label="GitHub">
<a class="text-white" target="_blank" href="https://github.com/kubernetes-sigs/kustomize">
<i class="fab fa-github"></i>
</a>
</li>
</ul>
</div>
<div class="col-12 col-sm-4 text-center py-2 order-sm-2">
<small class="text-white">&copy; 2020 Kubernetes Authors All Rights Reserved</small>
</div>
</div>
</div>
</footer>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
<script src="/kustomize/js/main.min.35b203b3c2114e187f6e4bbf0903c511aaaac5535186321e3b5e364656b6de0c.js" integrity="sha256-NbIDs8IRThh/bku/CQPFEaqqxVNRhjIeO142Rla23gw=" crossorigin="anonymous"></script>
<script src="https://kubernetes-sigs.github.io/kustomize//js/asciinema-player.js"></script>
</body>
</html>

17
docs/faq/index.xml Normal file
View File

@@ -0,0 +1,17 @@
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>Kustomize – FAQ</title>
<link>https://kubernetes-sigs.github.io/kustomize/faq/</link>
<description>Recent content in FAQ on Kustomize</description>
<generator>Hugo -- gohugo.io</generator>
<atom:link href="https://kubernetes-sigs.github.io/kustomize/faq/index.xml" rel="self" type="application/rss+xml" />
</channel>
</rss>

594
docs/faq/versioningpolicy/index.html Normal file
View File

@@ -0,0 +1,594 @@
<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="generator" content="Hugo 0.73.0-DEV" />
<META NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW">
<link rel="shortcut icon" href="/favicons/favicon.ico" >
<link rel="apple-touch-icon" href="/kustomize/favicons/apple-touch-icon-180x180.png" sizes="180x180">
<link rel="icon" type="image/png" href="/kustomize/favicons/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="/kustomize/favicons/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-36x36.png" sizes="36x36">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-48x48.png" sizes="48x48">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-72x72.png" sizes="72x72">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-96x96.png" sizes="96x96">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-144x144.png" sizes="144x144">
<link rel="icon" type="image/png" href="/kustomize/favicons/android-192x192.png" sizes="192x192">
<title>Versioning Policy | Kustomize</title><meta property="og:title" content="Versioning Policy" />
<meta property="og:description" content="Running kustomize means one is running a particular version of a program (a CLI), using a particular version of underlying packages (a Go API), and reading a particular version of a kustomization file.
If you&rsquo;re having trouble with go get, please read Go API Versioning and be patient.
CLI Program Versioning The command kustomize version prints a three field version tag (e.g. v3.0.0) that aspires to semantic versioning." />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/faq/versioningpolicy/" />
<meta property="article:modified_time" content="2020-06-07T21:07:46-07:00" /><meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="Versioning Policy">
<meta itemprop="description" content="Running kustomize means one is running a particular version of a program (a CLI), using a particular version of underlying packages (a Go API), and reading a particular version of a kustomization file.
If you&rsquo;re having trouble with go get, please read Go API Versioning and be patient.
CLI Program Versioning The command kustomize version prints a three field version tag (e.g. v3.0.0) that aspires to semantic versioning.">
<meta itemprop="dateModified" content="2020-06-07T21:07:46-07:00" />
<meta itemprop="wordCount" content="1054">
<meta itemprop="keywords" content="" /><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Versioning Policy"/>
<meta name="twitter:description" content="Running kustomize means one is running a particular version of a program (a CLI), using a particular version of underlying packages (a Go API), and reading a particular version of a kustomization file.
If you&rsquo;re having trouble with go get, please read Go API Versioning and be patient.
CLI Program Versioning The command kustomize version prints a three field version tag (e.g. v3.0.0) that aspires to semantic versioning."/>
<link rel="preload" href="/kustomize/scss/main.min.818a933df0186c907f1faea6730835dd5fa01c3b53af36bb68396dc80a2d3c45.css" as="style">
<link href="/kustomize/scss/main.min.818a933df0186c907f1faea6730835dd5fa01c3b53af36bb68396dc80a2d3c45.css" rel="stylesheet" integrity="">
<script
src="https://code.jquery.com/jquery-3.3.1.min.js"
integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
crossorigin="anonymous"></script>
<link rel="stylesheet" type="text/css" href="https://kubernetes-sigs.github.io/kustomize//css/asciinema-player.css" />
<title>Versioning Policy | Kustomize</title>
</head>
<body class="td-page">
<header>
<nav class="js-navbar-scroll navbar navbar-expand navbar-dark flex-column flex-md-row td-navbar">
<a class="navbar-brand" href="/kustomize/">
<span class="navbar-logo"></span><span class="text-uppercase font-weight-bold">Kustomize</span>
</a>
<div class="td-navbar-nav-scroll ml-md-auto" id="main_navbar">
<ul class="navbar-nav mt-2 mt-lg-0">
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/installation/" ><span>Installation</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/guides/" ><span>Guides</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/api-reference/" ><span>API Reference</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link active" href="/kustomize/faq/" ><span class="active">FAQ</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/blog/" ><span>Blog</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/contributing/" ><span>Contributing</span></a>
</li>
</ul>
</div>
<div class="navbar-nav d-none d-lg-block">
</div>
</nav>
</header>
<div class="container-fluid td-outer">
<div class="td-main">
<div class="row flex-xl-nowrap">
<div class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
<div id="td-sidebar-menu" class="td-sidebar__inner">
<form class="td-sidebar__search d-flex align-items-center">
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-docs-nav" aria-expanded="false" aria-label="Toggle section navigation">
</button>
</form>
<nav class="collapse td-sidebar-nav pt-2 pl-4" id="td-section-nav">
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/faq/" class="align-left pl-0 pr-2 active td-sidebar-link td-sidebar-link__section">FAQ</a>
</li>
<ul>
<li class="collapse show" id="kustomizefaq">
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/faq/eschewedfeatures/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">Eschewed Features</a>
</li>
<ul>
<li class="collapse " id="kustomizefaqeschewedfeatures">
</li>
</ul>
</ul>
<a class="td-sidebar-link td-sidebar-link__page active" id="m-kustomizefaqversioningpolicy" href="/kustomize/faq/versioningpolicy/">Versioning Policy</a>
</li>
</ul>
</ul>
</nav>
</div>
</div>
<div class="d-none d-xl-block col-xl-2 td-toc d-print-none">
<div class="td-page-meta ml-2 pb-1 pt-2 mb-0">
<a href="https://github.com/kubernetes-sigs/kustomize/edit/master/site/content/en/faq/versioningPolicy.md" target="_blank"><i class="fa fa-edit fa-fw"></i> Edit this page</a>
<a href="https://github.com/kubernetes-sigs/kustomize/issues/new?title=Versioning%20Policy" target="_blank"><i class="fab fa-github fa-fw"></i> Create documentation issue</a>
<a href="https://github.com/kubernetes-sigs/kustomize/issues/new" target="_blank"><i class="fas fa-tasks fa-fw"></i> Create project issue</a>
</div>
<nav id="TableOfContents">
<ul>
<li><a href="#cli-program-versioning">CLI Program Versioning</a>
<ul>
<li><a href="#installation">Installation</a></li>
</ul>
</li>
<li><a href="#go-api-versioning">Go API Versioning</a>
<ul>
<li></li>
</ul>
</li>
<li><a href="#kustomization-file-versioning">Kustomization File Versioning</a>
<ul>
<li><a href="#field-change-policy">Field Change Policy</a></li>
<li><a href="#the-edit-fix-command">The <code>edit fix</code> Command</a></li>
<li><a href="#examples">Examples</a></li>
</ul>
</li>
<li><a href="#relationship-to-the-k8s-api">Relationship to the k8s API</a>
<ul>
<li><a href="#review-of-k8s-api-versioning">Review of k8s API versioning</a></li>
<li><a href="#differences">Differences</a></li>
<li><a href="#additional-kustomization-file-rules">Additional Kustomization file rules</a></li>
</ul>
</li>
</ul>
</nav>
</div>
<main class="col-12 col-md-9 col-xl-8 pl-md-5" role="main">
<nav aria-label="breadcrumb" class="d-none d-md-block d-print-none">
<ol class="breadcrumb spb-1">
<li class="breadcrumb-item" >
<a href="https://kubernetes-sigs.github.io/kustomize/faq/">FAQ</a>
</li>
<li class="breadcrumb-item active" aria-current="page">
<a href="https://kubernetes-sigs.github.io/kustomize/faq/versioningpolicy/">Versioning Policy</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>Versioning Policy</h1>
<p>Running <code>kustomize</code> means one is running a
particular version of a program (a CLI), using a
particular version of underlying packages (a Go
API), and reading a particular version of a
<a href="/kustomize/api-reference/glossary#kustomization">kustomization</a> file.</p>
<blockquote>
<p>If you&rsquo;re having trouble with <code>go get</code>, please
read <a href="#go-api-versioning">Go API Versioning</a>
and be patient.</p>
</blockquote>
<h2 id="cli-program-versioning">CLI Program Versioning</h2>
<p>The command <code>kustomize version</code> prints a three
field version tag (e.g. <code>v3.0.0</code>) that aspires to
<a href="https://semver.org">semantic versioning</a>.</p>
<p>This notion of semver applies only to the CLI;
the command names, their arguments and their flags.</p>
<p>The major version changes when some backward
incompatibility appears in how the commands
behave.</p>
<h3 id="installation">Installation</h3>
<p>See the <a href="INSTALL.md">installation docs</a>.</p>
<h2 id="go-api-versioning">Go API Versioning</h2>
<p>The public methods in the public packages
of module <code>sigs.k8s.io/kustomize/api</code> constitute
the <em>kustomize Go API</em>.</p>
<h4 id="version-sigsk8siokustomizev3-and-earlier">Version sigs.k8s.io/kustomize/v3 and earlier</h4>
<p>In <code>kustomize/v3</code> (and preceding major versions), the
kustomize program and the API live the same Go
module at <code>sigs.k8s.io/kustomize</code>, at <a href="https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher">import path</a>
<code>sigs.k8s.io/kustomize/v3</code>.</p>
<p>This has been fine for the CLI, but it presents a
problem for the Go API.</p>
<p>The process around Go modules, in particular the
notion of <a href="https://research.swtch.com/vgo-mvs">minimal version selection</a>, demands
that the module respect semver.</p>
<p>Almost all the code in module
<code>sigs.k8s.io/kustomize/v3</code> is exposed (not in a
directory named <code>internal</code>). Even a minor
refactor changing a method name or argument type
in some deeply buried (but still public) method is
a backward incompatible change. As a result, Go
API semver hasn&rsquo;t been followed. This was a mistake.</p>
<p>Some options are</p>
<ul>
<li>
<p>continue to ignore Go API semver and stick to
CLI semver (eliminating the usefullness of
minimal version selection),</p>
</li>
<li>
<p>obey semver, and increment the module&rsquo;s major
version number with every release (drastically
reducing the usefullness of minimal version
selection - since virtually all releases will
be major),</p>
</li>
<li>
<p>slow down change in the huge API in favor of
stability, yet somehow continue to deliver
features,</p>
</li>
<li>
<p>drastically reduce the API surface, stabilize on
semver there, and refactor as needed inside
<code>internal</code>.</p>
</li>
</ul>
<p>The last option seems the most appealing.</p>
<h4 id="the-first-stable-api-version-is-coming">The first stable API version is coming</h4>
<p>The first stable API version will launch
as the Go module</p>
<pre><code>sigs.k8s.io/kustomize/api
</code></pre><p>The <em>kustomize</em> program itself (<code>main.go</code>
and CLI specific code) will have moved out of
<code>sigs.k8s.io/kustomize</code> and into the new module
<code>sigs.k8s.io/kustomize/kustomize</code>. This is a
submodule in the same repo, and it will retain its
current notion of semver (e.g. a backward
incompatible change in command behavior will
trigger a major version bump). This module will
not export packages; it&rsquo;s just home to a <code>main</code>
package.</p>
<p>The <code>sigs.k8s.io/kustomize/api</code> module will
obey semver with a sustainable public
surface, informed by current usage. Clients
should import packages from this module, i.e.
from import paths prefixed by
<code>sigs.k8s.io/kustomize/api/</code> at first,
and later by <code>sigs.k8s.io/kustomize/api/v2/</code>.
The kustomize binary
itself is an API client requiring this module.</p>
<p>The clients and API will evolve independently.</p>
<h2 id="kustomization-file-versioning">Kustomization File Versioning</h2>
<p>The kustomization file is a struct that is part of
the kustomize Go API (the <code>sigs.k8s.io/kustomize</code>
module), but it also evolves as a k8s API object -
it has an <code>apiVersion</code> field containing its
own version number.</p>
<h3 id="field-change-policy">Field Change Policy</h3>
<ul>
<li>A field&rsquo;s meaning cannot be changed.</li>
<li>A field may be deprecated, then removed.</li>
<li>Deprecation means triggering a <em>minor</em> (semver)
version bump in the kustomize Go API, and
defining a migration path in a non-fatal error
message.</li>
<li>Removal means triggering a <em>major</em> (semver)
version bump in the kustomize Go API, and fatal
error if field encountered (as with any unknown
field). Likewise a change in <code>apiVersion</code>.</li>
</ul>
<h3 id="the-edit-fix-command">The <code>edit fix</code> Command</h3>
<p>This <code>kustomize</code> command reads a Kustomization
file, converts deprecated fields to new
fields, and writes it out again in the latest
format.</p>
<p>This is a type version upgrade mechanism that
works within <em>major</em> API revisions. There is no
downgrade capability, as there&rsquo;s no use case for
it (see discussion below).</p>
<h3 id="examples">Examples</h3>
<p>With the 2.0.0 release, there were three field
removals:</p>
<ul>
<li><code>imageTag</code> was deprecated when <code>images</code> was
introduced, because the latter offers more
general features for image data manipulation.
<code>imageTag</code> was removed in v2.0.0.</li>
<li><code>patches</code> was deprecated and replaced by
<code>patchesStrategicMerge</code> when <code>patchesJson6902</code>
was introduced, to make a clearer
distinction between patch specification formats.
<code>patches</code> was removed in v2.0.0.</li>
<li><code>secretGenerator/commands</code> was removed
due to security concerns in v2.0.0
with no deprecation period.</li>
</ul>
<p>The <code>edit fix</code> command in a v2.0.x binary
will no longer recognize these fields.</p>
<h2 id="relationship-to-the-k8s-api">Relationship to the k8s API</h2>
<h3 id="review-of-k8s-api-versioning">Review of k8s API versioning</h3>
<p>The k8s API has specific <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md">conventions</a> and a
process for making <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md">changes</a>.</p>
<p>The presence of an <code>apiVersion</code> field in a k8s
native type signals:</p>
<ul>
<li>its reliability level (alpha vs beta vs
generally available),</li>
<li>the existence of code to provide default values
to fields not present in a serialization,</li>
<li>the existence of code to provide both forward
and backward conversion between different
versions of types.</li>
</ul>
<p>The k8s API promises a lossless <em>conversion</em>
between versions over a specific range. This
means that a recent client can write an object
bearing the newest possible value for its version,
the server will accept it and store it in
&ldquo;versionless&rdquo; JSON form in storage, and can
convert it to a range of older versions should
an older client request data.</p>
<p>For native k8s types, this all requires writing Go
code in the kubernetes core repo, to provide
defaulting and conversions.</p>
<p>For CRDs, there&rsquo;s a <a href="https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md">proposal</a> on how to manage
versioning (e.g. a remote service can offer type
defaulting and conversions).</p>
<h3 id="differences">Differences</h3>
<ul>
<li>A k8s API server is able to go <em>forward</em> and
<em>backward</em> in versioning, to work with older
clients, over <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy">some range</a>.</li>
<li>The <code>kustomize edit fix</code> command only moves
<em>forward</em> within a <em>major</em> API
version.</li>
</ul>
<p>At the time of writing, the YAML in a
kustomization file does not represent a <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md">k8s API</a>
object, and the kustomize command and associated
library is neither a server of, nor a client to,
the k8s API.</p>
<h3 id="additional-kustomization-file-rules">Additional Kustomization file rules</h3>
<p>In addition to the <a href="#field-change-policy">field change policy</a> described
above, kustomization files conform to
the following rules.</p>
<h4 id="eschew-classic-k8s-fields">Eschew classic k8s fields</h4>
<p>Field names with dedicated meaning in k8s
(<code>metadata</code>, <code>spec</code>, <code>status</code>, etc.) aren&rsquo;t used.
This is enforced via code review.</p>
<h4 id="default-values-for-k8s-kind-and-apiversion">Default values for k8s <code>kind</code> and <code>apiVersion</code></h4>
<p>In <code>v3</code> or below, the two <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources">special</a> k8s
resource fields <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds"><code>kind</code></a> and <a href="https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning"><code>apiVersion</code></a> may
be omitted from the kustomization file.</p>
<p>If either field is present, they both must be.
If present, the value of <code>kind</code> must be:</p>
<blockquote>
<pre><code>kind: Kustomization
</code></pre></blockquote>
<p>If missing, the value of <code>apiVersion</code> defaults to</p>
<blockquote>
<pre><code>apiVersion: kustomize.config.k8s.io/v1beta1
</code></pre></blockquote>
<div class="text-muted mt-5 pt-3 border-top">Last modified June 7, 2020: <a href="https://github.com/kubernetes-sigs/kustomize/commit/a2ea87d167bfd7a9dce16ff47d93b379f2a2d80d">Convert docs to docsy (a2ea87d1)</a>
</div>
</div>
</main>
</div>
</div>
<footer class="bg-dark py-5 row d-print-none">
<div class="container-fluid mx-sm-5">
<div class="row">
<div class="col-6 col-sm-4 text-xs-center order-sm-2">
<ul class="list-inline mb-0">
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="User mailing list" aria-label="User mailing list">
<a class="text-white" target="_blank" href="https://groups.google.com/forum/#!forum/kubernetes-sig-cli">
<i class="fa fa-envelope"></i>
</a>
</li>
</ul>
</div>
<div class="col-6 col-sm-4 text-right text-xs-center order-sm-3">
<ul class="list-inline mb-0">
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="GitHub" aria-label="GitHub">
<a class="text-white" target="_blank" href="https://github.com/kubernetes-sigs/kustomize">
<i class="fab fa-github"></i>
</a>
</li>
</ul>
</div>
<div class="col-12 col-sm-4 text-center py-2 order-sm-2">
<small class="text-white">&copy; 2020 Kubernetes Authors All Rights Reserved</small>
</div>
</div>
</div>
</footer>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
<script src="/kustomize/js/main.min.35b203b3c2114e187f6e4bbf0903c511aaaac5535186321e3b5e364656b6de0c.js" integrity="sha256-NbIDs8IRThh/bku/CQPFEaqqxVNRhjIeO142Rla23gw=" crossorigin="anonymous"></script>
<script src="https://kubernetes-sigs.github.io/kustomize//js/asciinema-player.js"></script>
</body>
</html>