kube-dsl 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7a616f5571a180de6f04decd298d902b823148b10596292fa69ab68ce7f2ddb
-  data.tar.gz: 51d822c6644973f06cb3f8c819eef7bf99f21d54ff7c7820f0e3105b712a1880
+  metadata.gz: 03cadaa643bb90a6baa5338e3de7905f8243c0032fde7991db072ad7b964691c
+  data.tar.gz: 40feae243bcc6e2a953b1b97ae0bbd865b6239354e7abe47b471227b2dff582a
 SHA512:
-  metadata.gz: 821f0332b1aa16b3ba3ffc2fad7a3f453878fa97993dfb71fc74386dc5a0b1aecd0e56f9bd86518a869721d1a5d21a7c2f433edc8bc82e378bba5b1b1900929f
-  data.tar.gz: 6882c287e01af9c05d32a8729e1999a485a75bfec2fd433a53d65efbbd1de0d6fa6dc72b4f6169150d7f00b419e650d8ac4766308f23ba9d766c7bd7af0df354
+  metadata.gz: f4c771dd4d07ee252b160c1ca4d0de23b913298974bf12f9374ac58ff05aa368a0962a458a9543cb959fea1e4a1596257b22a0b4571d88a0a6bf634f920d1210
+  data.tar.gz: 17ac1ab5ebea2c780623bc8d5bf7600b660b09d709c2a132bedb130477b9c61f8377ecf6f22cb9be8335778eb902f1736e5d0adf1d45fa4ad65a230c81be1bc9

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.6.0
+* Improve path and namespace handling in generator.
+
+## 0.5.1
+* Support Ruby 2.7
+  - Stop using the `RubyToken` class from irb, which doesn't exist anymore.
+* Fix bug causing `NoMethodError`s if the type field contains a single string and not an array.
+
+## 0.5.0
+* Recursively validate.
+* Add README.
+
+## 0.4.0
+* Add validations.
+  - You can now call `#valid?` and `#validate` methods on DSL objects.
+* Fixed several bad inflections causing Ruby keywords to appear in unexpected places, namely in `#serialize` methods.
+* Prevent JSON schema "$" variables (eg. "$ref") from being added as fields.
+
 ## 0.3.0
 * Introduce the `key_value_field` method to simplify creating key/value fields.
 * Add `#merge` and `#merge!` methods to anything that includes or extends `ValueFields`.

data/README.md

