Skip to content

loadbalancer: document ProxySQL with internal TLS - #1123

Merged
berendt merged 2 commits into
mainfrom
docs/proxysql-tls
Oct 27, 2026
Merged

berendt merged 2 commits into
mainfrom
docs/proxysql-tls

Conversation

@ideaship

Copy link
Copy Markdown
Contributor

The loadbalancer configuration guide does not mention the files ProxySQL needs once internal TLS is on, and its TLS procedure leaves some of the files it has the operator create uncommitted. Two commits:

  1. Commit everything the procedures add. Step 4 of the general procedure committed an explicit list of three files. The self-signed procedure, which ends by running the general procedure, also adds the custom CA under environments/kolla/certificates/ca/, certificates_ca in environments/configuration.yml and, up to OSISM 11.0.1, the REQUESTS_CA_BUNDLE override in environments/manager/configuration.yml. None of them was committed, so the next configuration sync on the manager reset them. Step 4 now stages the whole certificates directory, and the self-signed procedure names the two extra files.
  2. ProxySQL and internal TLS. database_enable_tls_internal defaults to kolla_enable_tls_internal and enable_proxysql, and osism/defaults enables ProxySQL for every OpenStack series after 2025.1. From OSISM 11 on, any deployment with internal TLS therefore needs ProxySQL's own certificate, key and CA, or osism apply loadbalancer fails at Copying over proxysql-cert.pem. A new subsection gives the two options: supply the files (certificate and key separately, only the key vault-encrypted), or set database_enable_tls_internal: "no".
    • It describes how the CA is looked up. From OSISM 11 on, proxysql-ca.pem is used when it exists; otherwise, and always on OSISM 10, ProxySQL reads certificates/ca/root.crt under that fixed name. That fallback only works with kolla_copy_ca_into_containers: "yes", which is off by default. The self-signed section gets a matching warning.
    • It covers the comment-only placeholders that cfg-cookiecutter generates for all three files. A proxysql-ca.pem placeholder left in place is handed to ProxySQL as its CA.
    • Step 2 of the general procedure points to the subsection, and the ProxySQL section says it is the default from OSISM 11 on.

🤖 Generated with Claude Code

Step 4 of the general TLS procedure staged and committed an explicit
list of files: haproxy.pem, haproxy-internal.pem and
environments/kolla/configuration.yml. git commit with paths commits
only those paths, so anything else the operator had added stayed
uncommitted.

The self-signed procedure ends by running the general procedure, and by
then the operator has changed three more files: the custom CA in
environments/kolla/certificates/ca/, certificates_ca in
environments/configuration.yml, and, up to OSISM 11.0.1, the
REQUESTS_CA_BUNDLE override in environments/manager/configuration.yml.
None of them was committed. The configuration sync on the manager
resets local changes to tracked files (osism.commons configuration
role, git with force: true), so an uncommitted change there does not
survive the next sync, and one made in a remote checkout never reaches
the manager.

Stage the whole certificates directory and commit everything staged,
and tell the self-signed procedure which two files to add in that step
as well.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Roger Luethi <luethi@osism.tech>
ProxySQL is coupled to internal TLS: database_enable_tls_internal
defaults to "kolla_enable_tls_internal and enable_proxysql".
osism/defaults enables ProxySQL for every OpenStack series after 2025.1
(all/099-kolla.yml), so from OSISM 11 on that expression resolves to yes
on every environment that follows the general procedure for TLS. The
loadbalancer role then copies proxysql-cert.pem and proxysql-key.pem out
of the configuration repository, and fails with "Could not find or
access .../certificates/proxysql-cert.pem" when they are missing.
Nothing in the documentation mentioned these files.

Say in the ProxySQL section that ProxySQL is the default from OSISM 11
on, and add a subsection on internal TLS with two options: supply the
certificate, key and CA, or decouple ProxySQL from internal TLS. Unlike
haproxy.pem, certificate and key are separate files, because ProxySQL
loads proxysql-ca.pem, proxysql-cert.pem and proxysql-key.pem from its
data directory; only the key is encrypted. The certificate has to be
valid for the internal API FQDN, because the OpenStack services reach
ProxySQL through the internal VIP.

