Skip to content

Commit b5c5be4

Browse files
FryguyFryguy
authored
Merge pull request #1689 from agrare/add_back_internal_database_configuration
Add back the internal database configuration docs
2 parents bbeebb4 + 0f7e84c commit b5c5be4

File tree

5 files changed

+153
-160
lines changed

5 files changed

+153
-160
lines changed

‎_includes/configuration-db-external.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#### Configuring an External Database
2+
3+
Based on your setup, you will choose to configure the appliance to use
4+
an external PostgreSQL database. For example, we can only have one
5+
database in a single region. However, a region can be segmented into
6+
multiple zones, such as database zone, user interface zone, and
7+
reporting zone, where each zone provides a specific function. The
8+
appliances in these zones must be configured to use an external
9+
database.
10+
11+
The `postgresql.conf` file requires
12+
specific settings for correct operation. For example, it must correctly
13+
reclaim table space, control session timeouts, and format the PostgreSQL
14+
server log for improved system support. It is recommended that external databases use a
15+
`postgresql.conf` file based on the standard file used by the
16+
{{ site.data.product.title_short }} appliance.
17+
18+
Ensure you configure the settings in the `postgresql.conf` to suit your
19+
system. For example, customize the `shared_buffers` setting according to
20+
the amount of real storage available in the external system hosting the
21+
PostgreSQL instance. In addition, depending on the aggregate number of
22+
appliances expected to connect to the PostgreSQL instance, it may be
23+
necessary to alter the `max_connections` setting.
24+
25+
**Note:**
26+
27+
- {{ site.data.product.title_short }} requires PostgreSQL version 13.
28+
29+
- `postgresql.conf` controls the operation of all databases managed by the
30+
PostgreSQL instance, therefore it is not recommended to run other databases
31+
on this PostgreSQL instance.
32+
33+
1. Start the appliance and open a terminal console.
34+
35+
2. Enter the `appliance_console` command. The appliance console summary screen will be displayed.
36+
37+
3. Press **Enter** to manually configure settings.
38+
39+
4. Select **Configure Application** from the menu.
40+
41+
5. Choose **Create Region in External Database** for the database location.
42+
43+
6. Enter the database hostname or IP address when prompted.
44+
45+
7. Enter the database name or leave blank for the default
46+
(`vmdb_production`).
47+
48+
8. Enter the database username or leave blank for the default (`root`).
49+
50+
9. Enter the chosen database user’s password.
51+
52+
10. Confirm the configuration if prompted.
53+
54+
{{ site.data.product.title_short }} will then configure the external database.

‎_includes/configuration-db-internal.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
#### Configuring an Internal Database
2+
3+
Before installing an internal database, add a disk to the infrastructure
4+
hosting your appliance. See the documentation specific to your
5+
infrastructure for instructions for adding a disk. As a storage disk
6+
usually cannot be added while a virtual machine is running, Red Hat
7+
recommends adding the disk before starting the appliance.
8+
{{ site.data.product.title_short }} only supports installing of an internal VMDB on blank
9+
disks; installation will fail if the disks are not blank.
10+
11+
</div>
12+
13+
1. Start the appliance and open a terminal console.
14+
15+
2. Enter the `appliance_console` command. The {{ site.data.product.title_short }} appliance
16+
summary screen displays.
17+
18+
3. Press **Enter** to manually configure settings.
19+
20+
4. Select **Configure Application** from the menu.
21+
22+
5. You are prompted to create or fetch an encryption key.
23+
24+
- If this is the first {{ site.data.product.title_short }} appliance, choose **Create
25+
key**.
26+
27+
- If this is not the first {{ site.data.product.title_short }} appliance, choose
28+
**Fetch key from remote machine** to fetch the key from the
29+
first appliance. For worker and multi-region setups, use this
30+
option to copy key from another appliance.
31+
32+
**Note:**
33+
34+
All {{ site.data.product.title_short }} appliances in a multi-region
35+
deployment must use the same key.
36+
37+
6. Choose **Create Internal Database** for the database location.
38+
39+
In the **Configure Messaging** menu, select **Make No messaging changes**. If you see ```Configuration failed: Internal database require a volume mounted at /var/lib/pgsql. Please add an unpartitioned disk and try again.``` message, then ensure to add a second disk for the database per instructions as defined above.
40+
41+
7. Choose a disk for the database. This can be either a disk you
42+
attached previously, or a partition on the current disk.
43+
44+
<div class="important">
45+
46+
Red Hat recommends using a separate disk for the database.
47+
48+
</div>
49+
50+
If there is an unpartitioned disk attached to the virtual machine,
51+
the dialog will show options similar to the following:
52+
53+
1) /dev/vdb: 20480
54+
2) Don't partition the disk
55+
56+
- Enter **1** to choose `/dev/vdb` for the database location. This
57+
option creates a logical volume using this device and mounts the
58+
volume to the appliance in a location appropriate for storing
59+
the database. The default location is `/var/lib/pgsql`, which
60+
can be found in the environment variable
61+
`$APPLIANCE_PG_MOUNT_POINT`.
62+
63+
- Enter **2** to continue without partitioning the disk. A second
64+
prompt will confirm this choice. Selecting this option results
65+
in using the root filesystem for the data directory (not advised
66+
in most cases).
67+
68+
8. Enter **Y** or **N** for **Should this appliance run as a standalone
69+
database server?**
70+
71+
- Select **Y** to configure the appliance as a database-only
72+
appliance. As a result, the appliance is configured as a basic
73+
PostgreSQL server, without a user interface.
74+
75+
- Select **N** to configure the appliance with the full
76+
administrative user interface.
77+
78+
9. When prompted, enter a unique number to create a new region.
79+
80+
<div class="important">
81+
82+
Creating a new region destroys any existing data on the chosen
83+
database.
84+
85+
</div>
86+
87+
10. Create and confirm a password for the database.
88+
89+
{{ site.data.product.title_short }} then configures the internal database. This takes a few
90+
minutes. After the database is created and initialized, you can log in
91+
to {{ site.data.product.title_short }}.

