Bug 1413878 - section '6.2 Managing Volumes using Heketi' needs a revamp
Summary: section '6.2 Managing Volumes using Heketi' needs a revamp
Keywords:
Status: CLOSED EOL
Alias: None
Product: Red Hat Gluster Storage
Classification: Red Hat Storage
Component: doc-Administration_Guide
Version: rhgs-3.1
Hardware: Unspecified
OS: Unspecified
unspecified
high
Target Milestone: ---
: RHGS 3.1.3 Async
Assignee: storage-doc
QA Contact: krishnaram Karthick
URL:
Whiteboard:
: 1361096 (view as bug list)
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-01-17 08:35 UTC by krishnaram Karthick
Modified: 2023-09-14 03:37 UTC (History)
9 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2020-04-21 14:51:40 UTC
Embargoed:


Attachments (Terms of Use)

Description krishnaram Karthick 2017-01-17 08:35:14 UTC
Document URL: 
https://access.redhat.com/documentation/en-US/Red_Hat_Storage/3.1/html/Administration_Guide/ch06s02.html

Section Number and Name: 6.2. Managing Volumes using Heketi

Describe the issue: 

There are multiple issues with the documentation. I've listed them here. Doc team may need to work with dev to resolve few issues.

Issue # 1:
 ⁠
6.2.3. Starting the Heketi Server:

Generate the passphrase-less SSH keys for the nodes which are going to be part of the trusted storage pool by running the following command:
ssh-keygen -f id_rsa -t rsa -N ''

The idea is to generate a public key for heketi user and heketi public key should be shared across hosts for passwordless ssh. Hence, the command has to be,

ssh-keygen -f /etc/heketi/heketi_key -t rsa -N ''

Issue # 2:

 Set up password-less SSH access between Heketi and the Red Hat Gluster Storage servers by running the following command:

# ssh-copy-id -i root@server
 
heketi's public key has to be used, so the command has to be..

ssh-copy-id -i /etc/heketi/heketi_key.pub root@server

Issue # 3:

configuration of /etc/heketi/heketi.json is very critical to setup heketi successfully. Mere explanation wouldn't help here. A proper example file and explanation about what are the mandatory parameters and optional parameters has to be documented.

Issue # 4:

owner and group permissions for heketi keys needs to be updated. This step is missing.

chown heketi:heketi /etc/heketi/heketi_key* 

Issue # 5:

section 6.2.3.2 Verifying the Configuration has to be done after setting up the cluster or at least adding the nodes. Please move this as 6.2.4.3

Issue # 6:

All the cli options should have '--' instead of '-'. for ex,

heketi-cli load -json=topology_libvirt.json

has to be,

heketi-cli load --json=topology_libvirt.json

Please change this throughout the section 6.2

Issue # 7:

For more information regarding the Heketi API, see Heketi API. 

This points to external github link, this has to be changed. I'm not sure if we have a downstream doc describing about heketi api. Please check with dev to confirm this.

Issue # 8:

SSH Access

    SSH user and public key must be setup on the node.
    SSH user must have password-less sudo. 

Please note that, SSH user would be 'heketi'. Please check with dev about the details.

Issue # 9:

Disks registered with Heketi must be in the raw format

should be,

Disks to be registered with Heketi must be in the raw format

Issue # 10:

After installing Red Hat Gluster Storage 3.1.2,

should be,

After installing Red Hat Gluster Storage 3.1.3,

Issue # 11:

(non-blocker comment)

For more information about subscribing to the required channels and installing Red Hat Gluster Storage, see the Red Hat Gluster Storage Installation Guide

It would be nice to have links to the doc rather than just providing the name of the doc

Issue # 12:

section 6.2.3 - Example on how to setup advanced configuration should be provided.

Issue # 13:

A note has to be provided under 6.2.3.1, that heketi logs are not persisted. Possibly, provide a way to persist heketi logs.

Issue # 14:

A short description of zones in 6.2.4.2 should be provided. The first paragraph describes what a failure domain is, but we'll have to explain that failure domain is represented as zone in topology file.

Issue # 15:

Location of sample topology file must be provided in section 6.2.4.2. The sample file is placed here --> /usr/share/heketi/topology-sample.json

Issue # 16:

The size provided while creating, expanding a volume is denoted in Gb. 

Issue # 17:

heketi-cli volume delete <volname>

should be,

heketi-cli volume delete <vol id>

Issue # 18:

6.2.5, step 3, Provide the syntax about expanding the volume and then give the example.

syntax would be,

heketi-cli volume expand --volume=<vol_id> --expand-size=<size to expand in Gb>

Issue # 19:

6.2.2. Installing Heketi, along with heketi's installation, heketi-client also has to be installed.

yum install heketi heketi-client

Comment 4 Bhavana 2017-02-28 11:01:15 UTC
Hi Ashiq,

Can you please let me know what is decided regarding Issue 7. Are we planning to include this for the 3.1.3 Async (3rd March) or not.

Thanks.

Comment 5 Mohamed Ashiq 2017-02-28 13:20:14 UTC
Hi Bhavana,

I checked the upstream API Documentation and There needs to be little change required upstream. I am not sure we can make it by 3rd March.

Thanks.

Comment 7 Anjana Suparna Sriram 2017-03-03 11:35:48 UTC
*** Bug 1361096 has been marked as a duplicate of this bug. ***

Comment 9 Bhavana 2017-03-13 06:42:57 UTC
Following is the updated 3.1.3 Admin Guide link. The API link to the github is removed along with the Tech Preview Note:

http://jenkinscat.gsslab.pnq.redhat.com:8080/view/Gluster/job/doc-Red_Hat_Gluster_Storage-3.1.3-Administration_Guide%20%28html-single%29/lastSuccessfulBuild/artifact/tmp/en-US/html-single/index.html#idm140379323642640

The release notes is updated too. but taking some time for the changes to be reflected online. I will add the link to this bug as soon as the changes are online.

Comment 25 Red Hat Bugzilla 2023-09-14 03:37:31 UTC
The needinfo request[s] on this closed bug have been removed as they have been unresolved for 1000 days


Note You need to log in before you can comment on or make changes to this bug.