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
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.
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
Note: x64 Ruby for Windows is known to have some compatibility issues.
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.
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).
In order to use the Azure SDK, you must supply the following values to the Azure SDK:
You could pass the above values in the following ways:
You can set the (above) values using the following environment variables:
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>
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
}
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.
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.
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.
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.
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.
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.
You can install the azure_sdk rollup gem with the following command:
gem install 'azure_sdk'
To start with, the azure_sdk rollup gem has two profiles.
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.
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
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'
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
In the previous section, we used the profile associated with individual gem. In the current section, we could use the version directly.
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'
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
The following samples could be used as a reference for Profiles usage::
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 azuremgmt* gem versions for samples.
git checkout -b my-new-feature
)git commit -am 'Add some feature'
)git push origin my-new-feature
)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
INTEG_RECORDED = true
rake arm:spec
INTEG_RECORDED = false
or un-set itrspec
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.
Running the command yard
will generate the API documentation in the ./doc
directory.
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.
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.