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

481
docs/guides/bespoke/index.html Normal file
View File

@@ -0,0 +1,481 @@
<!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/guides/bespoke/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>Bespoke Application | Kustomize</title><meta property="og:title" content="Bespoke Application" />
<meta property="og:description" content="Workflow for bespoke applications
" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/guides/bespoke/" />
<meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="Bespoke Application">
<meta itemprop="description" content="Workflow for bespoke applications
"><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Bespoke Application"/>
<meta name="twitter:description" content="Workflow for bespoke applications
"/>
<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>Bespoke Application | 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="/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>
</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/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 active td-sidebar-link td-sidebar-link__section">Bespoke Application</a>
</li>
<ul>
<li class="collapse show" 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 collapsed td-sidebar-link td-sidebar-link__section">Kustomize Plugins</a>
</li>
<ul>
<li class="collapse " 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/bespoke/_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=Bespoke%20Application" 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>
</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/bespoke/">Bespoke Application</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>Bespoke Application</h1>
<div class="lead">Workflow for bespoke applications</div>
<p>In this workflow, all configuration (resource YAML) files are owned by the user.
No content is incorporated from version control repositories owned by others.</p>
<p><img src="/kustomize/images/workflowBespoke.jpg" alt="bespoke config workflow image"></p>
<h4 id="1-create-a-directory-in-version-control">1) create a directory in version control</h4>
<p>Speculate some overall cluster application called <em>ldap</em>;
we want to keep its configuration in its own repo.</p>
<blockquote>
<pre><code>git init ~/ldap
</code></pre></blockquote>
<h4 id="2-create-a-base">2) create a <a href="/kustomize/api-reference/glossary#base">base</a></h4>
<blockquote>
<pre><code>mkdir -p ~/ldap/base
</code></pre></blockquote>
<p>In this directory, create and commit a <a href="/kustomize/api-reference/glossary#kustomization">kustomization</a>
file and a set of <a href="/kustomize/api-reference/glossary#resource">resources</a>.</p>
<h4 id="3-create-overlays">3) create <a href="/kustomize/api-reference/glossary#overlay">overlays</a></h4>
<blockquote>
<pre><code>mkdir -p ~/ldap/overlays/staging
mkdir -p ~/ldap/overlays/production
</code></pre></blockquote>
<p>Each of these directories needs a <a href="/kustomize/api-reference/glossary#kustomization">kustomization</a>
file and one or more <a href="/kustomize/api-reference/glossary#patch">patches</a>.</p>
<p>The <em>staging</em> directory might get a patch
that turns on an experiment flag in a configmap.</p>
<p>The <em>production</em> directory might get a patch
that increases the replica count in a deployment
specified in the base.</p>
<h4 id="4-bring-up-variants">4) bring up <a href="/kustomize/api-reference/glossary#variant">variants</a></h4>
<p>Run kustomize, and pipe the output to <a href="/kustomize/api-reference/glossary#apply">apply</a>.</p>
<blockquote>
<pre><code>kustomize build ~/ldap/overlays/staging | kubectl apply -f -
kustomize build ~/ldap/overlays/production | kubectl apply -f -
</code></pre></blockquote>
<p>You can also use <a href="https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/">kubectl-v1.14.0</a> to apply your <a href="/kustomize/api-reference/glossary#variant">variants</a>.</p>
<blockquote>
<pre><code>kubectl apply -k ~/ldap/overlays/staging
kubectl apply -k ~/ldap/overlays/production
</code></pre></blockquote>
<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/guides/bespoke/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 – Bespoke Application</title>
<link>https://kubernetes-sigs.github.io/kustomize/guides/bespoke/</link>
<description>Recent content in Bespoke Application on Kustomize</description>
<generator>Hugo -- gohugo.io</generator>
<atom:link href="https://kubernetes-sigs.github.io/kustomize/guides/bespoke/index.xml" rel="self" type="application/rss+xml" />
</channel>
</rss>

454
docs/guides/index.html Normal file
View File

