diff --git a/site/content/en/api-reference/_index.md b/site/content/en/api-reference/_index.md index 1c6be44dd..d4d3479e3 100644 --- a/site/content/en/api-reference/_index.md +++ b/site/content/en/api-reference/_index.md @@ -10,4 +10,6 @@ description: > Reference for Kustomize client-side APIs --- - \ No newline at end of file + + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/glossary/_index.md b/site/content/en/api-reference/glossary/_index.md index 2c72782ff..f4bcd80ed 100644 --- a/site/content/en/api-reference/glossary/_index.md +++ b/site/content/en/api-reference/glossary/_index.md @@ -8,474 +8,3 @@ description: > --- - - -# Glossary - -[CRD spec]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/ -[CRD]: #custom-resource-definition -[DAM]: #declarative-application-management -[Declarative Application Management]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md -[JSON]: https://www.json.org/ -[JSONPatch]: https://tools.ietf.org/html/rfc6902 -[JSONMergePatch]: https://tools.ietf.org/html/rfc7386 -[Resource]: #resource -[YAML]: http://www.yaml.org/start.html -[application]: #application -[apply]: #apply -[apt]: https://en.wikipedia.org/wiki/APT_(Debian) -[base]: #base -[bases]: #base -[bespoke]: #bespoke-configuration -[gitops]: #gitops -[k8s]: #kubernetes -[kubernetes]: #kubernetes -[kustomize]: #kustomize -[kustomization]: #kustomization -[kustomizations]: #kustomization -[off-the-shelf]: #off-the-shelf-configuration -[overlay]: #overlay -[overlays]: #overlay -[patch]: #patch -[patches]: #patch -[patchJson6902]: #patchjson6902 -[patchExampleJson6902]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/jsonpatch.md -[patchesJson6902]: #patchjson6902 -[proposal]: https://github.com/kubernetes/community/pull/1629 -[rebase]: https://git-scm.com/docs/git-rebase -[resource]: #resource -[resources]: #resource -[root]: #kustomization-root -[rpm]: https://en.wikipedia.org/wiki/Rpm_(software) -[strategic-merge]: https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md -[target]: #target -[transformer]: #transformer -[variant]: #variant -[variants]: #variant -[workflow]: /kustomize/guides - -## application - -An _application_ is a group of k8s resources related by -some common purpose, e.g. a load balancer in front of a -webserver backed by a database. -[Resource] labelling, naming and metadata schemes have -historically served to group resources together for -collective operations like _list_ and _remove_. - -This [proposal] describes a new k8s resource called -_application_ to more formally describe this idea and -provide support for application-level operations and -dashboards. - -[kustomize] configures k8s resources, and the proposed -application resource is just another resource. - -## apply - -The verb _apply_ in the context of k8s refers to a -kubectl command and an in-progress [API -endpoint](https://goo.gl/UbCRuf) for mutating a -cluster. - -One _applies_ a statement of what one wants to a -cluster in the form of a complete resource list. - -The cluster merges this with the previously applied -state and the actual state to arrive at a new desired -state, which the cluster's reconciliation loop attempts -to create. This is the foundation of level-based state -management in k8s. - -## base - -A _base_ is a [kustomization] referred to -by some other [kustomization]. - -Any kustomization, including an [overlay], can be a base to -another kustomization. - -A base has no knowledge of the overlays that refer to it. - -For simple [gitops] management, a base configuration -could be the _sole content of a git repository -dedicated to that purpose_. Same with [overlays]. -Changes in a repo could generate a build, test and -deploy cycle. - -## bespoke configuration - -A _bespoke_ configuration is a [kustomization] and some -[resources] created and maintained internally by some -organization for their own purposes. - -The [workflow] associated with a _bespoke_ config is -simpler than the workflow associated with an -[off-the-shelf] config, because there's no notion of -periodically capturing someone else's upgrades to the -[off-the-shelf] config. - -## custom resource definition - -One can extend the k8s API by making a -Custom Resource Definition ([CRD spec]). - -This defines a custom [resource] (CD), an entirely -new resource that can be used alongside _native_ -resources like ConfigMaps, Deployments, etc. - -Kustomize can customize a CD, but to do so -kustomize must also be given the corresponding CRD -so that it can interpret the structure correctly. - -## declarative application management - -Kustomize aspires to support [Declarative Application Management], -a set of best practices around managing k8s clusters. - -In brief, kustomize should - -* Work with any configuration, be it bespoke, - off-the-shelf, stateless, stateful, etc. -* Support common customizations, and creation of - [variants] (e.g. _development_ vs. - _staging_ vs. _production_). -* Expose and teach native k8s APIs, rather than - hide them. -* Add no friction to version control integration to - support reviews and audit trails. -* Compose with other tools in a unix sense. -* Eschew crossing the line into templating, domain - specific languages, etc., frustrating the other - goals. - -## generator - -A generator makes resources that can be used as is, -or fed into a [transformer]. - -## gitops - -Devops or CICD workflows that use a git repository as a -single source of truth and take action (e.g., build, -test or deploy) when that truth changes. - -## kustomization - -The term _kustomization_ refers to a -`kustomization.yaml` file, or more generally to a -directory (the [root]) containing the -`kustomization.yaml` file and all the relative file -paths that it immediately references (all the local -data that doesn't require a URL specification). - -I.e. if someone gives you a _kustomization_ for use -with [kustomize], it could be in the form of - -* one file called `kustomization.yaml`, -* a tarball (containing that YAML file plus what it references), -* a git archive (ditto), -* a URL to a git repo (ditto), etc. - -A kustomization file contains [fields](fields.md) -falling into four categories: - -* _resources_ - what existing [resources] are to be customized. - Example fields: _resources_, _crds_. - -* _generators_ - what _new_ resources should be created. - Example fields: _configMapGenerator_ (legacy), - _secretGenerator_ (legacy), _generators_ (v2.1). - -* _transformers_ - what to _do_ to the aforementioned resources. - Example fields: _namePrefix_, _nameSuffix_, _images_, - _commonLabels_, _patchesJson6902_, etc. and the more - general _transformers_ (v2.1) field. - -* _meta_ - fields which may influence all or some of - the above. Example fields: _vars_, _namespace_, - _apiVersion_, _kind_, etc. - -## kustomization root - -The directory that immediately contains a -`kustomization.yaml` file. - -When a kustomization file is processed, it may or may -not be able to access files outside its root. - -Data files like resource YAML files, or text files -containing _name=value_ pairs intended for a ConfigMap -or Secret, or files representing a patch to be used in -a patch transformation, must live _within or below_ the -root, and as such are specified via _relative -paths_ exclusively. - -A special flag (in v2.1), `--load_restrictions none`, -is provided to relax this security feature, to, say, -allow a patch file to be shared by more than one -kustomization. - -Other kustomizations (other directories containing a -`kustomization.yaml` file) may be referred to by URL, by -absolute path, or by relative path. - -If kustomization __A__ depends on kustomization __B__, then - -* __B__ may not _contain_ __A__. -* __B__ may not _depend on_ __A__, even transitively. - -__A__ may contain __B__, but in this case it might be -simplest to have __A__ directly depend on __B__'s -resources and eliminate __B__'s kustomization.yaml file -(i.e. absorb __B__ into __A__). - -Conventionally, __B__ is in a directory that's sibling -to __A__, or __B__ is off in a completely independent -git repository, referencable from any kustomization. - -A common layout is - -> ``` -> ├── base -> │   ├── deployment.yaml -> │   ├── kustomization.yaml -> │   └── service.yaml -> └── overlays -> ├── dev -> │   ├── kustomization.yaml -> │   └── patch.yaml -> ├── prod -> │   ├── kustomization.yaml -> │   └── patch.yaml -> └── staging -> ├── kustomization.yaml -> └── patch.yaml -> ``` - -The three roots `dev`, `prod` and `staging` -(presumably) all refer to the `base` root. One would -have to inspect the `kustomization.yaml` files to be -sure. - -## kubernetes - -[Kubernetes](https://kubernetes.io) is an open-source -system for automating deployment, scaling, and -management of containerized applications. - -It's often abbreviated as _k8s_. - -## kubernetes-style object - -[fields required]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields - -An object, expressed in a YAML or JSON file, with the -[fields required] by kubernetes. Basically just a -_kind_ field to identify the type, a _metadata/name_ -field to identify the particular instance, and an -_apiVersion_ field to identify the version (if there's -more than one version). - -## kustomize - -_kustomize_ is a command line tool supporting -template-free, structured customization of declarative -configuration targeted to k8s-style objects. - -_Targeted to k8s means_ that kustomize has some -understanding of API resources, k8s concepts like -names, labels, namespaces, etc. and the semantics of -resource patching. - -kustomize is an implementation of [DAM]. - -## off-the-shelf configuration - -An _off-the-shelf_ configuration is a kustomization and -resources intentionally published somewhere for others -to use. - -E.g. one might create a github repository like this: - -> ``` -> github.com/username/someapp/ -> kustomization.yaml -> deployment.yaml -> configmap.yaml -> README.md -> ``` - -Someone could then _fork_ this repo (on github) and -_clone_ their fork to their local disk for -customization. - -This clone could act as a [base] for the user's -own [overlays] to do further customization. - -## overlay - -An _overlay_ is a kustomization that depends on -another kustomization. - -The [kustomizations] an overlay refers to (via file -path, URI or other method) are called [bases]. - -An overlay is unusable without its bases. - -An overlay may act as a base to another overlay. - -Overlays make the most sense when there is _more than -one_, because they create different [variants] of a -common base - e.g. _development_, _QA_, _staging_ and -_production_ environment variants. - -These variants use the same overall resources, and vary -in relatively simple ways, e.g. the number of replicas -in a deployment, the CPU to a particular pod, the data -source used in a ConfigMap, etc. - -One configures a cluster like this: - -> ``` -> kustomize build someapp/overlays/staging |\ -> kubectl apply -f - -> -> kustomize build someapp/overlays/production |\ -> kubectl apply -f - -> ``` - -Usage of the base is implicit - the overlay's -kustomization points to the base. - -See also [root]. - -## package - -The word _package_ has no meaning in kustomize, as -kustomize is not to be confused with a package -management tool in the tradition of, say, [apt] or -[rpm]. - -## patch - -General instructions to modify a resource. - -There are two alternative techniques with similar -power but different notation - the -[strategic merge patch](#patchstrategicmerge) -and the [JSON patch](#patchjson6902). - -## patchStrategicMerge - -A _patchStrategicMerge_ is [strategic-merge]-style patch (SMP). - -An SMP looks like an incomplete YAML specification of -a k8s resource. The SMP includes `TypeMeta` -fields to establish the group/version/kind/name of the -[resource] to patch, then just enough remaining fields -to step into a nested structure to specify a new field -value, e.g. an image tag. - -By default, an SMP _replaces_ values. This is -usually desired when the target value is a simple -string, but may not be desired when the target -value is a list. - -To change this -default behavior, add a _directive_. Recognized -directives in YAML patches are _replace_ (the default) -and _delete_ (see [these notes][strategic-merge]). - -Note that for custom resources, SMPs are treated as -[json merge patches][JSONMergePatch]. - -Fun fact - any resource file can be used as -an SMP, overwriting matching fields in another -resource with the same group/version/kind/name, -but leaving all other fields as they were. - -TODO(monopole): add ptr to example. - -## patchJson6902 - -A _patchJson6902_ refers to a kubernetes [resource] and -a [JSONPatch] specifying how to change the resource. - -A _patchJson6902_ can do almost everything a -_patchStrategicMerge_ can do, but with a briefer -syntax. See this [example][patchExampleJson6902]. - -## plugin - -A chunk of code used by kustomize, but not necessarily -compiled into kustomize, to generate and/or transform a -kubernetes resource as part of a kustomization. - -Details [here](../../guides/plugins). - -## resource - -A _resource_ in the context of a REST-ful API is the -target object of an HTTP operation like _GET_, _PUT_ or -_POST_. k8s offers a REST-ful API surface to interact -with clients. - -A _resource_, in the context of a kustomization, is a -[root] relative path to a [YAML] or [JSON] file -describing a k8s API object, like a Deployment or a -ConfigMap, or it's a path to a kustomization, or a URL -that resolves to a kustomization. - -More generally, a resource can be any correct YAML file -that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) -with a _kind_ and a _metadata/name_ field. - -## root - -See [kustomization root][root]. - -## sub-target / sub-application / sub-package - -A _sub-whatever_ is not a thing. There are only -[bases] and [overlays]. - -## target - -The _target_ is the argument to `kustomize build`, e.g.: - -> ``` -> kustomize build $target -> ``` - -`$target` must be a path or a url to a [kustomization]. - -The target contains, or refers to, all the information -needed to create customized resources to send to the -[apply] operation. - -A target can be a [base] or an [overlay]. - -## transformer - -A transformer can modify a resource, or merely -visit it and collect information about it in the -course of a `kustomize build`. - -## variant - -A _variant_ is the outcome, in a cluster, of applying -an [overlay] to a [base]. - -E.g., a _staging_ and _production_ overlay both modify -some common base to create distinct variants. - -The _staging_ variant is the set of resources exposed -to quality assurance testing, or to some external users -who'd like to see what the next version of production -will look like. - -The _production_ variant is the set of resources -exposed to production traffic, and thus may employ -deployments with a large number of replicas and higher -cpu and memory requests. diff --git a/site/content/en/api-reference/kustomization/_index.md b/site/content/en/api-reference/kustomization/_index.md index c7c048d14..2d9358aa1 100644 --- a/site/content/en/api-reference/kustomization/_index.md +++ b/site/content/en/api-reference/kustomization/_index.md @@ -9,4 +9,4 @@ description: > - +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/bases/_index.md b/site/content/en/api-reference/kustomization/bases/_index.md index a2c61ecec..f30bcd5f2 100644 --- a/site/content/en/api-reference/kustomization/bases/_index.md +++ b/site/content/en/api-reference/kustomization/bases/_index.md @@ -8,11 +8,4 @@ description: > -{{% pageinfo color="warning" %}} -The `bases` field was deprecated in v2.1.0 -{{% /pageinfo %}} - -Move entries into the [resources](/kustomize/api-reference/kustomization/resources) -field. This allows bases - which are still a -[central concept](/kustomize/api-reference/glossary#base) - to be -ordered relative to other input resources. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/commonannotations/_index.md b/site/content/en/api-reference/kustomization/commonannotations/_index.md index af5becd99..96c41da26 100644 --- a/site/content/en/api-reference/kustomization/commonannotations/_index.md +++ b/site/content/en/api-reference/kustomization/commonannotations/_index.md @@ -8,52 +8,4 @@ description: > -Add annotations to all resources. If the annotation key is already present on the resource, -the value will be overridden. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -commonAnnotations: - oncallPager: 800-555-1212 -``` - -## Example - -### File Input - -```yaml -# kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -commonAnnotations: - oncallPager: 800-555-1212 - -resources: -- deploy.yaml -``` - -```yaml -# deploy.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example -spec: - ... -``` - -### Build Output - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example - annotations: - oncallPager: 800-555-1212 -spec: - ... -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/commonlabels/_index.md b/site/content/en/api-reference/kustomization/commonlabels/_index.md index af840a2da..056b89d49 100644 --- a/site/content/en/api-reference/kustomization/commonlabels/_index.md +++ b/site/content/en/api-reference/kustomization/commonlabels/_index.md @@ -8,97 +8,4 @@ description: > - -Add labels and selectors to all resources. If the label key already is present on the resource, -the value will be overridden. - -{{% pageinfo color="warning" %}} -Selectors for resources such as Deployments and Services shouldn't be changed once the -resource has been applied to a cluster. - -Changing commonLabels to live resources could result in failures. -{{% /pageinfo %}} - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -commonLabels: - someName: someValue - owner: alice - app: bingo -``` - -## Example - -### File Input - -```yaml -# kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -commonLabels: - someName: someValue - owner: alice - app: bingo - -resources: -- deploy.yaml -- service.yaml -``` - -```yaml -# deploy.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example -``` - -```yaml -# service.yaml -apiVersion: v1 -kind: Service -metadata: - name: example -``` - -### Build Output - -```yaml -apiVersion: v1 -kind: Service -metadata: - labels: - app: bingo - owner: alice - someName: someValue - name: example -spec: - selector: - app: bingo - owner: alice - someName: someValue ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - app: bingo - owner: alice - someName: someValue - name: example -spec: - selector: - matchLabels: - app: bingo - owner: alice - someName: someValue - template: - metadata: - labels: - app: bingo - owner: alice - someName: someValue -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/components/_index.md b/site/content/en/api-reference/kustomization/components/_index.md index aed56fe20..5fdb7df25 100644 --- a/site/content/en/api-reference/kustomization/components/_index.md +++ b/site/content/en/api-reference/kustomization/components/_index.md @@ -8,4 +8,4 @@ description: > -Please see +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/configmapgenerator/_index.md b/site/content/en/api-reference/kustomization/configmapgenerator/_index.md index 4131e4c87..143678759 100644 --- a/site/content/en/api-reference/kustomization/configmapgenerator/_index.md +++ b/site/content/en/api-reference/kustomization/configmapgenerator/_index.md @@ -8,87 +8,4 @@ description: > - -Each entry in this list results in the creation of -one ConfigMap resource (it's a generator of n maps). - -The example below creates four ConfigMaps: - -- first, with the names and contents of the given files -- second, with key/value as data using key/value pairs from files -- third, also with key/value as data, directly specified using `literals` -- and a fourth, which sets an annotation and label via `options` for that single ConfigMap - -Each configMapGenerator item accepts a parameter of -`behavior: [create|replace|merge]`. -This allows an overlay to modify or -replace an existing configMap from the parent. - -Also, each entry has an `options` field, that has the -same subfields as the kustomization file's `generatorOptions` field. - -This `options` field allows one to add labels and/or -annotations to the generated instance, or to individually -disable the name suffix hash for that instance. -Labels and annotations added here will not be overwritten -by the global options associated with the kustomization -file `generatorOptions` field. However, due to how -booleans behave, if the global `generatorOptions` field -specifies `disableNameSuffixHash: true`, this will -trump any attempt to locally override it. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -# These labels are added to all configmaps and secrets. -generatorOptions: - labels: - fruit: apple - -configMapGenerator: -- name: my-java-server-props - behavior: merge - files: - - application.properties - - more.properties -- name: my-java-server-env-file-vars - envs: - - my-server-env.properties - - more-server-props.env -- name: my-java-server-env-vars - literals: - - JAVA_HOME=/opt/java/jdk - - JAVA_TOOL_OPTIONS=-agentlib:hprof - options: - disableNameSuffixHash: true - labels: - pet: dog -- name: dashboards - files: - - mydashboard.json - options: - annotations: - dashboard: "1" - labels: - app.kubernetes.io/name: "app1" -``` - -It is also possible to -[define a key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file) -to set a name different than the filename. - -The example below creates a ConfigMap -with the name of file as `myFileName.ini` -while the _actual_ filename from which the -configmap is created is `whatever.ini`. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -configMapGenerator: -- name: app-whatever - files: - - myFileName.ini=whatever.ini -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/crds/_index.md b/site/content/en/api-reference/kustomization/crds/_index.md index e89031af8..8f266bcd4 100644 --- a/site/content/en/api-reference/kustomization/crds/_index.md +++ b/site/content/en/api-reference/kustomization/crds/_index.md @@ -8,36 +8,4 @@ description: > - -Each entry in this list should be a relative path to -a file for custom resource definition (CRD). - -The presence of this field is to allow kustomize be -aware of CRDs and apply proper -transformation for any objects in those types. - -Typical use case: A CRD object refers to a -ConfigMap object. In a kustomization, the ConfigMap -object name may change by adding namePrefix, -nameSuffix, or hashing. The name reference for this -ConfigMap object in CRD object need to be updated -with namePrefix, nameSuffix, or hashing in the -same way. - -The annotations can be put into openAPI definitions are: - -- "x-kubernetes-annotation": "" -- "x-kubernetes-label-selector": "" -- "x-kubernetes-identity": "" -- "x-kubernetes-object-ref-api-version": "v1", -- "x-kubernetes-object-ref-kind": "Secret", -- "x-kubernetes-object-ref-name-key": "name", - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -crds: -- crds/typeA.yaml -- crds/typeB.yaml -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/generatoroptions/_index.md b/site/content/en/api-reference/kustomization/generatoroptions/_index.md index 79719cd6f..b52640d0f 100644 --- a/site/content/en/api-reference/kustomization/generatoroptions/_index.md +++ b/site/content/en/api-reference/kustomization/generatoroptions/_index.md @@ -9,24 +9,4 @@ description: > - -Additionally, generatorOptions can be set on a per resource level within each -generator. For details on per-resource generatorOptions usage see -[field-name-configMapGenerator](/kustomize/api-reference/kustomization/configmapgenerator) and See [field-name-secretGenerator](/kustomize/api-reference/kustomization/secretgenerator). - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -generatorOptions: - # labels to add to all generated resources - labels: - kustomize.generated.resources: somevalue - # annotations to add to all generated resources - annotations: - kustomize.generated.resource: somevalue - # disableNameSuffixHash is true disables the default behavior of adding a - # suffix to the names of generated resources that is a hash of - # the resource contents. - disableNameSuffixHash: true -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/images/_index.md b/site/content/en/api-reference/kustomization/images/_index.md index 6d9465ce6..135b478a3 100644 --- a/site/content/en/api-reference/kustomization/images/_index.md +++ b/site/content/en/api-reference/kustomization/images/_index.md @@ -8,48 +8,4 @@ description: > - -Images modify the name, tags and/or digest for images without creating patches. E.g. Given this -kubernetes Deployment fragment: - -```yaml -kind: Deployment -... -spec: - template: - spec: - containers: - - name: mypostgresdb - image: postgres:8 - - name: nginxapp - image: nginx:1.7.9 - - name: myapp - image: my-demo-app:latest - - name: alpine-app - image: alpine:3.7 -``` - -one can change the `image` in the following ways: - -- `postgres:8` to `my-registry/my-postgres:v1`, -- nginx tag `1.7.9` to `1.8.0`, -- image name `my-demo-app` to `my-app`, -- alpine's tag `3.7` to a digest value - -all with the following *kustomization*: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -images: -- name: postgres - newName: my-registry/my-postgres - newTag: v1 -- name: nginx - newTag: 1.8.0 -- name: my-demo-app - newName: my-app -- name: alpine - digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/nameprefix/_index.md b/site/content/en/api-reference/kustomization/nameprefix/_index.md index eff83839a..f404e7219 100644 --- a/site/content/en/api-reference/kustomization/nameprefix/_index.md +++ b/site/content/en/api-reference/kustomization/nameprefix/_index.md @@ -8,12 +8,4 @@ description: > - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -namePrefix: alices- -``` - -A deployment named `wordpress` would become `alices-wordpress`. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/namespace/_index.md b/site/content/en/api-reference/kustomization/namespace/_index.md index ba5943ec1..097348bda 100644 --- a/site/content/en/api-reference/kustomization/namespace/_index.md +++ b/site/content/en/api-reference/kustomization/namespace/_index.md @@ -9,12 +9,4 @@ description: > -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -namespace: my-namespace -``` - -Will override the existing namespace if it is set on a resource, or add it -if it is not set on a resource. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/namesuffix/_index.md b/site/content/en/api-reference/kustomization/namesuffix/_index.md index a79fc7e3e..b0afaafe7 100644 --- a/site/content/en/api-reference/kustomization/namesuffix/_index.md +++ b/site/content/en/api-reference/kustomization/namesuffix/_index.md @@ -9,13 +9,4 @@ description: > -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -nameSuffix: -v2 -``` - -A deployment named `wordpress` would become `wordpress-v2`. - -**Note:** The suffix is appended before the content hash if the resource type is ConfigMap or Secret. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/patches/_index.md b/site/content/en/api-reference/kustomization/patches/_index.md index 21a4acf24..ce1f4b271 100644 --- a/site/content/en/api-reference/kustomization/patches/_index.md +++ b/site/content/en/api-reference/kustomization/patches/_index.md @@ -8,152 +8,4 @@ description: > - -[strategic merge]: /kustomize/api-reference/glossary#patchstrategicmerge -[JSON]: /kustomize/api-reference/glossary#patchjson6902 - -Patches (also call overlays) add or override fields on resources. They are provided using the -`patches` Kustomization field. - -The `patches` field contains a list of patches to be applied in the order they are specified. - -Each patch may: - -- be either a [strategic merge] patch, or a [JSON] patch -- be either a file, or an inline string -- target a single resource or multiple resources - -The patch target selects resources by group, version, kind, name, namespace, labelSelector and -annotationSelector. Any resource which matches all the **specified** fields has the patch applied -to it (regular expressions). - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -patches: -- path: patch.yaml - target: - group: apps - version: v1 - kind: Deployment - name: deploy.* - labelSelector: "env=dev" - annotationSelector: "zone=west" -- patch: |- - - op: replace - path: /some/existing/path - value: new value - target: - kind: MyKind - labelSelector: "env=dev" -``` - -The `name` and `namespace` fields of the patch target selector are -automatically anchored regular expressions. This means that the value `myapp` -is equivalent to `^myapp$`. - -Consider the following `deployment.yaml` common for both the examples: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - replicas: 5 - template: - containers: - - name: the-container - image: registry/conatiner:latest -``` - -## Example I - -### Intent - -To Make the container image point to a specific version and not to the latest container in the -registry. - -### File Input - -```yaml -# kustomization.yaml -resources: -- deployment.yaml - -patches: -- path: patch.yaml -``` - -```yaml -# patch.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - template: - containers: - - name: the-container - image: registry/conatiner:1.0.0 -``` - -### Build Output - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - replicas: 5 - template: - containers: - - image: registry/conatiner:1.0.0 - name: the-container -``` - -## Example II - -### Intent - -To Make the container image point to a specific version and not to the latest container in the -registry. - -### File Input - -```yaml -# kustomization.yaml -resources: -- deployment.yaml - -patches: -- target: - kind: Deployment - name: the-deployment - path: patch.json -``` - -```yaml -# patch.json -[ - {"op": "replace", "path": "/spec/template/containers/0/image", "value": "registry/conatiner:1.0.0"} -] - -``` - -### Build Output - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: the-deployment -spec: - replicas: 5 - template: - containers: - - image: registry/container:1.0.0 - name: the-container -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/patchesStrategicMerge/_index.md b/site/content/en/api-reference/kustomization/patchesStrategicMerge/_index.md index 58f47760d..fd7363cd5 100644 --- a/site/content/en/api-reference/kustomization/patchesStrategicMerge/_index.md +++ b/site/content/en/api-reference/kustomization/patchesStrategicMerge/_index.md @@ -8,53 +8,4 @@ description: > - -Each entry in this list should be either a relative -file path or an inline content -resolving to a partial or complete resource -definition. - -The names in these (possibly partial) resource -files must match names already loaded via the -`resources` field. These entries are used to -_patch_ (modify) the known resources. - -Small patches that do one thing are best, e.g. modify -a memory request/limit, change an env var in a -ConfigMap, etc. Small patches are easy to review and -easy to mix together in overlays. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -patchesStrategicMerge: -- service_port_8888.yaml -- deployment_increase_replicas.yaml -- deployment_increase_memory.yaml -``` - -The patch content can be a inline string as well. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -patchesStrategicMerge: -- |- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: nginx - spec: - template: - spec: - containers: - - name: nginx - image: nignx:latest -``` - -Note that kustomize does not support more than one patch -for the same object that contain a _delete_ directive. To remove -several fields / slice elements from an object create a single -patch that performs all the needed deletions. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/patchesjson6902/_index.md b/site/content/en/api-reference/kustomization/patchesjson6902/_index.md index 932a1a7c2..74639239d 100644 --- a/site/content/en/api-reference/kustomization/patchesjson6902/_index.md +++ b/site/content/en/api-reference/kustomization/patchesjson6902/_index.md @@ -8,67 +8,4 @@ description: > - -Each entry in this list should resolve to a kubernetes object and a JSON patch that will be applied -to the object. -The JSON patch is documented at - -target field points to a kubernetes object within the same kustomization -by the object's group, version, kind, name and namespace. -path field is a relative file path of a JSON patch file. -The content in this patch file can be either in JSON format as - -```json - [ - {"op": "add", "path": "/some/new/path", "value": "value"}, - {"op": "replace", "path": "/some/existing/path", "value": "new value"} - ] - ``` - -or in YAML format as - -```yaml -- op: add - path: /some/new/path - value: value -- op: replace - path: /some/existing/path - value: new value -``` - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -patchesJson6902: -- target: - version: v1 - kind: Deployment - name: my-deployment - path: add_init_container.yaml -- target: - version: v1 - kind: Service - name: my-service - path: add_service_annotation.yaml -``` - -The patch content can be an inline string as well: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -patchesJson6902: -- target: - version: v1 - kind: Deployment - name: my-deployment - patch: |- - - op: add - path: /some/new/path - value: value - - op: replace - path: /some/existing/path - value: "new value" -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/replicas/_index.md b/site/content/en/api-reference/kustomization/replicas/_index.md index b021fbc95..d7e378441 100644 --- a/site/content/en/api-reference/kustomization/replicas/_index.md +++ b/site/content/en/api-reference/kustomization/replicas/_index.md @@ -8,40 +8,4 @@ description: > - -Given this kubernetes Deployment fragment: - -``` -# deployment.yaml -kind: Deployment -metadata: - name: deployment-name -spec: - replicas: 3 -``` - -one can change the number of replicas to 5 -by adding the following to your kustomization: - -``` -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -replicas: -- name: deployment-name - count: 5 -``` - -This field accepts a list, so many resources can -be modified at the same time. - -As this declaration does not take in a `kind:` nor a `group:` -it will match any `group` and `kind` that has a matching name and -that is one of: - -- `Deployment` -- `ReplicationController` -- `ReplicaSet` -- `StatefulSet` - -For more complex use cases, revert to using a patch. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/resources/_index.md b/site/content/en/api-reference/kustomization/resources/_index.md index 12190a358..119d8374f 100644 --- a/site/content/en/api-reference/kustomization/resources/_index.md +++ b/site/content/en/api-reference/kustomization/resources/_index.md @@ -8,30 +8,4 @@ description: > - -Each entry in this list must be a path to a _file_, or a path (or URL) referring to another -kustomization _directory_, e.g. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -resources: -- myNamespace.yaml -- sub-dir/some-deployment.yaml -- ../../commonbase -- github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6 -- deployment.yaml -- github.com/kubernets-sigs/kustomize/examples/helloWorld?ref=test-branch -``` - -Resources will be read and processed in depth-first order. - -Files should contain k8s resources in YAML form. A file may contain multiple resources separated by -the document marker `---`. File paths should be specified _relative_ to the directory holding the -kustomization file containing the `resources` field. - -[hashicorp URL]: https://github.com/hashicorp/go-getter#url-format - -Directory specification can be relative, absolute, or part of a URL. URL specifications should -follow the [hashicorp URL] format. The directory must contain a `kustomization.yaml` file. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/secretegenerator/_index.md b/site/content/en/api-reference/kustomization/secretegenerator/_index.md index 49a1e05bf..8c118aec2 100644 --- a/site/content/en/api-reference/kustomization/secretegenerator/_index.md +++ b/site/content/en/api-reference/kustomization/secretegenerator/_index.md @@ -8,40 +8,4 @@ description: > - -Each entry in the argument list results in the creation of one Secret resource (it's a generator of N secrets). - -This works like the [configMapGenerator](/kustomize/api-reference/kustomization/configmapgenerator). - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -secretGenerator: -- name: app-tls - files: - - secret/tls.cert - - secret/tls.key - type: "kubernetes.io/tls" -- name: app-tls-namespaced - # you can define a namespace to generate - # a secret in, defaults to: "default" - namespace: apps - files: - - tls.crt=catsecret/tls.cert - - tls.key=secret/tls.key - type: "kubernetes.io/tls" -- name: env_file_secret - envs: - - env.txt - type: Opaque -- name: secret-with-annotation - files: - - app-config.yaml - type: Opaque - options: - annotations: - app_config: "true" - labels: - app.kubernetes.io/name: "app2" -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/api-reference/kustomization/vars/_index.md b/site/content/en/api-reference/kustomization/vars/_index.md index d84d0157e..5275fa6ed 100644 --- a/site/content/en/api-reference/kustomization/vars/_index.md +++ b/site/content/en/api-reference/kustomization/vars/_index.md @@ -8,112 +8,4 @@ description: > - -Vars are used to capture text from one resource's field -and insert that text elsewhere - a reflection feature. - -For example, suppose one specifies the name of a k8s Service -object in a container's command line, and the name of a -k8s Secret object in a container's environment variable, -so that the following would work: - -```yaml -# consider it is a deployment -containers: - - image: myimage - command: ["start", "--host", "$(MY_SERVICE_NAME)"] - env: - - name: SECRET_TOKEN - value: $(SOME_SECRET_NAME) - livenessProbe: - httpGet: - path: /healthz - # it enables the parser to lookup this field - port: $(APP_PORT) -``` - -To do so, add an entry to `vars:` as follows: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -configMapGenerator: -- name: my-config - literals: - - MY_PORT=8080 - -vars: -- name: SOME_SECRET_NAME - objref: - kind: Secret - name: my-secret - apiVersion: v1 -- name: MY_SERVICE_NAME - objref: - kind: Service - name: my-service - apiVersion: v1 - fieldref: - fieldpath: metadata.name -- name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY - objref: - kind: Deployment - name: my-deployment - apiVersion: apps/v1 - fieldref: - fieldpath: spec.template.spec.restartPolicy -# it exports a value as `APP_PORT` -# from `ConfigMap` named `my-config` -# in `data.MY_PORT` -- name: APP_PORT - objref: - kind: ConfigMap - name: my-config - apiVersion: v1 - fieldref: - fieldpath: data.MY_PORT - -configurations: - - lookup.yaml -``` - -Define the consuming resource(s) and the field(s) inside need to lookup. - -```yaml -# lookup.yaml -varReference: - # the path of field that you want the parser to lookups and replace. - - path: spec/template/spec/containers/livenessProbe/httpGet/port - kind: Deployment -``` - -A var is a tuple of variable name, object -reference and field reference within that object. -That's where the text is found. - -The field reference is optional; it defaults to -`metadata.name`, a normal default, since kustomize -is used to generate or modify the names of -resources. - -At time of writing, only string type fields are -supported. No ints, bools, arrays etc. It's not -possible to, say, extract the name of the image in -container number 2 of some pod template. - -A variable reference, i.e. the string '$(FOO)', -can only be placed in particular fields of -particular objects as specified by kustomize's -configuration data. - -The default config data for vars is at [/api/konfig/builtinpluginconsts/varreference.go](https://github.com/kubernetes-sigs/kustomize/blob/master/api/konfig/builtinpluginconsts/varreference.go) -Long story short, the default targets are all -container command args and env value fields. - -Vars should _not_ be used for inserting names in -places where kustomize is already handling that -job. E.g., a Deployment may reference a ConfigMap -by name, and if kustomize changes the name of a -ConfigMap, it knows to change the name reference -in the Deployment. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/blog/_index.md b/site/content/en/blog/_index.md index eda933bf5..9ebef4e0e 100644 --- a/site/content/en/blog/_index.md +++ b/site/content/en/blog/_index.md @@ -7,3 +7,5 @@ menu: --- + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/blog/releases/_index.md b/site/content/en/blog/releases/_index.md index 747493b71..943b5f15f 100644 --- a/site/content/en/blog/releases/_index.md +++ b/site/content/en/blog/releases/_index.md @@ -5,3 +5,5 @@ weight: 20 --- + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/contributing/bugs/_index.md b/site/content/en/contributing/bugs/_index.md index 6f4e17cdb..e12180773 100644 --- a/site/content/en/contributing/bugs/_index.md +++ b/site/content/en/contributing/bugs/_index.md @@ -9,51 +9,4 @@ description: > - -[krusty package]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/krusty -[reusable custom transformer test]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/krusty/customconfigreusable_test.go - -File issues as desired, but if you've found a problem -with how `kustomize build` works, please report - -* the output of `kustomize version`, -* the input (the content of `kustomization.yaml` - and any files it refers to), -* the expected YAML output. - -## If you have `go` installed - -kustomize has a simple test harness in the [krusty -package] for specifying a kustomization's input and the -expected output. - -Copy one of those tests, e.g. this [reusable custom -transformer test], to a new test file in the -krusty package. - -Insert the inputs you want to use, and run it as -you'd run the reusable custom transformer test: - -``` -(cd api; go test -run TestReusableCustomTransformers ./krusty) -``` - -The output will demonstrate the bug or missing feature. - -Record this output in the test file in a call to -`AssertActualEqualsExpected`, per all the other tests -in the [krusty package]. This makes the test pass, -albeit with output demonstrating behavior you -presumably want to change. - -Send the new test in a PR, along with commentary (in -the test) on what you'd prefer to see. - -The person who fixes the bug then has a clear bug -reproduction and a test to modify when the bug is -fixed. - -Any bug fix first requires a test demonstrating the bug -(so we have permanent regression coverage), so if the -_bug reporter_ does this, it saves time and avoids -misunderstandings. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/contributing/community/_index.md b/site/content/en/contributing/community/_index.md index f0c355400..9b209b102 100644 --- a/site/content/en/contributing/community/_index.md +++ b/site/content/en/contributing/community/_index.md @@ -9,18 +9,4 @@ description: > - -[CLI special interest group]: https://github.com/kubernetes/community/tree/master/sig-cli#cli-special-interest-group -[contributor roles]: https://github.com/kubernetes/community/blob/master/community-membership.md#community-membership -[mailing list]: https://groups.google.com/forum/#!forum/kubernetes-sig-cli -[bi-weekly meetings]: https://docs.google.com/document/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit?usp=sharing -[slack channel]: https://kubernetes.slack.com/messages/sig-cli - -Kustomize is a sub project of the Kubernetes [CLI special interest group] and follows the Kubernetes -project [contributor roles]. - -If you are interested in contributing towards Kustomize or getting more involved with the community: - -- join the [mailing list] and reach out -- join the [slack channel] and reach out -- attend one of the [bi-weekly meetings] (alternating Wednesdays at 9:00am Pacific Time) +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/contributing/docs/_index.md b/site/content/en/contributing/docs/_index.md index 6d913b7f4..43ab619b3 100644 --- a/site/content/en/contributing/docs/_index.md +++ b/site/content/en/contributing/docs/_index.md @@ -9,76 +9,4 @@ description: > - -Kustomize uses [Docsy](https://www.docsy.dev) for the site, and was -forked from the [docsy-example](https://github.com/google/docsy-example) - -## Prerequisites - -- [Install hugo](https://gohugo.io/getting-started/installing/#fetch-from-github) -- Clone kustomize - - `git clone git@github.com:kubernetes-sigs/kustomize && cd kustomize/` - -## Development - -The doc input files are in the `site` directory. The site can be hosted locally using -`hugo serve`. - -```shell script -cd site/ -hugo serve -``` - -```shell script -... -Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender -Web Server is available at http://localhost:1313/kustomize/ (bind address 127.0.0.1) -``` - -## Publishing - -Hugo compiles the files under `site` Hugo into html which it puts in the `docs` folder: - -```shell script -cd site/ -hugo -``` - -```shell script - | EN --------------------+----- - Pages | 99 - Paginator pages | 0 - Non-page files | 0 - Static files | 47 - Processed images | 0 - Aliases | 2 - Sitemaps | 1 - Cleaned | 0 -``` - -Add the `site/` and `docs/` folders to a commit, then create a PR. - -## Publishing docs to your kustomize fork - -It is possible to have the kustomize docs published to your forks github pages. - -### Setup GitHub Pages for the fork - -1. Go to the *forked repo's* **Settings** tab - - e.g. [https://github.com/pwittrock/kustomize](https://github.com/pwittrock/kustomize) -2. Go to the **GitHub Pages** section -3. Set the source to master branch **/docs folder** - -### Publish to the fork's GitHub Pages - -{{% pageinfo color="info" %}} -Changes must be pushed to the fork's **master branch** to be served as the fork's GitHub Page. -{{% /pageinfo %}} - -1. Make a change to a file under `site/content` -2. Run `hugo` from the `site/` directory -3. Add the `site` and `docs` directories to the **master branch** -4. Commit and push the changes to the *remote fork's* **master branch** -5. After a few minutes, the docs should be served from the fork's GitHub Page - - e.g. [https://pwittrock.github.io/kustomize/](https://pwittrock.github.io/kustomize/) +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/contributing/features/_index.md b/site/content/en/contributing/features/_index.md index cb19916aa..775448294 100644 --- a/site/content/en/contributing/features/_index.md +++ b/site/content/en/contributing/features/_index.md @@ -8,32 +8,4 @@ description: > --- - -[issue]: https://github.com/kubernetes-sigs/kustomize/issues -[sig-cli]: /kustomize/contributing/community/ -[meeting agenda]: https://docs.google.com/document/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit#heading=h.himo1st0tqyy -[KEP]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli -[table-driven]: https://github.com/kubernetes-sigs/kustomize/blob/a8b9741866cf8e0c43e643ab7a9f40a3bd7e2a4d/api/filters/imagetag/imagetag_test.go#L15 -[eschewed feature list]: https://kubernetes-sigs.github.io/kustomize/faq/eschewedfeatures/ -[kind/feature]: https://github.com/kubernetes-sigs/kustomize/labels/kind%2Ffeature - -Following is the process for proposing a new Kustomize feature: - -1. Check the [eschewed feature list] to see if the feature has already been proposed -2. File an [issue] describing the desired feature - - label it [kind/feature] - - the motivation for the feature - - example of how you would accomplish the motivating task *without* the feature - - example of how you would accomplish the motivating task *with* the feature -3. Email the [sig-cli] mailing list with the issue -4. Present the issue at [sig-cli] bi-weekly meeting on Zoom - - add it to the [meeting agenda] doc - - be present to discuss the feature - - response may be -- move forward with a PoC, not to move forward, defer and come back later, - or more information is needed. -5. Address the feedback on the issue - - Possibly write a KEP for tracking the feature -6. Implement the feature and send a PR - - Add [table-driven] tests - - Expect comments on the PR within 2 weeks -7. Kustomize team will release the kustomize `api` and `kustomize` modules +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/contributing/howitworks/_index.md b/site/content/en/contributing/howitworks/_index.md index 364b12b85..5585d872b 100644 --- a/site/content/en/contributing/howitworks/_index.md +++ b/site/content/en/contributing/howitworks/_index.md @@ -9,60 +9,4 @@ description: > - -{{% pageinfo color="info" %}} -To build kustomize using the locally modified modules, `replace` statements must be added to -the `kustomize/go.mod`. - -e.g. if code in `api` was modified, a `replace` statement would need to be added for the -`kustomize/api` module. -{{% /pageinfo %}} - -Call stack when running `kustomize build`, with links to code. - -## Run build - -* [RunBuild](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/kustomize/internal/commands/build/build.go#L121) - * [MakeKustomizer](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/krusty/kustomizer.go#L32) - * [Run](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/krusty/kustomizer.go#L47): performs a kustomization. It uses its internal filesystem reference to read the file at the given path argument, interpret it as a kustomization.yaml file, perform the kustomization it represents, and return the resulting resources. - * Create factories - * [tranformer.NewFactoryImpl](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/k8sdeps/transformer/factory.go#L17) - * [resmap.NewFactory](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/resmap/factory.go#L21) - * [resource.NewFactory](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/resource/factory.go#L23) - * [kustruct.NewKunstructuredFactoryImpl](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/k8sdeps/kunstruct/factory.go#L28) - * [loader.NewLoader](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/loader/loader.go#L19) - * [validator.NewKustValidator](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/k8sdeps/validator/validators.go#L23) - * [NewKustTarget](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L38) - * [Load](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L54) - * [MakeCustomizeResMap](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L109): details in next section - * [emitResources](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/kustomize/internal/commands/build/build.go#L143) - -## Make resource map - -* [makeCustomizeResMap](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L117) - * [AccumulateTarget](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L196): returns a new ResAccumulator, holding customized resources and the data/rules used to do so. The name back references and vars are not yet fixed. - * [accummulateResources](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L302): fills the given resourceAccumulator with resources read from the given list of paths. - * Merge config from builtin and CRDs - * [runGenerators](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L239) - * [configureBuiltinGenerators](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget_configplugin.go#L28) - * ConfigMapGenerator - * SecretGenerator - * [configureExternalGenerators]() - * Iterate all generators - * [runTransfomers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L274) - * [configureBuiltinTransformers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget_configplugin.go#L44) - * PatchStrategicMergeTransformer - * PatchTransformer - * NamespaceTransformer - * PrefixSuffixTransformer - * LabelTransformer - * AnnotationsTransformer - * PatchJson6902Transformer - * ReplicaCountTransformer - * ImageTagTransformer - * [configureExternalTransformers](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L291) - * [MergeVars](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L64) - * The following steps must be done last, not as part of the recursion implicit in AccumulateTarget. - * [addHashesToNames](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/target/kusttarget.go#L153) - * [FixBackReferences](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L160): Given that names have changed (prefixs/suffixes added), fix all the back references to those names. - * [ResolveVars](https://github.com/kubernetes-sigs/kustomize/blob/c7d78970fb86782dbdded3a93944b774f826071f/api/internal/accumulator/resaccumulator.go#L141) +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/contributing/mac/_index.md b/site/content/en/contributing/mac/_index.md index 31f8d8911..e6165287e 100644 --- a/site/content/en/contributing/mac/_index.md +++ b/site/content/en/contributing/mac/_index.md @@ -8,40 +8,4 @@ description: > --- -First install the tools to build and run tests - -### Install go 1.13 - -[Instructions](https://golang.org/doc/install) - -Add `go` to your PATH - -### Install kubeval - -[Instructions](https://github.com/instrumenta/kubeval) - -```sh -go get github.com/instrumenta/kubeval -``` - -Add `kubeval` to your PATH - -### Install gnu tools - -[Instructions](https://www.topbug.net/blog/2013/04/14/install-and-use-gnu-command-line-tools-in-mac-os-x/) - -```sh -brew install coreutils wget gnu-sed tree -``` - -Add the new tools to your PATH - -## Make everything - -Verify your install by running `make`: - -```sh -make -``` - -Be default, this runs all tests needed to qualify a pull request. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/contributing/windows/_index.md b/site/content/en/contributing/windows/_index.md index cc76a4255..a26983a4b 100644 --- a/site/content/en/contributing/windows/_index.md +++ b/site/content/en/contributing/windows/_index.md @@ -9,60 +9,4 @@ description: > -This is the PowerShell script to run all go tests for Kustomize on a windows based platform which mimics /build/pre-commit.sh - -## Pre-Reqs - -- PowerShell installed - - PowerShell Core is supported -- go installed -- golangci-lint installed -- mdrip installed - -This script should output to the current console and return an exit code if all tests are successful(0) or any failed(1). - -### If you are tryin to run these tests locally you can follow these instructions - -Assume: - -- Running a stock Windows 10 system -- Local Admin rights. -- You can open [PowerShell as administrator](http://lmgtfy.com/?iie=1&q=How+to+open+powershell+as+administrator) -- You should be knowledgeable enough to pull source for packages into your GO ```src``` directory - - Yes, this means you also need to know a bit about **git** usually - -#### Step 1 - Install Go - -- [Install Go](https://golang.org/dl/) - please use the msi - - If you use chocolatey - it's using the zip not msi and assumptions on where go is located are made for you. - -#### Step 2 - Install Go Packages - -- Open new PowerShell Administrative window - - Install golangci-lint - - ```go get -u github.com/golangci/golangci-lint/cmd/golangci-lint``` - - Install mdrip - - ```go get github.com/monopole/mdrip``` - -You should now be able to issue these commands and see comparable responses - -``` -C:\...> golangci-lint --help -Smart, fast linters runner. Run it in cloud for every GitHub pull request on https://golangci.com -... - -C:\...> mdrip --help -Usage: C:\_go\bin\mdrip.exe {fileName}... -... -``` - -#### Step 3 - Get Source and Test - -- In your GoRoot src - - ```Example: C:\_go\src``` -- Navigate to the Kustomize `travis` directory - - ```Example: C:\_go\src\sigs.k8s.io\kustomize\scripts``` -- Now Execute: - - ```.\Invoke-PreCommit.ps1``` - -This should run all pre-commit tests thus defined in the script. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/faq/_index.md b/site/content/en/faq/_index.md index a1e4e4728..f1981f8c1 100644 --- a/site/content/en/faq/_index.md +++ b/site/content/en/faq/_index.md @@ -9,75 +9,4 @@ menu: -## kubectl doesn't have the latest kustomize, when will it be updated? - -TLDR: This is blocked on either moving kubectl into its own repo, or changing its dependencies. ETA k8s ~1.20. - -The adoption of go modules in the kubernetes/kubernetes repo broke the update process for kustomize. -This is due to the kustomize libraries depending on the kubernetes apimachinery libraries, which are -published out of the kubernetes staging directory. - -2 pieces of work are underway which will allow kustomize to be updated in kubectl: - -- migrating kubectl out of kubernetes/kubernetes (expected Kubernetes ~1.20) -- migrating kustomize off of the apimachinery libraries (expected Kuberntes ~1.20) - - [2506](https://github.com/kubernetes-sigs/kustomize/issues/2506) - -Once either of these issues is resolved we will then update kubectl with the latest kustomize version. - -## security: file 'foo' is not in or below 'bar' - -v2.0 added a security check that prevents -kustomizations from reading files outside their own -directory root. - -This was meant to help protect the person inclined to -download kustomization directories from the web and use -them without inspection to control their production -cluster -(see [#693](https://github.com/kubernetes-sigs/kustomize/issues/693), -[#700](https://github.com/kubernetes-sigs/kustomize/pull/700), -[#995](https://github.com/kubernetes-sigs/kustomize/pull/995) and -[#998](https://github.com/kubernetes-sigs/kustomize/pull/998)) - -Resources (including configmap and secret generators) -can _still be shared_ via the recommended best practice -of placing them in a directory with their own -kustomization file, and referring to this directory as a -[`base`](/kustomize/api-reference/glossary#base) from any kustomization that -wants to use it. This encourages modularity and -relocatability. - -To disable this, use v3, and the `load_restrictor` flag: - -``` -kustomize build --load_restrictor none $target -``` - -## Some field is not transformed by kustomize - -Example: [#1319](https://github.com/kubernetes-sigs/kustomize/issues/1319), [#1322](https://github.com/kubernetes-sigs/kustomize/issues/1322), [#1347](https://github.com/kubernetes-sigs/kustomize/issues/1347) and etc. - -The fields transformed by kustomize is configured explicitly in [defaultconfig](https://github.com/kubernetes-sigs/kustomize/tree/master/api/konfig/builtinpluginconsts/defaultconfig.go). The configuration itself can be customized by including `configurations` in `kustomization.yaml`, e.g. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -configurations: -- kustomizeconfig.yaml -``` - -The configuration directive allows customization of the following transformers: - -```yaml -commonAnnotations: [] -commonLabels: [] -nameprefix: [] -namespace: [] -varreference: [] -namereference: [] -images: [] -replicas: [] -``` - -To persist the changes to default configuration, submit a PR like [#1338](https://github.com/kubernetes-sigs/kustomize/pull/1338), [#1348](https://github.com/kubernetes-sigs/kustomize/pull/1348) and etc. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/faq/eschewedfeatures/_index.md b/site/content/en/faq/eschewedfeatures/_index.md index 7c53dfa86..5b726add4 100644 --- a/site/content/en/faq/eschewedfeatures/_index.md +++ b/site/content/en/faq/eschewedfeatures/_index.md @@ -9,156 +9,4 @@ description: > -The maintainers established this list to -place bounds on the kustomize feature -set. The bounds can be changed with -a consensus on the risks. - -For a bigger picture about why kustomize -does some things and not others, see the -glossary entry for [DAM]. - -## Removal directives - -`kustomize` supports configurations that can be reasoned about as -_compositions_ or _mixins_ - concepts that are widely accepted as -a best practice in various programming languages. - -To this end, `kustomize` offers various _addition_ directives. -One may add labels, annotations, patches, resources, bases, etc. -Corresponding _removal_ directives are not offered. - -Removal semantics would introduce many possibilities for -inconsistency, and the need to add code to detect, report and -reject it. It would also allow, and possibly encourage, -unnecessarily complex configuration layouts. - -When faced with a situation where removal is desirable, it's -always possible to remove things from a base like labels and -annotations, and/or split multi-resource manifests into individual -resource files - then add things back as desired via the -[kustomization]. - -If the underlying base is outside of one's control, an [OTS -workflow] is the recommended best practice. Fork the base, remove -what you don't want and commit it to your private fork, then use -kustomize on your fork. As often as desired, use _git rebase_ to -capture improvements from the upstream base. - -## Unstructured edits - -_Structured edits_ are changes controlled by -knowledge of the k8s API, and YAML or JSON syntax. - -Most edits performed by kustomize can be expressed as -[JSON patches] or [SMP patches]. -Those can be verbose, so common patches, -like adding labels or annotatations, get dedicated -transformer plugins - `LabelTransformer`, -`AnnotationsTransformer`, etc. -These accept relatively simple YAML configuration -allowing easy targeting of any number of resources. - -Another class of edits take data from one specific -object's field and use it in another (e.g. a service -object's name found and copied into a container's -command line). These reflection-style edits -are called _replacements_. - -The above edits create valid output given valid input, -and can provide syntactically and semantically -informed error messages if inputs are invalid. - -_Unstructured edits_, edits that don't limit -themselves to a syntax or object structure, -come in many forms. A common one in the -configuration domain is the template or -parameterization approach. - -In this technique, the source -material is sprinkled with strings of the -form `${VAR}`. A scanner replaces them -with a value taken from a map using `VAR` -as the map key. It's trivial to implement. - -kustomize eschews parameterization, because - -- The source yaml gets polluted with `$VARs` - and can no longed be applied as is - to the cluster (it _must_ be processed). -- The source material is no longer structured, - making it unusable with any YAML processor. - It's no longer _data_, it's now logic that - must be compiled. -- Errors in the output are disconnected from - the edit that caused it. -- The input becomes [unintelligible] as the project - scales in any number of dimensions (resource - count, cluster count, environment count, etc.) - -Kustomizations are meant to be sharable and stackable. -Imagine tracing down a problem rooted in a -clever set of stacked regexp replacements -performed by various overlays on some remote base. -We've used such systems, and never want to again. - -Other tools (sed, jinja, erb, envsubst, kafka, helm, ksonnet, -etc.) provide varying degrees of unstructured editting -and/or embedded languages, and can be used instead -of, or in a pipe with, kustomize. If you want to -go all-in on _configuration as a language_, consider [cue]. - -kustomize is going to stick to YAML in / YAML out. - -## Build-time side effects from CLI args or env variables - -`kustomize` supports the best practice of storing one's -entire configuration in a version control system. - -Changing `kustomize build` configuration output as a result -of additional arguments or flags to `build`, or by -consulting shell environment variable values in `build` -code, would frustrate that goal. - -`kustomize` insteads offers [kustomization] file `edit` -commands. Like any shell command, they can accept -environment variable arguments. - -For example, to set the tag used on an image to match an -environment variable, run - -``` -kustomize edit set image nginx:$MY_NGINX_VERSION -``` - -as part of some encapsulating work flow executed before -`kustomize build`. - -## Globs in kustomization files - -`kustomize` supports the best practice of storing one's -entire configuration in a version control system. - -Globbing the local file system for files not explicitly -declared in the [kustomization] file at `kustomize build` time -would violate that goal. - -Allowing globbing in a kustomization file would also introduce -the same problems as allowing globbing in [java import] -declarations or BUILD/Makefile dependency rules. - -`kustomize` will instead provide kustomization file editting -commands that accept globbed arguments, expand them at _edit -time_ relative to the local file system, and store the resulting -explicit names into the kustomization file. - -[base]: /kustomize/api-reference/glossary#base -[DAM]: /kustomize/api-reference/glossary#declarative-application-management -[java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards -[JSON patches]: /kustomize/api-reference/glossary#patchjson6902 -[kustomization]: /kustomize/api-reference/glossary#kustomization -[OTS workflow]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[SMP patches]: /kustomize/api-reference/glossary#patchstrategicmerge -[parameterization pitfall discussion]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md#parameterization-pitfalls -[unintelligible]: https://github.com/helm/charts/blob/e002378c13e91bef4a3b0ba718c191ec791ce3f9/stable/artifactory/templates/artifactory-deployment.yaml -[cue]: https://cuelang.org/ +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/faq/versioningPolicy.md b/site/content/en/faq/versioningPolicy.md index c2ecddb3b..bf46721c8 100644 --- a/site/content/en/faq/versioningPolicy.md +++ b/site/content/en/faq/versioningPolicy.md @@ -7,266 +7,4 @@ type: docs -Running `kustomize` means one is running a -particular version of a program (a CLI), using a -particular version of underlying packages (a Go -API), and reading a particular version of a -[kustomization] file. - -> If you're having trouble with `go get`, please -> read [Go API Versioning](#go-api-versioning) -> and be patient. - -## CLI Program Versioning - -The command `kustomize version` prints a three -field version tag (e.g. `v3.0.0`) that aspires to -[semantic versioning]. - -This notion of semver applies only to the CLI; -the command names, their arguments and their flags. - -The major version changes when some backward -incompatibility appears in how the commands -behave. - -### Installation - -See the [installation docs](INSTALL.md). - -## Go API Versioning - -The public methods in the public packages -of module `sigs.k8s.io/kustomize/api` constitute -the _kustomize Go API_. - -#### Version sigs.k8s.io/kustomize/v3 and earlier - -[import path]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher - -In `kustomize/v3` (and preceding major versions), the -kustomize program and the API live the same Go -module at `sigs.k8s.io/kustomize`, at [import path] -`sigs.k8s.io/kustomize/v3`. - -This has been fine for the CLI, but it presents a -problem for the Go API. - -[minimal version selection]: https://research.swtch.com/vgo-mvs - -The process around Go modules, in particular the -notion of [minimal version selection], demands -that the module respect semver. - -Almost all the code in module -`sigs.k8s.io/kustomize/v3` is exposed (not in a -directory named `internal`). Even a minor -refactor changing a method name or argument type -in some deeply buried (but still public) method is -a backward incompatible change. As a result, Go -API semver hasn't been followed. This was a mistake. - -Some options are - -- continue to ignore Go API semver and stick to - CLI semver (eliminating the usefullness of - minimal version selection), - -- obey semver, and increment the module's major - version number with every release (drastically - reducing the usefullness of minimal version - selection - since virtually all releases will - be major), - -- slow down change in the huge API in favor of - stability, yet somehow continue to deliver - features, - -- drastically reduce the API surface, stabilize on - semver there, and refactor as needed inside - `internal`. - -The last option seems the most appealing. - -#### The first stable API version is coming - -The first stable API version will launch -as the Go module - -``` -sigs.k8s.io/kustomize/api -``` - -The _kustomize_ program itself (`main.go` -and CLI specific code) will have moved out of -`sigs.k8s.io/kustomize` and into the new module -`sigs.k8s.io/kustomize/kustomize`. This is a -submodule in the same repo, and it will retain its -current notion of semver (e.g. a backward -incompatible change in command behavior will -trigger a major version bump). This module will -not export packages; it's just home to a `main` -package. - -The `sigs.k8s.io/kustomize/api` module will -obey semver with a sustainable public -surface, informed by current usage. Clients -should import packages from this module, i.e. -from import paths prefixed by -`sigs.k8s.io/kustomize/api/` at first, -and later by `sigs.k8s.io/kustomize/api/v2/`. -The kustomize binary -itself is an API client requiring this module. - -The clients and API will evolve independently. - -## Kustomization File Versioning - -The kustomization file is a struct that is part of -the kustomize Go API (the `sigs.k8s.io/kustomize` -module), but it also evolves as a k8s API object - -it has an `apiVersion` field containing its -own version number. - -### Field Change Policy - -- A field's meaning cannot be changed. -- A field may be deprecated, then removed. -- Deprecation means triggering a _minor_ (semver) - version bump in the kustomize Go API, and - defining a migration path in a non-fatal error - message. -- Removal means triggering a _major_ (semver) - version bump in the kustomize Go API, and fatal - error if field encountered (as with any unknown - field). Likewise a change in `apiVersion`. - -### The `edit fix` Command - -This `kustomize` command reads a Kustomization -file, converts deprecated fields to new -fields, and writes it out again in the latest -format. - -This is a type version upgrade mechanism that -works within _major_ API revisions. There is no -downgrade capability, as there's no use case for -it (see discussion below). - -### Examples - -With the 2.0.0 release, there were three field -removals: - -- `imageTag` was deprecated when `images` was - introduced, because the latter offers more - general features for image data manipulation. - `imageTag` was removed in v2.0.0. -- `patches` was deprecated and replaced by - `patchesStrategicMerge` when `patchesJson6902` - was introduced, to make a clearer - distinction between patch specification formats. - `patches` was removed in v2.0.0. -- `secretGenerator/commands` was removed - due to security concerns in v2.0.0 - with no deprecation period. - -The `edit fix` command in a v2.0.x binary -will no longer recognize these fields. - -## Relationship to the k8s API - -### Review of k8s API versioning - -The k8s API has specific [conventions] and a -process for making [changes]. - -The presence of an `apiVersion` field in a k8s -native type signals: - -- its reliability level (alpha vs beta vs - generally available), -- the existence of code to provide default values - to fields not present in a serialization, -- the existence of code to provide both forward - and backward conversion between different - versions of types. - -The k8s API promises a lossless _conversion_ -between versions over a specific range. This -means that a recent client can write an object -bearing the newest possible value for its version, -the server will accept it and store it in -"versionless" JSON form in storage, and can -convert it to a range of older versions should -an older client request data. - -For native k8s types, this all requires writing Go -code in the kubernetes core repo, to provide -defaulting and conversions. - -For CRDs, there's a [proposal] on how to manage -versioning (e.g. a remote service can offer type -defaulting and conversions). - -### Differences - -- A k8s API server is able to go _forward_ and - _backward_ in versioning, to work with older - clients, over [some range]. -- The `kustomize edit fix` command only moves - _forward_ within a _major_ API - version. - -At the time of writing, the YAML in a -kustomization file does not represent a [k8s API] -object, and the kustomize command and associated -library is neither a server of, nor a client to, -the k8s API. - -### Additional Kustomization file rules - -In addition to the [field change policy] described -above, kustomization files conform to -the following rules. - -#### Eschew classic k8s fields - -Field names with dedicated meaning in k8s -(`metadata`, `spec`, `status`, etc.) aren't used. -This is enforced via code review. - -#### Default values for k8s `kind` and `apiVersion` - -In `v3` or below, the two [special] k8s -resource fields [`kind`] and [`apiVersion`] may -be omitted from the kustomization file. - -If either field is present, they both must be. -If present, the value of `kind` must be: - -> ``` -> kind: Kustomization -> ``` - -If missing, the value of `apiVersion` defaults to - -> ``` -> apiVersion: kustomize.config.k8s.io/v1beta1 -> ``` - -[field change policy]: #field-change-policy -[some range]: https://kubernetes.io/docs/reference/using-api/deprecation-policy -[proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md -[beta-level rules]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions -[changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md -[adapt]: /types/kustomization.go#L166 -[special]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources -[k8s API]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md -[conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md -[release page]: https://github.com/kubernetes-sigs/kustomize/releases -[release process]: https://github.com/kubernetes-sigs/kustomize/tree/master/releasing/README.md -[kustomization]: /kustomize/api-reference/glossary#kustomization -[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds -[`apiVersion`]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning -[semantic versioning]: https://semver.org +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/_index.md b/site/content/en/guides/_index.md index ee2c1b4ba..03fe6e134 100644 --- a/site/content/en/guides/_index.md +++ b/site/content/en/guides/_index.md @@ -9,4 +9,6 @@ menu: description: > Reference for Kustomize usage and best practices --- - \ No newline at end of file + + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/bespoke/_index.md b/site/content/en/guides/bespoke/_index.md index f96f801ba..e9787c682 100644 --- a/site/content/en/guides/bespoke/_index.md +++ b/site/content/en/guides/bespoke/_index.md @@ -9,76 +9,4 @@ description: > - -In this workflow, all configuration (resource YAML) files are owned by the user. -No content is incorporated from version control repositories owned by others. - -![bespoke config workflow image][workflowBespoke] - -#### 1) create a directory in version control - -Speculate some overall cluster application called _ldap_; -we want to keep its configuration in its own repo. - -> ``` -> git init ~/ldap -> ``` - -#### 2) create a [base] - -> ``` -> mkdir -p ~/ldap/base -> ``` - -In this directory, create and commit a [kustomization] -file and a set of [resources]. - -#### 3) create [overlays] - -> ``` -> mkdir -p ~/ldap/overlays/staging -> mkdir -p ~/ldap/overlays/production -> ``` - -Each of these directories needs a [kustomization] -file and one or more [patches]. - -The _staging_ directory might get a patch -that turns on an experiment flag in a configmap. - -The _production_ directory might get a patch -that increases the replica count in a deployment -specified in the base. - -#### 4) bring up [variants] - -Run kustomize, and pipe the output to [apply]. - -> ``` -> kustomize build ~/ldap/overlays/staging | kubectl apply -f - -> kustomize build ~/ldap/overlays/production | kubectl apply -f - -> ``` - -You can also use [kubectl-v1.14.0] to apply your [variants]. -> -> ``` -> kubectl apply -k ~/ldap/overlays/staging -> kubectl apply -k ~/ldap/overlays/production -> ``` - -[OTS]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[apply]: /kustomize/api-reference/glossary#apply -[applying]: /kustomize/api-reference/glossary#apply -[base]: /kustomize/api-reference/glossary#base -[fork]: https://guides.github.com/activities/forking/ -[variants]: /kustomize/api-reference/glossary#variant -[kustomization]: /kustomize/api-reference/glossary#kustomization -[off-the-shelf]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[overlays]: /kustomize/api-reference/glossary#overlay -[patch]: /kustomize/api-reference/glossary#patch -[patches]: /kustomize/api-reference/glossary#patch -[rebase]: https://git-scm.com/docs/git-rebase -[resources]: /kustomize/api-reference/glossary#resource -[workflowBespoke]: /kustomize/images/workflowBespoke.jpg -[workflowOts]: /kustomize/images/workflowOts.jpg -[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/ +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/cmd/_index.md b/site/content/en/guides/cmd/_index.md deleted file mode 100644 index 572ba0f1f..000000000 --- a/site/content/en/guides/cmd/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Command Line Options" -linkTitle: "Command Line Options" -type: docs -description: > - Usage of command line options ---- diff --git a/site/content/en/guides/cmd/build/_index.md b/site/content/en/guides/cmd/build/_index.md deleted file mode 100644 index 0e4ca4bfa..000000000 --- a/site/content/en/guides/cmd/build/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "build" -linkTitle: "build" -type: docs -description: > - Print configuration per contents of kustomization.yaml ---- diff --git a/site/content/en/guides/cmd/cfg/_index.md b/site/content/en/guides/cmd/cfg/_index.md deleted file mode 100644 index f22ac1b6d..000000000 --- a/site/content/en/guides/cmd/cfg/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "cfg" -linkTitle: "cfg" -type: docs -description: > - Commands for reading and writing configuration. ---- diff --git a/site/content/en/guides/cmd/create/_index.md b/site/content/en/guides/cmd/create/_index.md deleted file mode 100644 index d139a8237..000000000 --- a/site/content/en/guides/cmd/create/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "create" -linkTitle: "create" -type: docs -description: > - Create a new kustomization in the current directory ---- diff --git a/site/content/en/guides/cmd/edit/_index.md b/site/content/en/guides/cmd/edit/_index.md deleted file mode 100644 index d649691c5..000000000 --- a/site/content/en/guides/cmd/edit/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "edit" -linkTitle: "edit" -type: docs -description: > - Edits a kustomization file ---- diff --git a/site/content/en/guides/cmd/fn/_index.md b/site/content/en/guides/cmd/fn/_index.md deleted file mode 100644 index e5d4a973a..000000000 --- a/site/content/en/guides/cmd/fn/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "fn" -linkTitle: "fn" -type: docs -description: > - Commands for running functions against configuration ---- diff --git a/site/content/en/guides/cmd/help/_index.md b/site/content/en/guides/cmd/help/_index.md deleted file mode 100644 index 0b183f19a..000000000 --- a/site/content/en/guides/cmd/help/_index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "help" -linkTitle: "help" -type: docs -description: > - Help about any command ---- - -> ``` -> kustomize help -> -> Manages declarative configuration of Kubernetes. -> See https://sigs.k8s.io/kustomize -> -> Usage: -> kustomize [command] -> -> Available Commands: -> build Print configuration per contents of kustomization.yaml -> cfg Commands for reading and writing configuration. -> create Create a new kustomization in the current directory -> edit Edits a kustomization file -> fn Commands for running functions against configuration. -> help Help about any command -> install-completion Install shell completion. -> live Commands for reading and writing resources to a cluster. -> version Prints the kustomize version -> -> Flags: -> -h, --help help for kustomize -> --stack-trace print a stack-trace on error -> -> Additional help topics: -> kustomize docs-fn [Alpha] Documentation for developing and invoking Configuration Functions. -> kustomize docs-fn-spec [Alpha] Documentation for Configuration Functions Specification. -> kustomize docs-io-annotations [Alpha] Documentation for annotations used by io. -> kustomize docs-merge [Alpha] Documentation for merging Resources (2-way merge). -> kustomize docs-merge3 [Alpha] Documentation for merging Resources (3-way merge). -> kustomize tutorials-command-basics [Alpha] Tutorials for using basic config commands. -> kustomize tutorials-function-basics [Alpha] Tutorials for using functions. -> -> Use "kustomize [command] --help" for more information about a command. \ No newline at end of file diff --git a/site/content/en/guides/cmd/install-completion/_index.md b/site/content/en/guides/cmd/install-completion/_index.md deleted file mode 100644 index a4cfec63a..000000000 --- a/site/content/en/guides/cmd/install-completion/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "install-completion" -linkTitle: "install-completion" -type: docs -description: > - Installs shell completion ---- diff --git a/site/content/en/guides/cmd/live/_index.md b/site/content/en/guides/cmd/live/_index.md deleted file mode 100644 index 6ba80d260..000000000 --- a/site/content/en/guides/cmd/live/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "live" -linkTitle: "live" -type: docs -description: > - Commands for reading and writing resources to a cluster. ---- diff --git a/site/content/en/guides/cmd/version/_index.md b/site/content/en/guides/cmd/version/_index.md deleted file mode 100644 index ec1bda4db..000000000 --- a/site/content/en/guides/cmd/version/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "version" -linkTitle: "version" -type: docs -description: > - Prints the kustomize version ---- - -Prints the current kustomize version - -> ``` -> kustomize version -> {Version:kustomize/v3.8.1 GitCommit:0b359d0ef0272e6545eda0e99aacd63aef99c4d0 BuildDate:2020-07-16T00:58:46Z GoOs:linux GoArch:amd64} -> ``` \ No newline at end of file diff --git a/site/content/en/guides/components/_index.md b/site/content/en/guides/components/_index.md index 10cd329dc..b9ea9c9d5 100644 --- a/site/content/en/guides/components/_index.md +++ b/site/content/en/guides/components/_index.md @@ -8,365 +8,4 @@ description: > - -As of ``v3.7.0`` Kustomize supports a special type of kustomization that allows -one to define reusable pieces of configuration logic that can be included from -multiple overlays. - -Components come in handy when dealing with applications that support multiple -optional features and you wish to enable only a subset of them in different -overlays, i.e., different features for different environments or audiences. - -For more details regarding this feature you can read the -[Kustomize Components KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/1802-kustomize-components.md). - -## Use case - -Suppose you've written a very simple Web application: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example -spec: - template: - spec: - containers: - - name: example - image: example:1.0 -``` - -You want to deploy a **community** edition of this application as SaaS, so you -add support for persistence (e.g. an external database), and bot detection -(e.g. Google reCAPTCHA). - -You've now attracted **enterprise** customers who want to deploy it -on-premises, so you add LDAP support, and disable Google reCAPTCHA. At the same -time, the **devs** need to be able to test parts of the application, so they -want to deploy it with some features enabled and others not. - -Here's a matrix with the deployments of this application and the features -enabled for each one: - -| | External DB | LDAP | reCAPTCHA | -|------------|:------------------:|:------------------:|:------------------:| -| Community | ✔️ | | ✔️ | -| Enterprise | ✔️ | ✔️ | | -| Dev | ✅ | ✅ | ✅ | - -(✔️ enabled, ✅: optional) - -So, you want to make it easy to deploy your application in any of the above -three environments. Here's how you can do this with Kustomize components: each -opt-in feature gets packaged as a component, so that it can be referred to from -multiple higher-level overlays. - -First, define a place to work: - -```shell -DEMO_HOME=$(mktemp -d) -``` - -Define a common **base** that has a `Deployment` and a simple `ConfigMap`, that -is mounted on the application's container. - -```shell -BASE=$DEMO_HOME/base -mkdir $BASE - -cat <$BASE/kustomization.yaml -resources: -- deployment.yaml - -configMapGenerator: -- name: conf - literals: - - main.conf=| - color=cornflower_blue - log_level=info -EOF - -cat <$BASE/deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example -spec: - template: - spec: - containers: - - name: example - image: example:1.0 - volumeMounts: - - name: conf - mountPath: /etc/config - volumes: - - name: conf - configMap: - name: conf -EOF -``` - -Define an `external_db` component, using `kind: Component`, that creates a -`Secret` for the DB password and a new entry in the `ConfigMap`: - -```shell -EXT_DB=$DEMO_HOME/components/external_db -mkdir -p $EXT_DB - -cat <$EXT_DB/kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1alpha1 # <-- Component notation -kind: Component - -secretGenerator: -- name: dbpass - files: - - dbpass.txt - -patchesStrategicMerge: - - configmap.yaml - -patchesJson6902: -- target: - group: apps - version: v1 - kind: Deployment - name: example - path: deployment.yaml -EOF - -cat <$EXT_DB/deployment.yaml -- op: add - path: /spec/template/spec/volumes/0 - value: - name: dbpass - secret: - secretName: dbpass -- op: add - path: /spec/template/spec/containers/0/volumeMounts/0 - value: - mountPath: /var/run/secrets/db/ - name: dbpass -EOF - -cat <$EXT_DB/configmap.yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: conf -data: - db.conf: | - endpoint=127.0.0.1:1234 - name=app - user=admin - pass=/var/run/secrets/db/dbpass.txt -EOF -``` - -Define an `ldap` component, that creates a `Secret` for the LDAP password -and a new entry in the `ConfigMap`: - -```shell -LDAP=$DEMO_HOME/components/ldap -mkdir -p $LDAP - -cat <$LDAP/kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1alpha1 -kind: Component - -secretGenerator: -- name: ldappass - files: - - ldappass.txt - -patchesStrategicMerge: - - configmap.yaml - -patchesJson6902: -- target: - group: apps - version: v1 - kind: Deployment - name: example - path: deployment.yaml -EOF - -cat <$LDAP/deployment.yaml -- op: add - path: /spec/template/spec/volumes/0 - value: - name: ldappass - secret: - secretName: ldappass -- op: add - path: /spec/template/spec/containers/0/volumeMounts/0 - value: - mountPath: /var/run/secrets/ldap/ - name: ldappass -EOF - -cat <$LDAP/configmap.yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: conf -data: - ldap.conf: | - endpoint=ldap://ldap.example.com - bindDN=cn=admin,dc=example,dc=com - pass=/var/run/secrets/ldap/ldappass.txt -EOF -``` - -Define a `recaptcha` component, that creates a `Secret` for the reCAPTCHA -site/secret keys and a new entry in the `ConfigMap`: - -```shell -RECAPTCHA=$DEMO_HOME/components/recaptcha -mkdir -p $RECAPTCHA - -cat <$RECAPTCHA/kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1alpha1 -kind: Component - -secretGenerator: -- name: recaptcha - files: - - site_key.txt - - secret_key.txt - -# Updating the ConfigMap works with generators as well. -configMapGenerator: -- name: conf - behavior: merge - literals: - - recaptcha.conf=| - enabled=true - site_key=/var/run/secrets/recaptcha/site_key.txt - secret_key=/var/run/secrets/recaptcha/secret_key.txt - -patchesJson6902: -- target: - group: apps - version: v1 - kind: Deployment - name: example - path: deployment.yaml -EOF - -cat <$RECAPTCHA/deployment.yaml -- op: add - path: /spec/template/spec/volumes/0 - value: - name: recaptcha - secret: - secretName: recaptcha -- op: add - path: /spec/template/spec/containers/0/volumeMounts/0 - value: - mountPath: /var/run/secrets/recaptcha/ - name: recaptcha -EOF -``` - -Define a `community` variant, that bundles the external DB and reCAPTCHA -components: - -```shell -COMMUNITY=$DEMO_HOME/overlays/community -mkdir -p $COMMUNITY - -cat <$COMMUNITY/kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -resources: - - ../../base - -components: - - ../../components/external_db - - ../../components/recaptcha -EOF -``` - -Define an `enterprise` overlay, that bundles the external DB and LDAP -components: - -```shell -ENTERPRISE=$DEMO_HOME/overlays/enterprise -mkdir -p $ENTERPRISE - -cat <$ENTERPRISE/kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -resources: - - ../../base - -components: - - ../../components/external_db - - ../../components/ldap -EOF -``` - -Define a `dev` overlay, that points to all the components and has LDAP -disabled: - -```shell -DEV=$DEMO_HOME/overlays/dev -mkdir -p $DEV - -cat <$DEV/kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -resources: - - ../../base - -components: - - ../../components/external_db - #- ../../components/ldap - - ../../components/recaptcha -EOF -``` - -Now, the workspace has the following directories: - -```shell -├── base -│ ├── deployment.yaml -│ └── kustomization.yaml -├── components -│ ├── external_db -│ │ ├── configmap.yaml -│ │ ├── dbpass.txt -│ │ ├── deployment.yaml -│ │ └── kustomization.yaml -│ ├── ldap -│ │ ├── configmap.yaml -│ │ ├── deployment.yaml -│ │ ├── kustomization.yaml -│ │ └── ldappass.txt -│ └── recaptcha -│ ├── deployment.yaml -│ ├── kustomization.yaml -│ ├── secret_key.txt -│ └── site_key.txt -└── overlays - ├── community - │ └── kustomization.yaml - ├── dev - │ └── kustomization.yaml - └── enterprise - └── kustomization.yaml -``` - -With this structure, you can generate the YAML manifests for each deployment -using `kustomize build`: - -```shell -kustomize build overlays/community -kustomize build overlays/enterprise -kustomize build overlays/dev -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/offtheshelf/_index.md b/site/content/en/guides/offtheshelf/_index.md index 9aed80a10..354d7c80c 100644 --- a/site/content/en/guides/offtheshelf/_index.md +++ b/site/content/en/guides/offtheshelf/_index.md @@ -9,78 +9,4 @@ description: > - -In this workflow, all files are owned by the user and maintained in a repository under their control, but -they are based on an [off-the-shelf] configuration that is periodically consulted for updates. - -![off-the-shelf config workflow image][workflowOts] - -#### 1) find and [fork] an [OTS] config - -#### 2) clone it as your [base] - -The [base] directory is maintained in a repo whose upstream is an [OTS] configuration, in this case -some user's `ldap` repo: - -> ``` -> mkdir ~/ldap -> git clone https://github.com/$USER/ldap ~/ldap/base -> cd ~/ldap/base -> git remote add upstream git@github.com:$USER/ldap -> ``` - -#### 3) create [overlays] - -As in the bespoke case above, create and populate an _overlays_ directory. - -The [overlays] are siblings to each other and to the [base] they depend on. - -> ``` -> mkdir -p ~/ldap/overlays/staging -> mkdir -p ~/ldap/overlays/production -> ``` - -The user can maintain the `overlays` directory in a -distinct repository. - -#### 4) bring up [variants] - -> ``` -> kustomize build ~/ldap/overlays/staging | kubectl apply -f - -> kustomize build ~/ldap/overlays/production | kubectl apply -f - -> ``` - -You can also use [kubectl-v1.14.0] to apply your [variants]. -> -> ``` -> kubectl apply -k ~/ldap/overlays/staging -> kubectl apply -k ~/ldap/overlays/production -> ``` - -#### 5) (optionally) capture changes from upstream - -The user can periodically [rebase] their [base] to -capture changes made in the upstream repository. - -> ``` -> cd ~/ldap/base -> git fetch upstream -> git rebase upstream/master -> ``` - -[OTS]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[apply]: /kustomize/api-reference/glossary#apply -[applying]: /kustomize/api-reference/glossary#apply -[base]: /kustomize/api-reference/glossary#base -[fork]: https://guides.github.com/activities/forking/ -[variants]: /kustomize/api-reference/glossary#variant -[kustomization]: /kustomize/api-reference/glossary#kustomization -[off-the-shelf]: /kustomize/api-reference/glossary#off-the-shelf-configuration -[overlays]: /kustomize/api-reference/glossary#overlay -[patch]: /kustomize/api-reference/glossary#patch -[patches]: /kustomize/api-reference/glossary#patch -[rebase]: https://git-scm.com/docs/git-rebase -[resources]: /kustomize/api-reference/glossary#resource -[workflowBespoke]: /kustomize/images/workflowBespoke.jpg -[workflowOts]: /kustomize/images/workflowOts.jpg -[kubectl-v1.14.0]:https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/ +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/plugins/_index.md b/site/content/en/guides/plugins/_index.md index 9c60d55b1..06258389a 100644 --- a/site/content/en/guides/plugins/_index.md +++ b/site/content/en/guides/plugins/_index.md @@ -9,372 +9,4 @@ description: > -Kustomize offers a plugin framework allowing people to write their own resource _generators_ -and _transformers_. - -[generator options]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/generatorOptions.md -[transformer configs]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/transformerconfigs - -Write a plugin when changing [generator options] -or [transformer configs] doesn't meet your needs. - -[12-factor]: https://12factor.net - -* A _generator_ plugin could be a helm chart - inflator, or a plugin that emits all the - components (deployment, service, scaler, - ingress, etc.) needed by someone's [12-factor] - application, based on a smaller number of free - variables. - -* A _transformer_ plugin might perform special - container command line edits, or any other - transformation beyond those provided by the - builtin (`namePrefix`, `commonLabels`, etc.) - transformers. - -## Specification in `kustomization.yaml` - -Start by adding a `generators` and/or `transformers` -field to your kustomization. - -Each field accepts a string list: - -> ``` -> 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} -> ``` - -The value of each entry in a `generators` or -`transformers` list must be a relative path to a -YAML file, or a path or URL to a [kustomization]. -This is the same format as demanded by the -`resources` field. - -[kustomization]: /kustomize/api-reference/glossary#kustomization - -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 _plugin configuration_ object. - -## Configuration - -A kustomization file could have the following lines: - -``` -generators: -- chartInflator.yaml -``` - -Given this, the kustomization process would expect -to find a file called `chartInflator.yaml` in the -kustomization [root](/kustomize/api-reference/glossary#kustomization-root). - -This is the plugin's configuration file; -it contains a YAML configuration object. - -The file `chartInflator.yaml` could contain: - -``` -apiVersion: someteam.example.com/v1 -kind: ChartInflator -metadata: - name: notImportantHere -chartName: minecraft -``` - -__The `apiVersion` and `kind` fields are -used to locate the plugin.__ - -[k8s object]: /kustomize/api-reference/glossary#kubernetes-style-object - -Thus, these fields are required. They are also -required because a kustomize plugin configuration -object is also a [k8s object]. - -To get the plugin ready to generate or transform, -it is given the entire contents of the -configuration file. - -[NameTransformer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin/prefixsuffixtransformer/PrefixSuffixTransformer_test.go -[ChartInflator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator/ChartInflator_test.go -[plugins]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin - -For more examples of plugin configuration YAML, -browse the unit tests below the [plugins] root, -e.g. the tests for [ChartInflator] or -[NameTransformer]. - -## Placement - -Each plugin gets its own dedicated directory named - -[`XDG_CONFIG_HOME`]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html - -``` -$XDG_CONFIG_HOME/kustomize/plugin - /${apiVersion}/LOWERCASE(${kind}) -``` - -The default value of [`XDG_CONFIG_HOME`] is -`$HOME/.config`. - -The one-plugin-per-directory requirement eases -creation of a plugin bundle (source, tests, plugin -data files, etc.) for sharing. - -In the case of a [Go plugin](#go-plugins), it also -allows one to provide a `go.mod` file for the -single plugin, easing resolution of package -version dependency skew. - -When loading, kustomize will first look for an -_executable_ file called - -``` -$XDG_CONFIG_HOME/kustomize/plugin - /${apiVersion}/LOWERCASE(${kind})/${kind} -``` - -If this file is not found or is not executable, -kustomize will look for a file called `${kind}.so` -in the same directory and attempt to load it as a -[Go plugin](#go-plugins). - -If both checks fail, the plugin load fails the overall -`kustomize build`. - -## Execution - -Plugins are only used during a run of the -`kustomize build` command. - -Generator plugins are run after processing the -`resources` field (which itself can be viewed as a -generator, simply reading objects from disk). - -The full set of resources is then passed into the -transformation pipeline, wherein builtin -transformations like `namePrefix` and -`commonLabel` are applied (if they were specified -in the kustomization file), followed by the -user-specified transformers in the `transformers` -field. - -The order specified in the `transformers` field is -respected, as transformers cannot be expected to -be commutative. - -#### No Security - -Kustomize plugins do not run in any kind of -kustomize-provided sandbox. There's no notion -of _"plugin security"_. - -A `kustomize build` that tries to use plugins but -omits the flag - -> `--enable_alpha_plugins` - -will not load plugins and will fail with a -warning about plugin use. - -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. - -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 `kustomize build`. - -## Authoring - -There are two kinds of plugins, [exec](#exec-plugins) and [Go](#go-plugins). - -### Exec plugins - -A _exec plugin_ 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). - -> TODO: restrictions on plugin to allow the _same exec -> plugin_ to be targeted by both the -> `generators` and `transformers` fields. -> -> - first arg could be the fixed string -> `generate` or `transform`, -> (the name of the configuration file moves to -> the 2nd arg), or -> - or by default an exec plugin behaves as a tranformer -> unless a flag `-g` is provided, switching the -> exec plugin to behave as a generator. - -[helm chart inflator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/chartinflator -[bashed config map]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/bashedconfigmap -[sed transformer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/sedtransformer -[hashicorp go-getter]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/gogetter - -#### Examples - -* [helm chart inflator] - A generator that inflates a helm chart. -* [bashed config map] - Super simple configMap generation from bash. -* [sed transformer] - Define your unstructured edits using a - plugin like this one. -* [hashicorp go-getter] - Download kustomize layes and build it to generate resources - -A generator plugin accepts nothing on `stdin`, but emits -generated resources to `stdout`. - -A transformer plugin accepts resource YAML on `stdin`, -and emits those resources, presumably transformed, to -`stdout`. - -kustomize uses an exec plugin adapter to provide -marshalled resources on `stdin` and capture -`stdout` for further processing. - -#### Generator Options - -A generator exec plugin can adjust the generator options for the resources it emits by setting one of the following internal annotations. - -> NOTE: These annotations are local to kustomize and will not be included in the final output. - -**`kustomize.config.k8s.io/needs-hash`** - -Resources can be marked as needing to be processed by the internal hash transformer by including the `needs-hash` annotation. When set valid values for the annotation are `"true"` and `"false"` which respectively enable or disable hash suffixing for the resource. Omitting the annotation is equivalent to setting the value `"false"`. - -Hashes are determined as follows: - -* For `ConfigMap` resources, hashes are based on the values of the `name`, `data`, and `binaryData` fields. -* For `Secret` resources, hashes are based on the values of the `name`, `type`, `data`, and `stringData` fields. -* For any other object type, hashes are based on the entire object content (i.e. all fields). - -Example: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: cm-test - annotations: - kustomize.config.k8s.io/needs-hash: "true" -data: - foo: bar -``` - -**`kustomize.config.k8s.io/behavior`** - -The `behavior` annotation will influence how conflicts are handled for resources emitted by the plugin. Valid values include "create", "merge", and "replace" with "create" being the default. - -Example: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: cm-test - annotations: - kustomize.config.k8s.io/behavior: "merge" -data: - foo: bar -``` - -### Go plugins - -Be sure to read [Go plugin caveats](goplugincaveats/). - -[Go plugin]: https://golang.org/pkg/plugin/ - -A `.go` file can be a [Go plugin] if it declares -'main' as it's package, and exports a symbol to -which useful functions are attached. - -It can further be used as a _kustomize_ plugin if -the symbol is named 'KustomizePlugin' and the -attached functions implement the `Configurable`, -`Generator` and `Transformer` interfaces. - -A Go plugin for kustomize looks like this: - -> ``` -> package main -> -> import ( -> "sigs.k8s.io/kustomize/api/resmap" -> ... -> ) -> -> type plugin struct {...} -> -> var KustomizePlugin plugin -> -> func (p *plugin) Config( -> h *resmap.PluginHelpers, -> c []byte) error {...} -> -> func (p *plugin) Generate() (resmap.ResMap, error) {...} -> -> func (p *plugin) Transform(m resmap.ResMap) error {...} -> ``` - -Use of the identifiers `plugin`, `KustomizePlugin` -and implementation of the method signature -`Config` is required. - -Implementing the `Generator` or `Transformer` -method allows (respectively) the plugin's config -file to be added to the `generators` or -`transformers` field in the kustomization file. -Do one or the other or both as desired. - -[secret generator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/secretsfromdatabase -[service generator]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/someservicegenerator -[string prefixer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/stringprefixer -[date prefixer]: https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/someteam.example.com/v1/dateprefixer -[sops encoded secrets]: https://github.com/monopole/sopsencodedsecrets -[SOPSGenerator]: https://github.com/omninonsense/kustomize-sopsgenerator - -#### Examples - -* [service generator] - generate a service from a name and port argument. -* [string prefixer] - uses the value in `metadata/name` as the prefix. - This particular example exists to show how a plugin can - transform the behavior of a plugin. See the - `TestTransformedTransformers` test in the `target` package. -* [date prefixer] - prefix the current date to resource names, a simple - example used to modify the string prefixer plugin just mentioned. -* [secret generator] - generate secrets from a toy database. -* [sops encoded secrets] - a more complex secret generator that converts SOPS files into Kubernetes Secrets -* [SOPSGenerator] - another generator that decrypts SOPS files into Secrets -* [All the builtin plugins](https://github.com/kubernetes-sigs/kustomize/tree/master/plugin/builtin). - User authored plugins are - on the same footing as builtin operations. - -A Go plugin can be both a generator and a -transformer. The `Generate` method will run along -with all the other generators before the -`Transform` method runs. - -Here's a build command that sensibly assumes the -plugin source code sits in the directory where -kustomize expects to find `.so` files: - -``` -d=$XDG_CONFIG_HOME/kustomize/plugin\ -/${apiVersion}/LOWERCASE(${kind}) - -go build -buildmode plugin \ - -o $d/${kind}.so $d/${kind}.go -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/plugins/builtins.md b/site/content/en/guides/plugins/builtins.md index 4599635b0..ef2f41112 100644 --- a/site/content/en/guides/plugins/builtins.md +++ b/site/content/en/guides/plugins/builtins.md @@ -8,793 +8,4 @@ description: > - -# Builtin Plugins - -A list of kustomize's builtin plugins - both -generators and transformers. - -For each plugin, an example is given for - -- implicitly triggering - the plugin via a dedicated kustomization - file field (e.g. the `AnnotationsTransformer` is - triggered by the `commonAnnotations` field). - -- explicitly triggering the plugin - via the `generators` or `transformers` field - (by providing a config file specifying the - plugin). - -The former method is convenient but limited in -power as most of the plugins arguments must -be defaulted. The latter method allows for -complete plugin argument specification. - -[types.generatoroptions]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/generatoroptions.go -[types.secretargs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/secretargs.go -[types.configmapargs]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/configmapargs.go -[config.fieldspec]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/fieldspec.go -[types.objectmeta]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/objectmeta.go -[types.selector]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/selector.go -[types.replica]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/replica.go -[types.patchstrategicmerge]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/patchstrategicmerge.go -[types.patchtarget]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/patchtarget.go -[image.image]: https://github.com/kubernetes-sigs/kustomize/tree/master/api/types/image.go - -## _AnnotationTransformer_ - -### Usage via `kustomization.yaml` - -#### field name: `commonAnnotations` - -Adds annotions (non-identifying metadata) to add -all resources. Like labels, these are key value -pairs. - -``` -commonAnnotations: - oncallPager: 800-555-1212 -``` - -### Usage via plugin - -#### Arguments - -> Annotations map\[string\]string -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example - -> ``` -> apiVersion: builtin -> kind: AnnotationsTransformer -> metadata: -> name: not-important-to-example -> annotations: -> app: myApp -> greeting/morning: a string with blanks -> fieldSpecs: -> - path: metadata/annotations -> create: true -> ``` - -## _ConfigMapGenerator_ - -### Usage via `kustomization.yaml` - -#### field name: `configMapGenerator` - -Each entry in this list results in the creation of -one ConfigMap resource (it's a generator of n maps). - -The example below creates three ConfigMaps. One with the names and contents of -the given files, one with key/value as data, and a third which sets an -annotation and label via `options` for that single ConfigMap. - -Each configMapGenerator item accepts a parameter of -`behavior: [create|replace|merge]`. -This allows an overlay to modify or -replace an existing configMap from the parent. - -Also, each entry has an `options` field, that has the -same subfields as the kustomization file's `generatorOptions` field. - -This `options` field allows one to add labels and/or -annotations to the generated instance, or to individually -disable the name suffix hash for that instance. -Labels and annotations added here will not be overwritten -by the global options associated with the kustomization -file `generatorOptions` field. However, due to how -booleans behave, if the global `generatorOptions` field -specifies `disableNameSuffixHash: true`, this will -trump any attempt to locally override it. - -``` -# These labels are added to all configmaps and secrets. -generatorOptions: - labels: - fruit: apple - -configMapGenerator: -- name: my-java-server-props - behavior: merge - files: - - application.properties - - more.properties -- name: my-java-server-env-vars - literals: - - JAVA_HOME=/opt/java/jdk - - JAVA_TOOL_OPTIONS=-agentlib:hprof - options: - disableNameSuffixHash: true - labels: - pet: dog -- name: dashboards - files: - - mydashboard.json - options: - annotations: - dashboard: "1" - labels: - app.kubernetes.io/name: "app1" -``` - -It is also possible to -[define a key](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-the-key-to-use-when-creating-a-configmap-from-a-file) -to set a name different than the filename. - -The example below creates a ConfigMap -with the name of file as `myFileName.ini` -while the _actual_ filename from which the -configmap is created is `whatever.ini`. - -``` -configMapGenerator: -- name: app-whatever - files: - - myFileName.ini=whatever.ini -``` - -### Usage via plugin - -#### Arguments - -> [types.ConfigMapArgs] - -#### Example - -> ``` -> apiVersion: builtin -> kind: ConfigMapGenerator -> metadata: -> name: mymap -> envs: -> - devops.env -> - uxteam.env -> literals: -> - FRUIT=apple -> - VEGETABLE=carrot -> ``` - -## _ImageTagTransformer_ - -### Usage via `kustomization.yaml` - -#### field name: `images` - -Images modify the name, tags and/or digest for images -without creating patches. E.g. Given this -kubernetes Deployment fragment: - -``` -containers: -- name: mypostgresdb - image: postgres:8 -- name: nginxapp - image: nginx:1.7.9 -- name: myapp - image: my-demo-app:latest -- name: alpine-app - image: alpine:3.7 -``` - -one can change the `image` in the following ways: - -- `postgres:8` to `my-registry/my-postgres:v1`, -- nginx tag `1.7.9` to `1.8.0`, -- image name `my-demo-app` to `my-app`, -- alpine's tag `3.7` to a digest value - -all with the following _kustomization_: - -``` -images: -- name: postgres - newName: my-registry/my-postgres - newTag: v1 -- name: nginx - newTag: 1.8.0 -- name: my-demo-app - newName: my-app -- name: alpine - digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 -``` - -### Usage via plugin - -#### Arguments - -> ImageTag [image.Image] -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example - -> ``` -> apiVersion: builtin -> kind: ImageTagTransformer -> metadata: -> name: not-important-to-example -> imageTag: -> name: nginx -> newTag: v2 -> ``` - -## _LabelTransformer_ - -### Usage via `kustomization.yaml` - -#### field name: `commonLabels` - -Adds labels to all resources and selectors - -``` -commonLabels: - someName: someValue - owner: alice - app: bingo -``` - -### Usage via plugin - -#### Arguments - -> Labels map\[string\]string -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example - -> ``` -> apiVersion: builtin -> kind: LabelTransformer -> metadata: -> name: not-important-to-example -> labels: -> app: myApp -> env: production -> fieldSpecs: -> - path: metadata/labels -> create: true -> ``` - -## _NamespaceTransformer_ - -### Usage via `kustomization.yaml` - -#### field name: `namespace` - -Adds namespace to all resources - -``` -namespace: my-namespace -``` - -### Usage via plugin - -#### Arguments - -> [types.ObjectMeta] -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example - -> ``` -> apiVersion: builtin -> kind: NamespaceTransformer -> metadata: -> name: not-important-to-example -> namespace: test -> fieldSpecs: -> - path: metadata/namespace -> create: true -> - path: subjects -> kind: RoleBinding -> group: rbac.authorization.k8s.io -> - path: subjects -> kind: ClusterRoleBinding -> group: rbac.authorization.k8s.io -> ``` - -## _PatchesJson6902_ - -### Usage via `kustomization.yaml` - -#### field name: `patchesJson6902` - -Each entry in this list should resolve to -a kubernetes object and a JSON patch that will be applied -to the object. -The JSON patch is documented at - -target field points to a kubernetes object within the same kustomization -by the object's group, version, kind, name and namespace. -path field is a relative file path of a JSON patch file. -The content in this patch file can be either in JSON format as - -``` - [ - {"op": "add", "path": "/some/new/path", "value": "value"}, - {"op": "replace", "path": "/some/existing/path", "value": "new value"} - ] -``` - -or in YAML format as - -``` -- op: add - path: /some/new/path - value: value -- op: replace - path: /some/existing/path - value: new value -``` - -``` -patchesJson6902: -- target: - version: v1 - kind: Deployment - name: my-deployment - path: add_init_container.yaml -- target: - version: v1 - kind: Service - name: my-service - path: add_service_annotation.yaml -``` - -The patch content can be an inline string as well: - -``` -patchesJson6902: -- target: - version: v1 - kind: Deployment - name: my-deployment - patch: |- - - op: add - path: /some/new/path - value: value - - op: replace - path: /some/existing/path - value: "new value" -``` - -### Usage via plugin - -#### Arguments - -> Target [types.PatchTarget] -> -> Path string -> -> JsonOp string - -#### Example - -> ``` -> apiVersion: builtin -> kind: PatchJson6902Transformer -> metadata: -> name: not-important-to-example -> target: -> group: apps -> version: v1 -> kind: Deployment -> name: my-deploy -> path: jsonpatch.json -> ``` - -## _PatchesStrategicMerge_ - -### Usage via `kustomization.yaml` - -#### field name: `patchesStrategicMerge` - -Each entry in this list should be either a relative -file path or an inline content -resolving to a partial or complete resource -definition. - -The names in these (possibly partial) resource -files must match names already loaded via the -`resources` field. These entries are used to -_patch_ (modify) the known resources. - -Small patches that do one thing are best, e.g. modify -a memory request/limit, change an env var in a -ConfigMap, etc. Small patches are easy to review and -easy to mix together in overlays. - -``` -patchesStrategicMerge: -- service_port_8888.yaml -- deployment_increase_replicas.yaml -- deployment_increase_memory.yaml -``` - -The patch content can be a inline string as well. - -``` -patchesStrategicMerge: -- |- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: nginx - spec: - template: - spec: - containers: - - name: nginx - image: nignx:latest -``` - -Note that kustomize does not support more than one patch -for the same object that contain a _delete_ directive. To remove -several fields / slice elements from an object create a single -patch that performs all the needed deletions. - -### Usage via plugin - -#### Arguments - -> Paths \[\][types.PatchStrategicMerge] -> -> Patches string - -#### Example - -> ``` -> apiVersion: builtin -> kind: PatchStrategicMergeTransformer -> metadata: -> name: not-important-to-example -> paths: -> - patch.yaml -> ``` - -## _PatchTransformer_ - -### Usage via `kustomization.yaml` - -#### field name: `patches` - -Each entry in this list should resolve to an Patch -object, which includes a patch and a target selector. -The patch can be either a strategic merge patch or a -JSON patch. it can be either a patch file or an inline -string. The target selects -resources by group, version, kind, name, namespace, -labelSelector and annotationSelector. A resource -which matches all the specified fields is selected -to apply the patch. - -``` -patches: -- path: patch.yaml - target: - group: apps - version: v1 - kind: Deployment - name: deploy.* - labelSelector: "env=dev" - annotationSelector: "zone=west" -- patch: |- - - op: replace - path: /some/existing/path - value: new value - target: - kind: MyKind - labelSelector: "env=dev" -``` - -The `name` and `namespace` fields of the patch target selector are -automatically anchored regular expressions. This means that the value `myapp` -is equivalent to `^myapp$`. - -### Usage via plugin - -#### Arguments - -> Path string -> -> Patch string -> -> Target \*[types.Selector] - -#### Example - -> ``` -> apiVersion: builtin -> kind: PatchTransformer -> metadata: -> name: not-important-to-example -> patch: '[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value": "nginx:latest"}]' -> target: -> name: .*Deploy -> kind: Deployment -> ``` - -## _PrefixSuffixTransformer_ - -### Usage via `kustomization.yaml` - -#### field names: `namePrefix`, `nameSuffix` - -Prepends or postfixes the value to the names -of all resources. - -E.g. a deployment named `wordpress` could -become `alices-wordpress` or `wordpress-v2` -or `alices-wordpress-v2`. - -``` -namePrefix: alices- -nameSuffix: -v2 -``` - -The suffix is appended before the content hash if -the resource type is ConfigMap or Secret. - -### Usage via plugin - -#### Arguments - -> Prefix string -> -> Suffix string -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example - -> ``` -> apiVersion: builtin -> kind: PrefixSuffixTransformer -> metadata: -> name: not-important-to-example -> prefix: baked- -> suffix: -pie -> fieldSpecs: -> - path: metadata/name -> ``` - -## _ReplicaCountTransformer_ - -### Usage via `kustomization.yaml` - -#### field name: `replicas` - -Replicas modified the number of replicas for a resource. - -E.g. Given this kubernetes Deployment fragment: - -``` -kind: Deployment -metadata: - name: deployment-name -spec: - replicas: 3 -``` - -one can change the number of replicas to 5 -by adding the following to your kustomization: - -``` -replicas: -- name: deployment-name - count: 5 -``` - -This field accepts a list, so many resources can -be modified at the same time. - -As this declaration does not take in a `kind:` nor a `group:` -it will match any `group` and `kind` that has a matching name and -that is one of: - -- `Deployment` -- `ReplicationController` -- `ReplicaSet` -- `StatefulSet` - -For more complex use cases, revert to using a patch. - -### Usage via plugin - -#### Arguments - -> Replica [types.Replica] -> -> FieldSpecs \[\][config.FieldSpec] - -#### Example - -> ``` -> apiVersion: builtin -> kind: ReplicaCountTransformer -> metadata: -> name: not-important-to-example -> replica: -> name: myapp -> count: 23 -> fieldSpecs: -> - path: spec/replicas -> create: true -> kind: Deployment -> - path: spec/replicas -> create: true -> kind: ReplicationController -> ``` - -## _SecretGenerator_ - -### Usage via `kustomization.yaml` - -#### field name: `secretGenerator` - -Each entry in the argument list -results in the creation of -one Secret resource -(it's a generator of n secrets). - -This works like the `configMapGenerator` field -described above. - -``` -secretGenerator: -- name: app-tls - files: - - secret/tls.cert - - secret/tls.key - type: "kubernetes.io/tls" -- name: app-tls-namespaced - # you can define a namespace to generate - # a secret in, defaults to: "default" - namespace: apps - files: - - tls.crt=catsecret/tls.cert - - tls.key=secret/tls.key - type: "kubernetes.io/tls" -- name: env_file_secret - envs: - - env.txt - type: Opaque -- name: secret-with-annotation - files: - - app-config.yaml - type: Opaque - options: - annotations: - app_config: "true" - labels: - app.kubernetes.io/name: "app2" -``` - -### Usage via plugin - -#### Arguments - -> [types.ObjectMeta] -> -> [types.SecretArgs] - -#### Example - -> ``` -> apiVersion: builtin -> kind: SecretGenerator -> metadata: -> name: my-secret -> namespace: whatever -> behavior: merge -> envs: -> - a.env -> - b.env -> files: -> - obscure=longsecret.txt -> literals: -> - FRUIT=apple -> - VEGETABLE=carrot -> ``` - -## _HelmChartInflationGenerator_ - -### Usage via `kustomization.yaml` - -#### field name: `helmChartInflationGenerator` - -Each entry in the argument list results in the pulling -and rendering of a helm chart. - -Each entry can have following fields: - -- `chartName`: The name of the chart that you want to use. -- `chartRepoUrl`: [Optional] The URL of the repository which contains the chart. If - this is provided, the plugin will try to fetch remote charts. Otherwise it will - try to load local chart in `chartHome`. -- `chartVersion`: [Optional] Version of the chart. Will use latest version - if this is omitted. -- `chartHome`: [Optional] Provide the path to the parent directory for local chart. -- `chartRelease`: [Optional] The name of the repo where to find the chart. -- `values`: [Optional] A path to the values file. -- `releaseName`: [Optional] The release name that will be set in the chart. -- `releaseNamespace`: [Optional] The namespace which will be used by `--namespace` - flag in `helm template` command. -- `helmBin`: [Optional] Path to helm binary. Default is `helm`. -- `helmHome`: [Optional] Path to helm home directory. - -``` -helmChartInflationGenerator: -- chartName: minecraft - chartRepoUrl: https://kubernetes-charts.storage.googleapis.com - chartVersion: v1.2.0 - releaseName: test - releaseNamespace: testNamespace -``` - -### Usage via plugin - -#### Arguments - -> ChartName string -> -> ChartVersion string -> -> ChartRepoURL string -> -> ChartHome string -> -> ChartRepoName string -> -> HelmBin string -> -> HelmHome string -> -> Values string -> -> ReleaseName string -> -> ReleaseNamespace string - -#### Example - -> ``` -> apiVersion: builtin -> kind: HelmChartInflationGenerator -> metadata: -> name: myMap -> chartName: minecraft -> chartRepoUrl: https://kubernetes-charts.storage.googleapis.com -> chartVersion: v1.2.0 -> helmBin: /usr/bin/helm -> helmHome: /tmp/helmHome -> releaseName: test -> releaseNamespace: testNamespace -> values: values.yaml -> ``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/plugins/execPluginGuidedExample.md b/site/content/en/guides/plugins/execPluginGuidedExample.md index ecd91c5dc..5de5ec4cb 100644 --- a/site/content/en/guides/plugins/execPluginGuidedExample.md +++ b/site/content/en/guides/plugins/execPluginGuidedExample.md @@ -8,230 +8,4 @@ description: > - -This is a (no reading allowed!) 60 second copy/paste guided -example. Full plugin docs [here](..). - -This demo writes and uses a somewhat ridiculous -_exec_ plugin (written in bash) that generates a -`ConfigMap`. - -This is a guide to try it without damaging your -current setup. - -#### requirements - -* linux, git, curl, Go 1.13 - -## Make a place to work - -``` -DEMO=$(mktemp -d) -``` - -## Create a kustomization - -Make a kustomization directory to -hold all your config: - -``` -MYAPP=$DEMO/myapp -mkdir -p $MYAPP -``` - -Make a deployment config: - -``` -cat <<'EOF' >$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: ["/hello", - "--port=8080", - "--date=$(THE_DATE)", - "--enableRiskyFeature=$(ENABLE_RISKY)"] - 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 -``` - -Make a service config: - -``` -cat <$MYAPP/service.yaml -kind: Service -apiVersion: v1 -metadata: - name: the-service -spec: - type: LoadBalancer - ports: - - protocol: TCP - port: 8666 - targetPort: 8080 -EOF -``` - -Now make a config file for the plugin -you're about to write. - -This config file is just another k8s resource -object. The values of its `apiVersion` and `kind` -fields are used to _find_ the plugin code on your -filesystem (more on this later). - -``` -cat <<'EOF' >$MYAPP/cmGenerator.yaml -apiVersion: myDevOpsTeam -kind: SillyConfigMapGenerator -metadata: - name: whatever -argsOneLiner: Bienvenue true -EOF -``` - -Finally, make a kustomization file -referencing all of the above: - -``` -cat <$MYAPP/kustomization.yaml -commonLabels: - app: hello -resources: -- deployment.yaml -- service.yaml -generators: -- cmGenerator.yaml -EOF -``` - -Review the files - -``` -ls -C1 $MYAPP -``` - -## Make a home for plugins - -Plugins must live in a particular place for -kustomize to find them. - -This demo will use the ephemeral directory: - -``` -PLUGIN_ROOT=$DEMO/kustomize/plugin -``` - -The plugin config defined above in -`$MYAPP/cmGenerator.yaml` specifies: - -> ``` -> apiVersion: myDevOpsTeam -> kind: SillyConfigMapGenerator -> ``` - -This means the plugin must live in a directory -named: - -``` -MY_PLUGIN_DIR=$PLUGIN_ROOT/myDevOpsTeam/sillyconfigmapgenerator - -mkdir -p $MY_PLUGIN_DIR -``` - -The directory name is the plugin config's -_apiVersion_ followed by its lower-cased _kind_. - -A plugin gets its own directory to hold itself, -its tests and any supplemental data files it -might need. - -## Create the plugin - -There are two kinds of plugins, _exec_ and _Go_. - -Make an _exec_ plugin, installing it to the -correct directory and file name. The file name -must match the plugin's _kind_ (in this case, -`SillyConfigMapGenerator`): - -``` -cat <<'EOF' >$MY_PLUGIN_DIR/SillyConfigMapGenerator -#!/bin/bash -# Skip the config file name argument. -shift -today=`date +%F` -echo " -kind: ConfigMap -apiVersion: v1 -metadata: - name: the-map -data: - today: $today - altGreeting: "$1" - enableRisky: "$2" -" -EOF -``` - -By definition, an _exec_ plugin must be executable: - -``` -chmod a+x $MY_PLUGIN_DIR/SillyConfigMapGenerator -``` - -## Install kustomize - -Per the [instructions](/kustomize/installation): - -``` -curl -s "https://raw.githubusercontent.com/\ -kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -mkdir -p $DEMO/bin -mv kustomize $DEMO/bin -``` - -## Review the layout - -``` -tree $DEMO -``` - -## Build your app, using the plugin - -``` -XDG_CONFIG_HOME=$DEMO $DEMO/bin/kustomize build --enable_alpha_plugins $MYAPP -``` - -Above, if you had set - -> ``` -> PLUGIN_ROOT=$HOME/.config/kustomize/plugin -> ``` - -there would be no need to use `XDG_CONFIG_HOME` in the -_kustomize_ command above. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/plugins/goPluginCaveats.md b/site/content/en/guides/plugins/goPluginCaveats.md index 3a09a412c..1bc6ae1b2 100644 --- a/site/content/en/guides/plugins/goPluginCaveats.md +++ b/site/content/en/guides/plugins/goPluginCaveats.md @@ -8,120 +8,4 @@ description: > -[plugin package]: https://golang.org/pkg/plugin -[Go modules]: https://github.com/golang/go/wiki/Modules -[ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format -[tensorflow plugin]: https://www.tensorflow.org/guide/extend/op - -A _Go plugin_ is a compilation artifact described -by the Go [plugin package]. It is built with -special flags and cannot run on its own. -It must be loaded into a running Go program. - -> A normal program written in Go might be usable -> as _exec plugin_, but is not a _Go plugin_. - -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. - -Go plugins work as described in the [plugin -package], but fall short of common notions -associated with the word _plugin_. - -## The skew problem - -Go plugin compilation creates an [ELF] formatted -`.so` file, which by definition has no information -about the provenance of the object code. - -Skew between the compilation conditions (versions -of package dependencies, `GOOS`, `GOARCH`) of the -main program ELF and the plugin ELF will cause -plugin load failure, with non-helpful error -messages. - -Exec plugins also lack provenance, but won't fail -due to compilation skew. - -In either case, the only sensible way to share a -plugin is as some kind of _bundle_ (a git repo -URL, a git archive file, a tar file, etc.) -containing source code, tests and associated data, -unpackable under -`$XDG_CONFIG_HOME/kustomize/plugin`. - -In the case of a Go plugin, an _end user_ -accepting a shared plugin _must compile both -kustomize and the plugin_. - -This means a one-time run of - -``` -# Or whatever is appropriate at time of reading -GOPATH=${whatever} GO111MODULE=on go get sigs.k8s.io/kustomize/api -``` - -and then a normal development cycle using - -``` -go build -buildmode plugin \ - -o ${wherever}/${kind}.so ${wherever}/${kind}.go -``` - -with paths and the release version tag (e.g. `v3.0.0`) -adjusted as needed. - -For comparison, consider what one -must do to write a [tensorflow plugin]. - -## Why support Go plugins - -### Safety - -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. - -Minor point: if the plugin reads files via -the kustomize-provided file `Loader` interface, it -will be constrained by kustomize file loading -restrictions. Of course, nothing but a code audit -prevents a Go plugin from importing the `io` package -and doing whatever it wants. - -### Debugging - -A Go plugin developer can debug the plugin _in -situ_, setting breakpoints inside the plugin and -elsewhere while running a plugin in feature tests. - -To get the best of both worlds (shareability and safety), -a developer can write an `.go` program that functions -as an _exec plugin_, but can be processed by `go generate` -to emit a _Go plugin_ (or vice versa). - -### Unit of contribution - -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). - -### Ecosystems grow through use - -Tooling could ease Go plugin _sharing_, but this -requires some critical mass of Go plugin -_authoring_, which in turn is hampered by -confusion around sharing. [Go modules], once they -are more widely adopted, will solve the -biggest plugin sharing difficulty: ambiguous -plugin vs host dependencies. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/guides/plugins/goPluginGuidedExample.md b/site/content/en/guides/plugins/goPluginGuidedExample.md index e06b92f02..709c9b85b 100644 --- a/site/content/en/guides/plugins/goPluginGuidedExample.md +++ b/site/content/en/guides/plugins/goPluginGuidedExample.md @@ -8,371 +8,4 @@ description: > - -# Go Plugin Guided Example for Linux - -[SopsEncodedSecrets repository]: https://github.com/monopole/sopsencodedsecrets -[Go plugin]: https://golang.org/pkg/plugin -[Go plugin caveats]: goPluginCaveats.md - -This is a (no reading allowed!) 60 second copy/paste guided -example. - -Full plugin docs [here](README.md). -Be sure to read the [Go plugin caveats]. - -This demo uses a Go plugin, `SopsEncodedSecrets`, -that lives in the [sopsencodedsecrets repository]. -This is an inprocess [Go plugin], not an -sub-process exec plugin that happens to be written -in Go (which is another option for Go authors). - -This is a guide to try it without damaging your -current setup. - -#### requirements - -* linux, git, curl, Go 1.13 - -For encryption - -* gpg - -Or - -* Google cloud (gcloud) install -* a Google account with KMS permission - -## Make a place to work - -```shell -# Keeping these separate to avoid cluttering the DEMO dir. -DEMO=$(mktemp -d) -tmpGoPath=$(mktemp -d) -``` - -## Install kustomize - -Need v3.0.0 for what follows, and you must _compile_ -it (not download the binary from the release page): - -```shell -GOPATH=$tmpGoPath go install sigs.k8s.io/kustomize/kustomize -``` - -## Make a home for plugins - -A kustomize plugin is fully determined by -its configuration file and source code. - -[required fields]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields - -Kustomize plugin configuration files are formatted -as kubernetes resource objects, meaning -`apiVersion`, `kind` and `metadata` are [required -fields] in these config files. - -The kustomize program reads the config file -(because the config file name appears in the -`generators` or `transformers` field in the -kustomization file), then locates the Go plugin's -object code at the following location: - -> ```shell -> $XDG_CONFIG_HOME/kustomize/plugin/$apiVersion/$lKind/$kind.so -> ``` - -where `lKind` holds the lowercased kind. The -plugin is then loaded and fed its config, and the -plugin's output becomes part of the overall -`kustomize build` process. - -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's not -left to plugins to find their own config. - -This demo will house the plugin it uses at the -ephemeral directory - -```shell -PLUGIN_ROOT=$DEMO/kustomize/plugin -``` - -and ephemerally set `XDG_CONFIG_HOME` on a command -line below. - -### What apiVersion and kind - -At this stage in the development of kustomize -plugins, plugin code doesn't know or care what -`apiVersion` or `kind` appears in the config file -sent to it. - -The plugin could check these fields, but it'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. - -This demo uses a plugin called _SopsEncodedSecrets_, -and it lives in the [SopsEncodedSecrets repository]. - -Somewhat arbitrarily, we'll chose to install -this plugin with - -```shell -apiVersion=mygenerators -kind=SopsEncodedSecrets -``` - -### Define the plugin's home dir - -By convention, the ultimate home of the plugin -code and supplemental data, tests, documentation, -etc. is the lowercase form of its kind. - -```shell -lKind=$(echo $kind | awk '{print tolower($0)}') -``` - -### Download the SopsEncodedSecrets plugin - -In this case, the repo name matches the lowercase -kind already, so we just clone the repo and get -the proper directory name automatically: - -```shell -mkdir -p $PLUGIN_ROOT/${apiVersion} -cd $PLUGIN_ROOT/${apiVersion} -git clone git@github.com:monopole/sopsencodedsecrets.git -``` - -Remember this directory: - -```shell -MY_PLUGIN_DIR=$PLUGIN_ROOT/${apiVersion}/${lKind} -``` - -### Try the plugin's own test - -Plugins may come with their own tests. -This one does, and it hopefully passes: - -```shell -cd $MY_PLUGIN_DIR -go test SopsEncodedSecrets_test.go -``` - -Build the object code for use by kustomize: - -```shell -cd $MY_PLUGIN_DIR -GOPATH=$tmpGoPath go build -buildmode plugin -o ${kind}.so ${kind}.go -``` - -This step may succeed, but kustomize might -ultimately fail to load the plugin because of -dependency [skew]. - -[skew]: /docs/plugins/README.md#caveats -[used in this demo]: #install-kustomize - -On load failure - -* be sure to build the plugin with the same - version of Go (_go1.13_) on the same `$GOOS` - (_linux_) and `$GOARCH` (_amd64_) used to build - the kustomize being [used in this demo]. - -* change the plugin's dependencies in its `go.mod` - to match the versions used by kustomize (check - kustomize's `go.mod` used in its tagged commit). - -Lacking tools and metadata to allow this to be -automated, there won't be a Go plugin ecosystem. - -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. - -## Create a kustomization - -Make a kustomization directory to -hold all your config: - -```shell -MYAPP=$DEMO/myapp -mkdir -p $MYAPP -``` - -Make a config file for the SopsEncodedSecrets plugin. - -Its `apiVersion` and `kind` allow the plugin to be -found: - -```shell -cat <$MYAPP/secGenerator.yaml -apiVersion: ${apiVersion} -kind: ${kind} -metadata: - name: mySecretGenerator -name: forbiddenValues -namespace: production -file: myEncryptedData.yaml -keys: -- ROCKET -- CAR -EOF -``` - -This plugin expects to find more data in -`myEncryptedData.yaml`; we'll get to that shortly. - -Make a kustomization file referencing the plugin -config: - -```shell -cat <$MYAPP/kustomization.yaml -commonLabels: - app: hello -generators: -- secGenerator.yaml -EOF -``` - -Now generate the real encrypted data. - -### Assure you have an encryption tool installed - -We're going to use [sops](https://github.com/mozilla/sops) to encode a file. Choose either GPG or Google Cloud KMS as the secret provider to continue. - -#### GPG - -Try this: - -```shell -gpg --list-keys -``` - -If it returns a list, presumably you've already created keys. If not, try import test keys from sops for dev. - -```shell -curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc | gpg --import -SOPS_PGP_FP="1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A" -``` - -#### Google Cloude KMS - -Try this: - -```shell -gcloud kms keys list --location global --keyring sops -``` - -If it succeeds, presumably you've already created keys and placed them in a keyring called sops. If not, do this: - -```shell -gcloud kms keyrings create sops --location global -gcloud kms keys create sops-key --location global \ - --keyring sops --purpose encryption -``` - -Extract your keyLocation for use below: - -```shell -keyLocation=$(\ - gcloud kms keys list --location global --keyring sops |\ - grep GOOGLE | cut -d " " -f1) -echo $keyLocation -``` - -### Install `sops` - -```shell -GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops -``` - -### Create data encrypted with your private key - -Create raw data to encrypt: - -```shell -cat <$MYAPP/myClearData.yaml -VEGETABLE: carrot -ROCKET: saturn-v -FRUIT: apple -CAR: dymaxion -EOF -``` - -Encrypt the data into file the plugin wants to read: - -With PGP - -```shell -$tmpGoPath/bin/sops --encrypt \ - --pgp $SOPS_PGP_FP \ - $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml -``` - -Or GCP KMS - -```shell -$tmpGoPath/bin/sops --encrypt \ - --gcp-kms $keyLocation \ - $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml -``` - -Review the files - -```shell -tree $DEMO -``` - -This should look something like: - -> ```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 -> ``` - -## Build your app, using the plugin - -```shell -XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP -``` - -This should emit a kubernetes secret, with -encrypted data for the names `ROCKET` and `CAR`. - -Above, if you had set - -> ```shell -> PLUGIN_ROOT=$HOME/.config/kustomize/plugin -> ``` - -there would be no need to use `XDG_CONFIG_HOME` in the -_kustomize_ command above. +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/installation/_index.md b/site/content/en/installation/_index.md index eacb9d161..f15c992ed 100644 --- a/site/content/en/installation/_index.md +++ b/site/content/en/installation/_index.md @@ -9,3 +9,5 @@ menu: --- + +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/installation/binaries/_index.md b/site/content/en/installation/binaries/_index.md index 0e10a1799..42f913849 100644 --- a/site/content/en/installation/binaries/_index.md +++ b/site/content/en/installation/binaries/_index.md @@ -9,15 +9,4 @@ description: > -Binaries at various versions for linux, MacOs and Windows are published on the [releases page]. - -The following [script] detects your OS and downloads the appropriate kustomize binary to your -current working directory. - -``` -curl -s "https://raw.githubusercontent.com/\ -kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -``` - -[releases page]: https://github.com/kubernetes-sigs/kustomize/releases -[script]: https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/installation/chocolatey/_index.md b/site/content/en/installation/chocolatey/_index.md index e2e723608..dd9634179 100644 --- a/site/content/en/installation/chocolatey/_index.md +++ b/site/content/en/installation/chocolatey/_index.md @@ -10,12 +10,4 @@ description: > -``` -choco install kustomize -``` - -For support on the chocolatey package -and prior releases, see: - -- [Choco Package](https://chocolatey.org/packages/kustomize) -- [Package Source](https://github.com/kenmaglio/choco-kustomize) +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/installation/homebrew/_index.md b/site/content/en/installation/homebrew/_index.md index 5e422f8fb..8eed560b6 100644 --- a/site/content/en/installation/homebrew/_index.md +++ b/site/content/en/installation/homebrew/_index.md @@ -9,15 +9,4 @@ description: > - -For [Homebrew](https://brew.sh) users: - -``` -brew install kustomize -``` - -For [MacPorts](https://www.macports.org) users: - -``` -sudo port install kustomize -``` +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file diff --git a/site/content/en/installation/source/_index.md b/site/content/en/installation/source/_index.md index f4099b6c1..e5391b406 100644 --- a/site/content/en/installation/source/_index.md +++ b/site/content/en/installation/source/_index.md @@ -9,36 +9,4 @@ description: > -Requires [Go] to be installed. - -## Install the kustomize CLI from source without cloning the repo - -``` -GOBIN=$(pwd)/ GO111MODULE=on go get sigs.k8s.io/kustomize/kustomize/v3 -``` - -## Install the kustomize CLI from local source with cloning the repo - -``` -# Need go 1.13 or higher -unset GOPATH -# see https://golang.org/doc/go1.13#modules -unset GO111MODULES - -# clone the repo -git clone git@github.com:kubernetes-sigs/kustomize.git -# get into the repo root -cd kustomize - -# Optionally checkout a particular tag if you don't -# want to build at head -git checkout kustomize/v3.2.3 - -# build the binary -(cd kustomize; go install .) - -# run it -~/go/bin/kustomize version -``` - -[Go]: https://golang.org +Moved to https://github.com/kubernetes-sigs/cli-experimental \ No newline at end of file