mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-05-17 18:25:26 +00:00
786 lines
31 KiB
HTML
786 lines
31 KiB
HTML
<!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.68.3" />
|
|
|
|
<META NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW">
|
|
|
|
<link rel="alternate" type="application/rss+xml" href="https://kubernetes-sigs.github.io/kustomize/guides/plugins/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>Kustomize Plugins | Kustomize</title><meta property="og:title" content="Kustomize Plugins" />
|
|
<meta property="og:description" content="Kustomize plugins guide
|
|
" />
|
|
<meta property="og:type" content="website" />
|
|
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/guides/plugins/" />
|
|
<meta property="og:site_name" content="Kustomize" />
|
|
<meta itemprop="name" content="Kustomize Plugins">
|
|
<meta itemprop="description" content="Kustomize plugins guide
|
|
"><meta name="twitter:card" content="summary"/>
|
|
<meta name="twitter:title" content="Kustomize Plugins"/>
|
|
<meta name="twitter:description" content="Kustomize plugins guide
|
|
"/>
|
|
|
|
|
|
|
|
|
|
|
|
<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>Kustomize Plugins | 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 active" href="/kustomize/guides/" ><span class="active">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" href="https://github.com/kubernetes-sigs/kustomize/tree/master/examples" target="_blank" ><span>Example</span></a>
|
|
</li>
|
|
|
|
<li class="nav-item mr-4 mb-2 mb-lg-0">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a class="nav-link" href="/kustomize/faq/" ><span>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>
|
|
|
|
|
|
|
|
<li class="nav-item dropdown d-none d-lg-block">
|
|
|
|
|
|
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
|
|
English
|
|
</a>
|
|
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
|
|
|
|
<a class="dropdown-item" href="/kustomize/zh/guides/plugins/">简体中文</a>
|
|
|
|
</div>
|
|
</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">
|
|
|
|
<div class="nav-item dropdown d-block d-lg-none">
|
|
|
|
|
|
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
|
|
English
|
|
</a>
|
|
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
|
|
|
|
<a class="dropdown-item" href="/kustomize/zh/guides/plugins/">简体中文</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul class="td-sidebar-nav__section pr-md-3">
|
|
<li class="td-sidebar-nav__section-title">
|
|
<a href="/kustomize/guides/" class="align-left pl-0 pr-2 td-sidebar-link td-sidebar-link__section">Guides</a>
|
|
</li>
|
|
<ul>
|
|
<li class="collapse show" id="kustomizeguides">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul class="td-sidebar-nav__section pr-md-3">
|
|
<li class="td-sidebar-nav__section-title">
|
|
<a href="/kustomize/guides/bespoke/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">Bespoke Application</a>
|
|
</li>
|
|
<ul>
|
|
<li class="collapse " id="kustomizeguidesbespoke">
|
|
|
|
|
|
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul class="td-sidebar-nav__section pr-md-3">
|
|
<li class="td-sidebar-nav__section-title">
|
|
<a href="/kustomize/guides/offtheshelf/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">Off The Shelf Application</a>
|
|
</li>
|
|
<ul>
|
|
<li class="collapse " id="kustomizeguidesofftheshelf">
|
|
|
|
|
|
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul class="td-sidebar-nav__section pr-md-3">
|
|
<li class="td-sidebar-nav__section-title">
|
|
<a href="/kustomize/guides/plugins/" class="align-left pl-0 pr-2 active td-sidebar-link td-sidebar-link__section">Kustomize Plugins</a>
|
|
</li>
|
|
<ul>
|
|
<li class="collapse show" id="kustomizeguidesplugins">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizeguidespluginsbuiltins" href="/kustomize/guides/plugins/builtins/">Builtin Plugins</a>
|
|
|
|
|
|
|
|
|
|
|
|
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizeguidespluginsexecpluginguidedexample" href="/kustomize/guides/plugins/execpluginguidedexample/">Exec plugin on linux</a>
|
|
|
|
|
|
|
|
|
|
|
|
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizeguidespluginsgoplugincaveats" href="/kustomize/guides/plugins/goplugincaveats/">Go plugin Caveats</a>
|
|
|
|
|
|
|
|
|
|
|
|
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizeguidespluginsgopluginguidedexample" href="/kustomize/guides/plugins/gopluginguidedexample/">Go plugin example</a>
|
|
|
|
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
</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/guides/plugins/_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=Kustomize%20Plugins" 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="#specification-in-kustomizationyaml">Specification in <code>kustomization.yaml</code></a></li>
|
|
<li><a href="#configuration">Configuration</a></li>
|
|
<li><a href="#placement">Placement</a></li>
|
|
<li><a href="#execution">Execution</a>
|
|
<ul>
|
|
<li></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#authoring">Authoring</a>
|
|
<ul>
|
|
<li><a href="#exec-plugins">Exec plugins</a></li>
|
|
<li><a href="#go-plugins">Go plugins</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/guides/">Guides</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="breadcrumb-item active" aria-current="page">
|
|
<a href="https://kubernetes-sigs.github.io/kustomize/guides/plugins/">Kustomize Plugins</a>
|
|
</li>
|
|
|
|
</ol>
|
|
</nav >
|
|
|
|
|
|
<div class="td-content">
|
|
<h1>Kustomize Plugins</h1>
|
|
<div class="lead">Kustomize plugins guide</div>
|
|
<p>Kustomize offers a plugin framework allowing people to write their own resource <em>generators</em>
|
|
and <em>transformers</em>.</p>
|
|
<p>Write a plugin when changing <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/examples/generatorOptions.md">generator options</a>
|
|
or <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs">transformer configs</a> doesn’t meet your needs.</p>
|
|
<ul>
|
|
<li>
|
|
<p>A <em>generator</em> plugin could be a helm chart
|
|
inflator, or a plugin that emits all the
|
|
components (deployment, service, scaler,
|
|
ingress, etc.) needed by someone’s <a href="https://12factor.net">12-factor</a>
|
|
application, based on a smaller number of free
|
|
variables.</p>
|
|
</li>
|
|
<li>
|
|
<p>A <em>transformer</em> plugin might perform special
|
|
container command line edits, or any other
|
|
transformation beyond those provided by the
|
|
builtin (<code>namePrefix</code>, <code>commonLabels</code>, etc.)
|
|
transformers.</p>
|
|
</li>
|
|
</ul>
|
|
<h2 id="specification-in-kustomizationyaml">Specification in <code>kustomization.yaml</code></h2>
|
|
<p>Start by adding a <code>generators</code> and/or <code>transformers</code>
|
|
field to your kustomization.</p>
|
|
<p>Each field accepts a string list:</p>
|
|
<blockquote>
|
|
<pre><code>generators:
|
|
- relative/path/to/some/file.yaml
|
|
- relative/path/to/some/kustomization
|
|
- /absolute/path/to/some/kustomization
|
|
- https://github.com/org/repo/some/kustomization
|
|
|
|
transformers:
|
|
- {as above}
|
|
</code></pre></blockquote>
|
|
<p>The value of each entry in a <code>generators</code> or
|
|
<code>transformers</code> list must be a relative path to a
|
|
YAML file, or a path or URL to a <a href="/kustomize/api-reference/glossary#kustomization">kustomization</a>.
|
|
This is the same format as demanded by the
|
|
<code>resources</code> field.</p>
|
|
<p>YAML files are read from disk directly. Paths or
|
|
URLs leading to kustomizations trigger an
|
|
in-process kustomization run. Each of the
|
|
resulting objects is now further interpreted by
|
|
kustomize as a <em>plugin configuration</em> object.</p>
|
|
<h2 id="configuration">Configuration</h2>
|
|
<p>A kustomization file could have the following lines:</p>
|
|
<pre><code>generators:
|
|
- chartInflator.yaml
|
|
</code></pre><p>Given this, the kustomization process would expect
|
|
to find a file called <code>chartInflator.yaml</code> in the
|
|
kustomization <a href="/kustomize/api-reference/glossary#kustomization-root">root</a>.</p>
|
|
<p>This is the plugin’s configuration file;
|
|
it contains a YAML configuration object.</p>
|
|
<p>The file <code>chartInflator.yaml</code> could contain:</p>
|
|
<pre><code>apiVersion: someteam.example.com/v1
|
|
kind: ChartInflator
|
|
metadata:
|
|
name: notImportantHere
|
|
chartName: minecraft
|
|
</code></pre><p><strong>The <code>apiVersion</code> and <code>kind</code> fields are
|
|
used to locate the plugin.</strong></p>
|
|
<p>Thus, these fields are required. They are also
|
|
required because a kustomize plugin configuration
|
|
object is also a <a href="/kustomize/api-reference/glossary#kubernetes-style-object">k8s object</a>.</p>
|
|
<p>To get the plugin ready to generate or transform,
|
|
it is given the entire contents of the
|
|
configuration file.</p>
|
|
<p>For more examples of plugin configuration YAML,
|
|
browse the unit tests below the <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin">plugins</a> root,
|
|
e.g. the tests for <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator/ChartInflator_test.go">ChartInflator</a> or
|
|
<a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin/prefixsuffixtransformer/PrefixSuffixTransformer_test.go">NameTransformer</a>.</p>
|
|
<h2 id="placement">Placement</h2>
|
|
<p>Each plugin gets its own dedicated directory named</p>
|
|
<pre><code>$XDG_CONFIG_HOME/kustomize/plugin
|
|
/${apiVersion}/LOWERCASE(${kind})
|
|
</code></pre><p>The default value of <a href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html"><code>XDG_CONFIG_HOME</code></a> is
|
|
<code>$HOME/.config</code>.</p>
|
|
<p>The one-plugin-per-directory requirement eases
|
|
creation of a plugin bundle (source, tests, plugin
|
|
data files, etc.) for sharing.</p>
|
|
<p>In the case of a <a href="#go-plugins">Go plugin</a>, it also
|
|
allows one to provide a <code>go.mod</code> file for the
|
|
single plugin, easing resolution of package
|
|
version dependency skew.</p>
|
|
<p>When loading, kustomize will first look for an
|
|
<em>executable</em> file called</p>
|
|
<pre><code>$XDG_CONFIG_HOME/kustomize/plugin
|
|
/${apiVersion}/LOWERCASE(${kind})/${kind}
|
|
</code></pre><p>If this file is not found or is not executable,
|
|
kustomize will look for a file called <code>${kind}.so</code>
|
|
in the same directory and attempt to load it as a
|
|
<a href="#go-plugins">Go plugin</a>.</p>
|
|
<p>If both checks fail, the plugin load fails the overall
|
|
<code>kustomize build</code>.</p>
|
|
<h2 id="execution">Execution</h2>
|
|
<p>Plugins are only used during a run of the
|
|
<code>kustomize build</code> command.</p>
|
|
<p>Generator plugins are run after processing the
|
|
<code>resources</code> field (which itself can be viewed as a
|
|
generator, simply reading objects from disk).</p>
|
|
<p>The full set of resources is then passed into the
|
|
transformation pipeline, wherein builtin
|
|
transformations like <code>namePrefix</code> and
|
|
<code>commonLabel</code> are applied (if they were specified
|
|
in the kustomization file), followed by the
|
|
user-specified transformers in the <code>transformers</code>
|
|
field.</p>
|
|
<p>The order specified in the <code>transformers</code> field is
|
|
respected, as transformers cannot be expected to
|
|
be commutative.</p>
|
|
<h4 id="no-security">No Security</h4>
|
|
<p>Kustomize plugins do not run in any kind of
|
|
kustomize-provided sandbox. There’s no notion
|
|
of <em>“plugin security”</em>.</p>
|
|
<p>A <code>kustomize build</code> that tries to use plugins but
|
|
omits the flag</p>
|
|
<blockquote>
|
|
<p><code>--enable_alpha_plugins</code></p>
|
|
</blockquote>
|
|
<p>will not load plugins and will fail with a
|
|
warning about plugin use.</p>
|
|
<p>The use of this flag is an opt-in acknowledging
|
|
the unstable (alpha) plugin API, the absence of
|
|
plugin provenance, and the fact that a plugin
|
|
is not part of kustomize.</p>
|
|
<p>To be clear, some kustomize plugin downloaded
|
|
from the internet might wonderfully transform
|
|
k8s config in a desired manner, while also
|
|
quietly doing anything the user could do to the
|
|
system running <code>kustomize build</code>.</p>
|
|
<h2 id="authoring">Authoring</h2>
|
|
<p>There are two kinds of plugins, <a href="#exec-plugins">exec</a> and <a href="#go-plugins">Go</a>.</p>
|
|
<h3 id="exec-plugins">Exec plugins</h3>
|
|
<p>A <em>exec plugin</em> is any executable that accepts a
|
|
single argument on its command line - the name of
|
|
a YAML file containing its configuration (the file name
|
|
provided in the kustomization file).</p>
|
|
<blockquote>
|
|
<p>TODO: restrictions on plugin to allow the <em>same exec
|
|
plugin</em> to be targeted by both the
|
|
<code>generators</code> and <code>transformers</code> fields.</p>
|
|
<ul>
|
|
<li>first arg could be the fixed string
|
|
<code>generate</code> or <code>transform</code>,
|
|
(the name of the configuration file moves to
|
|
the 2nd arg), or</li>
|
|
<li>or by default an exec plugin behaves as a tranformer
|
|
unless a flag <code>-g</code> is provided, switching the
|
|
exec plugin to behave as a generator.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<h4 id="examples">Examples</h4>
|
|
<ul>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator">helm chart inflator</a> - A generator that inflates a helm chart.</li>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/bashedconfigmap">bashed config map</a> - Super simple configMap generation from bash.</li>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/sedtransformer">sed transformer</a> - Define your unstructured edits using a
|
|
plugin like this one.</li>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/gogetter">hashicorp go-getter</a> - Download kustomize layes and build it to generate resources</li>
|
|
</ul>
|
|
<p>A generator plugin accepts nothing on <code>stdin</code>, but emits
|
|
generated resources to <code>stdout</code>.</p>
|
|
<p>A transformer plugin accepts resource YAML on <code>stdin</code>,
|
|
and emits those resources, presumably transformed, to
|
|
<code>stdout</code>.</p>
|
|
<p>kustomize uses an exec plugin adapter to provide
|
|
marshalled resources on <code>stdin</code> and capture
|
|
<code>stdout</code> for further processing.</p>
|
|
<h4 id="generator-options">Generator Options</h4>
|
|
<p>A generator exec plugin can adjust the generator options for the resources it emits by setting one of the following internal annotations.</p>
|
|
<blockquote>
|
|
<p>NOTE: These annotations are local to kustomize and will not be included in the final output.</p>
|
|
</blockquote>
|
|
<p><strong><code>kustomize.config.k8s.io/needs-hash</code></strong></p>
|
|
<p>Resources can be marked as needing to be processed by the internal hash transformer by including the <code>needs-hash</code> annotation. When set valid values for the annotation are <code>"true"</code> and <code>"false"</code> which respectively enable or disable hash suffixing for the resource. Omitting the annotation is equivalent to setting the value <code>"false"</code>.</p>
|
|
<p>If this annotation is set on a resource not supported by the hash transformer the build will fail.</p>
|
|
<p>Example:</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>v1<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>ConfigMap<span style="color:#f8f8f8;text-decoration:underline">
|
|
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">metadata</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">name</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span>cm-test<span style="color:#f8f8f8;text-decoration:underline">
|
|
</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#204a87;font-weight:bold">annotations</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">kustomize.config.k8s.io/needs-hash</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#4e9a06">"true"</span><span style="color:#f8f8f8;text-decoration:underline">
|
|
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">data</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">foo</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span>bar<span style="color:#f8f8f8;text-decoration:underline">
|
|
</span></code></pre></div><p><strong><code>kustomize.config.k8s.io/behavior</code></strong></p>
|
|
<p>The <code>behavior</code> annotation will influence how conflicts are handled for resources emitted by the plugin. Valid values include “create”, “merge”, and “replace” with “create” being the default.</p>
|
|
<p>Example:</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>v1<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>ConfigMap<span style="color:#f8f8f8;text-decoration:underline">
|
|
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">metadata</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">name</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span>cm-test<span style="color:#f8f8f8;text-decoration:underline">
|
|
</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#204a87;font-weight:bold">annotations</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">kustomize.config.k8s.io/behavior</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span><span style="color:#4e9a06">"merge"</span><span style="color:#f8f8f8;text-decoration:underline">
|
|
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">data</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">foo</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span>bar<span style="color:#f8f8f8;text-decoration:underline">
|
|
</span></code></pre></div><h3 id="go-plugins">Go plugins</h3>
|
|
<p>Be sure to read <a href="goPluginCaveats.md">Go plugin caveats</a>.</p>
|
|
<p>A <code>.go</code> file can be a <a href="https://golang.org/pkg/plugin/">Go plugin</a> if it declares
|
|
‘main’ as it’s package, and exports a symbol to
|
|
which useful functions are attached.</p>
|
|
<p>It can further be used as a <em>kustomize</em> plugin if
|
|
the symbol is named ‘KustomizePlugin’ and the
|
|
attached functions implement the <code>Configurable</code>,
|
|
<code>Generator</code> and <code>Transformer</code> interfaces.</p>
|
|
<p>A Go plugin for kustomize looks like this:</p>
|
|
<blockquote>
|
|
<pre><code>package main
|
|
|
|
import (
|
|
"sigs.k8s.io/kustomize/api/resmap"
|
|
...
|
|
)
|
|
|
|
type plugin struct {...}
|
|
|
|
var KustomizePlugin plugin
|
|
|
|
func (p *plugin) Config(
|
|
h *resmap.PluginHelpers,
|
|
c []byte) error {...}
|
|
|
|
func (p *plugin) Generate() (resmap.ResMap, error) {...}
|
|
|
|
func (p *plugin) Transform(m resmap.ResMap) error {...}
|
|
</code></pre></blockquote>
|
|
<p>Use of the identifiers <code>plugin</code>, <code>KustomizePlugin</code>
|
|
and implementation of the method signature
|
|
<code>Config</code> is required.</p>
|
|
<p>Implementing the <code>Generator</code> or <code>Transformer</code>
|
|
method allows (respectively) the plugin’s config
|
|
file to be added to the <code>generators</code> or
|
|
<code>transformers</code> field in the kustomization file.
|
|
Do one or the other or both as desired.</p>
|
|
<h4 id="examples-1">Examples</h4>
|
|
<ul>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/someservicegenerator">service generator</a> - generate a service from a name and port argument.</li>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/stringprefixer">string prefixer</a> - uses the value in <code>metadata/name</code> as the prefix.
|
|
This particular example exists to show how a plugin can
|
|
transform the behavior of a plugin. See the
|
|
<code>TestTransformedTransformers</code> test in the <code>target</code> package.</li>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/dateprefixer">date prefixer</a> - prefix the current date to resource names, a simple
|
|
example used to modify the string prefixer plugin just mentioned.</li>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/secretsfromdatabase">secret generator</a> - generate secrets from a toy database.</li>
|
|
<li><a href="https://github.com/monopole/sopsencodedsecrets">sops encoded secrets</a> - a more complex secret generator that converts SOPS files into Kubernetes Secrets</li>
|
|
<li><a href="https://github.com/omninonsense/kustomize-sopsgenerator">SOPSGenerator</a> - another generator that decrypts SOPS files into Secrets</li>
|
|
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin">All the builtin plugins</a>.
|
|
User authored plugins are
|
|
on the same footing as builtin operations.</li>
|
|
</ul>
|
|
<p>A Go plugin can be both a generator and a
|
|
transformer. The <code>Generate</code> method will run along
|
|
with all the other generators before the
|
|
<code>Transform</code> method runs.</p>
|
|
<p>Here’s a build command that sensibly assumes the
|
|
plugin source code sits in the directory where
|
|
kustomize expects to find <code>.so</code> files:</p>
|
|
<pre><code>d=$XDG_CONFIG_HOME/kustomize/plugin\
|
|
/${apiVersion}/LOWERCASE(${kind})
|
|
|
|
go build -buildmode plugin \
|
|
-o $d/${kind}.so $d/${kind}.go
|
|
</code></pre>
|
|
<div class="section-index">
|
|
|
|
|
|
|
|
|
|
<hr class="panel-line">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="entry">
|
|
<h5>
|
|
<a href="/kustomize/guides/plugins/builtins/">Builtin Plugins</a>
|
|
</h5>
|
|
<p>Builtin Plugins</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="entry">
|
|
<h5>
|
|
<a href="/kustomize/guides/plugins/execpluginguidedexample/">Exec plugin on linux</a>
|
|
</h5>
|
|
<p>Exec plugin on linux in 60 seconds</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="entry">
|
|
<h5>
|
|
<a href="/kustomize/guides/plugins/goplugincaveats/">Go plugin Caveats</a>
|
|
</h5>
|
|
<p>Go plugin Caveats</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="entry">
|
|
<h5>
|
|
<a href="/kustomize/guides/plugins/gopluginguidedexample/">Go plugin example</a>
|
|
</h5>
|
|
<p>Go plugin example</p>
|
|
</div>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
<div class="text-muted mt-5 pt-3 border-top">Last modified June 26, 2020: <a href="https://github.com/kubernetes-sigs/kustomize/commit/69dc34500ad151a7ee04d3434c4cc17ff8827950">docs: add link to another Go plugin (69dc3450)</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">© 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> |