mirror of https://github.com/apache/cloudstack.git
530 lines
20 KiB
Plaintext
530 lines
20 KiB
Plaintext
image::images/cloudian_big_logo.png[align="center"]
|
|
|
|
= HyperStore Connect for CloudStack Configuration Guide
|
|
:Copyright: Copyright (c) 2013-2017 Cloudian KK. All rights reserved.
|
|
:Date: July 2016
|
|
:Revision: {cpver}-{hsver}
|
|
|
|
// NOTE: This text document uses asciidoc formatting and was used to
|
|
// generate the HTML document of the same name. If you are reading
|
|
// this you may find reading the HTML document in a browser easier.
|
|
|
|
== Overview
|
|
This document describes how to install and configure the HyperStore
|
|
Connect for CloudStack {cpver}. The Connector integrates
|
|
Cloudian S3 Storage into the CloudStack Management GUI and allows
|
|
administrators to easily give their CloudStack users access to and
|
|
manage their own S3 storage areas.
|
|
|
|
=== A Note about Cloudian as CloudStack Secondary Storage
|
|
CloudStack {cpver} can utilize Cloudian as S3 Secondary Storage out of the
|
|
box with no modifications. This Connector is not required for secondary
|
|
storage. There are some pointers to
|
|
link:secondary_storage.html[Configuring Secondary Storage]
|
|
in a separate guide.
|
|
|
|
=== HyperStore Connect for CloudStack
|
|
The connector comes in the form of an RPM package which is installed on
|
|
a running CloudStack Management server. When you first install the RPM,
|
|
the connector is disabled. You will first need to configure the connector
|
|
and then enable it as described in this document.
|
|
|
|
Installing the Connector package on top of the CloudStack Management
|
|
server has the following integration points:
|
|
|
|
==== Cloudian Storage GUI and Single-Sign-On Integration
|
|
The package adds a 'Cloudian Storage' button to the CloudStack GUI. This
|
|
button is available for all users on the bottom left of the menu.
|
|
|
|
image::images/cloudian_button.png["Cloudian S3 Storage Button"]
|
|
|
|
When a user clicks this button, a new window or tab (depending
|
|
on the web browser preferences) is opened for the HyperStore CMC GUI.
|
|
The CloudStack user is automatically logged in to CMC as the
|
|
correctly <<mapping,mapped HyperStore user>> using Single-Sign-On (SSO).
|
|
|
|
Single-Sign-On is a technique where CloudStack and HyperStore are
|
|
configured to trust each other. This is achieved by configuring both
|
|
HyperStore and the CloudStack connector with the same 'SSO Shared Key'.
|
|
The CloudStack connector creates a special login URL for CMC which
|
|
it signs using this shared key. Upon receiving the special signed login
|
|
URL, CMC validates the request by comparing the signature to its own
|
|
copy of the shared key and the user is automatically logged in.
|
|
|
|
anchor:mapping[]
|
|
|
|
==== User Mapping and Automatic Provisioning
|
|
CloudStack domains are mapped to Cloudian Groups. CloudStack Accounts
|
|
within those domains are mapped to Cloudian users. The Cloudian user is
|
|
created on demand if it doesn't already exist when the CloudStack user
|
|
accesses CMC through the 'Cloudian Storage' Button.
|
|
|
|
.CloudStack to Cloudian Mapping
|
|
[options="header",cols="2,3",width="60%"]
|
|
|======================
|
|
|CloudStack Entity|Equivalent Cloudian Entity
|
|
|Domain|Group
|
|
|Account|User
|
|
|User|Same as Account
|
|
|======================
|
|
|
|
NOTE: Adding groups or users directly through Cloudian does not add
|
|
corresponding CloudStack Domains or Accounts. The integration is driven
|
|
completely from the CloudStack side.
|
|
|
|
==== Special Admin User Mapping
|
|
The special CloudStack admin and Domain Admin accounts are mapped to a
|
|
special HyperStore Admin user account which defaults to the user id 'admin'. As
|
|
the admin user on HyperStore is configurable, there is a configuration option to control
|
|
this mapping. This mapping dictates which HyperStore user is automatically
|
|
logged in using SSO when the CloudStack admin user clicks "Cloudian Storage".
|
|
|
|
NOTE: The Cloudian Admin user default is called 'admin'. Older versions of Cloudian
|
|
used to use 'admin@cloudian.com'.
|
|
|
|
== Requirements
|
|
|
|
=== Package Requirement
|
|
.Required Software Packages
|
|
[options="header",cols="4,10",subs="attributes"]
|
|
|======================
|
|
|Software Package|Description
|
|
|Cloudian 6.0 or greater|Installed/configured and running.
|
|
|CloudStack {cpver}|Installed/configured and running
|
|
|Java 7|The Connector RPM requires at least Java 1.7.
|
|
|======================
|
|
|
|
=== DNS Name Resolution Requirement
|
|
The CloudStack Management Server will need to be access the Cloudian
|
|
Admin Service. The Cloudian admin service is commonly run on the same
|
|
nodes as your Cloudian S3 servers. The Admin Service is used to
|
|
provision and deprovision Cloudian users automatically by CloudStack.
|
|
|
|
Additionally, your CloudStack users will need to be able to resolve
|
|
your CMC server hostname on their desktops so that they can access CMC.
|
|
|
|
.Example Domain Names that should Resolve
|
|
[options="header",cols="6,5,8"]
|
|
|======================
|
|
|Resolvable Name|Required By|Description
|
|
|mgmt1.fluffy-cloud.com|User's Browser|CloudStack Management Server
|
|
|cmc.fluffy-cloud.com|User's Browser|Cloudian CMC
|
|
|s3-admin.fluffy-cloud.com|Management Server|Cloudian Admin Server
|
|
|======================
|
|
|
|
.Use the host command to test a name resolves in DNS:
|
|
----
|
|
$ host s3-admin.fluffy-cloud.com
|
|
s3-admin.fluffy-cloud.com has address X.X.X.X
|
|
----
|
|
|
|
anchor:install[]
|
|
|
|
== Installing the Connector
|
|
This section describes first time installation of the Connector.
|
|
If you are upgrading please see the section
|
|
<<upgrade,Upgrading the Connector>> below.
|
|
|
|
NOTE: Installing the Connector RPM does not immediately enable it.
|
|
After installation you will need some basic configuration and then manually
|
|
enable the connector. You can also subsequently disable or uninstall it at
|
|
any time.
|
|
|
|
=== Enable SSO on Cloudian CMC
|
|
Cloudian ships with SSO disabled by default. You will need to enable it on
|
|
each CMC server. Additionally you will need to choose a unique SSO shared key
|
|
that you will also configure in the CloudStack connector further below.
|
|
|
|
.Edit Puppet config to enable SSO on all CMC servers
|
|
[subs="quotes"]
|
|
----
|
|
# vi /etc/cloudian-[red]#[version]#-puppet/modules/cmc/templates/mts-ui.properties.erb
|
|
sso.enabled=[red]#true#
|
|
sso.shared.key=[red]#YourSecretKeyHere#
|
|
----
|
|
|
|
TIP: Once configured in Puppet, you should roll out out to each CMC server
|
|
and restart CMC services. Please refer to the HyperStore documentation for
|
|
how to do this.
|
|
|
|
=== Install the Connector RPM
|
|
The Connector RPM should be installed, configured and enabled on each
|
|
CloudStack management server in your network. After installation, restart
|
|
the CloudStack management server(s).
|
|
|
|
.Install using yum (easily resolves dependencies)
|
|
[subs="attributes, quotes"]
|
|
----
|
|
# yum install ./cloudian-cloudstack-{cpver}_{hsver}-{rc}.noarch.rpm
|
|
Loaded plugins: fastestmirror
|
|
Examining ./cloudian-cloudstack-{cpver}_{hsver}-{rc}.noarch.rpm: cloudian-cloudstack-{cpver}_{hsver}-{rc}.noarch
|
|
Marking ./cloudian-cloudstack-{cpver}_{hsver}-{rc}.noarch.rpm to be installed
|
|
Resolving Dependencies
|
|
--> Running transaction check
|
|
---> Package cloudian-cloudstack.noarch 0:{cpver}_{hsver}-{rc} will be installed
|
|
--> Finished Dependency Resolution
|
|
|
|
Dependencies Resolved
|
|
[...snipped...]
|
|
|
|
Install 1 Package
|
|
|
|
Total size: 531 k
|
|
Installed size: 531 k
|
|
Is this ok [y/d/N]: y
|
|
Downloading packages:
|
|
Running transaction check
|
|
Running transaction test
|
|
Transaction test succeeded
|
|
Running transaction
|
|
Installing : cloudian-cloudstack-{cpver}_{hsver}-{rc}.noarch 1/1
|
|
=====================================================================
|
|
[red]#Restart the CloudStack management server to load the Cloudian Connector plugin#
|
|
=====================================================================
|
|
Verifying : cloudian-cloudstack-{cpver}_{hsver}-{rc}.noarch 1/1
|
|
|
|
Installed:
|
|
cloudian-cloudstack.noarch 0:{cpver}_{hsver}-{rc}
|
|
|
|
Complete!
|
|
|
|
# systemctl restart cloudstack-management
|
|
----
|
|
|
|
TIP: When the connector RPM is installed for the first time
|
|
it suggests some next steps (marked in red above). We will follow those
|
|
steps below.
|
|
|
|
anchor:configure[]
|
|
|
|
=== Configure the Connector
|
|
|
|
The main way to configure, enable and disable the connector is using
|
|
the CloudStack global setting. The global settings provide an easy
|
|
way to configure the connector and synchronize setting across multiple
|
|
management server(s).
|
|
|
|
TIP: Except for the configuration to enable/disable the connector, changing the
|
|
configuration does not require restarting the management server(s).
|
|
|
|
NOTE: The new re-implementation of the connector deprecates the use of
|
|
connector.properties file, used by previous Cloudian connector versions.
|
|
|
|
.Connector specific Global Settings
|
|
[options="header",cols="3,10"]
|
|
|======================
|
|
|Property|Description
|
|
|
|
|cloudian.connector.enabled|The setting to enable/disable the Cloudian
|
|
Connector. When set to true, this enables the connector. By default, this is
|
|
false.
|
|
|
|
|cloudian.admin.host|The hostname of the Cloudian Admin Server. The Admin server is
|
|
usually running on the same server as the S3 servers. If you have a load
|
|
balanced address you can use that.
|
|
|
|
|cloudian.admin.port|The port the Cloudian Admin Server is listening on. This is usually
|
|
port 19443 for most default installations of Cloudian that are using a secure
|
|
(https) admin service or alternatively 18081 for insecure (http) connections.
|
|
|
|
|cloudian.admin.protocol|The protocol to use to access the Admin Server. This should match
|
|
the setting of the 'cloudian.admin.port' and should be either 'http' or 'https'.
|
|
|
|
|cloudian.validate.ssl|If the admin server is using https and has a valid SSL certificate
|
|
set this to 'true' to ensure you are connecting in a secure manner which validates
|
|
the certificate each time.
|
|
|
|
|cloudian.admin.user|Basic Authentication user name for the Cloudian Admin server. If
|
|
you have not enabled Basic Authentication any value is ok as the server will
|
|
ignore it.
|
|
|
|
|cloudian.admin.password|Basic Authentication password for the Cloudian Admin server. If
|
|
you have not enabled Basic Authentication any value is ok as the server will
|
|
ignore it.
|
|
|
|
|cloudian.api.request.timeout|The timeout in seconds to be used by the Cloudian
|
|
client when making admin API requests.
|
|
|
|
|cloudian.cmc.admin.user|The user id of the Cloudian administrator that you
|
|
would like to map to the CloudStack admin user. This is only required for
|
|
Single-Sign-On for the CloudStack admin user.
|
|
|
|
|cloudian.cmc.host|The hostname of the Cloudian CMC Server. This should be resolvable
|
|
on the hosts where your CloudStack users will run their browsers.
|
|
|
|
|cloudian.cmc.port|The port used by CMC. Usually this is 8443 if you are using HTTPS or
|
|
port 8080 if you are using HTTP.
|
|
|
|
|cloudian.cmc.protocol|The protocol for users to use to access CMC. This should match
|
|
the setting of the 'cloudian.cmc.port' and should be either 'http' or 'https'.
|
|
|
|
|cloudian.sso.key|This is a special shared secret between Cloudian and
|
|
CloudStack and it must be configured to the same value as-is configured
|
|
in Cloudian CMC. You can find the current value in your CMC configuration
|
|
file: /etc/cloudian-[red]#[version]#-puppet/modules/cmc/templates/mts-ui.properties.erb
|
|
|======================
|
|
|
|
=== Enable the Connector
|
|
|
|
Enabling the connector is the last step. You should have already installed
|
|
the RPM and configured it as per above before you enable it.
|
|
|
|
Log into the CloudStack UI as root admin, go to "Global Settings". Search for
|
|
'cloudian.connector.enabled' and set it to true and restart each of the
|
|
management server(s) to reload the connector.
|
|
|
|
.Enabling restarts the management server
|
|
----
|
|
# systemctl restart cloudstack-management
|
|
----
|
|
|
|
anchor:upgrade[]
|
|
|
|
== Upgrading
|
|
|
|
=== Upgrading the Connector
|
|
The Cloudian connector is easy to upgrade using the standard RPM
|
|
upgrade functionality. Any configuration changes you made to the
|
|
existing version will carry over automatically to the new version.
|
|
|
|
----
|
|
# yum upgrade ./cloudian-cloudstack-newpackage.noarch.rpm
|
|
----
|
|
|
|
If the new connector is not compatible with the existing CloudStack
|
|
version, you will have to upgrade CloudStack first to use it.
|
|
|
|
=== Upgrading CloudStack
|
|
Before upgrading CloudStack, we recommend removing the Connector
|
|
rpm by following the <<uninstall,Uninstalling the Connector>> section.
|
|
After you have upgraded CloudStack, install a new connector for that version.
|
|
|
|
When you uninstall the connector all created Domain/Account mappings remain
|
|
on Cloudian so simply re-enabling a new connector will work.
|
|
|
|
anchor:uninstall[]
|
|
|
|
== Uninstalling the Connector
|
|
If you wish to uninstall the connector you simply remove the RPM and restart
|
|
each of the management server(s) and clean up.
|
|
|
|
.Uninstall the Connector RPM
|
|
[subs="attributes, quotes"]
|
|
----
|
|
# yum remove cloudian-cloudstack.noarch
|
|
Loaded plugins: fastestmirror
|
|
Resolving Dependencies
|
|
--> Running transaction check
|
|
---> Package cloudian-cloudstack.noarch 0:{cpver}_{hsver}-{rc} will be erased
|
|
--> Finished Dependency Resolution
|
|
[...snipped...]
|
|
|
|
Installed size: 531 k
|
|
Is this ok [y/N]: y
|
|
Downloading packages:
|
|
Running transaction check
|
|
Running transaction test
|
|
Transaction test succeeded
|
|
Running transaction
|
|
Erasing : cloudian-cloudstack-{cpver}_{hsver}-{rc}.noarch 1/1
|
|
[red]#Restart the CloudStack management server to unload the Cloudian Connector plugin#
|
|
Verifying : cloudian-cloudstack-{cpver}_{hsver}-{rc}.noarch 1/1
|
|
|
|
Removed:
|
|
cloudian-cloudstack.noarch 0:{cpver}_{hsver}-{rc}
|
|
Complete!
|
|
|
|
# systemctl restart cloudstack-management
|
|
----
|
|
|
|
anchor:admin[]
|
|
|
|
== Connector Administration
|
|
The current connector is quite simple and there is not so much to
|
|
configure or administrate. See the section that explains how to configure
|
|
the connector for details.
|
|
|
|
=== Connector Logs
|
|
|
|
The connector runs as a plugin of the CloudStack Management server. Logging
|
|
is therefore integrated with the Management Server's log files. Logging
|
|
is only output when the connector is enabled and appropriate logging
|
|
configuration has been setup, for example:
|
|
|
|
----
|
|
# cat /etc/cloudstack/management/log4j-cloud.xml
|
|
|
|
[...snipped...]
|
|
<category name="org.apache.cloudstack.cloudian">
|
|
<priority value="DEBUG"/>
|
|
</category>
|
|
[...snipped...]
|
|
----
|
|
|
|
.Connector Log File
|
|
----
|
|
view /var/log/cloudstack/management/management-server.log
|
|
----
|
|
|
|
==== Example 1 - Start Up Messages
|
|
|
|
The following messages are normally logged when the connector is enabled
|
|
and the CloudStack Management Server is started up.
|
|
|
|
.Example Start up Messages:
|
|
----
|
|
INFO [o.a.c.s.m.m.i.DefaultModuleDefinitionSet] (localhost-startStop-1:null) (logid:) Module Hierarchy: cloudian
|
|
...
|
|
INFO [o.a.c.s.m.m.i.DefaultModuleDefinitionSet] (localhost-startStop-1:null) (logid:) Loaded module context [cloudian] in 272 ms
|
|
DEBUG [c.c.a.ApiServer] (localhost-startStop-1:null) (logid:) Discovered plugin CloudianConnectorImpl
|
|
INFO [o.a.c.s.m.m.i.DefaultModuleDefinitionSet] (localhost-startStop-1:null) (logid:) Starting module [cloudian]
|
|
...
|
|
DEBUG [c.c.c.CloudianConnectorImpl] (localhost-startStop-1:null) (logid:) Cloudian connector is enabled, completed configuration, integration is ready. Cloudian admin host:admin.hs.yadav.xyz, port:19443
|
|
----
|
|
|
|
==== SSO Failures
|
|
|
|
The following are a few examples of logging when your configuration is
|
|
incorrect. In this case the Cloudian admin user has been incorrectly mapped
|
|
to an invalid user id. i.e., it should have been mapped to 'admin'
|
|
but there was a typo and it was mapped to 'admn'.
|
|
|
|
.Example of an SSO Failure
|
|
----
|
|
[c.c.c.CloudianIntegrationServlet] (catalina-exec-23:null) EndUser: *admin|b3ebfd90-d73d-11e3-9a7c-002170530220|4069e3d2-d73d-11e3-9a7c-002170530220
|
|
[c.c.c.CloudianIntegrationServlet] (catalina-exec-23:null) Mapping admin to 'admn'
|
|
[c.c.c.CloudianIntegrationServlet] (catalina-exec-23:null) SSO login failed for admn user. Check config.
|
|
[c.c.c.CloudianIntegrationServlet] (catalina-exec-23:null) SSO login failed. Removing any existing SSO Cookie.
|
|
----
|
|
|
|
==== Other Failures
|
|
|
|
Connectivity problems with the Cloudian Admin server will probably be the
|
|
source of other problems logged. Below, we have incorrectly configured
|
|
Basic Auth and the connector is unable to connect to the Cloudian Admin server.
|
|
|
|
.Admin Server Connection problem logging in as admin
|
|
----
|
|
[c.c.c.CloudianIntegrationServlet] (catalina-exec-17:null) EndUser: *admin|b3ebfd90-d73d-11e3-9a7c-002170530220|4069e3d2-d73d-11e3-9a7c-002170530220
|
|
[c.c.c.CloudianIntegrationServlet] (catalina-exec-17:null) Mapping admin to 'admin'
|
|
[o.a.c.h.a.AuthChallengeProcessor] (catalina-exec-17:null) basic authentication scheme selected
|
|
[o.a.c.h.HttpMethodDirector] (catalina-exec-17:null) Failure authenticating with BASIC 'CloudianAdmin'@admin.cloudian.com:18081
|
|
[c.c.c.CloudianIntegrationServlet] (catalina-exec-17:null) SSO login request failed for '*admin|b3ebfd90-d73d-11e3-9a7c-002170530220|4069e3d2-d73d-11e3-9a7c-002170530220'
|
|
----
|
|
|
|
== Trouble Shooting
|
|
|
|
Most of the trouble you may run into will be configuration related.
|
|
|
|
. SSO Login Fails
|
|
+
|
|
There are a few things which can go wrong for SSO. Here are the
|
|
most common problems and things to check.
|
|
+
|
|
.SSO Check List
|
|
* Does the mapping of adminUserId point to the correct Cloudian user
|
|
in the <<properties,Connector Properties File>>?
|
|
* Is SSO configured and enabled on Cloudian HyperStore CMC?
|
|
* Check for errors in the CMC log file.
|
|
* Are both CloudStack and HyperStore CMC configured with the same
|
|
ssoSharedKey?
|
|
* Try running 'cloudian-cloudstack.sh configure' which runs through
|
|
the connectivity settings.
|
|
* Check the /var/log/cloudstack/management/management-server.log file and
|
|
search for errors relating to SSO.
|
|
* Try access the CMC host directly from the problem users host using
|
|
the configured cmcHost, cmcPort and cmcProtocol configured in the
|
|
<<properties,Connector Properties File>>.
|
|
* If you log out of the management server and log in again, does
|
|
the 'Cloudian Storage' button work?
|
|
|
|
. Adding/Deleting Domains or Accounts fails
|
|
+
|
|
These operations use the Cloudian Admin Server. Its likely that something
|
|
has changed with the connection or the admin server is down?
|
|
+
|
|
.Admin Check List
|
|
* Is the admin server alive and listening?
|
|
* Run the 'cloudian-cloudstack.sh configure' script as it tests the connection
|
|
using the configured properties. This will usually identify the problem.
|
|
* Look for errors in the admin log file /var/log/cloudian/cloudian-admin.log.
|
|
|
|
. CloudStack Patching
|
|
+
|
|
The enable and disable options of the 'cloudian-cloudstack.sh' script
|
|
usually manages all the patching for you. The following shows you
|
|
the normal clean state of the cloudstack-management installation. Note
|
|
though that the output will vary slightly depending on your installation
|
|
and what you have changed.
|
|
+
|
|
.With Connector not installed
|
|
----
|
|
# rpm -qV cloudstack-management
|
|
S.5....T. c /etc/cloudstack/management/db.properties
|
|
.......T. /var/run/cloudstack-management.pid
|
|
----
|
|
+
|
|
.With Connector installed
|
|
----
|
|
# rpm -qV cloudstack-management
|
|
|
|
# rpm -qV cloudstack-management
|
|
S.5....T. c /etc/cloudstack/management/db.properties
|
|
S.5....T. /usr/share/cloudstack-management/webapps/client/plugins/plugins.js
|
|
S.5....T. /usr/share/cloudstack-management/webapps/client/plugins/plugins.js.gz
|
|
.......T. /var/run/cloudstack-management.pid
|
|
----
|
|
|
|
. Fail-safe botched scripts recovery
|
|
+
|
|
This procedure is probably not required but is noted here as a
|
|
fail-safe recovery method if things fail when you for update
|
|
packages or otherwise and unexpected things happen.
|
|
+
|
|
RPM is luckily a great way to manage application files on a machine
|
|
as the original RPM contains everything you need to recover and
|
|
re-install the original state of the CloudStack Application. If
|
|
things don't work for some reason and you want to back things out
|
|
, but disable doesn't work for some reason, you can do the following:
|
|
+
|
|
.First, try uninstall the connector
|
|
----
|
|
# rpm -e cloudian-cloudplatform
|
|
----
|
|
+
|
|
If that fails to uninstall for some reason you can try to uninstall
|
|
it using the '--noscripts' option as below:
|
|
+
|
|
.Optionally, force uninstall the connector (if uninstall fails)
|
|
----
|
|
# rpm -e --noscripts cloudian-cloudplatform
|
|
----
|
|
+
|
|
Next re-install (without uninstalling) CloudStack. Re-install
|
|
will keep any configuration files belonging to CloudStack intact
|
|
and just gets the application files back to its initial installation
|
|
state.
|
|
+
|
|
[subs="attributes"]
|
|
----
|
|
# yum reinstall ./CloudStack-{cpver}.0.0-rhel/cloudstack-management-{cpver}.0.0-1.el6.x86_64.rpm
|
|
----
|
|
+
|
|
At this point you can install, configure and enable the connector again.
|
|
|
|
''''
|
|
|
|
_Confidentiality Notice_
|
|
|
|
_The information contained in this document is confidential to, and is the
|
|
intellectual property of, Cloudian, Inc. Neither this document nor any
|
|
information contained herein may be (1) used in any manner other than to
|
|
support the use of Cloudian software in accordance with a valid license
|
|
obtained from Cloudian, Inc, or (2) reproduced, disclosed or otherwise
|
|
provided to others under any circumstances, without the prior written
|
|
permission of Cloudian, Inc. Without limiting the foregoing, use of any
|
|
information contained in this document in connection with the development
|
|
of a product or service that may be competitive with Cloudian software
|
|
is strictly prohibited. Any permitted reproduction of this document or
|
|
any portion hereof must be accompanied by this legend._
|