azure-blob 0.5.9.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5b111fda5a789b4fb8c02172220432303a13091d27b3205864cecdbd7ba0aeb
-  data.tar.gz: d49dfffe286580867b7b9e4f75e2a4a02135ab52e6adc48ee067f94eb0e7e77c
+  metadata.gz: 0fd3246ce35e01647d7aaa6e5819320799d347a96d0b95b9bc4d4d89939ce9a1
+  data.tar.gz: b6ace232dddeed3415294e866115420a91935b7332c79494e5b17c9a2e91eb52
 SHA512:
-  metadata.gz: '08b2c38410ce15d81566c2759bd9395226e26cdb4bf0a47199e1dac9da4c9c34b92fdbda7069995eb3dd1b6d31214d0d14a38dadf5a5a36429315245e30fa609'
-  data.tar.gz: d76e2cd0c1c94696a87c769af32125cff0af7b46168b2ff45293b65f8d31447ff90734022595f235b03ca142e734f57cde582ae040bed76a78950320917f5d5e
+  metadata.gz: f375dca9e699671f5fc165b8463b313f1cc823d5cb6f3f0666cffc22665fa7becb7d075f61dd0cbb131cf85ddc14c47b37b236d6d28b276b2d13b89cc7626660
+  data.tar.gz: 06bfe2d031d6deb2a58da359258df5923ffab3c23d6edf0a36ee4adb93ee4ac69a82d50d571e97b4cfdff10913f2e6c4a834f5338258c33f0b0a0336de1cde17

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.7.0] 2025-01-05
+
+- Add optional `timeout` parameter to all API methods
+- Add `AzureBlob::Http::TimeoutError` for handling Azure `OperationTimedOut` errors
+
+## [0.6.0] 2025-12-01
+
+- Add support for AKS workload identity
+
 ## [0.5.9.1] 2025-06-30
 
 - Fix a regression in #13 + fix add a test

data/README.md

@@ -26,14 +26,13 @@ microsoft:
 
 ### Managed Identity (Entra ID)
 
-AzureBlob supports managed identities on :
+AzureBlob supports managed identities on:
 - Azure VM
 - App Service
+- AKS (Azure Kubernetes Service) with workload identity
 - Azure Functions (Untested but should work)
 - Azure Containers (Untested but should work)
 
-AKS support will likely require more work. Contributions are welcome.
-
 To authenticate through managed identities instead of a shared key, omit `storage_access_key` from your `storage.yml` file and pass in the identity `principal_id`.
 
 ActiveStorage config example:
@@ -46,6 +45,21 @@ prod:
   principal_id: 71b34410-4c50-451d-b456-95ead1b18cce
 ```
 
+#### AKS with Workload Identity
+
+ActiveStorage config example:
+
+```
+prod:
+  service: AzureBlob
+  container: container_name
+  storage_account_name: account_name
+  use_managed_identities: true
+```
+
+> uses `AZURE_CLIENT_ID`, `AZURE_TENANT_ID` and `AZURE_FEDERATED_TOKEN_FILE` environment variables, made available by AKS cluster when Azure AD Workload Identity is set up properly.
+
+
 ### Azurite
 
 To use Azurite, pass the `storage_blob_host` config key with the Azurite URL (`http://127.0.0.1:10000/devstoreaccount1` by default)
@@ -126,20 +140,26 @@ A dev environment is supplied through Nix with [devenv](https://devenv.sh/).
 
 To test with Entra ID, the `AZURE_ACCESS_KEY` environment variable must be unset and the code must be ran or proxied through a VPS with the proper roles.
 
-For cost saving, the terraform variable `create_vm` and `create_app_service` are false by default.
-To create the VPS and App service, Create a var file `var.tfvars` containing:
+For cost saving, the terraform variables `create_vm`, `create_app_service`, and `create_aks` are false by default.
+To create the VM, App Service, and/or AKS cluster, create a var file `var.tfvars` containing:
 
 ```
 create_vm = true
 create_app_service = true
+create_aks = true
 ```
 and re-apply terraform: `terraform apply -var-file=var.tfvars`.
 
-This will create the VPS and required managed identities.
+This will create the infrastructure and required managed identities.
+
+**Testing:**
+- `bin/rake test_azure_vm` - Establishes a VPN connection to the Azure VM and runs tests using node identity
+- `bin/rake test_app_service` - Establishes a VPN connection to the App Service container and runs tests
+- `bin/rake test_aks` - Establishes a VPN connection to the AKS cluster and runs tests using workload identity
 
-`bin/rake test_azure_vm` and `bin/rake test_app_service` will establish a VPN connection to the VM or App service container and run the test suite. You might be prompted for a sudo password when the VPN starts (sshuttle).
+You might be prompted for a sudo password when the VPN starts (sshuttle).
 
-After you are done, run terraform again without the var file (`terraform apply`) to destroy the VPS and App service application.
+After you are done, run terraform again without the var file (`terraform apply`) to destroy all resources.
 
 #### Cleanup
 

data/Rakefile

@@ -5,6 +5,7 @@ require "minitest/test_task"
 require "azure_blob"
 require_relative "test/support/app_service_vpn"
 require_relative "test/support/azure_vm_vpn"
+require_relative "test/support/aks_vpn"
 require_relative "test/support/azurite"
 
 Minitest::TestTask.create(:test_rails) do
@@ -49,6 +50,16 @@ ensure
   vpn.kill
 end
 
+task :test_aks do |t|
+  vpn = AksVpn.new
+  ENV["AZURE_CLIENT_ID"] = vpn.client_id
+  ENV["AZURE_TENANT_ID"] = vpn.tenant_id
+  ENV["AZURE_FEDERATED_TOKEN_FILE"] = vpn.token_file
+  Rake::Task["test_entra_id"].execute
+ensure
+  vpn.kill
+end
+
 task :test_azurite do |t|
   azurite = Azurite.new
   # Azurite well-known credentials

data/lib/azure_blob/client.rb

@@ -70,6 +70,7 @@ module AzureBlob
     #   Ending point in bytes
     def get_blob(key, options = {})
       uri = generate_uri("#{container}/#{key}")
+      uri.query = URI.encode_www_form(timeout: options[:timeout]) if options[:timeout]
 
       headers = {
         "x-ms-range": options[:start] && "bytes=#{options[:start]}-#{options[:end]}",
@@ -92,6 +93,7 @@ module AzureBlob
     def copy_blob(key, source_key, options = {})
       source_client = options.delete(:source_client) || self
       uri = generate_uri("#{container}/#{key}")
+      uri.query = URI.encode_www_form(timeout: options[:timeout]) if options[:timeout]
 
       source_uri = source_client.signed_uri(source_key, permissions: "r", expiry: Time.at(Time.now.to_i + 300).utc.iso8601)
 
@@ -114,6 +116,7 @@ module AzureBlob
     #   Sets the value of the x-ms-delete-snapshots header. Default to +include+
     def delete_blob(key, options = {})
       uri = generate_uri("#{container}/#{key}")
+      uri.query = URI.encode_www_form(timeout: options[:timeout]) if options[:timeout]
 
       headers = {
         "x-ms-delete-snapshots": options[:delete_snapshots] || "include",
@@ -152,6 +155,7 @@ module AzureBlob
         prefix: options[:prefix].to_s.gsub(/\\/, "/"),
       }
       query[:maxresults] = options[:max_results] if options[:max_results]
+      query[:timeout] = options[:timeout] if options[:timeout]
       uri.query = URI.encode_www_form(**query)
 
       fetcher = ->(marker) do
@@ -172,6 +176,7 @@ module AzureBlob
     # To check for blob presence, look for `blob_exist?` as `get_blob_properties` raises on missing blob.
     def get_blob_properties(key, options = {})
       uri = generate_uri("#{container}/#{key}")
+      uri.query = URI.encode_www_form(timeout: options[:timeout]) if options[:timeout]
 
       response = Http.new(uri, additional_headers(options), signer:).head
 
@@ -196,7 +201,9 @@ module AzureBlob
     # Returns a hash of the blob's tags.
     def get_blob_tags(key, options = {})
       uri = generate_uri("#{container}/#{key}")
-      uri.query = URI.encode_www_form(comp: "tags")
+      query = { comp: "tags" }
+      query[:timeout] = options[:timeout] if options[:timeout]
+      uri.query = URI.encode_www_form(**query)
       response = Http.new(uri, additional_headers(options), signer:).get
 
       Tags.from_response(response).to_h
@@ -209,7 +216,9 @@ module AzureBlob
     # This can be used to see if the container exist or obtain metadata.
     def get_container_properties(options = {})
       uri = generate_uri(container)
-      uri.query = URI.encode_www_form(restype: "container")
+      query = { restype: "container" }
+      query[:timeout] = options[:timeout] if options[:timeout]
+      uri.query = URI.encode_www_form(**query)
       response = Http.new(uri, additional_headers(options), signer:, raise_on_error: false).head
 
       Container.new(response)
@@ -232,7 +241,9 @@ module AzureBlob
       headers[:"x-ms-blob-public-access"] = options[:public_access] if [ "container", "blob" ].include?(options[:public_access])
       headers.merge!(additional_headers(options))
 
-      uri.query = URI.encode_www_form(restype: "container")
+      query = { restype: "container" }
+      query[:timeout] = options[:timeout] if options[:timeout]
+      uri.query = URI.encode_www_form(**query)
       response = Http.new(uri, headers, signer:).put
     end
 
@@ -241,7 +252,9 @@ module AzureBlob
     # Calls to {Delete Container}[https://learn.microsoft.com/en-us/rest/api/storageservices/delete-container]
     def delete_container(options = {})
       uri = generate_uri(container)
-      uri.query = URI.encode_www_form(restype: "container")
+      query = { restype: "container" }
+      query[:timeout] = options[:timeout] if options[:timeout]
+      uri.query = URI.encode_www_form(**query)
       response = Http.new(uri, additional_headers(options), signer:).delete
     end
 
@@ -283,6 +296,7 @@ module AzureBlob
     #   Will be saved on the blob in Azure.
     def create_append_blob(key, options = {})
       uri = generate_uri("#{container}/#{key}")
+      uri.query = URI.encode_www_form(timeout: options[:timeout]) if options[:timeout]
 
       headers = {
         "x-ms-blob-type": "AppendBlob",
@@ -306,7 +320,9 @@ module AzureBlob
     #   The checksum must be the checksum of the block not the blob.
     def append_blob_block(key, content, options = {})
       uri = generate_uri("#{container}/#{key}")
-      uri.query = URI.encode_www_form(comp: "appendblock")
+      query = { comp: "appendblock" }
+      query[:timeout] = options[:timeout] if options[:timeout]
+      uri.query = URI.encode_www_form(**query)
 
       headers = {
         "Content-Length": content_size(content),
@@ -330,7 +346,9 @@ module AzureBlob
     def put_blob_block(key, index, content, options = {})
       block_id = generate_block_id(index)
       uri = generate_uri("#{container}/#{key}")
-      uri.query = URI.encode_www_form(comp: "block", blockid: block_id)
+      query = { comp: "block", blockid: block_id }
+      query[:timeout] = options[:timeout] if options[:timeout]
+      uri.query = URI.encode_www_form(**query)
 
       headers = {
         "Content-Length": content_size(content),
@@ -358,7 +376,9 @@ module AzureBlob
       block_list = BlockList.new(block_ids)
       content = block_list.to_s
       uri = generate_uri("#{container}/#{key}")
-      uri.query = URI.encode_www_form(comp: "blocklist")
+      query = { comp: "blocklist" }
+      query[:timeout] = options[:timeout] if options[:timeout]
+      uri.query = URI.encode_www_form(**query)
 
       headers = {
         "Content-Length": content_size(content),
@@ -386,7 +406,7 @@ module AzureBlob
       block_size = options[:block_size] || DEFAULT_BLOCK_SIZE
       block_count = (content_size(content).to_f / block_size).ceil
       block_ids = block_count.times.map do |i|
-        put_blob_block(key, i, content.read(block_size))
+        put_blob_block(key, i, content.read(block_size), options.slice(:timeout))
       end
 
       commit_blob_blocks(key, block_ids, options)
@@ -395,6 +415,7 @@ module AzureBlob
     def put_blob_single(key, content, options = {})
       content = StringIO.new(content) if content.is_a? String
       uri = generate_uri("#{container}/#{key}")
+      uri.query = URI.encode_www_form(timeout: options[:timeout]) if options[:timeout]
 
       headers = {
         "x-ms-blob-type": "BlockBlob",

data/lib/azure_blob/http.rb

@@ -21,6 +21,7 @@ module AzureBlob
     class FileNotFoundError < Error; end
     class ForbiddenError < Error; end
     class IntegrityError < Error; end
+    class TimeoutError < Error; end
 
     include REXML
 
@@ -99,6 +100,7 @@ module AzureBlob
 
     ERROR_CODE_MAPPINGS = {
       "Md5Mismatch" => IntegrityError,
+      "OperationTimedOut" => TimeoutError,
     }
 
     def sanitize_headers

data/lib/azure_blob/identity_token.rb

@@ -1,21 +1,14 @@
+require_relative "instance_metadata_service"
+require_relative "workload_identity"
 require "json"
 
 module AzureBlob
   class IdentityToken
-    RESOURCE_URI = "https://storage.azure.com/"
     EXPIRATION_BUFFER = 600 # 10 minutes
 
-    IDENTITY_ENDPOINT = ENV["IDENTITY_ENDPOINT"] || "http://169.254.169.254/metadata/identity/oauth2/token"
-    API_VERSION = ENV["IDENTITY_ENDPOINT"] ? "2019-08-01" : "2018-02-01"
-
     def initialize(principal_id: nil)
-      @identity_uri = URI.parse(IDENTITY_ENDPOINT)
-      params = {
-        'api-version': API_VERSION,
-        resource: RESOURCE_URI,
-      }
-      params[:principal_id] = principal_id if principal_id
-      @identity_uri.query = URI.encode_www_form(params)
+      @service = AzureBlob::WorkloadIdentity.federated_token? ?
+                   AzureBlob::WorkloadIdentity.new : AzureBlob::InstanceMetadataService.new(principal_id: principal_id)
     end
 
     def to_s
@@ -31,13 +24,11 @@ module AzureBlob
 
     def refresh
       return unless expired?
-      headers =  { "Metadata" => "true" }
-      headers["X-IDENTITY-HEADER"] = ENV["IDENTITY_HEADER"] if ENV["IDENTITY_HEADER"]
 
       attempt = 0
       begin
         attempt += 1
-        response = JSON.parse(AzureBlob::Http.new(identity_uri, headers).get)
+        response = JSON.parse(service.request)
       rescue AzureBlob::Http::Error => error
         if should_retry?(error, attempt)
           attempt = 1 if error.status == 410
@@ -48,7 +39,7 @@ module AzureBlob
         raise
       end
       @token = response["access_token"]
-      @expiration = Time.at(response["expires_on"].to_i)
+      @expiration = service.expiration(response)
     end
 
     def should_retry?(error, attempt)
@@ -61,6 +52,6 @@ module AzureBlob
     end
     EXPONENTIAL_BACKOFF = [ 2, 6, 14, 30 ]
 
-    attr_reader :identity_uri, :expiration, :token
+    attr_reader :service, :expiration, :token
   end
 end

data/lib/azure_blob/instance_metadata_service.rb

@@ -0,0 +1,28 @@
+module AzureBlob
+  class InstanceMetadataService # :nodoc:
+    IDENTITY_ENDPOINT = ENV["IDENTITY_ENDPOINT"] || "http://169.254.169.254/metadata/identity/oauth2/token"
+    API_VERSION = ENV["IDENTITY_ENDPOINT"] ? "2019-08-01" : "2018-02-01"
+    RESOURCE_URI = "https://storage.azure.com/"
+
+    def initialize(principal_id: nil)
+      @identity_uri = URI.parse(IDENTITY_ENDPOINT)
+      params = {
+        'api-version': API_VERSION,
+        resource: RESOURCE_URI,
+      }
+      params[:principal_id] = principal_id if principal_id
+      @identity_uri.query = URI.encode_www_form(params)
+    end
+
+    def request
+      headers =  { "Metadata" => "true" }
+      headers["X-IDENTITY-HEADER"] = ENV["IDENTITY_HEADER"] if ENV["IDENTITY_HEADER"]
+
+      AzureBlob::Http.new(@identity_uri, headers).get
+    end
+
+    def expiration(response)
+      Time.at(response["expires_on"].to_i)
+    end
+  end
+end

data/lib/azure_blob/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AzureBlob
-  VERSION = "0.5.9.1"
+  VERSION = "0.7.0"
 end

data/lib/azure_blob/workload_identity.rb

@@ -0,0 +1,41 @@
+module AzureBlob
+  class WorkloadIdentity # :nodoc:
+    IDENTITY_ENDPOINT = "https://login.microsoftonline.com/#{ENV['AZURE_TENANT_ID']}/oauth2/v2.0/token"
+    CLIENT_ID = ENV["AZURE_CLIENT_ID"]
+    SCOPE = "https://storage.azure.com/.default"
+    GRANT_TYPE = "client_credentials"
+    CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+    FEDERATED_TOKEN_FILE = ENV["AZURE_FEDERATED_TOKEN_FILE"].to_s
+
+    def self.federated_token?
+      !FEDERATED_TOKEN_FILE.empty?
+    end
+
+    def initialize
+      @identity_uri = URI.parse(IDENTITY_ENDPOINT)
+    end
+
+    def request
+      AzureBlob::Http.new(@identity_uri).post(
+        URI.encode_www_form(
+          client_id: CLIENT_ID,
+          scope: SCOPE,
+          client_assertion_type: CLIENT_ASSERTION_TYPE,
+          client_assertion: federated_token,
+          grant_type: GRANT_TYPE
+        )
+      )
+    end
+
+    def expiration(response)
+      Time.now + response["expires_in"].to_i
+    end
+
+    private
+
+    def federated_token
+      File.read(FEDERATED_TOKEN_FILE).strip
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: azure-blob
 version: !ruby/object:Gem::Version
-  version: 0.5.9.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Joé Dupuis
@@ -49,11 +49,13 @@ files:
 - lib/azure_blob/errors.rb
 - lib/azure_blob/http.rb
 - lib/azure_blob/identity_token.rb
+- lib/azure_blob/instance_metadata_service.rb
 - lib/azure_blob/metadata.rb
 - lib/azure_blob/shared_key_signer.rb
 - lib/azure_blob/tags.rb
 - lib/azure_blob/user_delegation_key.rb
 - lib/azure_blob/version.rb
+- lib/azure_blob/workload_identity.rb
 homepage: https://github.com/testdouble/azure-blob
 licenses:
 - MIT