Microsoft Azure SDK for Ruby - Resource Management (preview)

This project provides a Ruby package for Azure Resource Management (ARM). If you're looking for Azure Service Management (ASM) please refer to this repo

Additional info on Azure deployment models https://docs.microsoft.com/azure/azure-resource-manager/resource-manager-deployment-model

Important Announcement

As of February 2021, Azure Resource Management SDK for Ruby has entered a retirement phase and is no longer officially supported by Microsoft. Here is the complete list of packages that are affected by this. We are committed to making critical security and bug fixes for libraries in this repo until December 31, 2021. After that date, this repo will no longer be maintained.

For current users of the Azure Resource Management SDK for Ruby, we have prepared a migration guide that points outlines different alternative approaches you can take moving forward. Please check the guide here.

Thank you for your support so far. Should you have any question, please feel free to open an issue on GitHub.

Packages that are no longer supported

All resource management Azure Resource Management packages that contains “azure-mgmt” will be retired as well as a few client libraries.

Note that the Azure Storage SDK for Ruby is excluded from this retirement and continues to be maintained. The Azure Storage SDK for Ruby is available in its own preview gem and GitHub repository, which is still being maintained

Below is the list of the packages that are being retired

Authorization Azure Resource Manager role based authorization
Batch Azure Batch Management Account & Application operations management
CDN Azure Content Delivery Network
Cognitive Services Azure Cognitive Services Account management
Commerce Azure Commerce Usage aggregates & Rate card management
Compute Virtual Machines, Images, Extensions, Availability Sets, etc...
Consumption Usage details, Operations, etc...
Data Lake Analytics Azure Data Lake Analytics Account, Catalog and Job management
Data Lake Store Azure Data Lake Store Account and FileSystem management
DevTest Labs Azure DevTest Labs LabOperations, ArtifactSourceOperations, ArtifactOperations, CostOperations etc...
DNS Azure DNS Record Set and Zone management
Features Feature Exposure Controls
Graph Azure Active Directory Applications, Users, etc...
Monitor Azure Monitor management
IoTCentral Azure IoTCentral's Resource Management
IoTHub Azure IoTHub's Resource Management
Key Vault Azure Key Vault's vault management
Locks Management locks for Azure Resources
Logic Integration Accounts, AccountSchemas, AccountMaps, AccountPartners etc...
Machine Learning Azure Machine Learning web services management
Media Services Media Services resource management APIs
Mobile Engagement Azure Mobile Engagement's Apps, App Collections, Devices management APIs
Managed Service Identity Create, update, list user assigned identities.
Network Load Balancers, Network Gateways, Security Groups, etc...
Notification Hubs Notification Hubs management
Policy Policy Assignment & Policy definition operations
Power BI Embedded Azure Power BI Embedded Workspace & WorkspaceCollection management
Redis Redis resource management
Resources Resource Groups, Resource Providers, Template Deployments, Operations, etc...
Resource Graph Query Azure Resource Manager resources at scale
Scheduler Manage scheduled jobs in Azure
Search Manage Search resources
Server Management Azure Server Management Service like node, gateway, powershell etc..
SQL Manage Azure SQL resources
Storage Account Creation, Usage Operations, etc...
Stream Analytics Create, update, start, stop streaming jobs etc...
Subscriptions Manage Azure subscriptions
Traffic Manager Azure Traffic Manager's profile & endpoint management
WebApps Manage WebApps, formally known as WebSites

Azure Services

Service Bus
- Relays
- Topics
- Queues

Supported Ruby Versions

Ruby 2+

Note: x64 Ruby for Windows is known to have some compatibility issues.

Getting Started with Azure Resource Manager Usage (Preview)

Install the rubygem packages

You can install the azure rubygem packages directly.

gem install azure_mgmt_compute
gem install azure_mgmt_storage
gem install azure_mgmt_resources
gem install azure_mgmt_network

Or use them in your Gemfile.

gem 'azure_mgmt_storage'
gem 'azure_mgmt_compute'
gem 'azure_mgmt_resources'
gem 'azure_mgmt_network'

Be aware the Azure Resource Manager Ruby SDK is in preview and will likely have breaking interface changes in upcoming releases. An increased number in Minor version may indicate breaking changes.

Authentication

The first step to using the SDK is authentication and permissions. For people unfamilar with Azure this may be one of the more difficult concepts. For a reference on setting up a service principal from the command line see Authenticating a service principal with Azure Resource Manager or Unattended Authentication. For a more robust explanation of authentication in Azure, see Developer’s guide to auth with Azure Resource Manager API.

After creating the service principal, you should have three pieces of information, a client id (GUID), client secret (string) and tenant id (GUID) or domain name (string).

