1=============================
2Getting Started With HP Cloud
3=============================
4
5HP Cloud is a major public cloud platform and uses the libcloud
6`openstack` driver. The current version of OpenStack that HP Cloud
7uses is Havana. When an instance is booted, it must have a
8floating IP added to it in order to connect to it and further below
9you will see an example that adds context to this statement.
10
11Set up a cloud provider configuration file
12==========================================
13
14To use the `openstack` driver for HP Cloud, set up the cloud
15provider configuration file as in the example shown below:
16
17``/etc/salt/cloud.providers.d/hpcloud.conf``:
18
19.. code-block:: yaml
20
21    hpcloud-config:
22      # Set the location of the salt-master
23      #
24      minion:
25        master: saltmaster.example.com
26
27      # Configure HP Cloud using the OpenStack plugin
28      #
29      identity_url: https://region-b.geo-1.identity.hpcloudsvc.com:35357/v2.0/tokens
30      compute_name: Compute
31      protocol: ipv4
32
33      # Set the compute region:
34      #
35      compute_region: region-b.geo-1
36
37      # Configure HP Cloud authentication credentials
38      #
39      user: myname
40      tenant: myname-project1
41      password: xxxxxxxxx
42
43      # keys to allow connection to the instance launched
44      #
45      ssh_key_name: yourkey
46      ssh_key_file: /path/to/key/yourkey.priv
47
48      driver: openstack
49
50
51The subsequent example that follows is using the openstack driver.
52
53.. note::
54    .. versionchanged:: 2015.8.0
55
56    The ``provider`` parameter in cloud provider definitions was renamed to ``driver``. This
57    change was made to avoid confusion with the ``provider`` parameter that is used in cloud profile
58    definitions. Cloud provider definitions now use ``driver`` to refer to the Salt cloud module that
59    provides the underlying functionality to connect to a cloud host, while cloud profiles continue
60    to use ``provider`` to refer to provider configurations that you define.
61
62Compute Region
63==============
64
65Originally, HP Cloud, in its OpenStack Essex version (1.0), had 3
66availability zones in one region, US West (region-a.geo-1), which
67each behaved each as a region.
68
69This has since changed, and the current OpenStack Havana version of
70HP Cloud (1.1) now has simplified this and now has two regions to choose from:
71
72.. code-block:: bash
73
74    region-a.geo-1 -> US West
75    region-b.geo-1 -> US East
76
77Authentication
78==============
79
80The ``user`` is the same user as is used to log into the HP Cloud management
81UI. The ``tenant`` can be found in the upper left under "Project/Region/Scope".
82It is often named the same as ``user`` albeit with a ``-project1`` appended.
83The ``password`` is of course what you created your account with. The management
84UI also has other information such as being able to select US East or US West.
85
86Set up a cloud profile config file
87==================================
88
89The profile shown below is a know working profile for an Ubuntu instance. The
90profile configuration file is stored in the following location:
91
92``/etc/salt/cloud.profiles.d/hp_ae1_ubuntu.conf``:
93
94.. code-block:: yaml
95
96    hp_ae1_ubuntu:
97        provider: hp_ae1
98        image: 9302692b-b787-4b52-a3a6-daebb79cb498
99        ignore_cidr: 10.0.0.1/24
100        networks:
101          - floating: Ext-Net
102        size: standard.small
103        ssh_key_file: /root/keys/test.key
104        ssh_key_name: test
105        ssh_username: ubuntu
106
107Some important things about the example above:
108
109* The ``image`` parameter can use either the image name or image ID which you can obtain by running in the example below (this case US East):
110
111.. code-block:: bash
112
113    # salt-cloud --list-images hp_ae1
114
115* The parameter ``ignore_cidr`` specifies a range of addresses to ignore when trying to connect to the instance. In this case, it's the range of IP addresses used for an private IP of the instance.
116
117* The parameter ``networks`` is very important to include. In previous versions of Salt Cloud, this is what made it possible for salt-cloud to be able to attach a floating IP to the instance in order to connect to the instance and set up the minion. The current version of salt-cloud doesn't require it, though having it is of no harm either. Newer versions of salt-cloud will use this, and without it, will attempt to find a list of floating IP addresses to use regardless.
118
119* The ``ssh_key_file`` and ``ssh_key_name`` are the keys that will make it possible to connect to the instance to set up the minion
120
121* The ``ssh_username`` parameter, in this case, being that the image used will be ubuntu, will make it possible to not only log in but install the minion
122
123
124Launch an instance
125==================
126
127To instantiate a machine based on this profile (example):
128
129.. code-block:: bash
130
131    # salt-cloud -p hp_ae1_ubuntu ubuntu_instance_1
132
133
134After several minutes, this will create an instance named ubuntu_instance_1
135running in HP Cloud in the US East region and will set up the minion and then
136return information about the instance once completed.
137
138Manage the instance
139===================
140
141Once the instance has been created with salt-minion installed, connectivity to
142it can be verified with Salt:
143
144.. code-block:: bash
145
146    # salt ubuntu_instance_1 ping
147
148SSH to the instance
149===================
150
151Additionally, the instance can be accessed via SSH using the floating IP assigned to it
152
153.. code-block:: bash
154
155    # ssh ubuntu@<floating ip>
156
157Using a private IP
158==================
159
160Alternatively, in the cloud profile, using the private IP to log into the instance to set up the minion is another option, particularly if salt-cloud is running within the cloud on an instance that is on the same network with all the other instances (minions)
161
162The example below is a modified version of the previous example. Note the use of ``ssh_interface``:
163
164.. code-block:: yaml
165
166    hp_ae1_ubuntu:
167        provider: hp_ae1
168        image: 9302692b-b787-4b52-a3a6-daebb79cb498
169        size: standard.small
170        ssh_key_file: /root/keys/test.key
171        ssh_key_name: test
172        ssh_username: ubuntu
173        ssh_interface: private_ips
174
175With this setup, salt-cloud will use the private IP address to ssh into the instance and set up the salt-minion
176