manageiq / manageiq-documentation Goto Github PK

In http://www.manageiq.org/docs/reference/latest/doc-Installing_on_Red_Hat_Virtualization/miq/

section 1.2 Uploading the Appliance on Red Hat Virtualization

add recommendations for sizing of qcow2 appliance.

As of when this was opened, I think we're using the wrong call in at least the following places still:
I'll fix them as time allows. It's worth noting these changes should all go back to h and i.

https://github.com/ManageIQ/manageiq_docs/blob/39503bb22c58e413b42da6c056167c2166cd389b/api/reference/service_custom_actions.adoc#L338

https://github.com/ManageIQ/manageiq_docs/blob/abdf3b617f9f1233f76dfd877271cb71052aa001/api/overview/json.adoc#L250

https://github.com/ManageIQ/manageiq_docs/blob/ca32417489b7aa768e73cdeeb79b41d1548a6ddb/api/reference/services.adoc#L666

Observation:
A group MUST be pre-defined within Manageiq that matches the group in use on LDAP. If this group is not pre-defined, redirected logins using SSO may fail.

User Impact:
Understanding configuration pre-requisites to enable SSO correctly can avoid end-user frustration.

Getting 404 Not Found error while accessing docs on mangeiq.org/docs.

Credit goes to @naltun for writing up and testing out the following steps:

How to get new certs running on ManageIQ.

1. Download any validation files, and upload them to the server. You can do this by:
   $ scp $my_file user@$ip_address:/path/to/location/
2. Validate your domain through your certificate authority
3. Download your certificates, and upload them to the server
   Can be done by using scp $my_file user@$ip_address:/path/to/location/
