Kessel SDK for Ruby

A Ruby gRPC library for connecting to Project Kessel services. This provides the foundational gRPC client library for Kessel Inventory API, with plans for a higher-level SDK with fluent APIs, OAuth support, and advanced features in future releases.

Add this line to your application's Gemfile:

gem 'kessel-sdk'

And then execute:

bundle install

Or install it yourself as:

gem install kessel-sdk

The SDK supports OAuth 2.0 Client Credentials flow. To use authentication features, add the OpenID Connect gem:

gem 'kessel-sdk'
gem 'openid_connect', '~> 2.0'  # Optional - only for authentication

This library provides direct access to Kessel Inventory API gRPC services. All generated classes are available under the Kessel::Inventory module.

require 'kessel/inventory/v1beta2/inventory_service_services_pb'

include Kessel::Inventory::V1beta2

# Create gRPC client (insecure for development)
client = KesselInventoryService::Stub.new('localhost:9000', :this_channel_is_insecure)

# Create subject reference
subject_reference = SubjectReference.new(
  resource: ResourceReference.new(
    reporter: ReporterReference.new(type: 'rbac'),
    resource_id: 'user123',
    resource_type: 'principal'
  )
)

# Create resource reference
resource = ResourceReference.new(
  reporter: ReporterReference.new(type: 'rbac'),
  resource_id: 'workspace456',
  resource_type: 'workspace'
)

# Check permissions
begin
  response = client.check(
    CheckRequest.new(
      object: resource,
      relation: 'inventory_host_view',
      subject: subject_reference
    )
  )
  puts "Permission check result: #{response.allowed}"
rescue => e
  puts "Error: #{e.message}"
end

require 'kessel/inventory/v1beta2/inventory_service_services_pb'

include Kessel::Inventory::V1beta2

client = KesselInventoryService::Stub.new('localhost:9000', :this_channel_is_insecure)

# Report a new resource
resource_data = {
  'apiVersion' => 'v1',
  'kind' => 'Namespace', 
  'metadata' => {
    'name' => 'my-namespace',
    'uid' => '12345'
  }
}

request = ReportResourceRequest.new(
  resource: ResourceRepresentations.new(
    kessel_inventory: {
      metadata: RepresentationMetadata.new(
        resource_type: 'k8s-namespace',
        resource_id: resource_data['metadata']['uid'],
        workspace: 'default'
      )
    },
    k8s_manifest: resource_data.to_json
  )
)

begin
  response = client.report_resource(request)
  puts "Resource reported successfully"
rescue => e
  puts "Error reporting resource: #{e.message}"
end

The library includes the following gRPC services:

• KesselInventoryService: Main inventory service
  • check(CheckRequest) - Check permissions
  • check_for_update(CheckForUpdateRequest) - Check for resource updates
  • report_resource(ReportResourceRequest) - Report resource state
  • delete_resource(DeleteResourceRequest) - Delete a resource
  • streamed_list_objects(StreamedListObjectsRequest) - Stream resource listings

All protobuf message classes are generated and available. Key classes include:

• CheckRequest, CheckResponse
• ReportResourceRequest, ReportResourceResponse
• DeleteResourceRequest, DeleteResourceResponse
• ResourceReference, SubjectReference
• ResourceRepresentations, RepresentationMetadata

See the examples/ directory for complete working examples.

This library includes RBS type signatures for enhanced type safety in Ruby. The type definitions are located in the sig/ directory and cover:

• Core library interfaces
• Configuration structures
• OAuth authentication classes
• gRPC client builders

To use with type checkers like Steep or Sorbet, ensure the sig/ directory is in your type checking configuration.

• Ruby 3.3 or higher
• buf for protobuf/gRPC code generation

Install buf:

# On macOS
brew install bufbuild/buf/buf

# On Linux
curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-$(uname -s)-$(uname -m)" -o "/usr/local/bin/buf" && chmod +x "/usr/local/bin/buf"

# Or see https://docs.buf.build/installation for other options

# Install dependencies
bundle install

# Generate gRPC code from Kessel Inventory API
buf generate

# Run tests
bundle exec rspec

# Run with coverage
COVERAGE=1 bundle exec rspec

# Run linting
bundle exec rubocop

# Security audit
bundle exec bundle-audit

This library uses buf to generate Ruby gRPC code from the official Kessel Inventory API protobuf definitions hosted at buf.build/project-kessel/inventory-api.

The generation is configured in buf.gen.yaml.

To regenerate the code:

buf generate

This will download the latest protobuf definitions and generate fresh Ruby classes in the lib/ directory.

# Build and install the gem locally
rake install_local

The examples/ directory contains working examples:

• check.rb - Permission checking
• report_resource.rb - Reporting resource state
• delete_resource.rb - Deleting resources
• check_for_update.rb - Checking for updates
• streamed_list_objects.rb - Streaming resource lists

Run examples:

cd examples
ruby check.rb

This is the foundational gRPC library. Future releases will include:

• High-level SDK: Fluent client builder API
• Authentication: OAuth 2.0 Client Credentials flow
• Convenience Methods: Simplified APIs for common operations*

This section provides step-by-step instructions for maintainers to release a new version of the Kessel SDK for Ruby.

This project follows Semantic Versioning 2.0.0. Version numbers use the format MAJOR.MINOR.PATCH:

• MAJOR: Increment for incompatible API changes
• MINOR: Increment for backward-compatible functionality additions
• PATCH: Increment for backward-compatible bug fixes

Note: SDK versions across different languages (Ruby, Python, Go, etc.) do not need to be synchronized. Each language SDK can evolve independently based on its specific requirements and release schedule.

• Write access to the GitHub repository
• RubyGems account with push access to the kessel-sdk gem
• Ensure CI/CD tests are passing
• Review and update CHANGELOG or release notes as needed
• Ruby 3.3 or higher
• buf for protobuf/gRPC code generation:

1. Update the Version

   # Edit lib/kessel/version.rb
   # Update the VERSION constant to the new version number
   vim lib/kessel/version.rb

2. Update Dependencies

   # Generate gRPC code from Kessel Inventory API
   buf generate
   # Update Gemfile.lock with any dependency changes
   bundle install

3. Run Quality Checks

   # Run the full test suite
   bundle exec rspec
   
   # Run linting
   bundle exec rubocop
   
   # Run security audit
   bundle exec bundle-audit check --update
   
   # Build and test the gem locally
   rake install_local

4. Commit Changes

   git add lib/kessel/version.rb Gemfile.lock
   git commit -m "Release version X.Y.Z"
   git push origin main # or git push upstream main

5. Build and Release the Gem

   # Build the gem
   gem build kessel-sdk.gemspec
   
   # Push to RubyGems (requires RubyGems account and gem ownership)
   gem push kessel-sdk-X.Y.Z.gem

6. Tag the Release

   # Create and push a git tag
   git tag -a vX.Y.Z -m "Release version X.Y.Z"
   git push origin vX.Y.Z

7. Clean Up

   # Remove the built gem file
   rake clean

This project includes bundler/gem_tasks which provides additional rake tasks:

# Show available bundler gem tasks
rake -T

# Build gem
rake build

# Install gem locally  
rake install

# Release gem (builds, tags, and pushes to RubyGems)
rake release

Note: The rake release command automates steps 5-6 above but requires proper git and RubyGems credentials to be configured.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.