mirror of https://github.com/apache/cloudstack.git
469 lines
20 KiB
Plaintext
469 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:
|
|
|
|
.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.abc.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
|
|
----
|
|
DEBUG [o.a.c.c.CloudianConnectorImpl] (qtp1809303591-31:ctx-6e8e8621 ctx-40a6e707) (logid:cd96b235) Attempting Cloudian SSO with user id=admn, group id=0
|
|
DEBUG [o.a.c.c.c.CloudianClient] (qtp1809303591-31:ctx-6e8e8621 ctx-40a6e707) (logid:cd96b235) Trying to find Cloudian user with id=admn and group id=0
|
|
INFO [c.c.a.ApiServer] (qtp1809303591-31:ctx-6e8e8621 ctx-40a6e707) (logid:cd96b235) Failed to find the requested resource and get valid response from Cloudian backend API call, please ask your administrator to diagnose and fix issues.
|
|
----
|
|
|
|
==== Other Failures
|
|
|
|
Connectivity problems with the Cloudian Admin server will probably be the
|
|
source of other problems logged. Below, we have logs from a timeout/connectivity
|
|
issue and incorrectly configured Basic Auth which causes authorization failures
|
|
and the connector fails to connect to the Cloudian Admin server.
|
|
|
|
.Admin Server connection problem due to time out
|
|
----
|
|
DEBUG [o.a.c.c.CloudianConnectorImpl] (qtp1809303591-372:ctx-a707eecc ctx-0e85865f) (logid:3efb32f0) Attempting Cloudian SSO with user id=753a62a8-978c-4bab-bfc4-b55ea2fda505, group id=16711de6-a806-11e7-b0a6-a434d91cd37e
|
|
DEBUG [o.a.c.c.c.CloudianClient] (qtp1809303591-372:ctx-a707eecc ctx-0e85865f) (logid:3efb32f0) Trying to find Cloudian user with id=753a62a8-978c-4bab-bfc4-b55ea2fda505 and group id=16711de6-a806-11e7-b0a6-a434d91cd37e
|
|
ERROR [o.a.c.c.c.CloudianClient] (qtp1809303591-372:ctx-a707eecc ctx-0e85865f) (logid:3efb32f0) Failed to list Cloudian user due to:
|
|
org.apache.http.conn.ConnectTimeoutException: Connect to admin.hs.yadav.xyz:19443 [admin.abc.xyz/10.5.1.6] failed: connect timed out
|
|
[...snipped...]
|
|
INFO [c.c.a.ApiServer] (qtp1638771699-28:ctx-e8b5b507 ctx-0632d279) (logid:94e8345e) Operation timed out, please try again.
|
|
----
|
|
|
|
.Admin Server Connection problem logging in as admin
|
|
----
|
|
DEBUG [o.a.c.c.CloudianConnectorImpl] (qtp1809303591-23:ctx-e9d61989 ctx-78760902) (logid:d3ea9e30) Attempting Cloudian SSO with user id=753a62a8-978c-4bab-bfc4-b55ea2fda505, group id=16711de6-a806-11e7-b0a6-a434d91cd37e
|
|
DEBUG [o.a.c.c.c.CloudianClient] (qtp1809303591-23:ctx-e9d61989 ctx-78760902) (logid:d3ea9e30) Trying to find Cloudian user with id=753a62a8-978c-4bab-bfc4-b55ea2fda505 and group id=16711de6-a806-11e7-b0a6-a434d91cd37e
|
|
ERROR [o.a.c.c.c.CloudianClient] (qtp1809303591-23:ctx-e9d61989 ctx-78760902) (logid:d3ea9e30) Cloudian backend API authentication failed, please check Cloudian configuration. Admin auth principal=[principal: admin], password=incorrect-password, API url=https://admin.abc.xyz:19443
|
|
INFO [c.c.a.ApiServer] (qtp1809303591-23:ctx-e9d61989 ctx-78760902) (logid:d3ea9e30) Cloudian backend API call unauthorized, please ask your administrator to fix integration issues.
|
|
----
|
|
|
|
== 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 global settings 'cloudian.cmc.admin.user' point to the correct
|
|
Cloudian (admin) user?
|
|
* 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
|
|
'cloudian.sso.key'?
|
|
* 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 'cloudian.cmc.host', 'cloudian.cmc.port' and 'cloudian.cmc.protocol'
|
|
configured in the CloudStack global settings.
|
|
* 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?
|
|
* Try access the admin server host directly from the problem users host using
|
|
the configured 'cloudian.admin.host', 'cloudian.admin.port' and
|
|
'cloudian.admin.protocol' configured in the CloudStack global settings. Check
|
|
the configured auth settings 'cloudian.admin.user' and
|
|
'cloudian.admin.password'.
|
|
* If you're experiencing timeout issues, trying changing the API timeout value
|
|
defined in 'cloudian.api.request.timeout' global setting.
|
|
* Look for errors in the admin log file /var/log/cloudian/cloudian-admin.log.
|
|
|
|
''''
|
|
|
|
_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._
|