Skip to content

Commit e84485b

Browse files
author
Ed Balduf
committed
Switch to formatted README
1 parent 733c1b9 commit e84485b

2 files changed

Lines changed: 144 additions & 14 deletions

File tree

‎README‎

Lines changed: 0 additions & 14 deletions
This file was deleted.

‎README.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
## SolidFire Puppet
2+
3+
#### Table of Contents
4+
5+
1. [Disclaimer](#disclaimer)
6+
2. [Overview](#overview)
7+
3. [Provider Description - What the provider does and why.](#description)
8+
4. Setup - The basics
9+
* [Connection to SolidFire](#connection)
10+
5. Usage - Configuration options
11+
* [Puppet device](#device)
12+
* [Puppet agent](#agent)
13+
* [Puppet apply](#apply)
14+
6. [Limitations - OS compatibility, etc.](#limitations)
15+
7. [Development - Guide for contributing to the module](#development)
16+
17+
## <a name="disclaimer"></a> Disclaimer
18+
19+
This provider is written as best effort and provides no warranty expressed or
20+
implied. Please contact the author(s) via the SolidFire developer portal on
21+
the [Puppet forum](http://developer.solidfire.com/forum/puppet) if you have
22+
questions about this module before running or modifying.
23+
24+
## <a name="overview"></a> Overview
25+
26+
The SolidFire provider allows you to provision volumes on a SolidFire cluster
27+
from either a puppet client or a puppet device proxy host. The provider also
28+
provides facts and resource lists from SolidFire clusters. The provider has
29+
been developed against CentOS 7.1 using Puppet-3.8.4. At this stage testiing
30+
is compeletely manual.
31+
32+
## <a name="description"></a> Provider Description
33+
34+
Using the solidfire\_account, solidfire\_volume and solidfire\_vag types, one
35+
can quickly provision remote storage and attach it via iSCSI (and FC) from a
36+
SolidFire cluster to a client.
37+
38+
The provider utilizes the robust API (json-rpc) available on the SolidFire
39+
storage clusters to remotely provision the necessary resources.
40+
41+
## Basics
42+
43+
### <a name="connection"></a> Connection to SolidFire
44+
45+
A connection to a SolidFire cluster is via the Management Virtual IP (MVIP)
46+
address and through use of a Cluster Admin account. A connection string is
47+
needed to inform the providers how to connect. The providers can get the
48+
connection string from various locations (see Usage below) but the three
49+
pieces of information necessary are 1) Cluster Admin account name 2) Cluster
50+
admin password and 3) MVIP address or dns name.
51+
52+
IF multiple connection options are provider to the provider, it will use them
53+
in the following order:
54+
55+
1. Existing Connection
56+
2. Facter supplied url
57+
3. User supplied url
58+
4. User supplied login, password and mvip
59+
60+
## Usage
61+
62+
### <a name="device"></a> Puppet device
63+
64+
The Puppet Network Device system is a way to configure devices' (switches,
65+
routers, storage) which do not have the ability to run puppet agent on
66+
the devices. The device application acts as a smart proxy between the Puppet
67+
Master and the managed network device. To do this, puppet device will
68+
sequentially connects to the master on behalf of the managed network device
69+
and will ask for a catalog (a catalog containing only network device
70+
resources). It will then apply this catalog to the said device by translating
71+
the resources to orders the network device understands. Puppet device will
72+
then report back to the master for any changes and failures as a standard node.
73+
74+
The SolidFire providers are designe to work with the puppet device concept and
75+
in this case will retreive their connection information from the _url_ given
76+
in the device.conf file, ane Example of which is shown below:
77+
78+
[cluster1.solidfire.com]
79+
type Solidfire
80+
url https://admin:password@cluster1.solidfire.com
81+
82+
In the case of Puppet Device connection to the SolidFire is from the machine
83+
running 'device' only.
84+
85+
### <a name="agent"></a> Puppet agent
86+
87+
Puppet agent is the client/slave side of the puppet master/slave relationship.
88+
In the case of puppet agent the connection inforation needs to be included in
89+
the manifest supplied to the agenet from the master _or_ it could be included
90+
in a custome Facter built and passed to the client. The connection string may
91+
be supplied as a URL or as the 3 independent pieces of information (login,
92+
password and mvip), see example manifests for details.
93+
94+
In the case of Puppet Agent, connections to the SolidFire array will be
95+
initiatied from every machine which utilizes the SolidFire puppet module this
96+
way. This may be of security concern for some folks. This method however has
97+
the most usefullness, since one can allocate a volume and mount it in a single
98+
manifest with proper depenedencies.
99+
100+
### <a name="apply"></a> Puppet apply
101+
102+
Puppet apply is the client only application of a local manifest. Puppet apply
103+
is supported similar to puppet agent by the SolidFire providers. With puppet
104+
apply it is easy to pass a connection string through facter using evironment
105+
variables and therefore this is the best method to use the providers to show
106+
resources. As an example the following command will run a manifest supplied on
107+
the command line:
108+
109+
FACTER\_url=https://admin:password@cluster1.solidfire.com puppet apply \
110+
-e "solidfire\_account { 'test-account': ensure => 'present'}"
111+
112+
And this code will show the complete list of Volume configured on a SolidFire
113+
cluster:
114+
115+
FACTER\_url=https://admin:password@cluster1.solidfire.com puppet \
116+
resource solidfire_volume
117+
118+
119+
## <a name="Limitations"></a> Limitations
120+
121+
Puppet as a whole expects to be able to define everything about an
122+
environment, and the concept of a smart appliance is foreign to it. Therefore
123+
some aspects of managing remote storage do not work well with Puppet. For
124+
example, the SolidFire array creates a new volume ID for every volume, and
125+
uses that as part of the IQN identifier for iSCSI. The SolidFire API and
126+
provider fetch both the Volume ID and IQN, but puppet has no mechanism for
127+
passing that dynamically created ID into the remainder of a manifest and
128+
puppet cannot dictate the Volume ID as it is a critical part of how SolidFire
129+
functions.
130+
131+
We have choosen in our example manifest to utilize Volume Access Groups as an
132+
example work around the above limitation. We have left it as an excecise to
133+
the users to find other creative work arounds. Please see the
134+
[development](#development) section below to provide feedback and improved options.
135+
136+
The providers today use version 7.0 of the SolidFire API, which introduces
137+
some additional compatibility, but also is slightly less efficient in some of
138+
it's operations.
139+
140+
## <a name="development"></a> Development
141+
142+
Please see the [Puppet forum](http://developer.solidfire.com/forum/puppet) on
143+
<https://developer.solidfire.com> for any issues (best effort help),
144+
discussion, advice or if you have a contribution.

0 commit comments

Comments
 (0)