@@ -0,0 +1,293 @@
+## kube-dsl
+A Ruby DSL for defining Kubernetes resources.
+
+## What is this thing?
+
+KubeDSL provides a [domain-specific language](https://en.wikipedia.org/wiki/Domain-specific_language) for defining Kubernetes resource objects in Ruby. Why would you want to do this? Well,
+
+1. I think Ruby code is easier to read than YAML.
+1. every property is a Ruby method, meaning Ruby will blow up if you try to configure the object the wrong way.
+1. doing so follows the principle of [infrastructure as code](https://en.wikipedia.org/wiki/Infrastructure_as_code).
+1. validations are built-in.
+
+## Installation
+
+Either run `gem install kube-dsl` or add it to your Gemfile:
+
+```ruby
+gem 'kube-dsl', '< 1'
+```
+
+## Usage
+
+KubeDSL directly mirrors the fields and nesting structure of each Kubernetes YAML (or JSON) object. Ruby fields are snake_cased while Kubernetes fields are camelCased. Let's take a look at a short example where we define a Namespace:
+
+```ruby
+ns = KubeDSL.namespace do
+  metadata do
+    name 'my-namespace'
+  end
+end
+```
+
+In the example above, we've defined a `KubeDSL::DSL::V1::Namespace` object and assigned it to a local variable called `ns`. Now let's convert it into a YAML string and print it out:
+
+```ruby
+# ---
+# apiVersion: v1
+# kind: Namespace
+# metadata:
+#   name: foo
+puts ns.to_resource.to_yaml
+```
+
+The `#to_resource` method returns an instance of the `KubeDSL::Resource` class while `#to_yaml` converts the resource into a YAML string. Pretty cool, eh? See the next few sections for examples creating other types of common Kubernetes objects.
+
+### ServiceAccount Example
+
+Note how key/value pairs are added to the `labels` field.
+
+```ruby
+KubeDSL.service_account do
+  metadata do
+    name 'my-service-account'
+    namespace 'my-namespace'
+
+    labels do
+      add :app, 'my-app'
+      add :role, 'web'
+    end
+  end
+end
+```
+
+### Service Example
+
+```ruby
+KubeDSL.service do
+  metadata do
+    name 'my-service'
+    namespace 'my-namespace'
+
+    labels do
+      add :app, 'my-app'
+      add :role, 'web'
+    end
+  end
+
+  spec do
+    type 'NodePort'
+
+    selector do
+      add :app, 'my-app'
+      add :role, 'web'
+    end
+
+    port do
+      name 'http'
+      port 3000
+      protocol 'TCP'
+      target_port 'http'
+    end
+  end
+end
+```
+
+### Deployment Example
+
+Note:
+
+1. Elements of arrays can be given names (see the use of the `#container` method below) so they can be easily retrieved and/or modified later.
+1. The example below shows how to add config maps and secrets to a deployment via references.
+
+```ruby
+KubeDSL.deployment do
+  metadata do
+    name 'my-deployment'
+    namespace 'my-namespace'
+
+    labels do
+      add :app, 'my-app'
+      add :role, 'web'
+    end
+  end
+
+  spec do
+    replicas 2
+
+    selector do
+      match_labels do
+        add :app, 'my-app'
+        add :role, 'web'
+      end
+    end
+
+    strategy do
+      type 'RollingUpdate'
+
+      rolling_update do
+        max_surge '25%'
+        max_unavailable 1
+      end
+    end
+
+    template do
+      metadata do
+        labels do
+          add :app, 'my-app'
+          add :role, 'web'
+        end
+      end
+
+      spec do
+        # elements of arrays can be given names (:web in this case) so they can be
+        # easily retrieved and/or modified later
+        container(:web) do
+          name 'my-web-container'
+          image_pull_policy 'IfNotPresent'
+
+          port do
+            container_port 3000
+            name 'http'
+            protocol 'TCP'
+          end
+
+          env_from do
+            config_map_ref do
+              name 'my-config-map'
+            end
+          end
+
+          env_from do
+            secret_ref do
+              name 'my-secrets'
+            end
+          end
+
+          readiness_probe do
+            success_threshold 1
+            failure_threshold 2
+            initial_delay_seconds 15
+            period_seconds 3
+            timeout_seconds 1
+
+            http_get do
+              path '/healthz'
+              port 3000
+              scheme 'HTTP'
+            end
+          end
+        end
+
+        image_pull_secret do
+          name 'my-registry-secret'
+        end
+      end
+
+      restart_policy 'Always'
+      service_account_name 'my-service-account'
+    end
+  end
+end
+```
+
+### Ingress Example
+
+NOTE: the example below includes an annotation that is specific to the Nginx ingress controller.
+
+```ruby
+KubeDSL::DSL::Extensions::V1beta1::Ingress.new do
+  metadata do
+    name 'my-ingress'
+    namespace 'my-namespace'
+
+    annotations do
+      add :'kubernetes.io/ingress.class', 'nginx'
+    end
+  end
+
+  spec do
+    rule do
+      host 'my-website.com'
+
+      http do
+        path do
+          path '/'
+
+          backend do
+            service_name 'my-service'
+            service_port 80
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+### ConfigMap Example
+
+```ruby
+KubeDSL.config_map do
+  metadata do
+    name 'my-config-map'
+    namespace 'my-namespace'
+  end
+
+  data do
+    add :MY_VAR, 'value'
+    add :MY_OTHER_VAR, 'value'
+  end
+end
+```
+
+### Secret Example
+
+```ruby
+KubeDSL.secret do
+  metadata do
+    name 'my-secrets'
+    namespace 'my-namespace'
+  end
+
+  type 'Opaque'
+
+  data do
+    add :MY_SECRET, 'value'
+  end
+end
+```
+
+## Validations
+
+All `KubeDSL::DSLObject`s respond to `#valid?` and `#validate` methods. Use `#valid?` to determine whether or not an object is valid. Use `#validate` to retrieve a list of validation errors:
+
+```ruby
+ns = KubeDSL.namespace do
+  metadata do
+    name 123
+  end
+end
+
+ns.valid?  # => false
+ns.validate  # => #<KubeDSL::Validations::ValidationErrors:0x00007fc8ce276e80 ... >
+ns.validate.messages  # => {"metadata.name"=>["is not a String"]}
+```
+
+The handy `#validate!` method will raise a `KubeDSL::ValidationError` if the object is invalid.
+
+## Code Generation
+
+All the Ruby code present in KubeDSL is generated from the Kubernetes JSON schema available [here](https://github.com/instrumenta/kubernetes-json-schema). Run the following rake task to regenerate:
+
+```bash
+bundle exec rake generate
+```
+
+## Authors
+
+* Cameron C. Dutro: http://github.com/camertron
+
+## License
+
+Licensed under the MIT license.

data/Rakefile

@@ -16,6 +16,7 @@ end
 
 task :generate do
   require 'dry/inflector'
+  require 'fileutils'
 
   FileUtils.rm_rf('./lib/kube-dsl/entrypoint.rb')
   FileUtils.rm_rf('./lib/kube-dsl/dsl.rb')
@@ -24,29 +25,36 @@ task :generate do
   FileUtils.mkdir_p('./vendor')
 
   export_url = "https://github.com/instrumenta/kubernetes-json-schema/trunk/v#{KubeDSL::KUBERNETES_VERSION}-local"
-  local_path = "vendor/kubernetes-json-schema/v#{KubeDSL::KUBERNETES_VERSION}-local"
+  local_schema_path = "vendor/kubernetes-json-schema/v#{KubeDSL::KUBERNETES_VERSION}-local"
 
-  unless File.exist?(local_path)
-    system("svn export #{export_url} #{local_path}")
+  unless File.exist?(local_schema_path)
+    system("svn export #{export_url} #{local_schema_path}")
   end
 
-  Dir.chdir('lib') do
-    generator = KubeDSL::Generator.new(
-      schema_dir: File.join('..', local_path),
-      output_dir: File.join('kube-dsl', 'dsl'),
-      inflector: Dry::Inflector.new do |inflections|
-        inflections.acronym('DSL')
-
-        inflections.plural('tls', 'tlses')
-        inflections.singular('tls', 'tls')
-      end
-    )
-
-    generator.generate_resource_files
-    generator.generate_autoload_files
-    generator.generate_entrypoint_file do |resource, ns|
-      version = resource.ref.version || ''
-      !version.include?('beta') && !version.include?('alpha')
+  generator = KubeDSL::Generator.new(
+    schema_dir: local_schema_path,
+    output_dir: File.join('lib'),
+    autoload_prefix: File.join('kube-dsl', 'dsl'),
+    dsl_namespace: ['KubeDSL', 'DSL'],
+    entrypoint_namespace: ['KubeDSL'],
+    inflector: Dry::Inflector.new do |inflections|
+      inflections.acronym('DSL')
+
+      inflections.singular('tls', 'tls')
+      inflections.singular('causes', 'cause')
+
+      inflections.plural('tls', 'tlses')
+      inflections.plural('enum', 'enums')
+      inflections.plural('one_of', 'one_ofs')
+      inflections.plural('any_of', 'any_ofs')
+      inflections.plural('all_of', 'all_ofs')
     end
+  )
+
+  generator.generate_resource_files
+  generator.generate_autoload_files
+  generator.generate_entrypoint_file do |resource, ns|
+    version = resource.ref.version || ''
+    !version.include?('beta') && !version.include?('alpha')
   end
 end

data/lib/kube-dsl/array_field_res.rb

@@ -0,0 +1,41 @@
+module KubeDSL
+  class ArrayFieldRes
+    include StringHelpers
+
+    attr_reader :name, :required, :elem_res
+
+    alias_method :required?, :required
+
+    def initialize(name, required, elem_res)
+      @name = name
+      @required = required
+      @elem_res = elem_res
+    end
+
+    def fields_to_ruby(inflector)
+      [
+        "array_field(:#{underscore(inflector.singularize(name))})"\
+          " { #{elem_res.ref.ruby_namespace.join('::')}::#{elem_res.ref.kind}.new }"
+      ]
+    end
+
+    def validations(inflector)
+      [].tap do |result|
+        ruby_type = [*elem_res.ref.ruby_namespace, elem_res.ref.kind].join('::')
+        result << "validates :#{plural_name(inflector)}, array: { kind_of: #{ruby_type} }, presence: #{required? ? 'true' : 'false'}"
+      end
+    end
+
+    def serialize_call(inflector)
+      "#{plural_name(inflector)}.map(&:serialize)"
+    end
+
+    private
+
+    def plural_name(inflector)
+      inflector.pluralize(
+        underscore(inflector.singularize(name))
+      )
+    end
+  end
+end

data/lib/kube-dsl/builder.rb

@@ -4,12 +4,17 @@ module KubeDSL
   class Builder
     include StringHelpers
 
-    attr_reader :schema_dir, :output_dir, :namespace, :inflector, :resolvers
+    attr_reader :schema_dir, :output_dir, :autoload_prefix
+    attr_reader :dsl_namespace, :entrypoint_namespace
+    attr_reader :inflector, :resolvers
 
-    def initialize(schema_dir:, output_dir:, inflector:)
+    def initialize(schema_dir:, output_dir:, autoload_prefix:, inflector:, dsl_namespace:, entrypoint_namespace:)
       @schema_dir = schema_dir
       @output_dir = output_dir
+      @autoload_prefix = autoload_prefix
       @inflector = inflector
+      @dsl_namespace = dsl_namespace
+      @entrypoint_namespace = entrypoint_namespace
       @resolvers ||= {}
     end
 
@@ -19,25 +24,17 @@ module KubeDSL
       end
     end
 
-    def each_resource
+    def each_resource_file
       return to_enum(__method__) unless block_given?
 
-      resources.each do |res|
-        # "External" resources are ones that live outside the current
-        # schema, i.e. k8s resources like ObjectMeta that other
-        # k8s-compatible schemas depend on.
-        #
-        # Resources can be "empty" if they contain no properties. This
-        # usually happens for resources that are really just aliases
-        # for basic types like integer and string. The k8s' Duration
-        # object is a good example. It's just an alias for string.
-        yield res if !res.external? && !res.empty?
+      each_resource do |res|
+        yield File.join(output_dir, res.ref.ruby_autoload_path), res
       end
     end
 
     def entrypoint(&block)
       ''.tap do |ruby_code|
-        ruby_code << "module #{namespace[0..-2].join('::')}::Entrypoint\n"
+        ruby_code << "module #{entrypoint_namespace.join('::')}::Entrypoint\n"
 
         each_resource do |resource|
           ns = resource.ref.ruby_namespace.join('::')
@@ -53,26 +50,15 @@ module KubeDSL
       end
     end
 
-    def namespace
-      @namespace ||= inflector.classify(
-        File
-          .split(output_dir)
-          .map { |seg| inflector.camelize(underscore(seg)) }
-          .join('/')
-      ).split('::')
-    end
-
     def entrypoint_path
-      File.join(File.dirname(output_dir), 'entrypoint.rb')
+      File.join(output_dir, File.dirname(autoload_prefix), 'entrypoint.rb')
     end
 
     def each_autoload_file(&block)
       return to_enum(__method__) unless block
 
-      start = output_dir.split(File::SEPARATOR).first
-
       each_autoload_file_helper(
-        autoload_map[start], [start], &block
+        autoload_map[:root], [], &block
       )
     end
 
@@ -82,18 +68,33 @@ module KubeDSL
       end
 
       res = resource_cache[ref.str] = ref.meta
-
       add_doc_to_resource(res, ref.document)
 
       res
     end
 
     def parse_ref(ref_str)
-      Ref.new(ref_str, namespace, output_dir, inflector, schema_dir)
+      Ref.new(ref_str, dsl_namespace, inflector, schema_dir, autoload_prefix)
     end
 
     private
 
+    def each_resource
+      return to_enum(__method__) unless block_given?
+
+      resources.each do |res|
+        # "External" resources are ones that live outside the current
+        # schema, i.e. k8s resources like ObjectMeta that other
+        # k8s-compatible schemas depend on.
+        #
+        # Resources can be "empty" if they contain no properties. This
+        # usually happens for resources that are really just aliases
+        # for basic types like integer and string. The k8s' Duration
+        # object is a good example. It's just an alias for string.
+        yield res if !res.external? && !res.empty?
+      end
+    end
+
     def resources
       JSON.parse(File.read(start_path))['oneOf'].map do |entry|
         resource_from_ref(resolve_ref(entry['$ref']))
@@ -106,7 +107,7 @@ module KubeDSL
           parts = res.ref.ruby_autoload_path.split(File::SEPARATOR)
           parts.reject!(&:empty?)
 
-          parts.inject(amap) do |ret, seg|
+          [:root, *parts].inject(amap) do |ret, seg|
             if seg.end_with?('.rb')
               ret[seg] = res
             else
@@ -138,7 +139,7 @@ module KubeDSL
         end
 
         ruby_code << "end\n"
-        yield File.join(*path, "#{ns}.rb"), ruby_code
+        yield File.join(output_dir, *path, "#{ns}.rb"), ruby_code
         each_autoload_file_helper(children, path + [ns], &block)
       end
     end
@@ -151,6 +152,7 @@ module KubeDSL
 
     def add_props_to_resource(properties, res)
       properties.each do |name, prop|
+        next if name.start_with?('$')
         add_prop_to_resource(name, prop, res)
       end
     end
@@ -168,27 +170,34 @@ module KubeDSL
     end
 
     def add_prop_to_resource(name, prop, res)
+      required = prop.include?('type') && !prop['type'].include?('null')
+
       case Array(prop['type']).first
         when 'array'
-          if ref_str = prop['items']['$ref']
+          if ref_str = prop.dig('items', '$ref')
             ref = resolve_ref(ref_str)
-            res.array_fields[name] = resource_from_ref(ref)
+            res.fields[name] = ArrayFieldRes.new(
+              name, required, resource_from_ref(ref)
+            )
           else
-            res.fields << name
+            res.fields[name] = FieldRes.new(
+              name, (prop.dig('items', 'types') || ['string']).first, required
+            )
           end
 
         when 'object' # this means key/value pairs
-          fmt = prop['additionalProperties']['format'] || 'string'
-          res.key_value_fields[name] = fmt
+          type = prop.dig('additionalProperties', 'format') || 'string'
+          res.fields[name] = KeyValueFieldRes.new(name, res, type, required)
 
         when 'string', 'integer', 'number', 'boolean', 'date-time'
           enum = prop['enum']
 
           if enum&.size == 1
-            # use JSON.generate to add quotes around strings, etc
-            res.default_fields[name] = JSON.generate(enum.first)
+            res.fields[name] = DefaultFieldRes.new(name, res, enum)
           else
-            res.fields << name
+            res.fields[name] = FieldRes.new(
+              name, Array(prop['type']).first, required
+            )
           end
 
         else
@@ -196,16 +205,20 @@ module KubeDSL
 
           if ref.object?
             # this ref refers to a nested type
-            res.object_fields[name] = resource_from_ref(ref)
+            res.fields[name] = ObjectFieldRes.new(
+              name, resource_from_ref(ref)
+            )
           else
             # this ref refers to just a field
-            res.fields << name
+            res.fields[name] = FieldRes.new(
+              name, (prop.dig('items', 'types') || ['string']).first, required
+            )
           end
       end
     end
 
     def start_path
-      @entrypoint_path ||= File.join(schema_dir, 'all.json')
+      @start_path ||= File.join(schema_dir, 'all.json')
     end
 
     def resource_cache