@@ -0,0 +1,454 @@
<!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/guides/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>Guides | Kustomize</title><meta property="og:title" content="Guides" />
<meta property="og:description" content="Reference for Kustomize CLI commands
" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/guides/" />
<meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="Guides">
<meta itemprop="description" content="Reference for Kustomize CLI commands
"><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Guides"/>
<meta name="twitter:description" content="Reference for Kustomize CLI commands
"/>
<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>Guides | 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="/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>
</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/guides/" class="align-left pl-0 pr-2 active 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 td-sidebar-link td-sidebar-link__section">Bespoke Application</a>
</li>
<ul>
<li class="collapse show" 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 td-sidebar-link td-sidebar-link__section">Off The Shelf Application</a>
</li>
<ul>
<li class="collapse show" 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 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/_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=Guides" 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>
</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/guides/">Guides</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>Guides</h1>
<div class="lead">Reference for Kustomize CLI commands</div>
<div class="section-index">
<hr class="panel-line">
<div class="entry">
<h5>
<a href="/kustomize/guides/bespoke/">Bespoke Application</a>
</h5>
<p>Workflow for bespoke applications</p>
</div>
<div class="entry">
<h5>
<a href="/kustomize/guides/offtheshelf/">Off The Shelf Application</a>
</h5>
<p>Workflow for off the shelf applications</p>
</div>
<div class="entry">
<h5>
<a href="/kustomize/guides/plugins/">Kustomize Plugins</a>
</h5>
<p>Kustomize plugins guide</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/guides/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 – Guides</title>
<link>https://kubernetes-sigs.github.io/kustomize/guides/</link>
<description>Recent content in Guides on Kustomize</description>
<generator>Hugo -- gohugo.io</generator>
<atom:link href="https://kubernetes-sigs.github.io/kustomize/guides/index.xml" rel="self" type="application/rss+xml" />
</channel>
</rss>

483
docs/guides/offtheshelf/index.html Normal file
View File

@@ -0,0 +1,483 @@
<!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/guides/offtheshelf/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>Off The Shelf Application | Kustomize</title><meta property="og:title" content="Off The Shelf Application" />
<meta property="og:description" content="Workflow for off the shelf applications
" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/guides/offtheshelf/" />
<meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="Off The Shelf Application">
<meta itemprop="description" content="Workflow for off the shelf applications
"><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Off The Shelf Application"/>
<meta name="twitter:description" content="Workflow for off the shelf applications
"/>
<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>Off The Shelf Application | 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="/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>
</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/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 active td-sidebar-link td-sidebar-link__section">Off The Shelf Application</a>
</li>
<ul>
<li class="collapse show" 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 collapsed td-sidebar-link td-sidebar-link__section">Kustomize Plugins</a>
</li>
<ul>
<li class="collapse " 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/offtheshelf/_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=Off%20The%20Shelf%20Application" 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>
</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/offtheshelf/">Off The Shelf Application</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>Off The Shelf Application</h1>
<div class="lead">Workflow for off the shelf applications</div>
<p>In this workflow, all files are owned by the user and maintained in a repository under their control, but
they are based on an <a href="/kustomize/api-reference/glossary#off-the-shelf-configuration">off-the-shelf</a> configuration that is periodically consulted for updates.</p>
<p><img src="/kustomize/images/workflowOts.jpg" alt="off-the-shelf config workflow image"></p>
<h4 id="1-find-and-fork-an-ots-config">1) find and <a href="https://guides.github.com/activities/forking/">fork</a> an <a href="/kustomize/api-reference/glossary#off-the-shelf-configuration">OTS</a> config</h4>
<h4 id="2-clone-it-as-your-base">2) clone it as your <a href="/kustomize/api-reference/glossary#base">base</a></h4>
<p>The <a href="/kustomize/api-reference/glossary#base">base</a> directory is maintained in a repo whose upstream is an <a href="/kustomize/api-reference/glossary#off-the-shelf-configuration">OTS</a> configuration, in this case
some user&rsquo;s <code>ldap</code> repo:</p>
<blockquote>
<pre><code>mkdir ~/ldap
git clone https://github.com/$USER/ldap ~/ldap/base
cd ~/ldap/base
git remote add upstream git@github.com:$USER/ldap
</code></pre></blockquote>
<h4 id="3-create-overlays">3) create <a href="/kustomize/api-reference/glossary#overlay">overlays</a></h4>
<p>As in the bespoke case above, create and populate an <em>overlays</em> directory.</p>
<p>The <a href="/kustomize/api-reference/glossary#overlay">overlays</a> are siblings to each other and to the <a href="/kustomize/api-reference/glossary#base">base</a> they depend on.</p>
<blockquote>
<pre><code>mkdir -p ~/ldap/overlays/staging
mkdir -p ~/ldap/overlays/production
</code></pre></blockquote>
<p>The user can maintain the <code>overlays</code> directory in a
distinct repository.</p>
<h4 id="4-bring-up-variants">4) bring up <a href="/kustomize/api-reference/glossary#variant">variants</a></h4>
<blockquote>
<pre><code>kustomize build ~/ldap/overlays/staging | kubectl apply -f -
kustomize build ~/ldap/overlays/production | kubectl apply -f -
</code></pre></blockquote>
<p>You can also use <a href="https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/">kubectl-v1.14.0</a> to apply your <a href="/kustomize/api-reference/glossary#variant">variants</a>.</p>
<blockquote>
<pre><code>kubectl apply -k ~/ldap/overlays/staging
kubectl apply -k ~/ldap/overlays/production
</code></pre></blockquote>
<h4 id="5-optionally-capture-changes-from-upstream">5) (optionally) capture changes from upstream</h4>
<p>The user can periodically <a href="https://git-scm.com/docs/git-rebase">rebase</a> their <a href="/kustomize/api-reference/glossary#base">base</a> to
capture changes made in the upstream repository.</p>
<blockquote>
<pre><code>cd ~/ldap/base
git fetch upstream
git rebase upstream/master
</code></pre></blockquote>
<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/guides/offtheshelf/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 – Off The Shelf Application</title>
<link>https://kubernetes-sigs.github.io/kustomize/guides/offtheshelf/</link>
<description>Recent content in Off The Shelf Application on Kustomize</description>
<generator>Hugo -- gohugo.io</generator>
<atom:link href="https://kubernetes-sigs.github.io/kustomize/guides/offtheshelf/index.xml" rel="self" type="application/rss+xml" />
</channel>
</rss>

