knife-azure 1.6.0.rc.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0d3c8d33de70a5a13ab8266a296901adc92470ce
-  data.tar.gz: e96796e88386edfea3100daf1248d025eaff0610
+  metadata.gz: 7780820cde5aa319045cb5befac28e85a6233112
+  data.tar.gz: 52a53c5e75597f6147ec4b296a44fa3e3743ca9f
 SHA512:
-  metadata.gz: 83df38d52600057e3b877bb03c46a28da6614c166a0286f66dd3bb0ac0d657e3f68875cffb2c917e438f20581e5e9cbcf174e0d5673b2ba6ac73386a4ab0e652
-  data.tar.gz: aae9e02a525a0f023632a5335b509a95fb7a8f8ad4d2c9fc436f587f9b8b76620310ec330288deb8ab0dbecd077416ad13217163bb234287cbe313aa8e3b210a
+  metadata.gz: b8b3d1f5345d5be91208a53fc9f0deb834e5507c3981e3855b328ad72b63b47391c537f1d0d5dcb501a669fe66cead87830b57851e296649e09406c0a580c2a5
+  data.tar.gz: e85e41b2659b2555dd16792af670ca805926f7a136a04d68b03ce033e09031335997fb611142e5d87dd533ba2adac155fa8bf1498900e9c677829227a68638ef

data/README.md

@@ -1,10 +1,16 @@
 # Knife Azure
 