‎_includes/configuration-db.md

Lines changed: 6 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,7 @@
1-
### Configuring an Internal Database
1+
{{ site.data.product.title_short }} uses a database to store information about the
2+
environment. Before using {{ site.data.product.title_short }}, configure the database
3+
options for it; {{ site.data.product.title_short }} provides the following two
4+
options for database configuration:
25

3-
Before installing an internal database, add a disk to the infrastructure
4-
hosting your appliance. See the documentation specific to your
5-
infrastructure for instructions for adding a disk. As a storage disk
6-
usually cannot be added while a virtual machine is running, Red Hat
7-
recommends adding the disk before starting the appliance.
8-
{{ site.data.product.title_short }} only supports installing of an internal VMDB on blank
9-
disks; installation will fail if the disks are not blank.
10-
11-
</div>
12-
13-
1. Start the appliance and open a terminal console.
14-
15-
2. Enter the `appliance_console` command. The {{ site.data.product.title_short }} appliance
16-
summary screen displays.
17-
18-
3. Press **Enter** to manually configure settings.
19-
20-
4. Select **Configure Application** from the menu.
21-
22-
5. You are prompted to create or fetch an encryption key.
23-
24-
- If this is the first {{ site.data.product.title_short }} appliance, choose **Create
25-
key**.
26-
27-
- If this is not the first {{ site.data.product.title_short }} appliance, choose
28-
**Fetch key from remote machine** to fetch the key from the
29-
first appliance. For worker and multi-region setups, use this
30-
option to copy key from another appliance.
31-
32-
**Note:**
33-
34-
All {{ site.data.product.title_short }} appliances in a multi-region
35-
deployment must use the same key.
36-
37-
6. Choose **Create Internal Database** for the database location.
38-
39-
In the **Configure Messaging** menu, select **Make No messaging changes**. If you see ```Configuration failed: Internal database require a volume mounted at /var/lib/pgsql. Please add an unpartitioned disk and try again.``` message, then ensure to add a second disk for the database per instructions as defined above.
40-
41-
7. Choose a disk for the database. This can be either a disk you
42-
attached previously, or a partition on the current disk.
43-
44-
<div class="important">
45-
46-
Red Hat recommends using a separate disk for the database.
47-
48-
</div>
49-
50-
If there is an unpartitioned disk attached to the virtual machine,
51-
the dialog will show options similar to the following:
52-
53-
1) /dev/vdb: 20480
54-
2) Don't partition the disk
55-
56-
- Enter **1** to choose `/dev/vdb` for the database location. This
57-
option creates a logical volume using this device and mounts the
58-
volume to the appliance in a location appropriate for storing
59-
the database. The default location is `/var/lib/pgsql`, which
60-
can be found in the environment variable
61-
`$APPLIANCE_PG_MOUNT_POINT`.
62-
63-
- Enter **2** to continue without partitioning the disk. A second
64-
prompt will confirm this choice. Selecting this option results
65-
in using the root filesystem for the data directory (not advised
66-
in most cases).
67-
68-
8. Enter **Y** or **N** for **Should this appliance run as a standalone
69-
database server?**
70-
71-
- Select **Y** to configure the appliance as a database-only
72-
appliance. As a result, the appliance is configured as a basic
73-
PostgreSQL server, without a user interface.
74-
75-
- Select **N** to configure the appliance with the full
76-
administrative user interface.
77-
78-
9. When prompted, enter a unique number to create a new region.
79-
80-
<div class="important">
81-
82-
Creating a new region destroys any existing data on the chosen
83-
database.
84-
85-
</div>
86-
87-
10. Create and confirm a password for the database.
88-
89-
{{ site.data.product.title_short }} then configures the internal database. This takes a few
90-
minutes. After the database is created and initialized, you can log in
91-
to {{ site.data.product.title_short }}.
6+
{% include configuration-db-internal.md %}
7+
{% include configuration-db-external.md %}