4. Your files may be using the .cer or the .crt extensions. Both work. However, you'll need to
   change the names of the files. ManageIQ uses server.cer and server.cer.key. These files
   can be found in /var/www/miq/vmdb/certs. Go into that directory, and ls. You'll see
   those two files. Now take your certificate and certificate key files and rename them;
   the certificate should be renamed to server.cer, and the key file to server.cer.key.
   If you are unsure which file is the certificate, and which is the key, then `cat' server.cer
   and server.cer.key, and compare the files to your files.
5. After you've replaced the files in /var/www/miq/vmdb/certs/, go back one directory (/var/www/miq/vmdb/)
   and run bundle exec rake evm:restart. Your certs should be active and you should be
   connected over HTTPS.

Also opened as https://bugzilla.redhat.com/show_bug.cgi?id=1632947

Actions "create", "set_ownership", "start", "stop" and "suspend" are not documented.

There is no need to download and upload the storage file as it is already stored in Google Storage as public. Steps in 1.1 and 1.2.3-1.2.5 are unnecessary. Instead you can jump to creating the image, just provide the bucket and storage file name in "Cloud Storage File" field, ie:
manageiq/gaprindashvili-1-rc1.tar.gz
See https://cloud.google.com/compute/docs/instances/create-start-instance#publicimage

Per ManageIQ/manageiq#19915 I don't think this section should still be in our docs.

With latest commit, the External Authentication documentation is no longer visible from the built asciibinder left table of content.

In the installation section, all index.adoc pages (doc-Installing_on_Google_Compute_Engine, doc-Installing_on_Red_Hat_Enterprise_Linux_OpenStack_Platform, etc will cause an error message rendered in the output html: (may be one or more lines similar to these)

Unresolved directive in <stdin> - include::topics/installation.adoc[]
Unresolved directive in <stdin> - include::topics/configuration.adoc[]

For example, http://manageiq.org/docs/reference/latest/doc-Installing_on_Google_Compute_Engine/miq/
I found this may be a bug of asciidoctor and it can't deal with include file in a symbolic links directory with one level upward. For example:

myfyb@myfyb-ThinkPad-X230:~/redhat/manageiq_docs/doc-Installing_on_Google_Compute_Engine/miq$ ls -l
total 12
lrwxrwxrwx 1 myfyb myfyb  13 Mar  9 10:51 common -> ../../common/
-rw-rw-r-- 1 myfyb myfyb 619 Mar  9 10:51 docinfo.xml
lrwxrwxrwx 1 myfyb myfyb  10 Mar  9 10:51 images -> ../images/
-rw-rw-r-- 1 myfyb myfyb 702 Mar  9 12:17 index.adoc
lrwxrwxrwx 1 myfyb myfyb  10 Mar  9 10:51 topics -> ../topics/

In this case, all adoc files in "common" can be correctly included, but all in "topics" can't. I have tried make other symbolic links, such as:

myfyb@myfyb-ThinkPad-X230:~/redhat/manageiq_docs/doc-Installing_on_Google_Compute_Engine/miq$ mkdir ../../duang
myfyb@myfyb-ThinkPad-X230:~/redhat/manageiq_docs/doc-Installing_on_Google_Compute_Engine/miq$ cp topics/configuration.adoc ../../duang/configuration.adoc
myfyb@myfyb-ThinkPad-X230:~/redhat/manageiq_docs/doc-Installing_on_Google_Compute_Engine/miq$ ln -s ../../duang/ duang
myfyb@myfyb-ThinkPad-X230:~/redhat/manageiq_docs/doc-Installing_on_Google_Compute_Engine/miq$ ls -l
total 12
lrwxrwxrwx 1 myfyb myfyb  13 Mar  9 10:51 common -> ../../common/
-rw-rw-r-- 1 myfyb myfyb 619 Mar  9 10:51 docinfo.xml
lrwxrwxrwx 1 myfyb myfyb  12 Mar  9 12:27 duang -> ../../duang/
lrwxrwxrwx 1 myfyb myfyb  10 Mar  9 10:51 images -> ../images/
-rw-rw-r-- 1 myfyb myfyb 798 Mar  9 12:18 #index.adoc#
-rw-rw-r-- 1 myfyb myfyb 702 Mar  9 12:17 index.adoc
lrwxrwxrwx 1 myfyb myfyb  10 Mar  9 10:51 topics -> ../topics/

And in this case, the include line in index.adoc:

[[Configuration]]
include::duang/configuration.adoc[]

will include as expected. Since "duang" is a meaningless name, and doesn't appear in any config files, so we know that the asciidoctor can't deal with files in a directory that symbolic linked to one level upward. And after examine its source, this def is the one asciidoctor to deal with parse include file path, which is buggy:
https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/abstract_node.rb#L541
That's also why every .adoc file in ../../common is correctly included but not files in ../topics. I think there are two ways to solve, one is to fork the asciidoctor and solve it there (However there are 500+ unsolved issues and many not merged pull requests for asciidoctor so we may have to keep our own fork until it's fixed by official repo). Another is a dirty fix to change the directory organization of our doc, which will make the doc website include these missing sections correctly but the doc is less organized. Actually I can do this, as I have fixed part of the doc in this way, but I don't know whether we should do this way. Which approach should we have? Or a third better solution?

https://github.com/ManageIQ/manageiq_docs/blob/master/common/configuration.adoc has a lot, but it's slightly wrong if the user wants the replication feature. If the user wishes to leverage the replication features of ManageIQ, then the user must install SCL's Postgres 9.5, and the pglogical/repmgr RPMs. We should mention that an alternate approach for an external database is to just launch another appliance and set it up to be database only.

cc @carbonin Can you verify what I'm saying to keep me honest

cc @adahms @cbudz

While Ansible features can be used on the ManageIQ Appliance, it is not installed by default on the appliance. This procedure must be documented.

Requesting subject matter expert and writer.

Original issue ManageIQ/manageiq.org#664

When running asciidoctor, the high availability isn't build into the result. Just guessing that the issue is around the topic map file and we might also miss other documentation parts.

This is causing the website not to have these docs 😞

http://www.manageiq.org/docs/reference/latest/doc-Installing_on_Red_Hat_Virtualization/miq/
Section 1.3, step 4d has broken link

In http://www.manageiq.org/docs/reference/latest/doc-Installing_on_Red_Hat_Virtualization/miq/
update the Stable from Stable (fine-2) to Stable (fine-4) or perhaps not specify the version number, but just "Stable"

See below, when one click on "Documentation" , it is showing "
For questions or problem reporting, visit ManageIQ.org "

I am hoping to reach http://www.manageiq.org/docs/ directly.

User Reference -> Installation -> Microsoft Azure (or Openstack/RHV), section 1.1

1. "navigate to manageiq.org/download" link is broken.

2. step 2 to 4 talk about choosing platform/release from list and follow instruction, but we no longer use dropdown lists in the download page.

http://manageiq.org/docs/reference/latest/api/reference/chargebacks_rates#creating-rates
The request described in doc fails with

{
  "error": {
    "kind": "bad_request",
    "message": "Chargeable field can't be blank",
    "klass": "Api::BadRequestError"
  }
}

In current version also "chargeable_field_id" needs to be specified.

https://github.com/ManageIQ/manageiq_docs/blob/master/api/reference/groups.adoc

    "filters" : {
      "belongsto" : [ "/managed/area/1", "/managed/area/2", "/managed/area/3" ],
      "managed" : [[ "/managed/infra/1", "/managed/infra/2"], ["/managed/other/3"]]
    }

This shows the structure (belongsto is flat, managed is grouped by tag category) but doesn't explain at all what these filters mean.

Corresponding UI seems to be documented here:
https://github.com/ManageIQ/manageiq_docs/blob/master/doc-General_Configuration/topics/Configuration.adoc#groups
https://access.redhat.com/documentation/en-us/red_hat_cloudforms/4.6/html/general_configuration/configuration#groups
but it's unclear how that maps to the API.

Limit what users in this group can view by selecting filters in the Assign Filters** area.

Does this reflect in filters.belongsto or filters.managed (or both)?
Does the nested structure of filters.managed reflect something like "AND by category, OR within category"?

• Select Tags Based On Expression, then create tags based on an expression using AND, OR, or NOT. This allows you to further limit the resources accessible to a user: for example, to specify a combination of tags that must exist on a resource.

How is this mode reflected in API?

(Source code is doesn't make these obvious either, especially since "groups" are involved with "entitlements" since ManageIQ/manageiq#8102 ...)

Several new collections were added over the last few releases but have no examples in the API Docs->Reference section other than the general mention in the Reference->Primary Collections and the HATEOAS like things one can query via /api, returned actions on collections and resources and OPTIONS on collections.

We need endpoint examples in their own Reference entry or part of a related topic section, i.e. Physical Server Management.

• /api/alert_definition_profiles
• /api/auth_key_pairs
• /api/automate_classes
• /api/availability_zones
• /api/cloud_networks - Cloud Object Management
• /api/cloud_object_store_containers
• /api/cloud_subnets
• /api/cloud_templates
• /api/cloud_volume_types
• /api/clusters
• /api/configuration_profiles
• /api/configuration_script_payloads
• /api/configuration_scripts
• /api/configured_systems
• /api/container_groups - Container Management
• /api/container_images
• /api/container_nodes
• /api/container_projects
• /api/container_templates
• /api/container_volumes
• /api/containers
• /api/currencies
• /api/customization_scripts
• /api/customization_templates
• /api/data_stores
• /api/enterprises
• /api/firmware_registries
• /api/firmwares
• /api/floating_ips
• /api/guest_devices
• /api/lans
• /api/load_balancers
• /api/measures
• /api/orchestration_stacks
• /api/physical_chassis - Physical Server Management
• /api/physical_racks
• /api/physical_storages
• /api/physical_switches
• /api/regions
• /api/request_tasks
• /api/resource_pools
• /api/servers
• /api/service_offerings
• /api/service_parameters_sets
• /api/switches
• /api/templates
• /api/tenant_groups
• /api/zones

cc @abellotti Please update this issue with other things you've found

With NetworkManager disabled, the NM_CONTROLLED line is not longer there in eth0, need to update the active_directory.adoc sed line accordingly.

It would be good to have a documented list of what is or is not supported via Central Admin

We have https://github.com/ManageIQ/manageiq_docs/blob/d61207004070e1a0e14ed6826812792ea67f61c3/doc-Deployment_Planning_Guide/topics/planning.adoc#centralized-administration

But I'm not sure that's exposed anywhere on http://manageiq.org/docs/reference/
This doc also has some good information
But I'm not sure that's exposed anywhere on http://manageiq.org/docs/reference/

Looks like Deployment Planning Guide is missing from https://github.com/ManageIQ/manageiq_docs/blob/master/_topic_map.yml ?

There are some users don't who understand, that MIQ doesn't autodetect domains for given Openstack user. Change on source code level would require huge changes in modelling. So we should document it better at least for now.

We need add the information [1] into (or close to) adding Cloud providers chapter [2].

[1] Something like: The provider you're creating will be able to see inventory from the given domain only. If you want see other domain inventory, add it as other Cloud provider
[2] 4.1.1. Adding OpenStack Providers, a bullet 5 Select the appropriate API Version... http://manageiq.org/docs/reference/latest/doc-Managing_Providers/miq/#openstack-providers

We need document, that user which is used in Openstack provider setup must have an admin role for his domain. Otherwise it causes various issues including failed refresh.

Multiple Openstack domains are supported since #9222 was merged.

This doc issue was moved from ManageIQ/manageiq#12860

REST API for arbitration_profiles, arbitration_settings and arbitration_rules is not documented.

From http://manageiq.org/docs/reference/
following link is broken.
http://manageiq.org/docs/reference/latest/doc-Installing_on_Red_Hat_Enterprise_Virtualization/miq

• Convert to Markdown: #1439
• Ensure website builds still work - ManageIQ/manageiq.org#850
  • Change website builds to build off of "old" docs on jansa branch
  • Update to work with new markdown
  • Change website builds to build jansa as legacy format
• Keep the ability to modify the name and other certain strings.
• Update jansa branch to be markdown based - #1467 & ManageIQ/manageiq.org#864
• Rename repo to manageiq-documentation
• Remove from nightly build: ManageIQ/manageiq-appliance-build#421

Arghhh I don't have time to fix this right now but the vm management should include retirement:

and should be using the new call, for RAAR

Hi

I am new to asciibinder sofware and I was able to check out manageiq_doc repo and run "asciibinder" to generate "_preview" ok.

But I encountered following error message.

asciidoctor: WARNING: image to embed not found or not readable: /home/tjyang/github/manageiq_docs/doc-Monitoring_Alert\
s_and_Reporting/miq/images/1862.png
asciidoctor: WARNING: image to embed not found or not readable: /home/tjyang/github/manageiq_docs/doc-Monitoring_Alert\
s_and_Reporting/miq/images/1862.png
asciidoctor: WARNING: image to embed not found or not readable: /home/tjyang/github/manageiq_docs/doc-Monitoring_Alert\
s_and_Reporting/miq/images/1862.png
g

By following the commands in README, I was able to build the docs, but final output looks like this:

This is nothing like http://manageiq.org/docs/ site.

AsciiBinder is no longer supported, and AsciiDoctor should give use everything we need.

• Document in manageiq-documentation a manual process for a basic transfer/upgrade (#1449 (comment)) #1486

Continued in #1510

In User Reference -> Installation, there are only 4 installation guides available (GCE, Azure, OpenStack and RHV). Please add other hypervisor installation guide to the installation section as well.

The users no longer need to resize/convert Azure appliance image manually as that's done in the build now.

Please remove "Converting and Aligning the ManageIQ Virtual Appliance Image" section from the installation doc and update the note right above as appropriate.

The change is in master build.

Need to update the OIDC configuration documentation to address the changes made in this PR

ManageIQ/manageiq-appliance#282

See ManageIQ/manageiq#14019 and ManageIQ/manageiq#14004

The situation is that there was a setting for whether or not to verify the peer certificate when connecting to Container or RHV providers. When verify_ssl was set to 1 (meaning, true) it wasn't actually verifying the peer certificate.

Additionally, the default was to set verify_ssl to 1.

The fix being put in place will start enforcing the verify_ssl setting. However, it's impossible to know whether the existing value for verify_ssl is correct or not.

The documentation need is to explain that there are two possible outcomes:

1. The user has a valid SSL certificate for their provider and it is signed by a trusted CA (e.g. Verisign). In which case, the user will notice no changes and will need to take no action.

2. The user has a self-signed SSL certificate for their provider. In which case, either the Schedule Worker or an attempt to collect inventory will render the provider connection invalid:

In this situation, the user has two options:

A) Configure a custom CA to trust:

B) Disable the certificate validation.

REST API for blueprints is not documented.

From here

https://github.com/ManageIQ/ui-components/blob/master/README link is broken.

Review What You Can See From The Provider

If we go down to Relationships for VMs, we see this image: https://manageiq.org/assets/images/docs/screenshot_0018.png

If I am not mistaken, this is a photo for the Cloud Provider - Relationships section.

With latest commit, v2.2.0 of the API documentation (upstream/cf 4.1) - no longer visible from the built asciibinder left table of content.

Because of the way the docs are structured, the left side nav becomes unusable.

An example of what I'd expect is present in the REST API docs, where clicking the specific item brings you to documentation for just that piece:

However, the docs that were transferred from CloudForms are in the following format, where clicking the "Index" brings you to giant page that has everything, including an embedded Table Of Contents.

I tried tweaking this myself, but the structure confuses me at the moment and I'm concerned I'm breaking something for CloudForms, which I can't test the build against. For example, the index file actually includes the topics files via a numbered: directive. I tried changing the _distro_map.yml to directly point to the topics files, bypassing the index file, but then I get some pathing errors because I think AsciiBinder can't handle that unexpected structure. I even tried tweaking AsciiBinder to deal with it, but then things like images are not referenced correctly.

cc @adahms
If you need more information, let's discuss. I have an idea for the structure of the repo, but I don't understand the limitations because of the downstream build.

I think we can just replace /images with ../images

cc @dehawkins512

Red Hat is mentioned unnecessarily

• On this line, fixed by PR
• Browser Requirements here, fixed by PR

In Developer setup for ManageIQ for Ubuntu,
in the section "Ubuntu fix for failing Bundler", the packages no longer point to correct location.

Original:
sudo apt remove libssl-dev
wget http://ftp.cz.debian.org/debian/pool/main/o/openssl1.0/libssl1.0-dev_1.0.2l-2_amd64.deb
wget http://ftp.cz.debian.org/debian/pool/main/o/openssl1.0/libssl1.0.2_1.0.2l-2_amd64.deb
sudo dpkg -i libssl1.0-dev_1.0.2l-2_amd64.deb libssl1.0.2_1.0.2l-2_amd64.deb

Modified version:
sudo apt remove libssl-dev
wget http://cdn-fastly.deb.debian.org/debian/pool/main/o/openssl1.0/libssl1.0-dev_1.0.2l-2+deb9u1_amd64.deb
wget http://cdn-fastly.deb.debian.org/debian/pool/main/o/openssl1.0/libssl1.0.2_1.0.2l-2+deb9u1_amd64.deb
sudo dpkg -i libssl1.0-dev_1.0.2l-2+deb9u1_amd64.deb libssl1.0.2_1.0.2l-2+deb9u1_amd64.deb

FYI @chessbyte @Fryguy @gtanzillo

This chapter:
https://github.com/ManageIQ/manageiq_docs/blob/master/doc-Managing_Infrastructure_and_Inventory/topics/Container_Entities.adoc
seems to be missing from on http://manageiq.org/docs/reference/latest/doc-Managing_Infrastructure_and_Inventory/miq/
It does exist downstream.