+[![Gem Version](https://badge.fury.io/rb/knife-azure.svg)](https://rubygems.org/gems/knife-azure)
+[![Build Status](https://travis-ci.org/chef/knife-azure.svg?branch=master)](https://travis-ci.org/chef/knife-azure)
+
 ## Description
-A [knife] (http://docs.chef.io/knife.html) plugin to create,
-delete, and enumerate
-[Microsoft Azure] (https://azure.microsoft.com)
-resources to be managed by Chef.
+A [knife] (http://docs.chef.io/knife.html) plugin to create, delete, and enumerate
+[Microsoft Azure] (https://azure.microsoft.com) resources to be managed by Chef.
+
+NOTE: You may also want to consider using the [azure-xplat-cli](https://github.com/Azure/azure-xplat-cli),
+this application is written by the Azure team and has many other integrations with
+Azure. If click [here](https://github.com/chef-partners/azure-chef-extension/blob/master/examples/azure-xplat-cli-examples.md)
+you'll see deeper examples of using the Chef extension and Azure.
 
 ## Installation
 Be sure you are running the latest version of Chef DK, which can be installed
@@ -14,12 +20,26 @@ via:
 
 This plugin is distributed as a Ruby Gem. To install it, run:
 
-    chef gem install knife-azure
+```bash
+chef gem install knife-azure
+```
 
 Depending on your system's configuration, you may need to run this command
 with root/administrator privileges.
 
+## Modes
+`knife-azure 1.6.0` onwards, we are adding support for Azure Resource Manager. You can easily switch between the
+
+* Service management: commands using the Azure service management API
+* Resource manager: commands using the Azure Resource Manager API
+
+They are not designed to work together. Commands starting with `knife azure` use ASM mode, while commands starting with `knife azurerm` use ARM mode.
+
+PLEASE NOTE that `Azuererm` subcommands are experimental and of alpha quality. Not suitable for production use. Please use ASM subcommands for production.
+
 ## Configuration
+
+### ASM mode
 For this plugin to interact with Azure's REST API, you will need to give Knife
 information about your Azure account and credentials. The easiest way to do
 this is to sign in to the Azure portal and download a publishsettings file
@@ -37,7 +57,36 @@ The plug-in also accepts authentication information specified using an
 alternative set of options -- see the section on "Alternative Management
 Certificate Specification" for details.
 
-## Basic Examples
+The plug-in can also read Azure account and credentials from the `Azure Profile` if Knife does not have the entry for `publish_settings_file`.
+An `Azure Profile` is a `JSON` file with subscription and environment information in it. Its default location is `~/.azure/azureProfile.json`.
+
+The Azure Profile file can be created and manipulated using the [Azure CLI](http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-command-line-tools/). You can
+also refer [Azure Xplat-CLI](https://github.com/Azure/azure-xplat-cli#use-publish-settings-file-management-certificate-authentication).
+
+If Azure Profile file has entries for multiple subscriptions then you can choose the default using `azure account set <subscription_name>`. The same default subscription will
+be picked up that you have configured.
+
+### ARM mode
+ARM mode requires setting up service principal for authentication and permissioning. For setting up a service principal from the command line please refer
+[Authenticating a service principal with Azure Resource Manager](http://aka.ms/cli-service-principal) or
+[Unattended Authentication](http://aka.ms/auth-unattended). For detailed explanation of authentication in Azure,
+see [Developer’s guide to auth with Azure Resource Manager API](http://aka.ms/arm-auth-dev-guide).
+
+After creating the service principal, you should have these 3 values, a client id (GUID), client secret(string) and tenant id (GUID).
+
+Be sure when you are creating the above user you change the example from `-o Reader` to `-o Contributor` otherwise you will not be able
+to spin up or delete machines.
+
+Put the following in your `knife.rb`
+
+```ruby
+knife[:azure_tenant_id] # found via: tenantId=$(azure account show -s <subscriptionId> --json | jq -r '.[0].tenantId')
+knife[:azure_subscription_id] # found via: <subscriptionId>
+knife[:azure_client_id] # appId=$(azure ad app show --search <principleappcreated> --json | jq -r '.[0].appId')
+knife[:azure_client_secret] # password you set at initally
+```
+
+## Basic Examples for ASM
 The following examples assume that you've configured the publishsettings file
 location in your knife.rb:
 
@@ -67,7 +116,7 @@ Use the --help option to read more about each subcommand. Eg:
 
     knife azure server create --help
 
-## Detailed Usage
+## Detailed Usage for ASM mode
 
 ### Common Configuration
 Most configuration options can be specified either in your knife.rb file or as command line parameters. The CLI parameters override the knife.rb parameters.
@@ -276,6 +325,19 @@ We have also added cloud-api support for Centos now, for this you just need to s
 
 `--delete-chef-extension-config` determines if Chef configuration files should be removed when Azure removes the Chef resource extension from the VM or not. This option is only valid for the 'cloud-api' bootstrap protocol. The default value is false. This is useful when `update` and `uninstall` commands are run for the extension on the VM created.
 
+It's possible to pass bootstrap options to the extension which get specified in `client.rb` file on the VM. Following options can be passed:
+
+    --environment
+    --node-name
+    --secret-file
+    --server
+    --validation-client-name
+    --[no-]node-verify-api-cert
+    --bootstrap-version
+    --node-ssl-verify-mode
+    --bootstrap-proxy
+
+
 #### Azure Server Create with Domain Join
 Following options are used for creating server with domain join
 
@@ -360,6 +422,241 @@ Knife options:
 For CIDR notation, see here: http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
 Address available are defined in RFC 1918: http://en.wikipedia.org/wiki/Private_network
 
+## Detailed Usage for ARM mode
+
+### Common Configuration
+
+ARM configuration options can be specified in your knife.rb file only.
+
+The following options are required for all azurerm subcommands:
+
+    option :azure_subscription_id            Your Azure subscription ID
+    option :azure_tenant_id                  Your subscription's tenant id
+    option :azure_client_id                  Your Active Directory Application id
+    option :azure_client_secret              Your Active Directory Application's password
+
+Note: The options mentioned above can be obtained from this [step](https://github.com/chef/knife-azure#arm-mode)
+
+### Azure Server Create Subcommand
+This subcommand provisions a new server in Azure and then performs a Chef bootstrap.
+
+User can either provide just `--azure-image-os-type` or other image reference parameters i.e. `--azure-image-reference-publisher`, `--azure-image-reference-offer`, `--azure-image-reference-sku` and `--azure-image-reference-version` to specify the image.
+
+Accepted values for `--azure-image-os-type` are `ubuntu`, `centos`, `rhel`, `debian ` and `windows`. It creates the server using standard image parameters for respective OS. However, they can be overridden using `--azure-image-reference-publisher`, `--azure-image-reference-offer`, `--azure-image-reference-sku` and `--azure-image-reference-version` options.
+`--azure-image-os-type` option should not be used with other image reference parameters.
+
+To see a list of commonly used image parameters, please refer https://azure.microsoft.com/en-in/documentation/articles/resource-groups-vm-searching/#table-of-commonly-used-images
+
+For Windows:
+
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-os-type windows
+  -x myuser -P mypassword
+  -r "recipe[cbk1::rec2]"
+  -c ~/.chef/knife.rb
+```
+OR
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-reference-publisher 'MicrosoftWindowsServer'
+  --azure-image-reference-offer 'WindowsServer'
+  --azure-image-reference-sku '2012-R2-Datacenter'
+  --azure-image-reference-version 'latest'
+  -x myuser -P mypassword
+  -r "recipe[cbk1::rec2]"
+  -c ~/.chef/knife.rb
+```
+
+For Centos:
+
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-os-type centos
+  --azure-vm-size Small
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+OR
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-reference-publisher 'OpenLogic'
+  --azure-image-reference-offer 'CentOS'
+  --azure-image-reference-sku '6.5'
+  --azure-image-reference-version 'latest'
+  --ssh-user myuser --ssh-password mypassword
+  --azure-vm-size Small
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+
+For Ubuntu:
+
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-os-type ubuntu
+  --ssh-user myuser --ssh-password mypassword
+  --azure-vm-size Small
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+OR
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-reference-publisher 'Canonical'
+  --azure-image-reference-offer 'UbuntuServer'
+  --azure-image-reference-sku '14.04.2-LTS'
+  --azure-image-reference-version 'latest'
+  --ssh-user myuser --ssh-password mypassword
+  --azure-vm-size Small
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+
+For Rhel:
+
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-os-type rhel
+  --ssh-user myuser --ssh-password mypassword
+  --azure-vm-size Small
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+OR
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-reference-publisher 'RedHat'
+  --azure-image-reference-offer 'RHEL'
+  --azure-image-reference-sku '7.2'
+  --azure-image-reference-version 'latest'
+  --ssh-user myuser --ssh-password mypassword
+  --azure-vm-size Small
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+
+For Debian:
+
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-os-type debian
+  --ssh-user myuser --ssh-password mypassword
+  --azure-vm-size Small
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+OR
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-reference-publisher 'credativ'
+  --azure-image-reference-offer 'Debian'
+  --azure-image-reference-sku '7'
+  --azure-image-reference-version 'latest'
+  --ssh-user myuser --ssh-password mypassword
+  --azure-vm-size Small
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+
+User can use existing virtual network and subnet while server create by providing `--azure-vnet-name` and `--azure-vnet-subnet-name` options.
+
+Note:
+
+1. If these options are not given, default vnet and subnet with the VM name will be created.
+2. User needs to provide valid existing vnet name and subnet name otherwise it will raise vnet or subnet not found error.
+3. Vnet should belong to the same resource group that is provided in the command.
+4. Subnet should belong to the same vnet that is provided in the command.
+
+```
+knife azurerm server create
+  --azure-resource-group-name MyResourceGrpName
+  --azure-vm-name MyNewVMName
+  --azure-service-location 'WEST US'
+  --azure-image-os-type ubuntu
+  --ssh-user myuser --ssh-password mypassword
+  --azure-vm-size Small
+  --azure-vnet-name 'VnetName'
+  --azure-vnet-subnet-name 'VnetSubnetName'
+  -r "recipe[cbk1::rec1]"
+  -c ~/.chef/knife.rb
+```
+
+#### --server-count option
+User can pass `--server-count` option to specify the number of servers to be created with same configuration.
+```
+--server-count COUNT         Number of servers to create with same configuration. Maximum count is 5. Default value is 1.
+
+Command:
+knife azurerm server create
+--azure-resource-group-name MyResourceGrpName
+--azure-vm-name MyNewVMName
+--azure-service-location 'WEST US'
+--azure-image-os-type centos
+--azure-vm-size Small
+--server-count 3
+-x myuser -P mypassword
+```
+This will create 3 VMs with names: `MyNewVMName0`, `MyNewVMName1` and `MyNewVMName2`
+
+
+### Azure Server Delete Subcommand
+Deletes an existing ARM server in the currently configured Azure account. By default, this does not delete the associated resource-group, associated node and client objects from the Chef server.
+For deleting associated resource-group along with server use --delete-resource-group flag.
+For deleting associated node and client objects from the Chef server, add the --purge flag.
+
+```
+knife azurerm server delete MyVMName --azure-resource-group-name MyResourceGrpName -c ~/.chef/knife.rb
+
+knife azurerm server delete MyVMName --azure-resource-group-name MyResourceGrpName -c ~/.chef/knife.rb --purge  #purge chef node
+
+knife azurerm server delete MyVMName --azure-resource-group-name MyResourceGrpName -c ~/.chef/knife.rb --delete-resource-group #deletes resource group
+```
+
+### Azure Server List Subcommand
+Outputs a list of all ARM servers in the currently configured Azure account. PLEASE NOTE - this shows all instances associated with the account, some of which may not be currently managed by the Chef server.
+
+```
+knife azurerm server list
+```
+
+### Azure Server Show Subcommand
+Outputs the details of an ARM server.
+
+```
+knife azurerm server show MyVMName --azure-resource-group-name MyResourceGrpName -c ~/.chef/knife.rb
+```
+
 
 ## Alternative Management Certificate Specification
 In addition to specifying the management certificate using the publishsettings
@@ -395,4 +692,3 @@ You might be asked to enter a password which is usually blank.
 You might be also asked to enter a passphrase. Please enter the phrase of your choice.
 
 It is possible to generate your own certificates and upload them. More Detailed Documentation about the Management Certificates is available : https://www.windowsazure.com/en-us/manage/linux/common-tasks/manage-certificates/
-

data/lib/azure/azure_interface.rb

@@ -0,0 +1,81 @@
+#
+# Author::
+# Copyright:: Copyright (c) 2016 Opscode, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'azure/custom_errors'
+require 'azure/helpers'
+
+
+module Azure
+  class AzureInterface
+    include CustomErrors
+    include Helpers
+
+    attr_accessor :ui
+
+    def initialize(options = {})
+    end
+
+    def create_server(params = {})
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def list_servers
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def delete_server(server_name)
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def list_images
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def show_server(server_name, resource_group = "")
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def create_vnet(params = {})
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def list_vnets
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def list_internal_lb
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def create_internal_lb(params = {})
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def list_affinity_groups
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def create_affinity_group(params = {})
+      AzureInterface.api_not_implemented(self)
+    end
+
+    def find_server(server_name)
+      AzureInterface.api_not_implemented(self)
+    end
+  end
+end