1043
docs/guides/plugins/builtins/index.html Normal file
View File

File diff suppressed because it is too large Load Diff

604
docs/guides/plugins/execpluginguidedexample/index.html Normal file
View File

@@ -0,0 +1,604 @@
<!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>Exec plugin on linux | Kustomize</title><meta property="og:title" content="Exec plugin on linux" />
<meta property="og:description" content="Exec plugin on linux in 60 seconds
" />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/guides/plugins/execpluginguidedexample/" />
<meta property="article:modified_time" content="2020-06-07T21:07:46-07:00" /><meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="Exec plugin on linux">
<meta itemprop="description" content="Exec plugin on linux in 60 seconds
">
<meta itemprop="dateModified" content="2020-06-07T21:07:46-07:00" />
<meta itemprop="wordCount" content="465">
<meta itemprop="keywords" content="" /><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Exec plugin on linux"/>
<meta name="twitter:description" content="Exec plugin on linux in 60 seconds
"/>
<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>Exec plugin on linux | 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="/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>
</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/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 active" 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/execPluginGuidedExample.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=Exec%20plugin%20on%20linux" 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>
<ul>
<li></li>
</ul>
</li>
<li><a href="#make-a-place-to-work">Make a place to work</a></li>
<li><a href="#create-a-kustomization">Create a kustomization</a></li>
<li><a href="#make-a-home-for-plugins">Make a home for plugins</a></li>
<li><a href="#create-the-plugin">Create the plugin</a></li>
<li><a href="#install-kustomize">Install kustomize</a></li>
<li><a href="#review-the-layout">Review the layout</a></li>
<li><a href="#build-your-app-using-the-plugin">Build your app, using the plugin:</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/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/execpluginguidedexample/">Exec plugin on linux</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>Exec plugin on linux</h1>
<div class="lead">Exec plugin on linux in 60 seconds</div>
<p>This is a (no reading allowed!) 60 second copy/paste guided
example. Full plugin docs <a href="README.md">here</a>.</p>
<p>This demo writes and uses a somewhat ridiculous
<em>exec</em> plugin (written in bash) that generates a
<code>ConfigMap</code>.</p>
<p>This is a guide to try it without damaging your
current setup.</p>
<h4 id="requirements">requirements</h4>
<ul>
<li>linux, git, curl, Go 1.13</li>
</ul>
<h2 id="make-a-place-to-work">Make a place to work</h2>
<pre><code>DEMO=$(mktemp -d)
</code></pre><h2 id="create-a-kustomization">Create a kustomization</h2>
<p>Make a kustomization directory to
hold all your config:</p>
<pre><code>MYAPP=$DEMO/myapp
mkdir -p $MYAPP
</code></pre><p>Make a deployment config:</p>
<pre><code>cat &lt;&lt;'EOF' &gt;$MYAPP/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: the-deployment
spec:
replicas: 3
template:
spec:
containers:
- name: the-container
image: monopole/hello:1
command: [&quot;/hello&quot;,
&quot;--port=8080&quot;,
&quot;--date=$(THE_DATE)&quot;,
&quot;--enableRiskyFeature=$(ENABLE_RISKY)&quot;]
ports:
- containerPort: 8080
env:
- name: THE_DATE
valueFrom:
configMapKeyRef:
name: the-map
key: today
- name: ALT_GREETING
valueFrom:
configMapKeyRef:
name: the-map
key: altGreeting
- name: ENABLE_RISKY
valueFrom:
configMapKeyRef:
name: the-map
key: enableRisky
EOF
</code></pre><p>Make a service config:</p>
<pre><code>cat &lt;&lt;EOF &gt;$MYAPP/service.yaml
kind: Service
apiVersion: v1
metadata:
name: the-service
spec:
type: LoadBalancer
ports:
- protocol: TCP
port: 8666
targetPort: 8080
EOF
</code></pre><p>Now make a config file for the plugin
you&rsquo;re about to write.</p>
<p>This config file is just another k8s resource
object. The values of its <code>apiVersion</code> and <code>kind</code>
fields are used to <em>find</em> the plugin code on your
filesystem (more on this later).</p>
<pre><code>cat &lt;&lt;'EOF' &gt;$MYAPP/cmGenerator.yaml
apiVersion: myDevOpsTeam
kind: SillyConfigMapGenerator
metadata:
name: whatever
argsOneLiner: Bienvenue true
EOF
</code></pre><p>Finally, make a kustomization file
referencing all of the above:</p>
<pre><code>cat &lt;&lt;EOF &gt;$MYAPP/kustomization.yaml
commonLabels:
app: hello
resources:
- deployment.yaml
- service.yaml
generators:
- cmGenerator.yaml
EOF
</code></pre><p>Review the files</p>
<pre><code>ls -C1 $MYAPP
</code></pre><h2 id="make-a-home-for-plugins">Make a home for plugins</h2>
<p>Plugins must live in a particular place for
kustomize to find them.</p>
<p>This demo will use the ephemeral directory:</p>
<pre><code>PLUGIN_ROOT=$DEMO/kustomize/plugin
</code></pre><p>The plugin config defined above in
<code>$MYAPP/cmGenerator.yaml</code> specifies:</p>
<blockquote>
<pre><code>apiVersion: myDevOpsTeam
kind: SillyConfigMapGenerator
</code></pre></blockquote>
<p>This means the plugin must live in a directory
named:</p>
<pre><code>MY_PLUGIN_DIR=$PLUGIN_ROOT/myDevOpsTeam/sillyconfigmapgenerator
mkdir -p $MY_PLUGIN_DIR
</code></pre><p>The directory name is the plugin config&rsquo;s
<em>apiVersion</em> followed by its lower-cased <em>kind</em>.</p>
<p>A plugin gets its own directory to hold itself,
its tests and any supplemental data files it
might need.</p>
<h2 id="create-the-plugin">Create the plugin</h2>
<p>There are two kinds of plugins, <em>exec</em> and <em>Go</em>.</p>
<p>Make an <em>exec</em> plugin, installing it to the
correct directory and file name. The file name
must match the plugin&rsquo;s <em>kind</em> (in this case,
<code>SillyConfigMapGenerator</code>):</p>
<pre><code>cat &lt;&lt;'EOF' &gt;$MY_PLUGIN_DIR/SillyConfigMapGenerator
#!/bin/bash
# Skip the config file name argument.
shift
today=`date +%F`
echo &quot;
kind: ConfigMap
apiVersion: v1
metadata:
name: the-map
data:
today: $today
altGreeting: &quot;$1&quot;
enableRisky: &quot;$2&quot;
&quot;
EOF
</code></pre><p>By definition, an <em>exec</em> plugin must be executable:</p>
<pre><code>chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator
</code></pre><h2 id="install-kustomize">Install kustomize</h2>
<p>Per the <a href="/kustomize/installation">instructions</a>:</p>
<pre><code>curl -s &quot;https://raw.githubusercontent.com/\
kubernetes-sigs/kustomize/master/hack/install_kustomize.sh&quot; | bash
mkdir -p $DEMO/bin
mv kustomize $DEMO/bin
</code></pre><h2 id="review-the-layout">Review the layout</h2>
<pre><code>tree $DEMO
</code></pre><h2 id="build-your-app-using-the-plugin">Build your app, using the plugin:</h2>
<pre><code>XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP
</code></pre><p>Above, if you had set</p>
<blockquote>
<pre><code>PLUGIN_ROOT=$HOME/.config/kustomize/plugin
</code></pre></blockquote>
<p>there would be no need to use <code>XDG_CONFIG_HOME</code> in the
<em>kustomize</em> command above.</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/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>

