knife-profitbricks 1.2.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0237bc45a0358a6e2620ffd9941416bb51442277
-  data.tar.gz: 59253a8e95dabc1e97b1f0f09c126b30b4eee233
+  metadata.gz: bce4842d7d224840142aac9373abb82b5d3d8f94
+  data.tar.gz: d854007f93993768dd63b43c946a8ee55b6024ad
 SHA512:
-  metadata.gz: f9b3fd767eb66142ed8eae7e8da5edf9abfbb56102ce77b0eff62798931f48d4fe021e35f593cfb033b8f05f87d072aea7a8f53bcd7dd12d44eb03a7ef8806d2
-  data.tar.gz: 429ea7698af89c5a632a5787daa1d2ea410d5321961f9371c85ccc98023c9b4fde5c9b8cc63e612cfe5a1700e1c70b8c62f5be0b38206051a6d5ca5215c5b276
+  metadata.gz: a4d695ad8f4971730c5945526d7bd682f617cea211a044557592f5a291cd5ce3d7e2428eecb25cba238fb9142e6da468a83313ac81958bdfb1474fc4daf96c13
+  data.tar.gz: 8a271f015f30c9c05384352c4c872d4c08f47878b1b9a72663d8cf6085678d1907d2112a85e8c243e99e291deef011c3bbc279575e90e73366b7c0cbb0b00389

data/.gitignore

@@ -22,3 +22,4 @@ tmp
 *.o
 *.a
 mkmf.log
+knife.rb

data/README.md

