kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-05-18 05:15:19 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity
Files
537ff024ddadf946a615afd602a8fe9b78ef498f
kustomize/docs/zh/guides/plugins/index.html
Syam Sundar K 3e5989ae18 docs/ build
2020-08-26 18:11:27 +05:30

680 lines
39 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="zh" 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.74.3" />
<META NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW">
<link rel="alternate" type="application/rss&#43;xml" href="https://kubernetes-sigs.github.io/kustomize/zh/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 插件 | Kustomize</title><meta property="og:title" content="Kustomize 插件" />
<meta property="og:description" content="Kustomize 插件指南
" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://kubernetes-sigs.github.io/kustomize/zh/guides/plugins/" />
<meta property="og:site_name" content="Kustomize" />
<meta itemprop="name" content="Kustomize 插件">
<meta itemprop="description" content="Kustomize 插件指南
">
<meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Kustomize 插件"/>
<meta name="twitter:description" content="Kustomize 插件指南
"/>
<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 插件 | 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/zh/">
<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/zh/installation/" ><span>安装</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link active" href="/kustomize/zh/guides/" ><span class="active">指南</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/zh/api-reference/" ><span>API 参考</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="https://github.com/kubernetes-sigs/kustomize/tree/master/examples" target="_blank" ><span>Example</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/zh/faq/" ><span>FAQ</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/zh/blog/" ><span>博客</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/kustomize/zh/contributing/" ><span>贡献指南</span></a>
</li>
<li class="nav-item dropdown d-none d-lg-block">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
简体中文
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
<a class="dropdown-item" href="/kustomize/guides/plugins/">English</a>
</div>
</li>
</ul>
</div>
<div class="navbar-nav d-none d-lg-block">
</div>
</nav>
</header>
<div class="container-fluid td-outer">
<div class="td-main">
<div class="row flex-xl-nowrap">
<div class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
<div id="td-sidebar-menu" class="td-sidebar__inner">
<form class="td-sidebar__search d-flex align-items-center">
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-docs-nav" aria-expanded="false" aria-label="Toggle section navigation">
</button>
</form>
<nav class="collapse td-sidebar-nav pt-2 pl-4" id="td-section-nav">
<div class="nav-item dropdown d-block d-lg-none">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
简体中文
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
<a class="dropdown-item" href="/kustomize/guides/plugins/">English</a>
</div>
</div>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/zh/guides/" class="align-left pl-0 pr-2 td-sidebar-link td-sidebar-link__section">指南</a>
</li>
<ul>
<li class="collapse show" id="kustomizezhguides">
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/zh/guides/bespoke/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">配置定制（Bespoke configuration）</a>
</li>
<ul>
<li class="collapse " id="kustomizezhguidesbespoke">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/zh/guides/offtheshelf/" class="align-left pl-0 pr-2 collapsed td-sidebar-link td-sidebar-link__section">通用配置（Off-the-shelf configuration）</a>
</li>
<ul>
<li class="collapse " id="kustomizezhguidesofftheshelf">
</li>
</ul>
</ul>
<ul class="td-sidebar-nav__section pr-md-3">
<li class="td-sidebar-nav__section-title">
<a href="/kustomize/zh/guides/plugins/" class="align-left pl-0 pr-2 active td-sidebar-link td-sidebar-link__section">Kustomize 插件</a>
</li>
<ul>
<li class="collapse show" id="kustomizezhguidesplugins">
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizezhguidespluginsbuiltins" href="/kustomize/zh/guides/plugins/builtins/">内置插件</a>
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizezhguidespluginsexecpluginguidedexample" href="/kustomize/zh/guides/plugins/execpluginguidedexample/">Exec 插件示例</a>
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizezhguidespluginsgoplugincaveats" href="/kustomize/zh/guides/plugins/goplugincaveats/">Go 插件注意事项</a>
<a class="td-sidebar-link td-sidebar-link__page " id="m-kustomizezhguidespluginsgopluginguidedexample" href="/kustomize/zh/guides/plugins/gopluginguidedexample/">Go 插件示例</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/zh/guides/plugins/_index.md" target="_blank"><i class="fa fa-edit fa-fw"></i> 编辑此页</a>
<a href="https://github.com/kubernetes-sigs/kustomize/issues/new?title=Kustomize%20%e6%8f%92%e4%bb%b6" target="_blank"><i class="fab fa-github fa-fw"></i> 提交文档问题</a>
<a href="https://github.com/kubernetes-sigs/kustomize/issues/new" target="_blank"><i class="fas fa-tasks fa-fw"></i> 提交项目问题</a>
</div>
<nav id="TableOfContents">
<ul>
<li><a href="#kustomizationyaml-的格式"><code>kustomization.yaml</code> 的格式</a></li>
<li><a href="#配置">配置</a></li>
<li><a href="#植入">植入</a></li>
<li><a href="#执行情况">执行情况</a>
<ul>
<li></li>
</ul>
</li>
<li><a href="#编写插件">编写插件</a>
<ul>
<li><a href="#exec-插件">Exec 插件</a></li>
<li><a href="#go-插件">Go 插件</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/zh/guides/">指南</a>
</li>
<li class="breadcrumb-item active" aria-current="page">
<a href="https://kubernetes-sigs.github.io/kustomize/zh/guides/plugins/">Kustomize 插件</a>
</li>
</ol>
</nav >
<div class="td-content">
<h1>Kustomize 插件</h1>
<div class="lead">Kustomize 插件指南</div>
<p>Kustomize 提供一个插件框架，允许用户开发自己的 <em>生成器</em> 和 <em>转化器</em>。</p>
<p>通过插件，实现 [generatorOptions] 和 [transformerconfigs] 无法满足的需求。</p>
<ul>
<li><em>generator</em> 插件生成 k8s 资源，比如 <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator">helm chart inflator</a> 是一个 generator 插件，基于少量自由变量生成一个 <a href="https://12factor.net">12-factor</a> 应用所包含的全部组件 deployment，service，scaler，ingress 等）也是一个 generator 插件。</li>
<li><em>transformer</em> 插件转化（修改）k8s 资源，比如可能会执行对特殊容器命令行的编辑，或为其他内置转换器（<code>namePrefix</code>、<code>commonLabels</code> 等）无法转换的内容提供转换。</li>
</ul>
<h2 id="kustomizationyaml-的格式"><code>kustomization.yaml</code> 的格式</h2>
<p>从为添加 <code>generators</code> 或 <code>transformers</code> 字段开始。</p>
<p>字段内容为一个 string list：</p>
<blockquote>
<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">generators</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>- relative/path/to/some/file.yaml<span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span>- relative/path/to/some/kustomization<span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span>- /absolute/path/to/some/kustomization<span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span>- https<span style="color:#000;font-weight:bold">:</span>//github.com/org/repo/some/kustomization<span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">transformers</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>- {as<span style="color:#f8f8f8;text-decoration:underline"> </span>above}<span style="color:#f8f8f8;text-decoration:underline">
</span></code></pre></div></blockquote>
<p>格式要求与 <code>resources</code> 字段相同，<code>generators</code> 或 <code>transformers</code> 列表的每一列内容都必须是一个 YAML 文件的相对路径或者指向 <a href="/kustomize/zh/api-reference/glossary#kustomization">kustomization</a> 的 URL。</p>
<p>从磁盘上读取 YAML 文件，kustomization 的路径或 URL 会触发 kustomization 的运行。由此产生的每个的对象都会被 kustomize 进一步解析为 <em>plugin configuration</em> 对象。</p>
<h2 id="配置">配置</h2>
<p>kustomization 文件可以包含如下内容：</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">generators</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>- chartInflator.yaml<span style="color:#f8f8f8;text-decoration:underline">
</span></code></pre></div><p>像这样，kustomization 进程将在 <a href="glossary.md#kustomization-root">kustomization root</a> 下寻找到一个名为 <code>chartInflator.yaml</code> 的文件。</p>
<p><code>chartInflator.yaml</code> 为插件配置文件，该文件包含 YAML 配置对象，内容如下：</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>someteam.example.com/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>ChartInflator<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>notImportantHere<span style="color:#f8f8f8;text-decoration:underline">
</span><span style="color:#f8f8f8;text-decoration:underline"></span><span style="color:#204a87;font-weight:bold">chartName</span><span style="color:#000;font-weight:bold">:</span><span style="color:#f8f8f8;text-decoration:underline"> </span>minecraft<span style="color:#f8f8f8;text-decoration:underline">
</span></code></pre></div><p><strong><code>apiVersion</code> 和 <code>kind</code> 字段用于定位插件。</strong></p>
<p>同时由于 kustomize 插件配置对象也是一个 <a href="/kustomize/zh/api-reference/glossary#Kubernetes-%E9%A3%8E%E6%A0%BC%E7%9A%84%E5%AF%B9%E8%B1%A1">k8s 对象</a>，因此这些字段是必要的。</p>
<p>为了让插件准备好生成或转换，它包含了配置文件的全部内容。</p>
<p>更多关于插件配置 YAML 的例子，请浏览根目录下 <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin">plugins</a> 中的单元测试，例如 <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator/ChartInflator_test.go">ChartInflator</a> 或 <a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin/prefixsuffixtransformer/PrefixSuffixTransformer_test.go">NameTransformer</a>。</p>
<h2 id="植入">植入</h2>
<p>每个插件都有自己的专用目录，名为：</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-bash" data-lang="bash"><span style="color:#000">$XDG_CONFIG_HOME</span>/kustomize/plugin
/<span style="color:#4e9a06">${</span><span style="color:#000">apiVersion</span><span style="color:#4e9a06">}</span>/LOWERCASE<span style="color:#ce5c00;font-weight:bold">(</span><span style="color:#4e9a06">${</span><span style="color:#000">kind</span><span style="color:#4e9a06">}</span><span style="color:#ce5c00;font-weight:bold">)</span>
</code></pre></div><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><a href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html"><code>XDG_CONFIG_HOME</code></a> 的默认值为 <code>$HOME/.config</code>。</p>
<p>为了便于插件包（源码、测试、插件数据文件等）的共享，要求每个目录存放一个插件。</p>
<p>在 <a href="#go-%E6%8F%92%E4%BB%B6">Go 插件</a>中，还可以为单个插件提供一个 <code>go.mod</code> 文件，可以缓解包版本依赖性偏移的问题。</p>
<p>加载时，kustomize 首先会寻找一个 <em>可执行</em> 文件，名为：</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-bash" data-lang="bash"><span style="color:#000">$XDG_CONFIG_HOME</span>/kustomize/plugin
/<span style="color:#4e9a06">${</span><span style="color:#000">apiVersion</span><span style="color:#4e9a06">}</span>/LOWERCASE<span style="color:#ce5c00;font-weight:bold">(</span><span style="color:#4e9a06">${</span><span style="color:#000">kind</span><span style="color:#4e9a06">}</span><span style="color:#ce5c00;font-weight:bold">)</span>/<span style="color:#4e9a06">${</span><span style="color:#000">kind</span><span style="color:#4e9a06">}</span>
</code></pre></div><p>如果没有找到这个文件，或者这个文件不是可执行的，kustomize 会在同一目录下寻找一个名为 <code>${kind}.so</code> 的文件，并尝试将其作为 <a href="#go-%E6%8F%92%E4%BB%B6">Go插件</a> 加载。</p>
<p>如果这两项检查都失败，则插件加载失败，<code>kustomize build</code> 失败。</p>
<h2 id="执行情况">执行情况</h2>
<p>插件只有在运行 <code>kustomize build</code> 命令时使用。</p>
<p>生成器插件是在处理完 <code>resources</code> 字段后运行的（<code>resources</code> 字段本身也可以看成是一个简单地从磁盘上读取对象的生成器）。</p>
<p>之后所有资源将被传递到转换管道中，由其中内置的转换器，如 <code>namePrefix</code> 和 <code>commonLabel</code> 等先转换应用（如果 kustomization 文件中指定了他们），然后再转换用户指定的 <code>transformers</code> 字段。</p>
<p>由于无法指定转化的顺序，所以需要遵守 <code>transformers</code> 字段中指定的顺序。</p>
<h4 id="no-security">No Security</h4>
<p>Kustomize 插件不会在任何形式的 kustomize 提供的沙盒中运行。不存在 <em>&ldquo;plugin security&rdquo;</em> 的概念。</p>
<p><code>kustomize build</code> 会尝试使用插件，但如果省略了 <code>--enable_alpha_plugins</code>，将导致插件无法加载，并且会有一个关于插件使用的警告。</p>
<p>使用这个 flag 就是承认使用不稳定的插件 API（alpha）、承认使用缺少出处插件，以及插件不属于 kustomize 的事实。</p>
<p>简单的说，一些从网上下载的 kustomize 插件可能会奇妙地将 k8s 的配置以理想的方式进行改造，同时也会悄悄地对运行 <code>kustomize build</code> 的系统做任何用户可以做的事情。</p>
<h2 id="编写插件">编写插件</h2>
<p>插件有 <a href="#exec-%E6%8F%92%E4%BB%B6">exec</a> 和 <a href="#go-%E6%8F%92%E4%BB%B6">Go</a> 两种.</p>
<h3 id="exec-插件">Exec 插件</h3>
<p><em>exec 插件</em> 是一个可以在命令行中接收参数可执行文件，该参数指向包含 kustomization 配置的 YAML 文件。</p>
<blockquote>
<p>TODO: 对插件的限制，允许同一个 <em>exec 插件</em> 同时被 <code>generators</code> 和 <code>transformers</code> 字段所触发。</p>
<ul>
<li>第一个参数可以是固定的字符串 <code>generate</code> 或 <code>transform</code>，（配置文件的名称移动到第2个参数）</li>
<li>默认情况下，exec plugin 会作为一个转化器,除非提供了标志 <code>-g</code>，将 exec 插件切换为生成器。</li>
</ul>
</blockquote>
<h4 id="示例">示例</h4>
<ul>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator">helm chart inflator</a> - helm chart inflates 生成器。</li>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/bashedconfigmap">bashed config map</a> - 使用 bash 生成十分简单的 configMap。</li>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/sedtransformer">sed transformer</a> - 使用插件来定义非结构化的编辑。</li>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/gogetter">hashicorp go-getter</a> - 下载 kustomize layes 并通过构建它来生成资源。</li>
</ul>
<p>生成器插件无需在 <code>stdin</code> 上输入任何东西，就会将生成的资源输出到 <code>stdout</code>。</p>
<p>转化器插件需要在 <code>stdin</code> 上输入资源的 YAML，并转化后的资源输出到 <code>stdout</code>。</p>
<p>kustomize 会使用 exec 插件适配器，为 <code>stdin</code> 提供的资源，并获取 <code>stdout</code> 以进行下一步的处理。</p>
<h4 id="generator-选项">Generator 选项</h4>
<p>生成器 exec 插件可以通过设置以下内部注释中的一个来调整生成器选项。</p>
<blockquote>
<p>注意：这些注释只会在本地的 kustomize 中，不会出现在最终输出中。</p>
</blockquote>
<p><strong><code>kustomize.config.k8s.io/needs-hash</code></strong></p>
<p>通过包含 <code>needs-hash</code> 注释，可以将资源标记为需要由内部哈希转换器处理的资源。当设置注释的有效值为 <code>&quot;true&quot;</code> 和 <code>&quot;false&quot;</code> 时，分别启用或禁用资源的哈希后缀。忽略该注解相当于将值设置为 <code>&quot;false&quot;</code>。</p>
<p>如果此注释被设置在不受哈希转换器支持的资源上，将导致构建将失败。</p>
<p>示例：</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><code>behavior</code> 注释为当资源发生冲突时插件的处理方式，有效值包括：&ldquo;create&rdquo;、&ldquo;merge &ldquo;和 &ldquo;replace&rdquo;，默认为 &ldquo;create&rdquo;。</p>
<p>示例：</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-插件">Go 插件</h3>
<p>请务必阅读 <a href="goPluginCaveats.md">Go 插件注意事项</a>。</p>
<p>如果一个 <code>.go</code> 文件声明 <code>package main</code>，并附加了有用的功能标志，那么它就可以成为一个 <a href="https://golang.org/pkg/plugin/">Go 插件</a>。</p>
<p>如果标志被命名为 “KustomizePlugin”，并且附加的函数实现了 <code>Configurable</code>、<code>Generator</code> 和 <code>Transformer</code> 接口，那么它可以进一步作为 <em>kustomize</em> 插件使用。</p>
<p>kustomize 的一个 Go 插件看起来是这样的：</p>
<blockquote>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-go" data-lang="go"><span style="color:#204a87;font-weight:bold">package</span> <span style="color:#000">main</span>
<span style="color:#204a87;font-weight:bold">import</span> <span style="color:#000;font-weight:bold">(</span>
<span style="color:#4e9a06">&#34;sigs.k8s.io/kustomize/api/ifc&#34;</span>
<span style="color:#4e9a06">&#34;sigs.k8s.io/kustomize/api/resmap&#34;</span>
<span style="color:#ce5c00;font-weight:bold">...</span>
<span style="color:#000;font-weight:bold">)</span>
<span style="color:#204a87;font-weight:bold">type</span> <span style="color:#000">plugin</span> <span style="color:#204a87;font-weight:bold">struct</span> <span style="color:#000;font-weight:bold">{</span><span style="color:#ce5c00;font-weight:bold">...</span><span style="color:#000;font-weight:bold">}</span>
<span style="color:#204a87;font-weight:bold">var</span> <span style="color:#000">KustomizePlugin</span> <span style="color:#000">plugin</span>
<span style="color:#204a87;font-weight:bold">func</span> <span style="color:#000;font-weight:bold">(</span><span style="color:#000">p</span> <span style="color:#ce5c00;font-weight:bold">*</span><span style="color:#000">plugin</span><span style="color:#000;font-weight:bold">)</span> <span style="color:#000">Config</span><span style="color:#000;font-weight:bold">(</span>
<span style="color:#000">ldr</span> <span style="color:#000">ifc</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">Loader</span><span style="color:#000;font-weight:bold">,</span>
<span style="color:#000">rf</span> <span style="color:#ce5c00;font-weight:bold">*</span><span style="color:#000">resmap</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">Factory</span><span style="color:#000;font-weight:bold">,</span>
<span style="color:#000">c</span> <span style="color:#000;font-weight:bold">[]</span><span style="color:#204a87;font-weight:bold">byte</span><span style="color:#000;font-weight:bold">)</span> <span style="color:#204a87;font-weight:bold">error</span> <span style="color:#000;font-weight:bold">{</span><span style="color:#ce5c00;font-weight:bold">...</span><span style="color:#000;font-weight:bold">}</span>
<span style="color:#204a87;font-weight:bold">func</span> <span style="color:#000;font-weight:bold">(</span><span style="color:#000">p</span> <span style="color:#ce5c00;font-weight:bold">*</span><span style="color:#000">plugin</span><span style="color:#000;font-weight:bold">)</span> <span style="color:#000">Generate</span><span style="color:#000;font-weight:bold">()</span> <span style="color:#000;font-weight:bold">(</span><span style="color:#000">resmap</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">ResMap</span><span style="color:#000;font-weight:bold">,</span> <span style="color:#204a87;font-weight:bold">error</span><span style="color:#000;font-weight:bold">)</span> <span style="color:#000;font-weight:bold">{</span><span style="color:#ce5c00;font-weight:bold">...</span><span style="color:#000;font-weight:bold">}</span>
<span style="color:#204a87;font-weight:bold">func</span> <span style="color:#000;font-weight:bold">(</span><span style="color:#000">p</span> <span style="color:#ce5c00;font-weight:bold">*</span><span style="color:#000">plugin</span><span style="color:#000;font-weight:bold">)</span> <span style="color:#000">Transform</span><span style="color:#000;font-weight:bold">(</span><span style="color:#000">m</span> <span style="color:#000">resmap</span><span style="color:#000;font-weight:bold">.</span><span style="color:#000">ResMap</span><span style="color:#000;font-weight:bold">)</span> <span style="color:#204a87;font-weight:bold">error</span> <span style="color:#000;font-weight:bold">{</span><span style="color:#ce5c00;font-weight:bold">...</span><span style="color:#000;font-weight:bold">}</span>
</code></pre></div></blockquote>
<p>需要使用标识符 <code>plugin</code>，<code>KustomizePlugin</code> 并且需要实现方法签名 <code>Config</code>。</p>
<p>实现 <code>Generatoror</code> 或 <code>Transformer</code> 方法允许（分别）将插件的配置文件添加到 kustomization 文件的 <code>generatorsor</code> 或 <code>transformers</code> 字段中，并根据需要执行。</p>
<h4 id="示例-1">示例</h4>
<ul>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/someservicegenerator">service generator</a> - 使用 name 和 port 参数生成一个 service。</li>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/stringprefixer">string prefixer</a> - 使用 <code>metadata/name</code> 值作为前缀。这个特殊的示例是为了展示插件的转化行为。详见 <code>target</code> 包中的 <code>TestTransformedTransformers</code> 测试。</li>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/dateprefixer">date prefixer</a> - 将当前日期作为前缀添加到资源名称上，这是一个用于修改刚才提到的字符串前缀插件的简单示例。</li>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/secretsfromdatabase">secret generator</a> - 从 toy 数据库生成 secret。</li>
<li><a href="https://github.com/monopole/sopsencodedsecrets">sops encoded secrets</a> - 一个更复杂的 secret 生成器。</li>
<li><a href="https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin">All the builtin plugins</a>.
用户自制的插件与内置插件是一样的。</li>
</ul>
<p>Go 插件既可以是生成器，也可以是转化器。<code>Generate</code> 方法将在 <code>Transform</code> 方法运行之前与所有其他生成器一起运行。</p>
<p>如下的构建命令，假设插件源代码位于 kustomize 期望查找 <code>.so</code> 文件的目录中：</p>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-bash" data-lang="bash"><span style="color:#000">d</span><span style="color:#ce5c00;font-weight:bold">=</span><span style="color:#000">$XDG_CONFIG_HOME</span>/kustomize/plugin<span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span>/<span style="color:#4e9a06">${</span><span style="color:#000">apiVersion</span><span style="color:#4e9a06">}</span>/LOWERCASE<span style="color:#ce5c00;font-weight:bold">(</span><span style="color:#4e9a06">${</span><span style="color:#000">kind</span><span style="color:#4e9a06">}</span><span style="color:#ce5c00;font-weight:bold">)</span>
go build -buildmode plugin <span style="color:#4e9a06">\
</span><span style="color:#4e9a06"></span> -o <span style="color:#000">$d</span>/<span style="color:#4e9a06">${</span><span style="color:#000">kind</span><span style="color:#4e9a06">}</span>.so <span style="color:#000">$d</span>/<span style="color:#4e9a06">${</span><span style="color:#000">kind</span><span style="color:#4e9a06">}</span>.go
</code></pre></div>
<div class="section-index">
<hr class="panel-line">
<div class="entry">
<h5>
<a href="/kustomize/zh/guides/plugins/builtins/">内置插件</a>
</h5>
<p>内置插件</p>
</div>
<div class="entry">
<h5>
<a href="/kustomize/zh/guides/plugins/execpluginguidedexample/">Exec 插件示例</a>
</h5>
<p>60 秒在 Linux 构建一个 Exec 插件</p>
</div>
<div class="entry">
<h5>
<a href="/kustomize/zh/guides/plugins/goplugincaveats/">Go 插件注意事项</a>
</h5>
<p>Go 插件注意事项</p>
</div>
<div class="entry">
<h5>
<a href="/kustomize/zh/guides/plugins/gopluginguidedexample/">Go 插件示例</a>
</h5>
<p>Go 插件示例</p>
</div>
</div>
<div class="text-muted mt-5 pt-3 border-top">最后修改 2020年07月16日: <a href="https://github.com/kubernetes-sigs/kustomize/commit/f9ee578aed600136133c3232fff03029cdfc526e">Docs: Auto-fix markdownlint issues (f9ee578a)</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>
Reference in New Issue View Git Blame Copy Permalink