Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-04-21 13:37:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 91

Docs: Clarify MySQL read replica config is independent from primary (#43013)

Browse source 
## Summary

- Clarifies in the MySQL docs intro that read replica configuration is
fully independent — no values are inherited from the primary config
- Adds explicit callout that `mysql_read_replica_region` must be set
separately when using IAM authentication
- Adds note to `mysql_tls_config` explaining that this setting is
typically not needed for RDS IAM auth since Fleet uses bundled RDS CA
certificates (including GovCloud regions)

These changes address real-world customer confusion where a GovCloud
deployment failed because `FLEET_MYSQL_READ_REPLICA_REGION` was not set
independently of `FLEET_MYSQL_REGION`.

Note: related to #39832

## Testing

Documentation-only change — no code impact.
This commit is contained in:
Mitch Francese 2026-04-08 18:43:14 -04:00 committed by GitHub
parent baf5dab92a
commit e21e3a7f67
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 7 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changes/docs-read-replica-config-clarity Normal file
View file

@ -0,0 +1 @@
* Improved documentation for MySQL read replica configuration, clarifying that all settings (including region for IAM authentication) must be explicitly set for the read replica.

8
docs/Configuration/fleet-server-configuration.md
View file

@ -15,7 +15,7 @@ You can specify configuration options in the following formats:
## MySQL
This section describes the configuration options for the primary. Suppose you also want to set up a read replica. In that case the options are the same, except that the YAML section is `mysql_read_replica`, and the flags have the `mysql_read_replica_` prefix instead of `mysql_` (the corresponding environment variables follow the same transformation). Note that there is no default value for `mysql_read_replica_address`, it must be set explicitly for Fleet to use a read replica, and it is recommended in that case to set a non-zero value for `mysql_read_replica_conn_max_lifetime` as in some environments, the replica's address may dynamically change to point
This section describes the configuration options for the primary. Suppose you also want to set up a read replica. In that case the options are the same, except that the YAML section is `mysql_read_replica`, and the flags have the `mysql_read_replica_` prefix instead of `mysql_` (the corresponding environment variables follow the same transformation). **Read replica configuration is fully independent from the primary — no values are inherited.** All required settings (address, region, TLS, authentication, etc.) must be explicitly set for the read replica using the `mysql_read_replica_` prefix. For example, if IAM authentication is used, both `FLEET_MYSQL_REGION` and `FLEET_MYSQL_READ_REPLICA_REGION` must be set. Note that there is no default value for `mysql_read_replica_address`, it must be set explicitly for Fleet to use a read replica, and it is recommended in that case to set a non-zero value for `mysql_read_replica_conn_max_lifetime` as in some environments, the replica's address may dynamically change to point
from the primary to an actual distinct replica based on auto-scaling options, so existing idle connections need to be recycled
periodically.
@ -119,7 +119,9 @@ The path to a PEM encoded private key used for TLS authentication.
### mysql_tls_config
The TLS value in an MYSQL DSN. Can be `true`,`false`,`skip-verify`, or the CN value of the certificate.
The TLS value in a MySQL DSN. Can be `true`,`false`,`skip-verify`, or the CN value of the certificate.
When using IAM authentication with RDS, this setting is typically not needed — Fleet automatically uses `rdsmysql` as the TLS config, which includes bundled RDS CA certificates (including GovCloud regions). Setting this to `true` uses the system CA pool instead, which may not include RDS certificates in minimal container environments.
- Default value: none
- Environment variable: `FLEET_MYSQL_TLS_CONFIG`
@ -205,6 +207,8 @@ AWS region to use for Identity and Access Management (IAM) authentication of an
- `mysql_password` is not set
- `mysql_password_path` is not set
If a read replica is configured, the read replica's region must also be set explicitly via `mysql_read_replica_region` — it is not inherited from this setting.
- Default value: none
- Environment variable: `FLEET_MYSQL_REGION`
- Config file format: