search

Azure / azure-sdk-for-ruby

Ruby SDK for Azure Resource Manager: build and manage your Azure cloud infrastructure (Compute, Virtual Networks, Storage, etc...) using Ruby.
MIT License
275 stars 246 forks source link
azure-resource-manager azure-resources azure-sdk azure-sdk-for-ruby hacktoberfest

readme

[RETIRED] Microsoft Azure SDK for Ruby - Resource Management (preview)

Build Status Code Climate

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

Azure Services

Supported Ruby Versions

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:

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:

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?

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.

  1. V2017_03_09 (Profile built for Azure Stack)
  2. 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 azuremgmt* gem versions for samples.

Contribute Code or Provide Feedback

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. 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

Re-Record Integration Tests

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.