From 44e974f5799bad22cabf54984505e3a8f0739df1 Mon Sep 17 00:00:00 2001 From: DeeJay Date: Thu, 3 Apr 2014 21:22:22 +0530 Subject: [PATCH] Updated README --- README.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 104 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a147b84..04e9c17 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,111 @@ # Vagrant Azure Provider -This is a [Vagrant](http://www.vagrantup.com) 1.2+ plugin that adds [Windows Azure](https://www.windowsazure.com) +![Gem Version](https://badge.fury.io/rb/vagrant-azure.png) + +This is a [Vagrant](http://www.vagrantup.com) 1.5.2+ plugin that adds [Windows Azure](https://www.windowsazure.com) provider to Vagrant, allowing Vagrant to control and provision machines in Windows Azure. -**NOTE:** This plugin requires Vagrant 1.2+, +**NOTE:** This plugin requires Vagrant 1.5.2+, + +## Usage + +Install Vagrant 1.5.2 or higher - [Download Vagrant](http://www.vagrantup.com/downloads.html) + +Install the vagrant-azure plugin using the standarn Vagrant 1.1+ installation methods. After installing the plugin, you can you can ```vagrant up``` and use ```azure``` provider. For example: + +``` +C:\> vagrant plugin install vagrant-azure +... +C:\> vagrant up --provider=azure +... +``` + +You'll need an ```azure``` box before you can do ```vagrant up``` though. + +## Quick Start + +You can use the dummy box and specify all the required details manually in the ```confiv.vm.provider``` block in your ```Vagrantfile```. Add the dummy box with the name you want: + +``` +C:\> vagrant box add azure https://github.com/msopentech/vagrant-azure/raw/master/dummy.box +... +``` + +Now edit your ```Vagrantfile``` as shown below and provide all the values as explained. + +```ruby +Vagrant.configure('2') do |config| + config.vm.box = 'azure' + + config.vm.provider :azure do |azure| + azure.mgmt_certificate = 'YOUR AZURE MANAGEMENT CERTIFICATE' + azure.mgmt_endpoint = 'https://management.core.windows.net' + azure.subscription_id = 'YOUR AZURE SUBSCRIPTION ID' + auzre.storage_acct_name = 'NAME OF YOUR STORAGE ACCOUNT' # optional. A new one will be generated if not provided. + + azure.vm_user = 'PROVIDE A USERNAME' # defaults to 'vagrant' if not provided + azure.vm_password = 'PROVIDE A VALID PASSWORD' # min 8 characters. should contain a lower case letter, an uppercase letter, a number and a special character + + azure.vm_name = 'PROVIDE A NAME FOR YOUR VIRTUAL MACHINE' # max 15 characters. contains letters, number and hyphens. can start with letters and can end with letters and numbers + azure.cloud_service_name = 'PROVIDE A NAME FOR YOUR CLOUD SERVICE' # same as vm_name. leave blank to auto-generate + azure.deployment_name = 'PROVIDE A NAME FOR YOUR DEPLOYMENT' # defaults to cloud_service_name + azure.vm_location = 'PROVIDE A LOCATION FOR VM' # e.g., West US + azure.ssh_private_key_file = 'PATH TO YOUR KEY FILE' + azure.ssh_certificate_file = 'PATH TO YOUR CERTIFICATE FILE' + + # Provide the following values if creating a *Nix VM + azure.ssh_port = 'A VALID PUBLIC PORT' + + # Provide the following values if creating a Windows VM + azure.winrm_transport = [ 'http', 'https' ] # this will open up winrm ports on both http (5985) and http (5986) ports + azure.winrm_https_port = 'A VALID PUBLIC PORT' # customize the winrm https port, instead of 5986 + azure.winrm_http_port = 'A VALID PUBLIC PORT' # customize the winrm http port, insted of 5985 + + azure.tcp_endpoints = '3389:53389' # opens the Remote Desktop internal port that listens on public port 53389. Without this, you cannot RDP to a Windows VM. + end + + config.ssh.username = 'YOUR USERNAME' # the one used to create the VM + config.ssh.password = 'YOUR PASSOWRD' # the one used to create the VM +end +``` + +Now you can run + +``` +C:\> vagrant up --provider=azure +``` + +This will bring up an Azure VM as per the configuration options set above. + +You can now either SSH (if its a *Nix VM) using ```vagrant ssh```, or RDP (if its a Windows VM) using ```vagrant rdp```. + +Normally, a lot of this options, e.g., ```vm_image```, will be embedded in a box file and you just have to provide minimal options in the ```Vagrantfile```. Since, we're using a dummy box, there are no pre-configured defaults. + +## Azure Boxes + +The vagrant-azure plugin provides the ability to use ```azure``` boxes with Vagrant. Please see the example box provided in [example_box/ directory](https://github.com/msopentech/vagrant-azure/tree/master/example_box) and follow the instructions there to build an ```azure``` box. + +Please see [Vagrant Docs](http://docs.vagrantup.com/v2/) for more details. ## Configuration + +The vagrant-azure provide exposes a few Azure specific configration options: + +* `mgmt_certificate` - Your Azure Management certificate which has been uploaded to the Azure portal for your account. +* `mgmt_endpoint` - Azure Management endpoint. `https://management.core.windows.net` +* `subscription_id` - Your Azure Subscription ID. +* `storage_acct_name` - The Storage account to use when creating VMs. +* `vm_user` - The username to create the VM with. Defaults to `vagrant`. +* `vm_password`- The password to set for the user created with the VM. +* `vm_name` - The name of the created VM. +* `cloud_service_name` - The name of the cloud service under which to create the VM. +* `deployment_name` - The name to give the deployment in the cloud service and add the VM to. +* `vm_location` - The location to create the cloud service, storage account. +* `ssh_private_key_file` - The private key file to use for SSH and if WinRM is enabled over HTTP/S. +* `ssh_certificate_file` - The certificate file to use for SSH and if WinRM is enabled over HTTP/S. +* `ssh_port` - To map the internal SSH port 22 to a different public port. +* `winrm_transport` - Enables or disables WinRm. Allowed values are `http` and `https`. +* `winrm_https_port` To map the internal WinRM https port 5986 to a different public port. +* `winrm_http_port` To map the internal WinRM http port 5985 to a different public port. +* `tcp_endpoints` - To open any additional ports. E.g., `80` opens port `80` and `80,3389:53389` opens port `80` and `3389`. Also maps the interal port `3389` to public port `53389`