@@ -1,17 +1,61 @@
-# Knife ProfitBricks
-
-## Description
-
-ProfitBricks Chef Knife plugin
+# ProfitBricks Chef Knife Plugin
+
+## Table of Contents
+
+* [Concepts](#concepts)
+* [Requirements](#requirements)
+* [Getting Started](#getting-started)
+* [Installation](#installation)
+* [Configuration](#configuration)
+* [How To](#how-to)
+    * [List Data Centers](#list-data-centers)
+    * [Create Data Center](#create-data-center)
+    * [Create Server](#create-server)
+    * [List Servers](#list-servers)
+    * [List Images](#list-images)
+    * [Create Volume](#create-volume)
+    * [List Volumes](#list-volumes)
+    * [Attach and Detach Volume](#attach-and-detach-volume)
+    * [Reserve IP Block](#reserve-ip-block)
+    * [Create Public LAN](#create-public-lan)
+    * [Create NIC](#create-nic)
+    * [Create Composite Server](#create-composite-server)
+    * [Delete Data Center](#delete-data-center)
+* [Reference](#reference)
+    * [Location](#location)
+    * [Data Center](#data-center)
+    * [Server](#server)
+    * [Volume](#volume)
+    * [Image](#image)
+    * [LAN](#lan)
+    * [NIC](#nic)
+    * [IP Block](#ip-block)
+    * [Firewall](#firewall)
+    * [IP Failover](#ip-failover)
+* [Support](#support)
+* [Testing](#testing)
+* [Contributing](#contributing)
+
+## Concepts
+
+Chef is a popular configuration management tool that allows simplified configuration and maintenance of both servers and cloud provider environments through the use of common templates called recipes. The Chef `knife` command line tool allows management of various nodes within those environments. The `knife-profitbricks` plugin utilizes the ProfitBricks REST API to provision and manage various cloud resources on the ProfitBricks platform.
 
 ## Requirements
 
 * Chef 12.3.0 or higher
 * Ruby 2.0.x or higher
 
+## Getting Started
+
+Before you begin you will need to have [signed-up](https://www.profitbricks.com/signup/) for a ProfitBricks account. The credentials you establish during sign-up will be used to authenticate against the [ProfitBricks Cloud API](https://devops.profitbricks.com/api/).
+
 ## Installation
 
-Add this line to your application's Gemfile:
+The `knife-profitbricks` plugin can be installed as a gem:
+
+    $ gem install knife-profitbricks
+
+Or the plugin can be installed by adding the following line to your application's Gemfile:
 
     gem 'knife-profitbricks'
 
@@ -19,190 +63,353 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
-
-    $ gem install knife-profitbricks
-
 ## Configuration
 
-The ProfitBricks Chef Knife plugin requires valid ProfitBricks account credentials. These credentials can be added to the `knife.rb` configuration file.
+The ProfitBricks account credentials can be added to the `knife.rb` configuration file.
 
     knife[:profitbricks_username] = 'username'
     knife[:profitbricks_password] = 'password'
 
-If a virtual data center has already been created under the ProfitBricks account, then the data center ID can be added to the `knife.rb` which reduces the need to include the --datacenter-id parameter for each action within the data center.
- 
+If a virtual data center has already been created under the ProfitBricks account, then the data center UUID can be added to the `knife.rb` which reduces the need to include the `--datacenter-id [datacenter_id]` parameter for each action within the data center.
+
     knife[:datacenter_id] = 'f3f3b6fe-017d-43a3-b42a-a759144b2e99'
 
 Optional parameters include the following:
 
     knife[:profitbricks_url] = 'https://api.profitbricks.com'
     knife[:profitbricks_debug] = true
- 
-## Sub Commands
 
-### knife profitbricks datacenter create
+The configuration parameters can also be passed using shell environment variables. First, the following should be added to the `knife.rb` configuration file:
 
-Creates a new data center where servers, volumes, and other resources will reside.
+    knife[:profitbricks_username] = ENV['PROFITBRICKS_USERNAME']
+    knife[:profitbricks_password] = ENV['PROFITBRICKS_PASSWORD']
 
-### knife profitbricks datacenter delete
+Now the parameters can be set as environment variables:
 
-**USE WITH EXTREME CAUTION**
+    $ export PROFITBRICKS_USERNAME='username'
+    $ export PROFITBRICKS_PASSWORD='password'
 
-Deletes an existing data center and all resources within that data center.
+# How To
 
-### knife profitbricks datacenter list
+## List Data Centers
 
-List all available data centers under the ProfitBricks account.
+ProfitBricks introduces the concept of virtual data centers. These are logically separated from one another and allow you to have a self-contained environment for all servers, volumes, networking, and other resources. The goal is to give you the same experience as you would have if you were running your own physical data center.
 
-### knife profitbricks firewall create
+A list of available data centers can be obtained with the following command.
 
-Creates a new firewall rule on an existing NIC.
+    knife profitbricks datacenter list
 
-### knife profitbricks firewall delete
+## Create Data Center
 
-Deletes a firewall rule from an existing NIC.
+Unless you are planning to manage an existing ProfitBricks environment, the first step will typically involve choosing the location for a new virtual data center. A list of locations can be obtained with location command.
 
-### knife profitbricks firewall list
+    knife profitbricks location list
 
-Lists all available firewall rules assigned to a NIC.
+Make a note of the desired location ID and now the data center can be created.
 
-### knife profitbricks image list
+    knife profitbricks datacenter create --name "Production" --description "Production webserver environment" --location "us/las"
 
-Lists all available images.
+## Create Server
 
-### knife profitbricks ipblock create
+One of the unique features of the ProfitBricks platform when compared with the other providers is that they allow you to define your own settings for cores, memory, and disk size without being tied to a particular size or flavor.
 
-Reserves a new IP block.
+Note: *The memory parameter value must be a multiple of 256, e.g. 256, 512, 768, 1024, and so forth.*
 
-### knife profitbricks ipblock delete
+The following example shows you how to create a new server in the data center created above:
 
-Releases a currently assigned IP block.
+    knife profitbricks server create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --name "Frontend Webserver" --cores 1 --ram 1024 --availability-zone ZONE_1 --cpu-family INTEL_XEON
 
-### knife profitbricks ipblock list
+## List Servers
 
-Lists all available IP blocks.
+The new server should appear when listing all servers under the specified data center.
 
-### knife profitbricks lan create
+    knife profitbricks server list --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1
 
-Creates a new LAN under a data center.
+## List Images
 
-### knife profitbricks lan delete
+A list of disk and ISO images are available from ProfitBricks for immediate use. These can be easily reviewed and selected with the following command.
 
-Deletes an existing LAN.
+    knife profitbricks image list
 
-### knife profitbricks lan list
+Make sure the image you use is in the same location as the virtual data center.
 
-Lists all available LANs under a data center.
+## Create Volume
 
-### knife profitbricks location list
+ProfitBricks allows for the creation of multiple storage volumes that can be attached and detached as needed. It is useful to attach an image when creating a storage volume. The storage size is in gigabytes (GB).
 
-List all available regions where a data center may reside.
+    knife profitbricks volume create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --name "OS Volume" --size 20 --type HDD --image c4263e0f-e75e-11e4-91fd-8fa3eaae9f6b --ssh-keys "ssh-rsa AAAAB3NzaC1..."
 
-### knife profitbricks nic create
+## List Volumes
 
-Creates a NIC on the specified server.
+The following example will list all available volumes under a data center.
 
-### knife profitbricks nic delete
+    knife profitbricks volume list --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1
 
-Deletes an existing NIC from a server.
+You can also list all volumes attached to a specific server.
 
-### knife profitbricks nic list
+    knife profitbricks volume list --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --server-id 2e438d3b-02f0-47d0-8594-4ace38ed2804
 
-List all available NICs connected to a server.
+## Attach and Detach Volume
 
-### knife profitbricks composite server create
+ProfitBricks allows for the creation of multiple storage volumes. You can detach and reattach these on the fly. This allows for various scenarios such as re-attaching a failed OS disk to another server for possible recovery or moving a volume to another location and bringing it online.
 
-Creates a new composite server with attached volume and NIC in a specified data center.
+The following illustrates how you would attach a volume with a UUID of 9b45f734-01ec-46ca-b163-d06c5a9d707f to a server:
 
-### knife profitbricks server create
+    knife profitbricks volume attach --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --server-id 2e438d3b-02f0-47d0-8594-4ace38ed2804 9b45f734-01ec-46ca-b163-d06c5a9d707f
 
-Creates a new server within a specified data center.
+If you need to detach the same volume:
 
-### knife profitbricks server delete
+    knife profitbricks volume detach --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --server-id 2e438d3b-02f0-47d0-8594-4ace38ed2804 9b45f734-01ec-46ca-b163-d06c5a9d707f
 
-Deletes an existing server.
+## Reserve IP Block
+
+The IP block size (number of IP addresses) and location are required to reserve an IP block:
+
+    knife profitbricks ipblock create --size 5 --location "us/las"
+
+## Create Public LAN
+
+A pubic LAN must be created within a data center.
+
+    knife profitbricks lan create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --name "Public Network" --public
 
-### knife profitbricks server list
+## Create NIC
+
+The ProfitBricks platform supports adding multiple NICs to a server. These NICs can be used to create different, segmented networks on the platform.
+
+The example below shows you how to add a second NIC to an existing server and LAN:
+
+    knife profitbricks nic create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --server-id 2e438d3b-02f0-47d0-8594-4ace38ed2804 --name "Public NIC" --lan 1
+
+## Create Composite Server
+
+This creates a new composite server with an attached volume and NIC in a specified virtual data center.
+
+    knife profitbricks composite server create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --name "Backend Database" --cores 1 --ram 8192 --size 5 --type SSD --lan 1 --image 2ead2908-df61-11e5-80a4-52540005ab80 --ssh-keys "ssh-rsa AAAAB3NzaC1..."
+
+## Delete Data Center
+
+You will want to exercise a bit of caution here. Removing a data center will destroy all objects contained within that data center -- servers, volumes, snapshots, and so on. The objects -- once removed -- will be unrecoverable.
+
+    knife profitbricks datacenter delete ade28808-9253-4d4e-9f5d-f1f7f1038fb1
+
+# Reference
+
+## Location
+
+### List Locations
+
+List available physical locations where resources can reside.
+
+    knife profitbricks location list
+
+## Data Center
+
+### List Data Centers
+
+List all available data centers under the ProfitBricks account.
+
+    knife profitbricks datacenter list
+
+### Create Data Center
+
+Creates a new data center where servers, volumes, and other resources will reside.
+
+    knife profitbricks datacenter create --name [string] --description [string] --location [location_id]
+
+### Delete Data Center
+
+* **USE WITH EXTREME CAUTION**
+
+Deletes an existing data center and all resources within that data center.
+
+    knife profitbricks datacenter delete [datacenter_id]
+
+## Server
+
+### List Servers
 
 List all available servers under a specified data center.
 
-### knife profitbricks server reboot
+    knife profitbricks server list --datacenter-id [datacenter_id]
+
+### Create Server
+
+Creates a new server within a specified data center.
+
+    knife profitbricks server create --datacenter-id [datacenter_id] --name [string] --cores [int] --ram [int] ...
+
+### Delete Server
+
+Deletes an existing server.
+
+    knife profitbricks server delete --datacenter-id [datacenter_id] [server_id]
+
+### Reboot Server
 
 Performs a hard reset on a server.
 
-### knife profitbricks server start
+    knife profitbricks server reboot --datacenter-id [datacenter_id] [server_id]
+
+### Start Server
 
 Starts a server.
 
-### knife profitbricks server stop
+    knife profitbricks server start --datacenter-id [datacenter_id] [server_id]
+
+### Stop Server
 
 Stops a server.
 
-### knife profitbricks volume attach
+    knife profitbricks server stop --datacenter-id [datacenter_id] [server_id]
 
-Attaches an existing volume to a server.
+## Volume
 
-### knife profitbricks volume create
+### List Volumes
+
+Lists all available volumes under a data center. Passing the `--server-id` parameter will also list all volumes attached to the specified server.
+
+    knife profitbricks volume list --datacenter-id [datacenter_id]
+
+    knife profitbricks volume list --datacenter-id [datacenter_id] --server-id [server_id]
+
+### Create Volume
 
 Creates a new volume.
 
-### knife profitbricks volume delete
+    knife profitbricks volume create --datacenter-id [datacenter_id] --name [string] --size [int] --image [image_id] ...
+
+### Delete Volume
 
 Deletes an existing volume.
 
-### knife profitbricks volume detach
+    knife profitbricks volume delete --datacenter-id [datacenter_id] [volume_id]
 
-Detaches a volume from a server.
+### Attach Volume
 
-### knife profitbricks volume list
+Attaches an existing volume to a server.
 
-Lists all available volumes under a data center. Passing the `--server-id` parameter will also list all volumes attached to the specified server.
+    knife profitbricks volume attach --datacenter-id [datacenter_id] --server-id [server_id] [volume_id]
 
-## Examples
+### Detach Volume
 
-To review a list of existing data centers:
+Detaches a volume from a server.
 
-    knife profitbricks datacenter list
+    knife profitbricks volume detach --datacenter-id [datacenter_id] --server-id [server_id] [volume_id]
 
-The first step is to usually identify a location where the data center should reside as well as an image to use. It is **important** to note that the image must exist in the same location as the data center. Make a note of the image UUID.
+## Image
+
+### List Images
+
+Lists all available images.
 
     knife profitbricks image list
-    knife profitbricks location list
 
-Now the data center can be created.
+## LAN
 
-    knife profitbricks datacenter create --name "Production" --description "Production webserver environment" --location "us/las"
+### List LANs
 
-Once the data center is provisioned, both a server and volume can be created. The volume will use an existing image as identified above.
+Lists all available LANs under a data center.
 
-    knife profitbricks server create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --name "Frontend Webserver" --cores 1 --ram 1024 --availability-zone ZONE_1 --cpu-family INTEL_XEON
-    knife profitbricks volume create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --name "OS Volume" --size 5 --type HDD --image c4263e0f-e75e-11e4-91fd-8fa3eaae9f6b --ssh-keys "ssh-rsa AAAAB3NzaC1..."
+    knife profitbricks lan list
 
-The volume can then be attached to the server.
+### Create LAN
 
-    knife profitbricks volume attach --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --server-id 2e438d3b-02f0-47d0-8594-4ace38ed2804 9b45f734-01ec-46ca-b163-d06c5a9d707f
+Creates a new LAN under a data center.
 
-Now a NIC can be added the new server. The LAN will automatically be created if a non-existent LAN ID is passed with the `--lan` parameter.
+    knife profitbricks lan create --datacenter-id [datacenter_id] --name [string] [--public]
 
-    knife profitbricks nic create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --server-id 2e438d3b-02f0-47d0-8594-4ace38ed2804 --name "Primary NIC" --lan 1
+### Delete LAN
 
-Here is an example of adding a firewall rule to the newly created NIC.
+Deletes an existing LAN.
 
-    knife profitbricks firewall create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --server-id 2e438d3b-02f0-47d0-8594-4ace38ed2804 --nic-id e4270ecc-e9c5-4de0-940a-8a0a99d962fd --name "SSH" --protocol TCP --port-range-start 22 --port-range-end 22 --source-ip 203.0.113.10
+    knife profitbricks lan delete --datacenter-id [datacenter_id]
 
-A composite server can also be created with attached volume and NIC in a single command.
+## NIC
 
-    knife profitbricks composite server create --datacenter-id ade28808-9253-4d4e-9f5d-f1f7f1038fb1 --name "Backend Database" --cores 1 --ram 8192 --size 5 --type SSD --lan 1 --image 2ead2908-df61-11e5-80a4-52540005ab80 --ssh-keys "ssh-rsa AAAAB3NzaC1..."
+### List NICs
 
-The new data center and **all resources within that data center** can be deleted.
+List all available NICs connected to a server.
 
-    knife profitbricks datacenter delete ade28808-9253-4d4e-9f5d-f1f7f1038fb1
+    knife profitbricks nic list
+
+### Create NIC
+
+Creates a NIC on the specified server.
+
+    knife profitbricks nic create --datacenter-id [datacenter_id] --server-id [server_id] --name [string] --lan [int] -ips IP[,IP,...] [--dhcp]
+
+### Delete NIC
+
+Deletes an existing NIC from a server.
+
+    knife profitbricks nic delete --datacenter-id [datacenter_id] [nic_id]
+
+## IP Block
+
+### List IP Blocks
+
+Lists all available IP blocks.
+
+    knife profitbricks ipblock list
+
+### Reserve IP Block
+
+Reserve a new IP block.
+
+    knife profitbricks ipblock create --size [int] --location [string]
+
+### Release IP Block
+
+Releases a currently assigned IP block.
+
+    knife profitbricks ipblock delete [ipblock_id]
+
+## Firewall
+
+### List Firewall Rules
+
+Lists all available firewall rules assigned to a NIC.
+
+    knife profitbricks firewall list
+
+### Create Firewall Rule
+
+Creates a new firewall rule on an existing NIC.
+
+    knife profitbricks firewall create --datacenter-id [datacenter_id] --server-id [server_id] --nic-id [nic_id] --name [string] --protocol [TCP, UDP] --port-range-start [int] --port-range-end [int] --source-ip [IP]
+
+### Delete Firewall Rule
+
+Deletes a firewall rule from an existing NIC.
+
+    knife profitbricks firewall delete --datacenter-id [datacenter_id] --server-id [server_id] --nic-id [nic_id] [firewall_id]
+
+## IP Failover
+
+### Add IP to LAN failover group
+
+Adds IPs to LAN
+
+    knife profitbricks failover add --datacenter-id [datacenter_id] --lan-id [lan_id] --ip [ip1] --nic-id [nic_id]
+
+### Remove IP from LAN failover group
+
+Remove IP Failover from LAN
+
+    knife profitbricks failover remove --datacenter-id [datacenter_id] --lan-id [lan_id] --ip [ip1] --nic-id [nic_id]
+
+## Contract Resources
+
+Lists information about available contract resources
+
+    knife profitbricks contract list
+
+## Support
 
-## Documentation and Support
+Please report any issues through the [project repository on GitHub](https://github.com/profitbricks/knife-profitbricks).
 
-* [ProfitBricks REST API](https://devops.profitbricks.com/api/rest/) documentation.
-* Ask a question or discuss at [ProfitBricks DevOps Central](https://devops.profitbricks.com/community).
+Questions and discussions can be directed to [ProfitBricks DevOps Central](https://devops.profitbricks.com/) site.
 
 ## Testing
 
@@ -210,8 +417,8 @@ The new data center and **all resources within that data center** can be deleted
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/knife-profitbricks/fork )
-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 a new Pull Request
+1. Fork it ( https://github.com/[my-github-username]/knife-profitbricks/fork ).
+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 a new Pull Request.