...

Source file src/sigs.k8s.io/kustomize/api/internal/plugins/doc.go

Documentation: sigs.k8s.io/kustomize/api/internal/plugins

     1  // Copyright 2019 The Kubernetes Authors.
     2  // SPDX-License-Identifier: Apache-2.0
     3  
     4  /*
     5  
     6  Read docs/plugins.md first for an overview of kustomize plugins.
     7  
     8  
     9  BUILTIN PLUGIN CONFIGURATION
    10  
    11  There are two kinds of plugins, Go plugins (shared
    12  object library) and exec plugins (independent binary).
    13  For performance and standardized testing reasons, all
    14  builtin plugins are Go plugins (not exec plugins).
    15  
    16  Using "SecretGenerator" as an example in what
    17  follows.
    18  
    19  The plugin config file looks like
    20  
    21    apiVersion: builtin
    22    kind: SecretGenerator
    23    metadata:
    24      name: whatever
    25    otherField1: whatever
    26    otherField2: whatever
    27    ...
    28  
    29  The apiVersion must be 'builtin'.
    30  
    31  The kind is the CamelCase name of the plugin.
    32  
    33  The source for a builtin plugin must be at:
    34  
    35    repo=$GOPATH/src/sigs.k8s.io/kustomize
    36    ${repo}/plugin/builtin/LOWERCASE(${kind})/${kind}
    37  
    38  k8s wants 'kind' values to follow CamelCase, while
    39  Go style doesn't like but does allow such names.
    40  
    41  The lowercased value of kind is used as the name of the
    42  directory holding the plugin, its test, and any
    43  optional associated files (possibly a go.mod file).
    44  
    45  
    46  BUILTIN PLUGIN GENERATION
    47  
    48  The `pluginator` program is a code generator that
    49  converts kustomize generator (G) and/or
    50  transformer (T) Go plugins to statically linkable
    51  code.
    52  
    53  It arises from following requirements:
    54  
    55  * extension
    56    kustomize does two things - generate or
    57    transform k8s resources.  Plugins let
    58    users write their own G&T's without
    59    having to fork kustomize and learn its
    60    internals.
    61  
    62  * dogfooding
    63    A G&T extension framework one can trust
    64    should be used by its authors to deliver
    65    builtin G&T's.
    66  
    67  * distribution
    68    kustomize should be distributable via
    69    `go get` and should run where Go
    70       programs are expected to run.
    71  
    72  The extension requirement led to building
    73  a framework that accommodates writing a
    74  G or T as either
    75  
    76  * an 'exec' plugin (any executable file
    77    runnable as a kustomize subprocess), or
    78  
    79  * as a Go plugin - see
    80    https://golang.org/pkg/plugin.
    81  
    82  The dogfooding (and an implicit performance
    83  requirement) requires a 'builtin' G or T to
    84  be written as a Go plugin.
    85  
    86  The distribution ('go get') requirement demands
    87  conversion of Go plugins to statically linked
    88  code, hence this program.
    89  
    90  
    91  TO GENERATE CODE
    92  
    93    repo=$GOPATH/src/sigs.k8s.io/kustomize
    94    cd $repo/plugin/builtin
    95    go generate ./...
    96  
    97  This creates
    98  
    99    $repo/api/plugins/builtins/SecretGenerator.go
   100  
   101  etc.
   102  
   103  Generated plugins are used in kustomize via
   104  
   105    package whatever
   106    import sigs.k8s.io/kustomize/api/plugins/builtins
   107    ...
   108    g := builtin.NewSecretGenerator()
   109    g.Config(h, k)
   110    resources, err := g.Generate()
   111    err = g.Transform(resources)
   112    // Eventually emit resources.
   113  
   114  */
   115  package plugins
   116  

View as plain text