‎_includes/configuration.md

Lines changed: 1 addition & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -34,69 +34,7 @@ after five minutes of inactivity.
3434

3535
### Configuring a Database
3636

37-
{{ site.data.product.title_short }} uses a database to store information about the
38-
environment. Before using {{ site.data.product.title_short }}, configure the database
39-
options for it; {{ site.data.product.title_short }} provides the following two
40-
options for database configuration:
41-
42-
- Configure the appliance to use an external PostgreSQL database
43-
44-
#### Configuring an External Database
45-
46-
Based on your setup, you will choose to configure the appliance to use
47-
an external PostgreSQL database. For example, we can only have one
48-
database in a single region. However, a region can be segmented into
49-
multiple zones, such as database zone, user interface zone, and
50-
reporting zone, where each zone provides a specific function. The
51-
appliances in these zones must be configured to use an external
52-
database.
53-
54-
The `postgresql.conf` file used with {{ site.data.product.title_short }} databases requires
55-
specific settings for correct operation. For example, it must correctly
56-
reclaim table space, control session timeouts, and format the PostgreSQL
57-
server log for improved system support. It is recommended that external databases use a
58-
`postgresql.conf` file based on the standard file used by the
59-
{{ site.data.product.title_short }} appliance.
60-
61-
Ensure you configure the settings in the `postgresql.conf` to suit your
62-
system. For example, customize the `shared_buffers` setting according to
63-
the amount of real storage available in the external system hosting the
64-
PostgreSQL instance. In addition, depending on the aggregate number of
65-
appliances expected to connect to the PostgreSQL instance, it may be
66-
necessary to alter the `max_connections` setting.
67-
68-
**Note:**
69-
70-
- {{ site.data.product.title_short }} requires PostgreSQL version 10.
71-
72-
- Because the `postgresql.conf` file controls the operation of all
73-
databases managed by a single instance of PostgreSQL, do not mix
74-
{{ site.data.product.title_short }} databases with other types of databases in a single
75-
PostgreSQL instance.
76-
77-
1. Start the appliance and open a terminal console.
78-
79-
2. Enter the `appliance_console` command. The {{ site.data.product.title_short }} appliance
80-
summary screen displays.
81-
82-
3. Press **Enter** to manually configure settings.
83-
84-
4. Select **Configure Application** from the menu.
85-
86-
5. Choose **Create Region in External Database** for the database location.
87-
88-
6. Enter the database hostname or IP address when prompted.
89-
90-
7. Enter the database name or leave blank for the default
91-
(`vmdb_production`).
92-
93-
8. Enter the database username or leave blank for the default (`root`).
94-
95-
9. Enter the chosen database user’s password.
96-
97-
10. Confirm the configuration if prompted.
98-
99-
{{ site.data.product.title_short }} will then configure the external database.
37+
{% include configuration-db.md %}
10038

10139
### Configure Messaging
10240

‎quickstart_openstack_provider_guide/_topics/configuration-quick.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,7 @@ through `virsh`:
2323

2424
{% include configuration-advanced.md %}
2525

26-
### Configuring a Database for {{ site.data.product.title_short }}
27-
28-
{{ site.data.product.title_short }} supports the use of an internal or external database.
29-
The following instructions are suitable for configuring an *internal*
30-
database. For instructions on how to configure an external database
31-
instead, see [Configuring an External
32-
Database](https://access.redhat.com/documentation/en/red-hat-cloudforms/4.1/single/installing-red-hat-cloudforms-on-red-hat-enterprise-linux-openstack-platform#configuring_an_external_database).
26+
### Configuring a Database
3327

3428
{% include configuration-db.md %}
3529

0 commit comments

Comments
 (0)