531
docs/guides/plugins/goplugincaveats/index.html Normal file
View File

@@ -0,0 +1,531 @@
<!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>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="/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>
</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/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&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>
<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>

691
docs/guides/plugins/gopluginguidedexample/index.html Normal file
View File

@@ -0,0 +1,691 @@
<!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>Go plugin example | Kustomize</title><meta property="og:title" content="Go plugin example" />
<meta property="og:description" content="Go plugin example
" />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/guides/plugins/gopluginguidedexample/" />
<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 example">
<meta itemprop="description" content="Go plugin example
">
<meta itemprop="dateModified" content="2020-06-07T21:07:46-07:00" />
<meta itemprop="wordCount" content="1057">
<meta itemprop="keywords" content="" /><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Go plugin example"/>
<meta name="twitter:description" content="Go plugin example
"/>
<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 example | 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="/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>
</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/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 active" 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/goPluginGuidedExample.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%20example" 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>
<ul>
<li></li>
</ul>
</li>
<li><a href="#make-a-place-to-work">Make a place to work</a></li>
<li><a href="#install-kustomize">Install kustomize</a></li>
<li><a href="#make-a-home-for-plugins">Make a home for plugins</a>
<ul>
<li><a href="#what-apiversion-and-kind">What apiVersion and kind?</a></li>
<li><a href="#define-the-plugins-home-dir">Define the plugin&rsquo;s home dir</a></li>
<li><a href="#download-the-sopsencodedsecrets-plugin">Download the SopsEncodedSecrets plugin</a></li>
<li><a href="#try-the-plugins-own-test">Try the plugin&rsquo;s own test</a></li>
</ul>
</li>
<li><a href="#create-a-kustomization">Create a kustomization</a>
<ul>
<li><a href="#assure-you-have-an-encryption-tool-installed">Assure you have an encryption tool installed</a></li>
<li><a href="#install-sops">Install <code>sops</code></a></li>
<li><a href="#create-data-encrypted-with-your-private-key">Create data encrypted with your private key</a></li>
</ul>
</li>
<li><a href="#build-your-app-using-the-plugin">Build your app, using the plugin:</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/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/gopluginguidedexample/">Go plugin example</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>Go plugin example</h1>
<div class="lead">Go plugin example</div>
<h1 id="go-plugin-guided-example-for-linux">Go Plugin Guided Example for Linux</h1>
<p>This is a (no reading allowed!) 60 second copy/paste guided
example.</p>
<p>Full plugin docs <a href="README.md">here</a>.
Be sure to read the <a href="goPluginCaveats.md">Go plugin caveats</a>.</p>
<p>This demo uses a Go plugin, <code>SopsEncodedSecrets</code>,
that lives in the <a href="https://github.com/monopole/sopsencodedsecrets">sopsencodedsecrets repository</a>.
This is an inprocess <a href="https://golang.org/pkg/plugin">Go plugin</a>, not an
sub-process exec plugin that happens to be written
in Go (which is another option for Go authors).</p>
<p>This is a guide to try it without damaging your
current setup.</p>
<h4 id="requirements">requirements</h4>
<ul>
<li>linux, git, curl, Go 1.13</li>
</ul>
<p>For encryption</p>
<ul>
<li>gpg</li>
</ul>
<p>Or</p>
<ul>
<li>Google cloud (gcloud) install</li>
<li>a Google account with KMS permission</li>
</ul>
<h2 id="make-a-place-to-work">Make a place to work</h2>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#8f5902;font-style:italic"># Keeping these separate to avoid cluttering the DEMO dir.</span>
<span style="color:#000">DEMO</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#204a87;font-weight:bold">$(</span>mktemp -d<span style="color:#204a87;font-weight:bold">)</span>
<span style="color:#000">tmpGoPath</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#204a87;font-weight:bold">$(</span>mktemp -d<span style="color:#204a87;font-weight:bold">)</span>
</code></pre></div><h2 id="install-kustomize">Install kustomize</h2>
<p>Need v3.0.0 for what follows, and you must <em>compile</em>
it (not download the binary from the release page):</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">GOPATH</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$tmpGoPath</span> go install sigs.k8s.io/kustomize/kustomize
</code></pre></div><h2 id="make-a-home-for-plugins">Make a home for plugins</h2>
<p>A kustomize plugin is fully determined by
its configuration file and source code.</p>
<p>Kustomize plugin configuration files are formatted
as kubernetes resource objects, meaning
<code>apiVersion</code>, <code>kind</code> and <code>metadata</code> are <a href="https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields">required
fields</a> in these config files.</p>
<p>The kustomize program reads the config file
(because the config file name appears in the
<code>generators</code> or <code>transformers</code> field in the
kustomization file), then locates the Go plugin&rsquo;s
object code at the following location:</p>
<blockquote>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">$XDG_CONFIG_HOME</span>/kustomize/plugin/<span style="color:#000">$apiVersion</span>/<span style="color:#000">$lKind</span>/<span style="color:#000">$kind</span>.so
</code></pre></div></blockquote>
<p>where <code>lKind</code> holds the lowercased kind. The
plugin is then loaded and fed its config, and the
plugin&rsquo;s output becomes part of the overall
<code>kustomize build</code> process.</p>
<p>The same plugin might be used multiple times in
one kustomize build, but with different config
files. Also, kustomize might customize config
data before sending it to the plugin, for whatever
reason. For these reasons, kustomize owns the
mapping between plugins and config data; it&rsquo;s not
left to plugins to find their own config.</p>
<p>This demo will house the plugin it uses at the
ephemeral directory</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">PLUGIN_ROOT</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$DEMO</span>/kustomize/plugin
</code></pre></div><p>and ephemerally set <code>XDG_CONFIG_HOME</code> on a command
line below.</p>
<h3 id="what-apiversion-and-kind">What apiVersion and kind?</h3>
<p>At this stage in the development of kustomize
plugins, plugin code doesn&rsquo;t know or care what
<code>apiVersion</code> or <code>kind</code> appears in the config file
sent to it.</p>
<p>The plugin could check these fields, but it&rsquo;s the
remaining fields that provide actual configuration
data, and at this point the successful parsing of
these other fields are the only thing that matters
to a plugin.</p>
<p>This demo uses a plugin called <em>SopsEncodedSecrets</em>,
and it lives in the <a href="https://github.com/monopole/sopsencodedsecrets">SopsEncodedSecrets repository</a>.</p>
<p>Somewhat arbitrarily, we&rsquo;ll chose to install
this plugin with</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">apiVersion</span><span style="color:#ce5c00;font-weight:bold">=</span>mygenerators
<span style="color:#000">kind</span><span style="color:#ce5c00;font-weight:bold">=</span>SopsEncodedSecrets
</code></pre></div><h3 id="define-the-plugins-home-dir">Define the plugin&rsquo;s home dir</h3>
<p>By convention, the ultimate home of the plugin
code and supplemental data, tests, documentation,
etc. is the lowercase form of its kind.</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">lKind</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#204a87;font-weight:bold">$(</span><span style="color:#204a87">echo</span> <span style="color:#000">$kind</span> <span style="color:#000;font-weight:bold">|</span> awk <span style="color:#4e9a06">&#39;{print tolower($0)}&#39;</span><span style="color:#204a87;font-weight:bold">)</span>
</code></pre></div><h3 id="download-the-sopsencodedsecrets-plugin">Download the SopsEncodedSecrets plugin</h3>
<p>In this case, the repo name matches the lowercase
kind already, so we just clone the repo and get
the proper directory name automatically:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">mkdir -p <span style="color:#000">$PLUGIN_ROOT</span>/<span style="color:#4e9a06">${</span><span style="color:#000">apiVersion</span><span style="color:#4e9a06">}</span>
<span style="color:#204a87">cd</span> <span style="color:#000">$PLUGIN_ROOT</span>/<span style="color:#4e9a06">${</span><span style="color:#000">apiVersion</span><span style="color:#4e9a06">}</span>
git clone git@github.com:monopole/sopsencodedsecrets.git
</code></pre></div><p>Remember this directory:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">MY_PLUGIN_DIR</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$PLUGIN_ROOT</span>/<span style="color:#4e9a06">${</span><span style="color:#000">apiVersion</span><span style="color:#4e9a06">}</span>/<span style="color:#4e9a06">${</span><span style="color:#000">lKind</span><span style="color:#4e9a06">}</span>
</code></pre></div><h3 id="try-the-plugins-own-test">Try the plugin&rsquo;s own test</h3>
<p>Plugins may come with their own tests.
This one does, and it hopefully passes:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#204a87">cd</span> <span style="color:#000">$MY_PLUGIN_DIR</span>
go <span style="color:#204a87">test</span> SopsEncodedSecrets_test.go
</code></pre></div><p>Build the object code for use by kustomize:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#204a87">cd</span> <span style="color:#000">$MY_PLUGIN_DIR</span>
<span style="color:#000">GOPATH</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$tmpGoPath</span> go build -buildmode plugin -o <span style="color:#4e9a06">${</span><span style="color:#000">kind</span><span style="color:#4e9a06">}</span>.so <span style="color:#4e9a06">${</span><span style="color:#000">kind</span><span style="color:#4e9a06">}</span>.go
</code></pre></div><p>This step may succeed, but kustomize might
ultimately fail to load the plugin because of
dependency <a href="/docs/plugins/README.md#caveats">skew</a>.</p>
<p>On load failure</p>
<ul>
<li>
<p>be sure to build the plugin with the same
version of Go (<em>go1.13</em>) on the same <code>$GOOS</code>
(<em>linux</em>) and <code>$GOARCH</code> (<em>amd64</em>) used to build
the kustomize being <a href="#install-kustomize">used in this demo</a>.</p>
</li>
<li>
<p>change the plugin&rsquo;s dependencies in its <code>go.mod</code>
to match the versions used by kustomize (check
kustomize&rsquo;s <code>go.mod</code> used in its tagged commit).</p>
</li>
</ul>
<p>Lacking tools and metadata to allow this to be
automated, there won&rsquo;t be a Go plugin ecosystem.</p>
<p>Kustomize has adopted a Go plugin architecture as
to ease accept new generators and transformers
(just write a plugin), and to be sure that native
operations (also constructed and tested as
plugins) are compartmentalized, orderable and
reusable instead of bizarrely woven throughout the
code as a individual special cases.</p>
<h2 id="create-a-kustomization">Create a kustomization</h2>
<p>Make a kustomization directory to
hold all your config:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">MYAPP</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$DEMO</span>/myapp
mkdir -p <span style="color:#000">$MYAPP</span>
</code></pre></div><p>Make a config file for the SopsEncodedSecrets plugin.</p>
<p>Its <code>apiVersion</code> and <code>kind</code> allow the plugin to be
found:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">cat <span style="color:#4e9a06">&lt;&lt;EOF &gt;$MYAPP/secGenerator.yaml
</span><span style="color:#4e9a06">apiVersion: ${apiVersion}
</span><span style="color:#4e9a06">kind: ${kind}
</span><span style="color:#4e9a06">metadata:
</span><span style="color:#4e9a06"> name: mySecretGenerator
</span><span style="color:#4e9a06">name: forbiddenValues
</span><span style="color:#4e9a06">namespace: production
</span><span style="color:#4e9a06">file: myEncryptedData.yaml
</span><span style="color:#4e9a06">keys:
</span><span style="color:#4e9a06">- ROCKET
</span><span style="color:#4e9a06">- CAR
</span><span style="color:#4e9a06">EOF</span>
</code></pre></div><p>This plugin expects to find more data in
<code>myEncryptedData.yaml</code>; we&rsquo;ll get to that shortly.</p>
<p>Make a kustomization file referencing the plugin
config:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">cat <span style="color:#4e9a06">&lt;&lt;EOF &gt;$MYAPP/kustomization.yaml
</span><span style="color:#4e9a06">commonLabels:
</span><span style="color:#4e9a06"> app: hello
</span><span style="color:#4e9a06">generators:
</span><span style="color:#4e9a06">- secGenerator.yaml
</span><span style="color:#4e9a06">EOF</span>
</code></pre></div><p>Now generate the real encrypted data.</p>
<h3 id="assure-you-have-an-encryption-tool-installed">Assure you have an encryption tool installed</h3>
<p>We&rsquo;re going to use <a href="https://github.com/mozilla/sops">sops</a> to encode a file. Choose either GPG or Google Cloud KMS as the secret provider to continue.</p>
<h4 id="gpg">GPG</h4>
<p>Try this:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">gpg --list-keys
</code></pre></div><p>If it returns a list, presumably you&rsquo;ve already created keys. If not, try import test keys from sops for dev.</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc <span style="color:#000;font-weight:bold">|</span> gpg --import
<span style="color:#000">SOPS_PGP_FP</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#4e9a06">&#34;1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A&#34;</span>
</code></pre></div><h4 id="google-cloude-kms">Google Cloude KMS</h4>
<p>Try this:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">gcloud kms keys list --location global --keyring sops
</code></pre></div><p>If it succeeds, presumably you&rsquo;ve already created keys and placed them in a keyring called sops. If not, do this:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">gcloud kms keyrings create sops --location global
gcloud kms keys create sops-key --location global <span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span> --keyring sops --purpose encryption
</code></pre></div><p>Extract your keyLocation for use below:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">keyLocation</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#204a87;font-weight:bold">$(</span><span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span> gcloud kms keys list --location global --keyring sops <span style="color:#000;font-weight:bold">|</span><span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span> grep GOOGLE <span style="color:#000;font-weight:bold">|</span> cut -d <span style="color:#4e9a06">&#34; &#34;</span> -f1<span style="color:#204a87;font-weight:bold">)</span>
<span style="color:#204a87">echo</span> <span style="color:#000">$keyLocation</span>
</code></pre></div><h3 id="install-sops">Install <code>sops</code></h3>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">GOPATH</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$tmpGoPath</span> go install go.mozilla.org/sops/cmd/sops
</code></pre></div><h3 id="create-data-encrypted-with-your-private-key">Create data encrypted with your private key</h3>
<p>Create raw data to encrypt:</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">cat <span style="color:#4e9a06">&lt;&lt;EOF &gt;$MYAPP/myClearData.yaml
</span><span style="color:#4e9a06">VEGETABLE: carrot
</span><span style="color:#4e9a06">ROCKET: saturn-v
</span><span style="color:#4e9a06">FRUIT: apple
</span><span style="color:#4e9a06">CAR: dymaxion
</span><span style="color:#4e9a06">EOF</span>
</code></pre></div><p>Encrypt the data into file the plugin wants to read:</p>
<p>With PGP</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">$tmpGoPath</span>/bin/sops --encrypt <span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span> --pgp <span style="color:#000">$SOPS_PGP_FP</span> <span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span> <span style="color:#000">$MYAPP</span>/myClearData.yaml &gt;<span style="color:#000">$MYAPP</span>/myEncryptedData.yaml
</code></pre></div><p>Or GCP KMS</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">$tmpGoPath</span>/bin/sops --encrypt <span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span> --gcp-kms <span style="color:#000">$keyLocation</span> <span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span> <span style="color:#000">$MYAPP</span>/myClearData.yaml &gt;<span style="color:#000">$MYAPP</span>/myEncryptedData.yaml
</code></pre></div><p>Review the files</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">tree <span style="color:#000">$DEMO</span>
</code></pre></div><p>This should look something like:</p>
<blockquote>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">/tmp/tmp.0kIE9VclPt
├── kustomize
│   └── plugin
│   └── mygenerators
│   └── sopsencodedsecrets
│   ├── go.mod
│   ├── go.sum
│   ├── LICENSE
│   ├── README.md
│   ├── SopsEncodedSecrets.go
│   ├── SopsEncodedSecrets.so
│   └── SopsEncodedSecrets_test.go
└── myapp
├── kustomization.yaml
├── myClearData.yaml
├── myEncryptedData.yaml
└── secGenerator.yaml
</code></pre></div></blockquote>
<h2 id="build-your-app-using-the-plugin">Build your app, using the plugin:</h2>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">XDG_CONFIG_HOME</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$DEMO</span> <span style="color:#000">$tmpGoPath</span>/bin/kustomize build --enable_alpha_plugins <span style="color:#000">$MYAPP</span>
</code></pre></div><p>This should emit a kubernetes secret, with
encrypted data for the names <code>ROCKET</code> and <code>CAR</code>.</p>
<p>Above, if you had set</p>
<blockquote>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#000">PLUGIN_ROOT</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$HOME</span>/.config/kustomize/plugin
</code></pre></div></blockquote>
<p>there would be no need to use <code>XDG_CONFIG_HOME</code> in the
<em>kustomize</em> command above.</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/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>

753
docs/guides/plugins/index.html Normal file
View File

@@ -0,0 +1,753 @@
<!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/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="/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>
</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/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&rsquo;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&rsquo;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&rsquo;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&rsquo;s no notion
of <em>&ldquo;plugin security&rdquo;</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>&quot;true&quot;</code> and <code>&quot;false&quot;</code> which respectively enable or disable hash suffixing for the resource. Omitting the annotation is equivalent to setting the value <code>&quot;false&quot;</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">&#34;true&#34;</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 &ldquo;create&rdquo;, &ldquo;merge&rdquo;, and &ldquo;replace&rdquo; with &ldquo;create&rdquo; 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">&#34;merge&#34;</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
&lsquo;main&rsquo; as it&rsquo;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 &lsquo;KustomizePlugin&rsquo; 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 (
&quot;sigs.k8s.io/kustomize/api/ifc&quot;
&quot;sigs.k8s.io/kustomize/api/resmap&quot;
...
)
type plugin struct {...}
var KustomizePlugin plugin
func (p *plugin) Config(
ldr ifc.Loader,
rf *resmap.Factory,
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&rsquo;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.</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&rsquo;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 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>

1076
docs/guides/plugins/index.xml Normal file
View File

File diff suppressed because it is too large Load Diff