kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-11 17:12:51 +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

337
docs/guides/plugins/goplugincaveats/index.html
View File

@@ -25,12 +25,12 @@
" />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/guides/plugins/goplugincaveats/" />
<meta property="article:modified_time" content="2020-11-04T11:15:40-08:00" /><meta property="og:site_name" content="Kustomize" />
<meta property="article:modified_time" content="2020-11-11T08:29:43-08:00" /><meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="Go plugin Caveats">
<meta itemprop="description" content="Go plugin Caveats
">
<meta itemprop="dateModified" content="2020-11-04T11:15:40-08:00" />
<meta itemprop="wordCount" content="532">
<meta itemprop="dateModified" content="2020-11-11T08:29:43-08:00" />
<meta itemprop="wordCount" content="3">
@@ -310,236 +310,6 @@
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">Command Line Options</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmd">
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/build/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">build</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdbuild">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/cfg/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">cfg</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdcfg">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/create/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">create</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdcreate">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/edit/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">edit</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdedit">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/fn/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">fn</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdfn">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/help/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">help</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdhelp">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/install-completion/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">install-completion</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdinstall-completion">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/live/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">live</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdlive">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/cmd/version/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">version</a>
</li>
<ul>
<li class="collapse " id="kustomizeguidescmdversion">
</li>
</ul>
</ul>
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/guides/components/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">Kustomize Components</a>
@@ -593,20 +363,6 @@
<nav id="TableOfContents">
<ul>
<li><a href="#the-skew-problem">The skew problem</a></li>
<li><a href="#why-support-go-plugins">Why support Go plugins</a>
<ul>
<li><a href="#safety">Safety</a></li>
<li><a href="#debugging">Debugging</a></li>
<li><a href="#unit-of-contribution">Unit of contribution</a></li>
<li><a href="#ecosystems-grow-through-use">Ecosystems grow through use</a></li>
</ul>
</li>
</ul>
</nav>
</div>
@@ -653,94 +409,11 @@
<h1>Go plugin Caveats</h1>
<div class="lead">Go plugin Caveats</div>
<meta http-equiv="refresh" content="0; url=https://kubectl.docs.kubernetes.io/guides/extending_kustomize/goplugincaveats" />
<p>A <em>Go plugin</em> is a compilation artifact described
by the Go <a href="https://golang.org/pkg/plugin">plugin package</a>. It is built with
special flags and cannot run on its own.
It must be loaded into a running Go program.</p>
<blockquote>
<p>A normal program written in Go might be usable
as <em>exec plugin</em>, but is not a <em>Go plugin</em>.</p>
</blockquote>
<p>Go plugins allow kustomize extensions that run
without the cost marshalling/unmarshalling all
resource data to/from a subprocess for each plugin
run. The Go plugin API assures a certain level of
consistency to avoid confusing downstream
transformers.</p>
<p>Go plugins work as described in the <a href="https://golang.org/pkg/plugin">plugin
package</a>, but fall short of common notions
associated with the word <em>plugin</em>.</p>
<h2 id="the-skew-problem">The skew problem</h2>
<p>Go plugin compilation creates an <a href="https://en.wikipedia.org/wiki/Executable_and_Linkable_Format">ELF</a> formatted
<code>.so</code> file, which by definition has no information
about the provenance of the object code.</p>
<p>Skew between the compilation conditions (versions
of package dependencies, <code>GOOS</code>, <code>GOARCH</code>) of the
main program ELF and the plugin ELF will cause
plugin load failure, with non-helpful error
messages.</p>
<p>Exec plugins also lack provenance, but won&rsquo;t fail
due to compilation skew.</p>
<p>In either case, the only sensible way to share a
plugin is as some kind of <em>bundle</em> (a git repo
URL, a git archive file, a tar file, etc.)
containing source code, tests and associated data,
unpackable under
<code>$XDG_CONFIG_HOME/kustomize/plugin</code>.</p>
<p>In the case of a Go plugin, an <em>end user</em>
accepting a shared plugin <em>must compile both
kustomize and the plugin</em>.</p>
<p>This means a one-time run of</p>
<pre><code># Or whatever is appropriate at time of reading
GOPATH=${whatever} GO111MODULE=on go get sigs.k8s.io/kustomize/api
</code></pre><p>and then a normal development cycle using</p>
<pre><code>go build -buildmode plugin \
-o ${wherever}/${kind}.so ${wherever}/${kind}.go
</code></pre><p>with paths and the release version tag (e.g. <code>v3.0.0</code>)
adjusted as needed.</p>
<p>For comparison, consider what one
must do to write a <a href="https://www.tensorflow.org/guide/extend/op">tensorflow plugin</a>.</p>
<h2 id="why-support-go-plugins">Why support Go plugins</h2>
<h3 id="safety">Safety</h3>
<p>The Go plugin developer sees the same API offered
to native kustomize operations, assuring certain
semantics, invariants, checks, etc. An exec
plugin sub-process dealing with this via
stdin/stdout will have an easier time screwing
things up for downstream transformers and
consumers.</p>
<p>Minor point: if the plugin reads files via
the kustomize-provided file <code>Loader</code> interface, it
will be constrained by kustomize file loading
restrictions. Of course, nothing but a code audit
prevents a Go plugin from importing the <code>io</code> package
and doing whatever it wants.</p>
<h3 id="debugging">Debugging</h3>
<p>A Go plugin developer can debug the plugin <em>in
situ</em>, setting breakpoints inside the plugin and
elsewhere while running a plugin in feature tests.</p>
<p>To get the best of both worlds (shareability and safety),
a developer can write an <code>.go</code> program that functions
as an <em>exec plugin</em>, but can be processed by <code>go generate</code>
to emit a <em>Go plugin</em> (or vice versa).</p>
<h3 id="unit-of-contribution">Unit of contribution</h3>
<p>All the builtin generators and transformers
are themselves Go plugins. This means that
the kustomize maintainers can promote a contributed
plugin to a builtin without needing code changes
(beyond those mandated by normal code review).</p>
<h3 id="ecosystems-grow-through-use">Ecosystems grow through use</h3>
<p>Tooling could ease Go plugin <em>sharing</em>, but this
requires some critical mass of Go plugin
<em>authoring</em>, which in turn is hampered by
confusion around sharing. <a href="https://github.com/golang/go/wiki/Modules">Go modules</a>, once they
are more widely adopted, will solve the
biggest plugin sharing difficulty: ambiguous
plugin vs host dependencies.</p>
<p>Moved to <a href="https://github.com/kubernetes-sigs/cli-experimental">https://github.com/kubernetes-sigs/cli-experimental</a></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>