Prerequisite

In order to use the Azure SDK, you must supply the following values to the Azure SDK:

Tenant Id
Client Id
Subscription Id
Client Secret

You could pass the above values in the following ways:

Option 1 - Environment Variables

You can set the (above) values using the following environment variables:

AZURE_TENANT_ID
AZURE_CLIENT_ID
AZURE_SUBSCRIPTION_ID
AZURE_CLIENT_SECRET

To set the environment variables, in Windows, you could use the command such as:

set AZURE_TENANT_ID=<YOUR_TENANT_ID>

In Unix based systems, you could use the command such as:

export AZURE_TENANT_ID=<YOUR_TENANT_ID>

Option 2 - Options Hash

The initialization of profile clients take an options hash as a parameter. This options hash consists of tenant_id, client_id, client_secret, subscription_id, active_directory_settings and credentials. Among these, the active_directory_settings and credentials are optional.

You can set the (above) values using the options hash:

options = {
  tenant_id: 'YOUR TENANT ID',
  client_id: 'YOUR CLIENT ID',
  client_secret: 'YOUR CLIENT SECRET',
  subscription_id: 'YOUR SUBSCRIPTION ID'
}

If you would like to pass in the credentials object, you could use the the following code:

provider = MsRestAzure::ApplicationTokenProvider.new(
       'YOUR TENANT ID',
       'YOUR CLIENT ID',
       'YOUR CLIENT SECRET')
credentials = MsRest::TokenCredentials.new(provider)

options = {
  tenant_id: 'YOUR TENANT ID',
  client_id: 'YOUR CLIENT ID',
  client_secret: 'YOUR CLIENT SECRET',
  subscription_id: 'YOUR SUBSCRIPTION ID',
  credentials: credentials
}

Option 3 - Combination of Environment Variables & Options Hash

You can set the (above) values using a combination of environment variables and options hash. The values mentioned in the options hash will take precedence over the environment variables.

Azure Multiple API versions & Profiles

With 0.15.0 of Azure SDK, multiple API versions and profiles are introduced. With these changes, each individual gem has multiple versions of the services and several profiles. The azure_sdk rollup gem also consists of several profiles. The following section provides details on the usage of multiple API versions and profiles.

Why Multiple API versions?

Versions 0.14.0 and older, would have access to the latest versions of Azure services at the time of release. Each release up to 0.14.0, would include the latest available api-version of the services. There wasn't an option to use an older api-version of the service (except for using an older version of the sdk gem). With the introduction of multiple API versions per gem, any api-version available for the service can be explicitly targeted.

What is a Profile?

A profile is a combination of different resource types with different versions from different services. Using a profile, will help you mix and match between various resource types.

What to use?

If you would like to use the latest versions of all the services, then the recommendation is to use the Latest profile of the Azure SDK rollup gem.
If you would like to use the services compatible with the Azure Stack, then the recommendation is to use the V2017_03_09 profile of the Azure SDK rollup gem.
If you would like to use the latest api-version of a service, then the recommendation is to use the Latest profile of the specific gem. For example, if you would like to use the latest api-version of compute service alone, use the Latest profile of compute gem.
If you would like to use specific api-version of a service, then the recommendation is to use the specific API versions defined inside that gem.

Note: All the above options could be combined within the same application.

Usage of azure_sdk gem

azure_sdk gem is a rollup of all the supported gems in the Ruby SDK. This gem consists of a Latest profile which supports the latest version of all services. it introduces a versioned profile V2017_03_09 profile which is built for Azure Stack.

Install

You can install the azure_sdk rollup gem with the following command:

gem install 'azure_sdk'

Existing Profiles

To start with, the azure_sdk rollup gem has two profiles.

V2017_03_09 (Profile built for Azure Stack)
Latest (Profile consists of Latest versions of all services)

You could choose the profile that you would like to use. If you would like to use the latest versions of all the services, then the recommendation is to use the Latest profile of the azure_sdk rollup gem.

If you would like to use the services compatible with the Azure Stack, then the recommendation is to use the V2017_03_09 profile of the Azure SDK rollup gem.

Usage

The following lines should be used to instantiate a profile client:

# Provide credentials
options = {
  tenant_id: ENV['AZURE_TENANT_ID'],
  client_id: ENV['AZURE_CLIENT_ID'],
  client_secret: ENV['AZURE_CLIENT_SECRET'],
  subscription_id: ENV['AZURE_SUBSCRIPTION_ID']
}

# Target profile built for Azure Stack
profile_client = Azure::Profiles::V2017_03_09::Mgmt::Client.new(options)

The profile client could be used to access individual RPs:

# To access the operations associated with Compute
profile_client.compute.virtual_machines.get 'RESOURCE_GROUP_NAME', 'VIRTUAL_MACHINE_NAME'