In kolla-ansible stable/2026.1, ProxySQL uses
certificates/proxysql-ca.pem when the file exists
(roles/loadbalancer/tasks/config.yml,
templates/proxysql/proxysql.json.j2). Otherwise, and always before
2026.1 (OSISM 10), it reads root.crt from certificates/ca/, under that
fixed name whatever name the certificates_ca entry uses, and only when
kolla_copy_ca_into_containers is enabled, which osism/defaults turns off
(all/001-haproxy.yml). Describe both, in the subsection and in a warning
in the self-signed certificates section.

cfg-cookiecutter generates all three files as comment-only placeholders
(926f9ec). A proxysql-ca.pem placeholder left in place is handed to
ProxySQL as its CA, so tell the operator to replace the placeholders.

Step 2 of the general procedure lists the certificates an operator has
to supply; add a note there that points to the new subsection.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Roger Luethi <luethi@osism.tech>
@github-actions

Copy link
Copy Markdown

✅⚠️MegaLinter analysis: Success with warnings

Descriptor Linter Files Fixed Errors Max errors Warnings Elapsed time
✅ ACTION actionlint 5 0 0 0.04s
✅ JSON jsonlint 4 0 0 0.07s
✅ JSON prettier 4 0 0 0.31s
✅ JSON v8r 4 0 0 8.36s
✅ MARKDOWN markdownlint 183 0 0 1.74s
✅ MARKDOWN markdown-table-formatter 183 0 0 0.2s
✅ REPOSITORY betterleaks yes no no 0.53s
✅ REPOSITORY checkov yes no no 13.88s
✅ REPOSITORY git_diff yes no no 0.05s
✅ REPOSITORY secretlint yes no no 0.91s
✅ REPOSITORY trufflehog yes no no 2.67s
✅ SPELL codespell 193 0 0 0.31s
⚠️ SPELL lychee 193 5 0 18.11s
✅ YAML prettier 6 0 0 0.21s
✅ YAML v8r 6 0 0 4.41s
✅ YAML yamllint 6 0 0 0.26s

Detailed Issues

⚠️ SPELL / lychee - 5 errors
📝 Summary
---------------------
🔍 Total.........1253
🔗 Unique.........928
✅ Successful....1139
⏳ Timeouts.........0
🔀 Redirected.......9
👻 Excluded.......109
❓ Unknown..........0
🚫 Errors...........5
⛔ Unsupported......5

Errors in .claude/skills/security-advisory/reference/style.md
[ERROR] file://.claude/skills/guides/operations-guide/openstack/security-updates.md (at 189:3) | File not found. Check if file exists and path is correct

Errors in .claude/skills/security-advisory/SKILL.md
[400] https://cveawg.mitre.org/api/cve/ (at 16:18) | Rejected status code: 400 Bad Request
[404] https://raw.githubusercontent.com/osism/ (at 17:18) | Rejected status code: 404 Not Found
[400] https://registry.osism.tech/service/token (at 18:19) | Rejected status code: 400 Bad Request

Errors in docs/guides/developer-guide/style-guide.md
[ERROR] https://wiki.openstack.org/wiki/GitCommitMessages (at 79:1) | Network unreachable. Check internet connection or VPN settings

Hint: Followed 9 redirects. You might want to consider replacing redirecting URLs with the resolved URLs. Use verbose mode (`-v`/`-vv`) to see redirection details.

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

  • Documentation: Custom Flavors
  • Command: npx mega-linter-runner@10.1.0 --custom-flavor-setup --custom-flavor-linters ACTION_ACTIONLINT,JSON_JSONLINT,JSON_V8R,JSON_PRETTIER,MARKDOWN_MARKDOWNLINT,MARKDOWN_MARKDOWN_TABLE_FORMATTER,REPOSITORY_CHECKOV,REPOSITORY_GIT_DIFF,REPOSITORY_BETTERLEAKS,REPOSITORY_SECRETLINT,REPOSITORY_TRUFFLEHOG,SPELL_LYCHEE,SPELL_CODESPELL,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R

MegaLinter is provided by OX Security
Show us your support by starring ⭐ the repository

@ideaship
ideaship marked this pull request as ready for review October 27, 2026 12:58
@ideaship
ideaship requested a review from berendt October 27, 2026 12:59
@berendt
berendt merged commit da05a9f into main Oct 27, 2026
6 checks passed
@berendt
berendt deleted the docs/proxysql-tls branch October 27, 2026 13:52
@github-project-automation github-project-automation Bot moved this from New to Done in Human Board Oct 27, 2026
@ideaship ideaship self-assigned this Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants