kustomizer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b88c7e828be9c93ec00ef81cd1fa0b583f2772c6b621cfab5ce0e422418d49c
-  data.tar.gz: a08c5c25f4c234ea9b698d64e6f327a5e3a17147d1cf17c613471fcf0f32a7cf
+  metadata.gz: 961ff655cafb23672a01fae7147f08a28d4198a59f72a07c092cfd8907acb98f
+  data.tar.gz: fdafe50e353de94b2105fa754a31ff6a40b347585f1d0359924410581ffa7b58
 SHA512:
-  metadata.gz: 42ecbbe674b0b4f49c434457f99cc43084e4c6d432789d15ac4a3081e345a5dda6b459ca1db1f15057f2279f3b00454dd46e5d350a4c60fe0e391495c26d5952
-  data.tar.gz: dbb5dbbca1c1b1ae4e95584fb9601284b5f8c3f73a2b4ba15f02d4f1bf382634d87e86632ec7319e90761beb6de8ef8cc946909531718df4bfeff3a9793351fd
+  metadata.gz: 60136761417e2ddcdeef7af0e1fb8898ba1cdb95b62e638e0355fba04af252c9b14fce85801f924109ebbae4be01f19e83a3b9795dbb29a9ea49303e71f62bfa
+  data.tar.gz: 1bce76a9ccb5549dc71e3bf1acb0a8c26f0ded8c0a785332f6d72c77d81fffc71ec9629fa593462312fe67bee80ffb19c5b78d792b5e6e3b3f02b0e39d805e93

data/Gemfile.lock

@@ -1,13 +1,15 @@
 PATH
   remote: .
   specs:
-    kustomizer (0.1.0)
+    kustomizer (0.1.1)
       accessory (~> 0.1.9)
+      base32-multi
 
 GEM
   remote: https://rubygems.org/
   specs:
     accessory (0.1.9)
+    base32-multi (0.1.1)
     diff-lcs (1.4.4)
     rake (13.0.3)
     rspec (3.10.0)

data/README.md

@@ -9,9 +9,14 @@ the user to have the native Go version of Kustomize installed.
 ## Roadmap
 
 KustomizeR is **not yet feature-complete**, i.e. it does not yet do everything
-that Kustomize does.
+that Kustomize does. KustomizeR probably won't work for arbitrary
+`kustomization.yaml` files.
 
-Status of `kustomization.yaml` support:
+(KustomizeR *is*, however, in production use; it is being used with
+`kustomization.yaml` files matching its current feature set. We wrote Just
+Enough Library to solve our own problems :wink:)
+
+Status of `kustomization.yaml` feature support:
 
 * [x] `bases`
 * [ ] `commonAnnotations`
@@ -31,7 +36,7 @@ Status of `kustomization.yaml` support:
 * [ ] `transformers` (see [Extending Kustomize](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/))
 * [ ] `vars`
 
-Status of support for other features:
+Status of support for other Kustomize features:
 
 * [ ] Resource loading
   * [x] resource-config files on disk
@@ -44,6 +49,15 @@ Status of support for other features:
   * [x] Secrets
   * [ ] ConfigMaps
 
+Status of support for "extra" features not supported by Kustomize:
+
+* [ ] `filters` (a plugin-type for dropping resource-configs from output)
+* [ ] `rewriters` (a plugin-type for entirely replacing output; takes all
+      intermediate resource-config docs as a single input)
+* [ ] Built-in plugins:
+  * [ ] `SealedSecretGenerator`
+  * [ ] `DerivedSecretGenerator`
+
 #### Differences from Kustomize
 
 * KustomizeR is **not yet feature-complete**. (KustomizeR will be bumped to
@@ -55,12 +69,16 @@ Status of support for other features:
 * KustomizeR is modular, and is intended to be loaded and used as a library,
   rather than being spawned as a subprocess. Crucially, the load path for
   plugins is under the caller's control, and so higher-level frameworks can
-  manage project-level KustomizeR plugins.
+  inject plugins into a KustomizeR session to suit their needs.
 
 * Some `kustomization.yaml` features have been temporarily extended in
-  non-compatible ways.
-  * `patchesJson6902` accepts an inline an `ops` array
-  * `patchesJson6902` accepts a `gsub` op
+  non-compatible ways:
+  * `patchesJson6902`
+    * accepts an inline `ops` array
+    * accepts lens accessor names in `path` (e.g. `/spec/rules/:all/host`)
+    * accepts a `paths` array rather than a single `path`
+    * accepts a `gsub` op (works like `replace` but with a regular expression;
+      has `pattern` and `replacement` fields)
 
 (Before v1.0, these extensions will be moved to become built-in plugins, to
 allow for inter-compatibility with Kustomize, which could support them as
@@ -86,12 +104,114 @@ Or install it yourself as:
 
 ```ruby
 require 'kustomize'
+```
+
+### Loading Kustomization documents
+
+You can either load a `kustomization.yaml` file by specifying its path:
+
+```ruby
 k = Kustomize.load("./path/to/kustomization.yaml")
 
-k.emit # Array of Hashes (the final resource-configs)
-k.to_yaml_stream # String (merged YAML multi-document stream)
+# equivalent; discovers the kustomization.yaml within the directory
+k = Kustomize.load("./path/to")
 ```
 
+Or you can load a `Kustomization` document spec directly:
+
+```ruby
+k_doc = {
+  'apiVersion' => 'kustomize.config.k8s.io/v1beta1',
+  'kind' => 'Kustomization',
+  # ...
+}
+
+k = Kustomization.load(k_doc, source_path: "./path/to/kustomization.yaml")
+```
+
+Note the `source_path` keyword parameter. Specifying a `source_path` for an
+in-memory Kustomization document is optional, but will usually be necessary, as
+the Kustomization document will need an effective path for itself, to use as a
+relative navigation prefix for any referenced on-disk resource files/directories.
+
+The `source_path` can be left out if all the resources a Kustomization document
+references are either remote or generated.
+
+### Rendering resource-configuration documents
+
+To get the final resource-configurations directly, as an Array of Hashes, call
+`KustomizationDocument#emit`:
+
+```ruby
+k.emit # => [{'kind' => 'Deployment', ...}, ...]
+```
+
+Or, to get a merged YAML multi-document stream suitable for feeding to
+`kubectl apply -f`, call `KustomizationDocument#to_yaml_stream`:
+
+```ruby
+k.to_yaml_stream # => "---\nkind: Deployment\n..."
+```
+
+### Accessing intermediate resources
+
+KustomizeR represents your Kustomization document as a digraph of `Emitter`
+instances, a combination of `FileEmitter`s, `DirectoryEmitter`s,
+`DocumentEmitter`s, and `PluginEmitter`s. You can think of these as being
+arranged akin to an audio VST digraph, where emitters are "plugged into" other
+downstream emitters, with the outputs (resource configs) of one emitter becoming
+inputs to another.
+
+All `Emitter` types support the following methods:
+
+```ruby
+e.input_emitters  # gets the emitters that feed their output into this emitter
+
+e.input_resources # runs the input emitters, gathering their outputs and
+                  # caching it as this emitter's input
+
+e.emit            # runs this emitter, producing the output that would be fed
+                  # into any downstream emitters
+```
+
+A `KustomizationDocument` constructed by `Kustomize.load` is just a regular
+`Emitter`; you can use it as the starting point to explore or manipulate the
+rest of the `Emitter` graph.
+
+### Sessions
+
+All emitters belong to a `Kustomize::Session`. When you call `Kustomize.load`,
+you pass in (or implicitly create) a new `Kustomize::Session`:
+
+```ruby
+Kustomize.load("./foo", session: Kustomize::Session.new)
+Kustomize.load("./foo") # equivalent to above
+```
+
+#### Plugin Load-Paths
+
+The `Kustomize::Session` manages plugin load-paths. By default, it defines a
+load-path referencing only the built-in plugins embedded within this gem.
+
+You can create your own subclass of `Kustomize::Session` to define a new
+load-path, and pass in an instance of it as the `session` keyword-parameter
+to `Kustomize.load`. This custom Session will be inherited by all `Emitter`s
+created under the loaded `KustomizeDocument` emitter.
+
+You can also add other features to your `Kustomize::Session` subclass. The
+passed-in `Session` is accessible within `Kustomize::Plugin`s as
+`this.session`, so it can be useful to pass e.g. a framework context object as
+a member of your `Kustomize::Session` subclass, for use by framework-specific
+plugins.
+
+#### Plugin Discovery and Loading
+
+The `Kustomize::Session` also holds an instance of `Kustomize::PluginManager`,
+which discovers, loads, and caches plugins.
+
+As such, if you're calling `Kustomize.load` a lot, it is recommended to reuse
+your `Kustomize::Session`, so that plugins need only be discovered+loaded once.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/kustomizer.gemspec

@@ -25,4 +25,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_runtime_dependency "accessory", "~> 0.1.9"
+  spec.add_runtime_dependency "base32-multi"
 end

data/lib/kustomize/version.rb

@@ -1,3 +1,3 @@
 module Kustomize
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kustomizer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Levi Aul
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.9
+- !ruby/object:Gem::Dependency
+  name: base32-multi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A pure-ruby implementation of the Kubernetes 'kustomize' command.
 email:
 - levi@leviaul.com