# Option 1: To access the models associated with Compute
purchase_plan_obj = profile_client.compute.model_classes.purchase_plan.new

# Option 2: To access the models associated with Compute
# Notice Namespace: Azure::Profiles::<Profile Name>::<Service Name>::Mgmt::Models::<Model Name>
purchase_plan_obj = Azure::Profiles::V2017_03_09::Compute::Mgmt::Models::PurchasePlan.new

Usage of Individual gem using Profiles

Install

You can install the individual gems using gem install. For eg, to install azure_mgmt_compute, use the following command:

gem install 'azure_mgmt_compute'

Usage

The following lines should be used to instantiate a profile client:

# Provide credentials
options = {
  tenant_id: ENV['AZURE_TENANT_ID'],
  client_id: ENV['AZURE_CLIENT_ID'],
  client_secret: ENV['AZURE_CLIENT_SECRET'],
  subscription_id: ENV['AZURE_SUBSCRIPTION_ID']
}

# Target profile built for Latest Compute
profile_client = Azure::Compute::Profiles::Latest::Mgmt::Client.new(options)

The profile client could be used to access operations and models:

# To access the operations associated with Compute
profile_client.virtual_machines.get 'RESOURCE_GROUP_NAME', 'VIRTUAL_MACHINE_NAME'

# Option 1: To access the models associated with Compute
purchase_plan_obj = profile_client.model_classes.purchase_plan.new

# Option 2: To access the models associated with Compute
# Notice Namespace: Azure::<Service Name>::Profiles::<Profile Name>::Mgmt::Models::<Model Name>
purchase_plan_obj = Azure::Compute::Profiles::Latest::Mgmt::Models::PurchasePlan.new

Usage of Individual gem using using specific api-version

In the previous section, we used the profile associated with individual gem. In the current section, we could use the version directly.

Install

You can install the individual gems using gem install. For eg, to install azure_mgmt_compute, use the following command:

gem install 'azure_mgmt_compute'

Usage

The following lines should be used to instantiate a profile client:

# To use this scenario, you must specify the tenant id, client id, subscription id
# and client secret using the environment variables.
# Provide credentials
provider = MsRestAzure::ApplicationTokenProvider.new(
       ENV['AZURE_TENANT_ID'],
       ENV['AZURE_CLIENT_ID'],
       ENV['AZURE_CLIENT_SECRET'])
credentials = MsRest::TokenCredentials.new(provider)

# Target client for 2016_03_30 version of Compute
compute_client = Azure::Compute::Mgmt::V2016_03_30::ComputeManagementClient.new(credentials)
compute_client.subscription_id = ENV['AZURE_SUBSCRIPTION_ID']

The compute client could be used to access operations and models:

# To access the operations associated with Compute
compute_client.virtual_machines.get 'RESOURCE_GROUP_NAME', 'VIRTUAL_MACHINE_NAME'

# To access the models associated with Compute
# Notice Namespace: Azure::<Service Name>::Mgmt::<Version Name>::Models::<Model Name>
purchase_plan_obj = Azure::Compute::Mgmt::V2016_03_30::Models::PurchasePlan.new

Samples using Profiles

The following samples could be used as a reference for Profiles usage::

Getting Started Samples

The tests for the libraries should provide a good example of how to get started with the clients. You can also see the readme for each of the libraries Compute, Network, Storage, or Resources.

For more getting started samples go to Azure-Samples. Please make sure to look for the azure_mgmt_* gem versions for samples.

Contribute Code or Provide Feedback

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Development Environment Setup

Download Source Code

To get the source code of the SDK via git just type:

git clone https://github.com/Azure/azure-sdk-for-ruby.git
cd ./azure-sdk-for-ruby

Then, run bundler to install all the gem dependencies:

bundle install

Run Recorded Integration Tests

Set the environment variable INTEG_RECORDED = true
Run rake arm:spec

Re-Record Integration Tests

Set the environment variable INTEG_RECORDED = false or un-set it
Copy .env_sample to .env
Update .env with your Azure credentials .env is in the .gitignore, so should only reside locally
Run specific test using rspec example:

 cd ./management/azure_mgmt_compute
 rspec spec/2017-03-30/virtual_machines_spec.rb

If the vcr cassette exists, then it'll replay the test, otherwise it'll record it.

Generate Documentation

Running the command yard will generate the API documentation in the ./doc directory.

Provide Feedback

If you encounter any bugs with the library please file an issue in the Issues section of the project. Please make sure to label the issues with either arm or asm to help us expedite the process.

Azure CLI Tooling

For documentation on Azure PowerShell. For documentation on Azure CLI.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.