mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-05-17 18:25:26 +00:00
565 lines
16 KiB
HTML
565 lines
16 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="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>Go plugin Caveats | Kustomize</title><meta property="og:title" content="Go plugin Caveats" />
|
|
<meta property="og:description" content="Go plugin Caveats
|
|
" />
|
|
<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-06-07T21:07:46-07: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-06-07T21:07:46-07:00" />
|
|
<meta itemprop="wordCount" content="532">
|
|
|
|
|
|
|
|
<meta itemprop="keywords" content="" /><meta name="twitter:card" content="summary"/>
|
|
<meta name="twitter:title" content="Go plugin Caveats"/>
|
|
<meta name="twitter:description" content="Go plugin Caveats
|
|
"/>
|
|
|
|
|
|
|
|
|
|
|
|
<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>Go plugin Caveats | 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 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/goplugincaveats/">简体中文</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/goplugincaveats/">简体中文</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 active" 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/goPluginCaveats.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=Go%20plugin%20Caveats" 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="#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>
|
|
<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" >
|
|
<a href="https://kubernetes-sigs.github.io/kustomize/guides/plugins/">Kustomize Plugins</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li class="breadcrumb-item active" aria-current="page">
|
|
<a href="https://kubernetes-sigs.github.io/kustomize/guides/plugins/goplugincaveats/">Go plugin Caveats</a>
|
|
</li>
|
|
|
|
</ol>
|
|
</nav >
|
|
|
|
|
|
<div class="td-content">
|
|
<h1>Go plugin Caveats</h1>
|
|
<div class="lead">Go plugin Caveats</div>
|
|
<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’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>
|
|
|
|
|
|
|
|
<div class="text-muted mt-5 pt-3 border-top">Last modified June 7, 2020: <a href="https://github.com/kubernetes-sigs/kustomize/commit/42497c664f619a36cc86156e366b53099bd633cb">Convert docs to docsy (42497c66)</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> |