Merge pull request juju#918 from pmatulis/issue_781-config-rackspace.md

Issue 781 config rackspace.md

Author: evilnick

htmldocs/media/config-rackspace_portal-machine_0.png

@@ -0,0 +1,123 @@
+Title: Configuring for Rackspace
+TODO: Review again soon (created: March 2016)
+      'juju add-credential rackspace' should exist
+      Need exhaustive list of conf/cred parameters to use
+      Does 'juju show-cloud rackspace' replace 'juju help rackspace-provider'? Confirm these commands
+      Confirm navigation.tpl contains controllers & models (see links in first paragraph)
+      Explain the configuration parameters (like credentials parameters)
+      Explain how to use auth-type 'access-key'
+
+
+# Configuring for Rackspace
+
+Here we gather the ingredients necessary for the creation of a *controller* for
+the Rackspace cloud provider (see [Controllers](./controllers.html)). If your
+objective is instead to create a Rackspace *model* please see [Defining a
+model](./models-defining.html).
+
+
+## Prerequisites
+
+ - A Rackspace cloud account is required. See https://cart.rackspace.com/cloud .
+
+ - The Juju client (the host running the below commands) will need the ability
+   to contact the Rackspace infrastructure on TCP ports 22 and 17070.
+
+ - An understanding of the [Getting started](./getting-started.html) page.
+
+
+## Credentials
+
+Values will need to be found for certain parameters:
+
+**`default-region`**<br/>
+Decide on the default Rackspace *region*. See 
+[Rackspace regions](https://support.rackspace.com/how-to/about-regions/).
+or the output to `juju list-clouds`.
+
+**`auth-type`**<br/>
+This can be either 'access-key' or 'userpass'. Here, we'll use 'userpass'.
+
+**`username`**<br/>
+For the 'userpass' auth-type, this is the name used to log in to the
+[Rackspace cloud control panel](https://mycloud.rackspace.com).
+
+**`password`**<br/>
+For the 'userpass' auth-type, this is the password associated with the value of
+'username'.
+
+**`tenant-name`**<br/>
+This is the Rackspace account number. You can view it in the cloud control
+panel in the top-right corner (under your username).
+
+See `juju show-cloud rackspace`.
+
+### Add credentials
+
+Create a YAML file called, say, `credentials-rackspace.yaml` and provide the
+credential-related material. In this example, it would look like this:
+
+```yaml
+    rackspace:
+        default-credential: some_label
+        default-region: DFW
+        some_label:
+            auth-type: userpass
+            username: your_username
+            password: your_password
+            tenant-name: "123456"
+```
+
+Now add this to the system. At time of this writing, you must manually add the
+above block to the user-wide credentials file
+`~/.local/share/juju/credentials`. Put it under the 'credentials:' section.
+Therefore, if this is the sole block in that file, the entire file would appear
+as:
+
+```yaml
+credentials:
+    rackspace:
+        default-credential: some_label
+        default-region: DFW
+        some_label:
+            auth-type: userpass
+            username: your_username
+            password: your_password
+            tenant-name: "123456"
+```
+
+
+## Configuration
+
+Create a YAML file called, say, `~/config-rackspace.yaml` and provide the
+configuration-related material. In this example, it would look like this:
+
+```yaml
+logging-config: "<root>=DEBUG"
+agent-metadata-url: https://streams.canonical.com/juju/tools
+image-metadata-url: http://0315ec36e423bb7dba4b-3eabf88619cf7b7e6fc262bcf48df10b.r19.cf1.rackcdn.com/images
+image-stream: "released"
+default-series: "trusty"
+```
+
+!!! Note: A temporary URL provided by Rackspace has been used for
+'image-metadata-url' in the example configuration. This should not be needed in
+the long term.
+
+
+## Create controller
+
+Once the configuration and credentials information have been entered it is time
+to create the controller for Rackspace. See
+[Creating a controller](./controllers-creating.html).
+
+This will result in the controller being visible in the
+[Rackspace cloud control panel](https://mycloud.rackspace.com):
+
+![bootstrap machine 0 in Rackspace portal](./media/config-rackspace_portal-machine_0.png)
+
+
+## Additional notes
+
+See [General configuration options](https://jujucharms.com/docs/stable/config-general)
+for additional and advanced customization of your environment.

src/en/config-rackspace.md

@@ -0,0 +1,26 @@
+Title: Creating a Juju Controller
+TODO: Review again soon (created: March 2016)
+
+
+# Creating a controller
+
+Use the `juju bootstrap` command to create a controller (and model) for a given
+cloud provider:
+
+`juju bootstrap <controller name> <provider name> [--options]`
+
+See `juju help bootstrap` for details on this command or see the
+[command reference page](./commands.html#juju-bootstrap).
+
+
+## Examples
+
+**1.** The controller is for Rackspace. We call the controller 'controller-rackspace'
+and use `--upload-tools` to make the agent software available to our default
+series (specified in the provider's configuration):
+
+```bash
+juju bootstrap \
+	controller-rackspace rackspace \
+	--debug --upload-tools --config=~/config-rackspace.yaml
+```

src/en/controllers-creating.md

@@ -0,0 +1,40 @@
+Title: Juju Controllers
+TODO: Review again soon (created: March 2016)
+
+
+# Controllers
+
+A Juju *controller* is a machine that gets provisioned when the initial cloud
+provider *model* is created. The controller is therefore also called the
+*controller model* due to it being associated with that initial model.  It
+describes this model whose primary purpose is to run and manage the Juju API
+servers and underlying database.
+
+Once a controller model has been created you can define multiple models within
+that environment. See [Models](./models.html).
+
+When a controller is intended to be used by multiple people, it is recommended
+that Juju's [multi-user functionality](./juju-multiuser-environments.html) be
+leveraged.
+
+It is not possible to create a second controller model for the same cloud
+provider type (an error will be returned).
+
+Since a controller can now *host* multiple models, the destruction of a
+controller must be done with extreme caution as all models will be destroyed
+along with it.
+
+See [Creating a controller](./controllers-creating.html).
+
+
+## Related commands
+
+`juju bootstrap`<br/ >
+`juju list-controllers`<br/ >
+`juju show-controller`<br/ >
+`juju destroy-controller`<br/ >
+`juju kill-controller`<br/ >
+`juju switch`<br/ >
+`juju switch <controller>`
+
+See the [command reference page](./commands.html) for all Juju commands.

src/en/controllers.md

@@ -1,4 +1,5 @@
 Title: Juju and multi-user environments  
+TODO: Convert to 2.0 ASAP
 
 
 # Managing multi-user environments

src/en/juju-multiuser-environments.md

@@ -0,0 +1,30 @@
+Title: Defining a Juju Model
+TODO: Review again soon (created: March 2016)
+      Remove bug citation (1552469) when fixed and remove --config option from example command
+
+
+# Defining a model
+
+Use the `juju create-model` command to create a *hosted model* for a given
+cloud provider:
+
+`juju create-model [--options] <name> [key=[value] ...]`
+
+See `juju help create-model` for details on this command or see the
+[command reference page](./commands.html#juju-create-model).
+
+
+## Examples
+
+**1.** Create a model for the current controller. We call the model
+'rackspace-prod':
+
+!!! Note: Due to
+[LP #1552469](https://bugs.launchpad.net/juju-core/+bug/1552469) credentials
+already set during the creation of the controller model are not utilised
+automatically. You will need to create a 3-line file for these parameters:
+`username`, `password`, and `tenant-name` and then refer to it.
+
+```bash
+juju create-model --config=~/config-rackspace_creds.yaml rackspace-prod
+```

src/en/models-defining.md

@@ -0,0 +1,34 @@
+Title: Juju Models
+TODO: Review again soon (created: March 2016)
+
+
+# Models
+
+A Juju *model* is an environment associated with a cloud provider type. When
+the **initial** model is created a *controller* (see
+[Controllers](./controllers.html)) is provisioned along with it. It is not
+possible to create a second controller for the same cloud provider type (an
+error will be returned).
+
+Once the initial model has been created, multiple subsequent models can be
+created. Indeed, it is considered best practice to create additional models for
+deploying workloads, leaving the controller model for Juju's own
+infrastructure. Services can still be deployed to the controller model, but it
+is generally expected that these be solely for management and monitoring
+purposes (e.g. Nagios, Landscape).
+
+See [Defining a model](./models-defining.html).
+
+
+## Related commands
+
+`juju list-models`<br/ >
+`juju create-model`<br/ >
+`juju use-model`<br/ >
+`juju share-model`<br/ >
+`juju list-shares`<br/ >
+`juju destroy-model`<br/ >
+`juju switch`<br/ >
+`juju switch <model>`<br/ >
+
+See the [command reference page](./commands.html) for all Juju commands.

src/en/models.md

@@ -13,6 +13,7 @@
                       <li><a href="config-local.html">Local</a></li>
                       <li><a href="config-maas.html">MAAS (bare metal)</a></li>
                       <li><a href="config-openstack.html">OpenStack</a></li>
+                      <li><a href="config-rackspace.html">Rackspace</a></li>
                       <li><a href="config-scaleway.html">Scaleway</a></li>
                       <li><a href="config-vagrant.html">Vagrant</a></li>
                       <li><a href="config-vmware.html">VMWare vSphere</a></li>