kube-dsl 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c028c471596448f6e06ff1aa0bf50bc3ccdd93e22559a9805d4078921571f8a
-  data.tar.gz: b6e10a2a2f59d21af138e18db5a46b015a331e762642f7d2292daa69e9f4365f
+  metadata.gz: 2b49cbbb2071a035cf03ba3b5a945ac776fb3df15573875f8d5790f25335aeae
+  data.tar.gz: bc2c169581f445a84dd1104935b6a4b89273bd52d87e4091dd0d6fca884b2d0a
 SHA512:
-  metadata.gz: 7bda26da0d442fbe59af67f1a8c60aad632bb91f789332aa951032d6f25be6dd72461b20c0e24e0ed995f15f7a925ead791feca3b9e99a0d226cc6cf4c3dc423
-  data.tar.gz: 8102bb8df5fdc935f3df34c9ff9a2ae2e3d0f1c6eb3222441d4b082c9cc932a7d5d9856028435726b0d4821e94413e4af377d1869fcfba1e08153052d25f9af0
+  metadata.gz: faae392718b9cc76a9d699c77fed71764ef503918e75b3a83e9255259c4db7bb279c0d0db377e6913c78c623dc40d6f14c73921e7d0aa951c4a1a550dc9f5dd6
+  data.tar.gz: 61be1d7e1693604c30d6189517e23d260f6c27bfb4926ba8070dd75cb0d8a487beb877a70158801595f2c86bcbeacf7806dc5829aabedf3396692a6168ab76c1

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.5.0
+* Recursively validate.
+* Add README.
+
 ## 0.4.0
 * Add validations.
   - You can now call `#valid?` and `#validate` methods on DSL objects.

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/lib/kube-dsl/dsl/pkg/version/info.rb

@@ -1,24 +1,6 @@
 module KubeDSL::DSL::Pkg::Version
   class Info < ::KubeDSL::DSLObject
-    value_field :build_date
-    value_field :compiler
-    value_field :git_commit
-    value_field :git_tree_state
-    value_field :git_version
-    value_field :go_version
-    value_field :major
-    value_field :minor
-    value_field :platform
-
-    validates :build_date, field: { format: :string }, presence: false
-    validates :compiler, field: { format: :string }, presence: false
-    validates :git_commit, field: { format: :string }, presence: false
-    validates :git_tree_state, field: { format: :string }, presence: false
-    validates :git_version, field: { format: :string }, presence: false
-    validates :go_version, field: { format: :string }, presence: false
-    validates :major, field: { format: :string }, presence: false
-    validates :minor, field: { format: :string }, presence: false
-    validates :platform, field: { format: :string }, presence: false
+    value_fields :build_date, :compiler, :git_commit, :git_tree_state, :git_version, :go_version, :major, :minor, :platform
 
     def serialize
       {}.tap do |result|

data/lib/kube-dsl/validations.rb

@@ -27,9 +27,9 @@ module KubeDSL
         @presence = presence
       end
 
-      def validate(obj, errors)
+      def validate(obj, errors, nesting)
         if presence && obj_empty?(obj)
-          errors.add(field_name, 'is required')
+          errors.add([*nesting, field_name].join('.'), 'is required')
         end
       end
 
@@ -52,17 +52,17 @@ module KubeDSL
         @kind_of = opts.fetch(:kind_of)
       end
 
-      def validate(obj, errors)
+      def validate(obj, errors, nesting)
         unless obj.is_a?(Array)
-          errors.add(field_name, 'is not an array')
+          errors.add([*nesting, field_name].join('.'), 'is not an array')
           return
         end
 
         obj.each_with_index do |elem, idx|
           unless elem.nil? || elem.is_a?(kind_of)
             errors.add(
-              field_name, "contains an object at index #{idx} of type '#{elem.class.name}', "\
-                "expected '#{kind_of.name}'"
+              [*nesting, field_name].join('.'), "contains an object at index #{idx} "\
+                "of type '#{elem.class.name}', expected '#{kind_of.name}'"
             )
           end
         end
@@ -102,9 +102,9 @@ module KubeDSL
         @format_validator ||= FormatValidator.new(options[:format])
       end
 
-      def validate(obj, errors)
+      def validate(obj, errors, nesting)
         unless format_validator.valid?(obj)
-          errors.add(field_name, "is not a #{format_validator.klasses.map(&:to_s).join(', ')}")
+          errors.add([*nesting, field_name].join('.'), "is not a #{format_validator.klasses.map(&:to_s).join(', ')}")
         end
       end
     end
@@ -117,9 +117,9 @@ module KubeDSL
         @kind_of = opts.fetch(:kind_of)
       end
 
-      def validate(obj, errors)
+      def validate(obj, errors, nesting)
         unless obj.nil? || obj.is_a?(kind_of)
-          errors.add(field_name, "'#{obj.class.name}', expected '#{kind_of.name}'")
+          errors.add([*nesting, field_name].join('.'), "'#{obj.class.name}', expected '#{kind_of.name}'")
         end
       end
     end
@@ -132,10 +132,12 @@ module KubeDSL
         @format_validator ||= FormatValidator.new(options[:value_format])
       end
 
-      def validate(obj, errors)
+      def validate(obj, errors, nesting)
         obj.kv_pairs.each_pair do |k, v|
           unless format_validator.valid?(v)
-            errors.add(field_name, "expected element '#{k}' to be a #{format_validator.klasses.map(&:to_s).join(', ')}, got #{v.class.name}")
+            errors.add(
+              [*nesting, field_name].join('.'),
+              "expected element '#{k}' to be a #{format_validator.klasses.map(&:to_s).join(', ')}, got #{v.class.name}")
           end
         end
       end
@@ -149,9 +151,9 @@ module KubeDSL
         @list = opts[:in]
       end
 
-      def validate(obj, errors)
+      def validate(obj, errors, nesting)
         unless list.include?(obj)
-          errors.add(field_name, "is not in #{list.join(', ')}")
+          errors.add([*nesting, field_name].join('.'), "is not in #{list.join(', ')}")
         end
       end
     end
@@ -186,12 +188,16 @@ module KubeDSL
     end
 
     module InstanceMethods
-      def validate
-        errors = ValidationErrors.new
+      def validate(errors = nil, nesting = [])
+        errors ||= ValidationErrors.new
 
         self.class.validators.each do |field_name, validators|
           field = send(field_name)
-          validators.each { |val| val.validate(field, errors) }
+          validators.each { |val| val.validate(field, errors, nesting) }
+
+          if field.respond_to?(:validate)
+            field.validate(errors, nesting + [field_name.to_s])
+          end
         end
 
         errors

data/lib/kube-dsl/value_fields.rb

@@ -15,7 +15,7 @@ module KubeDSL
         define_method(field) do |*args|
           if args.empty?
             instance_variable_get(:"@#{field}") || (
-              default.respond_to?(:call) ? default.call : default
+              default.respond_to?(:call) ? default.call(self) : default
             )
           else
             instance_variable_set(:"@#{field}", args.first)

data/lib/kube-dsl/version.rb

@@ -1,3 +1,3 @@
 module KubeDSL
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kube-dsl
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Cameron Dutro
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-30 00:00:00.000000000 Z
+date: 2021-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-inflector
@@ -34,6 +34,7 @@ files:
 - CHANGELOG.md
 - Gemfile
 - LICENSE
+- README.md
 - Rakefile
 - kube-dsl.gemspec
 - lib/kube-dsl.rb